API reference

Users

A user is one of your customers: a person or a business. Users verify their identity and accept the terms through hosted links before they can hold or move money.

List users

GET/v1/users

Returns a page of User objects.

Query parameters

limitinteger: Default 10.
starting_afterstring: Cursor; an object ID. Returns the page after it. Cannot be combined with ending_before.
ending_beforestring: Cursor; an object ID. Returns the page before it. Cannot be combined with starting_after.
external_referencestring
kyc_statusstring: One of not_started, under_review, incomplete, approved, rejected.
statusstring: One of active, deactivated.

Responses

200A page of users.
400The request is malformed.
401The API key is missing, invalid or revoked.
429The key is over its rate limit.
5XXServer error. Safe to retry with the same idempotency key.

Request

curl "https://sandbox.api.ndeipi.example/v1/users?limit=20" \
  -H "Api-Key: $NDEIPI_API_KEY"

Response 200

{
  "data": [
    {
      "id": "usr_01JA8Z2F5G6H7J8K9M0N1P2Q3R",
      "object": "user",
      "type": "individual",
      "external_reference": "crm-1042",
      "email": "ama.moyo@example.com",
      "phone": "+263771234567",
      "first_name": "Ama",
      "last_name": "Moyo",
      "business_name": null,
      "country": "ZW",
      "status": "active",
      "kyc_status": "approved",
      "terms_status": "approved",
      "rejection_reasons": [],
      "metadata": {
        "segment": "retail"
      },
      "version": 3,
      "created_at": "2026-10-16T09:30:00Z",
      "updated_at": "2026-10-16T10:12:44Z"
    }
  ],
  "has_more": false
}

Creates an individual or business user. Identity data is collected through the hosted onboarding link, not through this call. external_reference is unique per integrator; a second create with the same reference returns 409 external_reference_exists naming the existing user.

Returns User.

Headers

Idempotency-Keyheaderrequired: A unique key for this write, up to 255 characters. Send the same key to retry safely; see idempotency.

Body

typestringrequired: One of individual, business.
external_referencestringrequired: Integrator's own ID for the user; unique per integrator.
emailstring
phonestring: E.164.
first_namestring: Individuals only.
last_namestring: Individuals only.
business_namestring: Businesses only; required for them.
countrystring: ISO 3166-1 alpha-2 country code.
metadataobject: Integrator key-value data, returned unchanged. Up to 50 keys; keys up to 40 characters, values up to 500.

Responses

201User created.
400The request is malformed.
401The API key is missing, invalid or revoked.
409The request conflicts with the object's current state or an earlier request.
422The request is well formed but fails validation or a business rule.
429The key is over its rate limit.
5XXServer error. Safe to retry with the same idempotency key.

Request

curl -X POST "https://sandbox.api.ndeipi.example/v1/users" \
  -H "Api-Key: $NDEIPI_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "individual",
    "external_reference": "crm-1042",
    "email": "ama.moyo@example.com",
    "phone": "+263771234567",
    "first_name": "Ama",
    "last_name": "Moyo",
    "country": "ZW",
    "metadata": {
      "segment": "retail"
    }
  }'

Response 201

{
  "id": "usr_01JA8Z2F5G6H7J8K9M0N1P2Q3R",
  "object": "user",
  "type": "individual",
  "external_reference": "crm-1042",
  "email": "ama.moyo@example.com",
  "phone": "+263771234567",
  "first_name": "Ama",
  "last_name": "Moyo",
  "business_name": null,
  "country": "ZW",
  "status": "active",
  "kyc_status": "approved",
  "terms_status": "approved",
  "rejection_reasons": [],
  "metadata": {
    "segment": "retail"
  },
  "version": 3,
  "created_at": "2026-10-16T09:30:00Z",
  "updated_at": "2026-10-16T10:12:44Z"
}

Get a user

GET/v1/users/{user_id}

Returns User.

Path parameters

user_idstringrequired: Starts with usr_.

Responses

200The user.
401The API key is missing, invalid or revoked.
404The object does not exist or belongs to another integrator.
429The key is over its rate limit.
5XXServer error. Safe to retry with the same idempotency key.

Request

curl "https://sandbox.api.ndeipi.example/v1/users/usr_01JA8Z2F5G6H7J8K9M0N1P2Q3R" \
  -H "Api-Key: $NDEIPI_API_KEY"

Response 200

{
  "id": "usr_01JA8Z2F5G6H7J8K9M0N1P2Q3R",
  "object": "user",
  "type": "individual",
  "external_reference": "crm-1042",
  "email": "ama.moyo@example.com",
  "phone": "+263771234567",
  "first_name": "Ama",
  "last_name": "Moyo",
  "business_name": null,
  "country": "ZW",
  "status": "active",
  "kyc_status": "approved",
  "terms_status": "approved",
  "rejection_reasons": [],
  "metadata": {
    "segment": "retail"
  },
  "version": 3,
  "created_at": "2026-10-16T09:30:00Z",
  "updated_at": "2026-10-16T10:12:44Z"
}

Update a user

PATCH/v1/users/{user_id}

Updates contact details and metadata. Identity data changes go through a new onboarding link.

Returns User.

Path parameters

