Senders

Sender management and KYC

Get all senders

get

/api/v1/

/senders

Retrieve a list of all senders (money remitters) for the authenticated tenant. Returns only active senders (not soft-deleted). Senders are individuals who initiate money transfers to beneficiaries.

Authorizations

ApiKeyAuth

x-api-keystringRequired

API key for tenant authentication

Responses

200

Successfully retrieved list of senders

application/json

get

/senders

HTTPcURLJavaScriptPython

GET /api/v1/senders HTTP/1.1
x-api-key: YOUR_API_KEY
Accept: */*

200

Successfully retrieved list of senders

[
  {
    "sender_id": "s1a2b3c4-d5e6-4f7a-8b9c-0d1e2f3a4b5c",
    "created_at": "2025-09-01T09:30:00.000Z",
    "updated_at": "2025-11-12T14:15:00.000Z",
    "deleted_at": null,
    "first_name": "Sipho",
    "middle_name": null,
    "last_name": "Nkosi",
    "country": "South Africa",
    "phone_number": "[phone]",
    "daily_limit": 10000,
    "monthly_limit": 100000
  },
  {
    "sender_id": "s2b3c4d5-e6f7-4a8b-9c0d-1e2f3a4b5c6d",
    "created_at": "2025-08-20T11:00:00.000Z",
    "updated_at": "2025-11-08T16:30:00.000Z",
    "deleted_at": null,
    "first_name": "Joseph",
    "middle_name": "Kato",
    "last_name": "Ssemakula",
    "country": "Uganda",
    "phone_number": "[phone]",
    "daily_limit": 15000,
    "monthly_limit": 150000
  }
]

Create sender

post

/api/v1/

/senders

Create a new sender (money remitter) for the authenticated tenant. The country code must be exactly 3 characters (ISO Alpha-3). Phone number must be in international E.164 format. Daily and monthly limits must be at least 1. Senders may require KYC verification before initiating transactions.

Authorizations

ApiKeyAuth

x-api-keystringRequired

API key for tenant authentication

Body

application/json

first_namestring · min: 1Required

Sender's first name

middle_namestring · nullableOptional

Sender's middle name (optional)

last_namestring · min: 1Required

Sender's last name

countrystring · min: 3 · max: 3Required

ISO 3166-1 alpha-3 country code (e.g., ZAF for South Africa, UGA for Uganda)

phone_numberstringRequired

International phone number in E.164 format (e.g., [phone])

daily_limitnumber · min: 1Required

Maximum amount this sender can transfer per day

monthly_limitnumber · min: 1Required

Maximum amount this sender can transfer per month

Responses

201

Sender created successfully

application/json

400

Bad request - Invalid input data

401

Unauthorized - Invalid or missing API key

409

Conflict - Sender already exists

500

Internal server error

post

/senders

HTTPcURLJavaScriptPython

POST /api/v1/senders HTTP/1.1
x-api-key: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 140

{
  "first_name": "Sipho",
  "last_name": "Nkosi",
  "country": "South Africa",
  "phone_number": "[phone]",
  "daily_limit": 10000,
  "monthly_limit": 100000
}

South African SenderUgandan Sender with Middle Name

{
  "sender_id": "text",
  "first_name": "text",
  "middle_name": null,
  "last_name": "text",
  "country": "text",
  "phone_number": "text",
  "daily_limit": 1,
  "monthly_limit": 1,
  "daily_limit_remaining": null,
  "monthly_limit_usage": null,
  "kyc": {
    "kyc_status": "VERIFIED",
    "kyc_source": "TENANT",
    "kyc_details": {
      "kyc_reference_id": "text",
      "kyc_docs": [
        {
          "doc_type": "PASSPORT",
          "doc_number": "text"
        }
      ]
    }
  }
}

Get sender details

get

/api/v1/

/senders/{senderId}

Retrieve sender details by ID

Authorizations

ApiKeyAuth

x-api-keystringRequired

API key for tenant authentication

Path parameters

senderIdstringRequired

Responses

200

Successfully retrieved sender details

application/json

404

Not found - Sender does not exist or has been deleted

application/json

get

/senders/{senderId}

HTTPcURLJavaScriptPython

GET /api/v1/senders/{senderId} HTTP/1.1
x-api-key: YOUR_API_KEY
Accept: */*

{
  "sender_id": "s1a2b3c4-d5e6-4f7a-8b9c-0d1e2f3a4b5c",
  "created_at": "2025-09-01T09:30:00.000Z",
  "updated_at": "2025-11-12T14:15:00.000Z",
  "deleted_at": null,
  "first_name": "Sipho",
  "middle_name": null,
  "last_name": "Nkosi",
  "country": "South Africa",
  "phone_number": "[phone]",
  "daily_limit": 10000,
  "monthly_limit": 100000
}

Update sender

put

/api/v1/

/senders/{senderId}

Update sender by ID

Authorizations

ApiKeyAuth

x-api-keystringRequired

API key for tenant authentication

Path parameters

senderIdstringRequired

Body

application/json

first_namestring · min: 1Required

middle_namestring · nullableOptional

last_namestring · min: 1Required

countrystring · min: 1Required

phone_numberstringRequired

International phone number in E.164 format

daily_limitnumber · min: 1Required

monthly_limitnumber · min: 1Required

Responses

200

Sender updated successfully

application/json

400

Bad request - Invalid input data

401

Unauthorized - Invalid or missing API key

404

Not found - Sender does not exist

application/json

500

Internal server error

put

/senders/{senderId}

HTTPcURLJavaScriptPython

PUT /api/v1/senders/{senderId} HTTP/1.1
x-api-key: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 132

{
  "first_name": "text",
  "middle_name": null,
  "last_name": "text",
  "country": "text",
  "phone_number": "text",
  "daily_limit": 1,
  "monthly_limit": 1
}

{
  "sender_id": "text",
  "first_name": "text",
  "middle_name": null,
  "last_name": "text",
  "country": "text",
  "phone_number": "text",
  "daily_limit": 1,
  "monthly_limit": 1,
  "daily_limit_remaining": null,
  "monthly_limit_usage": null,
  "kyc": {
    "kyc_status": "VERIFIED",
    "kyc_source": "TENANT",
    "kyc_details": {
      "kyc_reference_id": "text",
      "kyc_docs": [
        {
          "doc_type": "PASSPORT",
          "doc_number": "text"
        }
      ]
    }
  }
}

Delete sender

delete

/api/v1/

/senders/{senderId}

Delete sender by ID

Authorizations

ApiKeyAuth

x-api-keystringRequired

API key for tenant authentication

Path parameters

senderIdstringRequired

Responses

200

Sender deleted successfully

application/json

401

Unauthorized - Invalid or missing API key

404

Not found - Sender does not exist

application/json

500

Internal server error

delete

/senders/{senderId}

HTTPcURLJavaScriptPython

DELETE /api/v1/senders/{senderId} HTTP/1.1
x-api-key: YOUR_API_KEY
Accept: */*

{
  "id": "text"
}

Get sender KYC details

get

/api/v1/

/senders/{senderId}/kyc

Retrieve KYC status and details for a sender

Authorizations

ApiKeyAuth

x-api-keystringRequired

API key for tenant authentication

Path parameters

senderIdstringRequired

Responses

200

Successfully retrieved sender KYC details and status

application/json

404

Not found - Sender or KYC details do not exist

application/json

get

/senders/{senderId}/kyc

HTTPcURLJavaScriptPython

GET /api/v1/senders/{senderId}/kyc HTTP/1.1
x-api-key: YOUR_API_KEY
Accept: */*

{
  "sender_id": "s1a2b3c4-d5e6-4f7a-8b9c-0d1e2f3a4b5c",
  "kyc_status": "verified",
  "kyc_verified_at": "2025-09-05T14:00:00.000Z",
  "documents": [
    {
      "document_type": "national_id",
      "document_url": "https://example.com/docs/id_front.jpg",
      "uploaded_at": "2025-09-02T10:30:00.000Z"
    },
    {
      "document_type": "proof_of_address",
      "document_url": "https://example.com/docs/address.pdf",
      "uploaded_at": "2025-09-02T10:32:00.000Z"
    }
  ]
}

Upload KYC documents

post

/api/v1/

/senders/{senderId}/kyc

Upload KYC documents for senders who are not verified by a marketplace

Authorizations

ApiKeyAuth

x-api-keystringRequired

API key for tenant authentication

Path parameters

senderIdstringRequired

Body

multipart/form-data

documentsstring · binary[]Optional

Responses

200

KYC documents uploaded successfully

application/json

400

Bad request - Invalid or missing documents

401

Unauthorized - Invalid or missing API key

404

Not found - Sender does not exist

500

Internal server error

post

/senders/{senderId}/kyc

HTTPcURLJavaScriptPython

POST /api/v1/senders/{senderId}/kyc HTTP/1.1
x-api-key: YOUR_API_KEY
Content-Type: multipart/form-data
Accept: */*
Content-Length: 24

{
  "documents": [
    "binary"
  ]
}

{
  "kyc_status": "VERIFIED",
  "kyc_source": "TENANT",
  "kyc_details": {
    "kyc_reference_id": "text",
    "kyc_docs": [
      {
        "doc_type": "PASSPORT",
        "doc_number": "text"
      }
    ]
  }
}

Update KYC status

put

/api/v1/

/senders/{senderId}/kyc

Update KYC status after verification

Authorizations

ApiKeyAuth

x-api-keystringRequired

API key for tenant authentication

Path parameters

senderIdstringRequired

Body

application/json

kyc_statusstring · enumRequiredPossible values:

rejection_reasonstring · min: 1Required

Responses

200

KYC status updated successfully

application/json

400

Bad request - Invalid status or input data

401

Unauthorized - Invalid or missing API key

404

Not found - Sender does not exist

application/json

500

Internal server error

put

/senders/{senderId}/kyc

HTTPcURLJavaScriptPython

PUT /api/v1/senders/{senderId}/kyc HTTP/1.1
x-api-key: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 51

{
  "kyc_status": "VERIFIED",
  "rejection_reason": "text"
}

{
  "kyc_status": "VERIFIED",
  "kyc_source": "TENANT",
  "kyc_details": {
    "kyc_reference_id": "text",
    "kyc_docs": [
      {
        "doc_type": "PASSPORT",
        "doc_number": "text"
      }
    ]
  }
}