user_idstringrequired: Starts with usr_.

Body

emailstring
phonestring
metadataobject: Integrator key-value data, returned unchanged. Up to 50 keys; keys up to 40 characters, values up to 500.

Responses

200The updated user.
400The request is malformed.
401The API key is missing, invalid or revoked.
404The object does not exist or belongs to another integrator.
422The request is well formed but fails validation or a business rule.
429The key is over its rate limit.
5XXServer error. Safe to retry with the same idempotency key.

Request

curl -X PATCH "https://sandbox.api.ndeipi.example/v1/users/usr_01JA8Z2F5G6H7J8K9M0N1P2Q3R" \
  -H "Api-Key: $NDEIPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "phone": "+263772345678"
  }'

Response 200

{
  "id": "usr_01JA8Z2F5G6H7J8K9M0N1P2Q3R",
  "object": "user",
  "type": "individual",
  "external_reference": "crm-1042",
  "email": "ama.moyo@example.com",
  "phone": "+263771234567",
  "first_name": "Ama",
  "last_name": "Moyo",
  "business_name": null,
  "country": "ZW",
  "status": "active",
  "kyc_status": "approved",
  "terms_status": "approved",
  "rejection_reasons": [],
  "metadata": {
    "segment": "retail"
  },
  "version": 3,
  "created_at": "2026-10-16T09:30:00Z",
  "updated_at": "2026-10-16T10:12:44Z"
}

Deactivate a user

POST/v1/users/{user_id}/deactivate

A deactivated user cannot send or receive funds and cannot be reactivated through the API. Deactivation is refused with 409 user_has_balance while any of the user's wallets holds an available or pending balance, and with 409 user_has_open_transfers while a transfer involving the user is not in a final state. The integrator pays the balance out first.

Returns User.

Path parameters

user_idstringrequired: Starts with usr_.

Headers

Idempotency-Keyheaderrequired: A unique key for this write, up to 255 characters. Send the same key to retry safely; see idempotency.

Responses

200The deactivated user.
401The API key is missing, invalid or revoked.
404The object does not exist or belongs to another integrator.
409The request conflicts with the object's current state or an earlier request.
429The key is over its rate limit.
5XXServer error. Safe to retry with the same idempotency key.

Request

curl -X POST "https://sandbox.api.ndeipi.example/v1/users/usr_01JA8Z2F5G6H7J8K9M0N1P2Q3R/deactivate" \
  -H "Api-Key: $NDEIPI_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)"

Response 200

{
  "id": "usr_01JA8Z2F5G6H7J8K9M0N1P2Q3R",
  "object": "user",
  "type": "individual",
  "external_reference": "crm-1042",
  "email": "ama.moyo@example.com",
  "phone": "+263771234567",
  "first_name": "Ama",
  "last_name": "Moyo",
  "business_name": null,
  "country": "ZW",
  "status": "deactivated",
  "kyc_status": "approved",
  "terms_status": "approved",
  "rejection_reasons": [],
  "metadata": {
    "segment": "retail"
  },
  "version": 4,
  "created_at": "2026-10-16T09:30:00Z",
  "updated_at": "2026-10-16T10:12:44Z"
}

Create onboarding links

POST/v1/users/{user_id}/onboarding_links

Issues a hosted KYC link and a terms-of-service link in one call. Calling again issues fresh links and expires the previous ones.

Returns OnboardingLinks.

Path parameters

user_idstringrequired: Starts with usr_.

Headers

Idempotency-Keyheaderrequired: A unique key for this write, up to 255 characters. Send the same key to retry safely; see idempotency.

Body

redirect_urlstring: HTTPS URL the hosted flow returns the user to when finished.

Responses

201Links issued.
401The API key is missing, invalid or revoked.
404The object does not exist or belongs to another integrator.
409The request conflicts with the object's current state or an earlier request.
422The request is well formed but fails validation or a business rule.
429The key is over its rate limit.
5XXServer error. Safe to retry with the same idempotency key.

Request

curl -X POST "https://sandbox.api.ndeipi.example/v1/users/usr_01JA8Z2F5G6H7J8K9M0N1P2Q3R/onboarding_links" \
  -H "Api-Key: $NDEIPI_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "redirect_url": "https://app.yourapp.example/onboarding/done"
  }'

Response 201

{
  "object": "onboarding_links",
  "user_id": "usr_01JA8Z2F5G6H7J8K9M0N1P2Q3R",
  "kyc": {
    "url": "https://onboarding.ndeipi.example/kyc/ol_01JA8ZL2ZV5X0G3E1D8C7B6A5Z",
    "status": "not_started",
    "expires_at": "2026-10-23T09:30:00Z"
  },
  "terms": {
    "url": "https://onboarding.ndeipi.example/terms/ol_01JA8ZL2ZV5X0G3E1D8C7B6A5Z",
    "status": "pending",
    "expires_at": "2026-10-23T09:30:00Z"
  }
}

Users

List users

Query parameters

Responses

Create a user

Headers

Body

Responses

Get a user

Path parameters

Responses

Update a user

Path parameters

Body

Responses

Deactivate a user

Path parameters

Headers

Responses

Create onboarding links

Path parameters

Headers

Body

Responses