Customers

Onboard a customer and open its main wallet

POST/api/v1/tenant/customers

Scope customers:write · Write — send Idempotency-Key and X-Request-Id

Request body

Field	Type	Required	Description
customerType	enum	no	Defaults to person. One of person, organization.
displayName	string	yes
dateOfBirth	string | null	no	ISO-8601 date.
regionCode	string | null	no
preferredLocale	string | null	no	BCP-47; defaults to en.
identifiers	object[]	yes
identifiers[].class	enum	no	Derived from type for phone, email and identity-document types; required only for a type Neo Wallet does not recognise. One of contact, identity_document.
identifiers[].type	string	yes	e.g. msisdn, email, national_id, passport.
identifiers[].value	string	yes	Clear-text value; reads return it masked.
identifiers[].isPrimary	boolean | null	no	The first identifier is primary unless one of them says otherwise.
identifiers[].verificationStatus	enum	no	Defaults to verified for a contact identifier (you verified it to reach the customer) and pending for an identity document (Neo Wallet's compliance review verifies those). One of unverified, pending, verified, rejected, expired, revoked.
identifiers[].verifiedAt	string | null	no	ISO-8601; defaults to now for a verified identifier.
identifiers[].issuingCountry	string | null	no	ISO-3166-1 alpha-2.
kyc	object	yes
kyc.tierCode	string	yes	Code of an active KYC level, e.g. tier_1.
kyc.verificationSource	string | null	no	The KYC system or provider that verified the customer; defaults to client_asserted.
kyc.sourceReference	string | null	no	Opaque reference into your KYC system.
kyc.evidence	object	yes
kyc.riskRating	enum	yes	One of low, medium, high, prohibited.
agreements	object[]	yes	The documents the customer accepted in your channel. wallet_opening, privacy and fee_schedule are required: a request missing any of them is refused with 422 RequiredAgreementsMissing and nothing is created.
agreements[].agreementType	enum	yes	One of wallet_opening, privacy, fee_schedule, mandate, other.
agreements[].documentType	string | null	no	Defaults to agreementType.
agreements[].documentVersion	string	yes
agreements[].documentUri	string	yes
agreements[].documentHash	string	yes	SHA-256 of the accepted document, 64 hex characters.
agreements[].acceptedAt	string	yes	ISO-8601.
agreements[].acceptedChannel	string | null	no	Your channel the consent was captured in; defaults to client_channel.
agreements[].evidence	object	yes
rulesProfileKey	string | null	no	The wallet profile to open the customer's wallet on; it decides what the wallet can do. Must be one your account is approved for. Omit it to use your account's default profile.
clientReference	string | null	no	Your own reference for this customer; stored and returned verbatim, never interpreted. Unique among your customers: a second customer with the same value is refused with 409.
metadata	object	no

Example (placeholder values)

{
  "displayName": "string",
  "identifiers": [
    {
      "type": "string",
      "value": "string"
    }
  ],
  "kyc": {
    "tierCode": "string",
    "evidence": {},
    "riskRating": "low"
  },
  "agreements": [
    {
      "agreementType": "wallet_opening",
      "documentVersion": "string",
      "documentUri": "string",
      "documentHash": "string",
      "acceptedAt": "2026-09-03T10:15:30.000Z",
      "evidence": {}
    }
  ]
}

Response · 201

Field	Type	Description
uid	string
status	enum	One of pending, active, restricted, suspended, deceased, closed.
customerType	enum	One of person, organization.
displayName	string
walletUid	string	The customer's main wallet; you can credit it immediately (POST /tenant/wallet-credits).
kycTierCode	string	Code of the customer's KYC level, e.g. tier_1.
rulesProfileKey	string	The wallet profile the customer's wallet was opened on.
identifiers	object[]
identifiers[].uid	string
identifiers[].class	enum	One of contact, identity_document.
identifiers[].type	string
identifiers[].maskedValue	string	The identifier value, masked.
identifiers[].isPrimary	boolean
identifiers[].verificationStatus	enum	One of unverified, pending, verified, rejected, expired, revoked.
clientReference	string | null	Your reference, exactly as you supplied it.
createdAt	string

Example (placeholder values)

{
  "uid": "01J9Z3K5X8QW2R4T6V8Y0B1C3D",
  "status": "pending",
  "customerType": "person",
  "displayName": "string",
  "walletUid": "01J9Z3K5X8QW2R4T6V8Y0B1C3D",
  "kycTierCode": "string",
  "rulesProfileKey": "string",
  "identifiers": [
    {
      "uid": "01J9Z3K5X8QW2R4T6V8Y0B1C3D",
      "class": "contact",
      "type": "string",
      "maskedValue": "string",
      "isPrimary": true,
      "verificationStatus": "unverified"
    }
  ],
  "clientReference": "string",
  "createdAt": "2026-09-03T10:15:30.000Z"
}

Errors

400 401 403 404 409 422 429 500 503 — one body shape for all of them, see Errors.

Customer summary: status, KYC, wallets, identifiers, agreements, mandates

GET/api/v1/tenant/customers/{uid}

Scope customers:read

Path parameters

Name	Type	Required	Description
uid	string	yes

Response · 200

Field	Type	Description
uid	string
status	enum	One of pending, active, restricted, suspended, deceased, closed.
customerType	enum	One of person, organization.
displayName	string
kyc	object | null
kyc.tierCode	string	Code of the customer's KYC level, e.g. tier_1.
kyc.tierName	string	Display name of the KYC level.
kyc.riskRating	enum	One of low, medium, high, prohibited.
kyc.approvedAt	string
kyc.limits	object
kyc.limits.currency	string
kyc.limits.maxBalance	string	A decimal amount with two decimal places.
kyc.limits.maxSingleTxn	string | null	A decimal amount; null where the KYC level sets no limit.
kyc.limits.aggregateDailyLimit	string	A decimal amount with two decimal places.
kyc.limits.monthlyOutLimit	string | null	A decimal amount; null where the KYC level sets no limit.
wallets	object[]
wallets[].walletUid	string
wallets[].purpose	enum	One of main, incentive, commission, savings, other.
wallets[].status	enum	One of pending, active, debit_blocked, credit_blocked, frozen, dormant, closed.
wallets[].currency	string
wallets[].rulesProfileKey	string	The wallet profile the wallet was opened on.
wallets[].balance	object | null
wallets[].balance.currency	string
wallets[].balance.current	string	A decimal amount with two decimal places.
wallets[].balance.held	string	A decimal amount with two decimal places.
wallets[].balance.available	string	A decimal amount with two decimal places.
wallets[].balance.asOf	string
identifiers	object[]
identifiers[].uid	string
identifiers[].class	enum	One of contact, identity_document.
identifiers[].type	string
identifiers[].maskedValue	string	The identifier value, masked.
identifiers[].isPrimary	boolean
identifiers[].verificationStatus	enum	One of unverified, pending, verified, rejected, expired, revoked.
identifiers[].payoutEligible	boolean	Whether a payout may go to this identifier: a verified contact identifier that is valid now.
agreements	object[]
agreements[].agreementType	enum	One of wallet_opening, privacy, fee_schedule, mandate, other.
agreements[].documentVersion	string
agreements[].acceptedAt	string
mandatesCount	number	Number of debit mandates you hold on this customer.
clientReference	object | null	Your reference, exactly as you supplied it.
createdAt	string

Example (placeholder values)

{
  "uid": "01J9Z3K5X8QW2R4T6V8Y0B1C3D",
  "status": "pending",
  "customerType": "person",
  "displayName": "string",
  "kyc": {
    "tierCode": "string",
    "tierName": "string",
    "riskRating": "low",
    "approvedAt": "2026-09-03T10:15:30.000Z",
    "limits": {
      "currency": "ETB",
      "maxBalance": "50000.00",
      "maxSingleTxn": "string",
      "aggregateDailyLimit": "25000.00",
      "monthlyOutLimit": "string"
    }
  },
  "wallets": [
    {
      "walletUid": "01J9Z3K5X8QW2R4T6V8Y0B1C3D",
      "purpose": "main",
      "status": "pending",
      "currency": "ETB",
      "rulesProfileKey": "string",
      "balance": {
        "currency": "ETB",
        "current": "2500.00",
        "held": "0.00",
        "available": "2500.00",
        "asOf": "string"
      }
    }
  ],
  "identifiers": [
    {
      "uid": "01J9Z3K5X8QW2R4T6V8Y0B1C3D",
      "class": "contact",
      "type": "string",
      "maskedValue": "string",
      "isPrimary": true,
      "verificationStatus": "unverified",
      "payoutEligible": true
    }
  ],
  "agreements": [
    {
      "agreementType": "wallet_opening",
      "documentVersion": "string",
      "acceptedAt": "2026-09-03T10:15:30.000Z"
    }
  ],
  "mandatesCount": 0,
  "clientReference": {},
  "createdAt": "2026-09-03T10:15:30.000Z"
}

Errors

400 401 403 404 429 500 503 — one body shape for all of them, see Errors.

Attach an identifier to a customer

POST/api/v1/tenant/customers/{uid}/identifiers

Scope customers:write · Write — send Idempotency-Key and X-Request-Id

Path parameters

Name	Type	Required	Description
uid	string	yes

Request body

Field	Type	Required	Description
class	enum	yes	One of contact, identity_document.
type	string	yes	e.g. msisdn, email, national_id, passport.
value	string	yes	Clear-text value; reads return it masked.
isPrimary	boolean	no	Demotes the previous primary of the same class.
verificationStatus	enum	yes	One of unverified, pending, verified, rejected, expired, revoked.
verifiedAt	object	no	ISO-8601.
issuingCountry	object	no	ISO-3166-1 alpha-2.

Example (placeholder values)

{
  "class": "contact",
  "type": "string",
  "value": "string",
  "verificationStatus": "unverified"
}

Response · 201

Field	Type	Description
uid	string
class	enum	One of contact, identity_document.
type	string
maskedValue	string	The identifier value, masked.
isPrimary	boolean
verificationStatus	enum	One of unverified, pending, verified, rejected, expired, revoked.
issuingCountry	object | null
verifiedAt	object | null
validFrom	string
validTo	object | null
payoutEligible	boolean	True for a verified contact identifier inside its validity window; only these can be a payout destination.

Example (placeholder values)

{
  "uid": "01J9Z3K5X8QW2R4T6V8Y0B1C3D",
  "class": "contact",
  "type": "string",
  "maskedValue": "string",
  "isPrimary": true,
  "verificationStatus": "unverified",
  "issuingCountry": {},
  "verifiedAt": {},
  "validFrom": "2026-09-03T10:15:30.000Z",
  "validTo": {},
  "payoutEligible": true
}

Errors

400 401 403 404 409 422 429 500 503 — one body shape for all of them, see Errors.

Update an identifier's verification state

PATCH/api/v1/tenant/customers/{uid}/identifiers/{iid}

Scope customers:write · Write — send Idempotency-Key and X-Request-Id

Path parameters

Name	Type	Required	Description
uid	string	yes
iid	string	yes

Request body

Field	Type	Required	Description
verificationStatus	enum	yes	One of unverified, pending, verified, rejected, expired, revoked.
verifiedAt	object | null	yes	ISO-8601; required when verificationStatus is verified.
validTo	object	no	ISO-8601; retires the identifier at this instant.

Example (placeholder values)

{
  "verificationStatus": "unverified",
  "verifiedAt": {}
}

Response · 200

Field	Type	Description
uid	string
class	enum	One of contact, identity_document.
type	string
maskedValue	string	The identifier value, masked.
isPrimary	boolean
verificationStatus	enum	One of unverified, pending, verified, rejected, expired, revoked.
issuingCountry	object | null
verifiedAt	object | null
validFrom	string
validTo	object | null
payoutEligible	boolean	True for a verified contact identifier inside its validity window; only these can be a payout destination.

Example (placeholder values)

{
  "uid": "01J9Z3K5X8QW2R4T6V8Y0B1C3D",
  "class": "contact",
  "type": "string",
  "maskedValue": "string",
  "isPrimary": true,
  "verificationStatus": "unverified",
  "issuingCountry": {},
  "verifiedAt": {},
  "validFrom": "2026-09-03T10:15:30.000Z",
  "validTo": {},
  "payoutEligible": true
}

Errors

400 401 403 404 409 422 429 500 503 — one body shape for all of them, see Errors.

Record a customer's acceptance of a document

POST/api/v1/tenant/customers/{uid}/agreements

Scope customers:write · Write — send Idempotency-Key and X-Request-Id

Path parameters

Name	Type	Required	Description
uid	string	yes

Request body

Field	Type	Required	Description
agreementType	enum	yes	One of wallet_opening, privacy, fee_schedule, mandate, other.
documentType	string	yes	e.g. terms, fee_schedule_v3, privacy_notice.
documentVersion	string	yes
documentUri	string	yes
documentHash	string	yes	SHA-256 of the accepted document, 64 hex characters.
acceptedAt	string	yes	ISO-8601.
acceptedChannel	string	yes	Your channel the consent was captured in; portal is not accepted.
evidence	object	yes	Your proof of the acceptance; never returned — evidenceHash stands in for it.

Example (placeholder values)

{
  "agreementType": "wallet_opening",
  "documentType": "string",
  "documentVersion": "string",
  "documentUri": "string",
  "documentHash": "string",
  "acceptedAt": "2026-09-03T10:15:30.000Z",
  "acceptedChannel": "string",
  "evidence": {}
}

Response · 201

Field	Type	Description
uid	string
agreementType	enum	One of wallet_opening, privacy, fee_schedule, mandate, other.
documentType	string
documentVersion	string
documentUri	string
documentHash	string
status	enum	One of accepted, revoked, expired, superseded.
acceptedAt	string
acceptedChannel	string
evidenceHash	string	SHA-256 of the canonical consent evidence.

Example (placeholder values)

{
  "uid": "01J9Z3K5X8QW2R4T6V8Y0B1C3D",
  "agreementType": "wallet_opening",
  "documentType": "string",
  "documentVersion": "string",
  "documentUri": "string",
  "documentHash": "string",
  "status": "accepted",
  "acceptedAt": "2026-09-03T10:15:30.000Z",
  "acceptedChannel": "string",
  "evidenceHash": "string"
}

Errors

400 401 403 404 409 422 429 500 503 — one body shape for all of them, see Errors.

Submit a KYC update or KYC level change for a customer

POST/api/v1/tenant/customers/{uid}/kyc-versions

Scope customers:write · Write — send Idempotency-Key and X-Request-Id

Adds a new KYC version to the customer's history; earlier versions are never edited. A move to Level 1 (upgrade/downgrade to tier_1, risk rating not prohibited) is approved on your declaration alone and takes effect immediately: the previous version is superseded, the customer's wallets move to the new KYC level, a wallet whose balance is above that level's maximum is flagged credit_blocked, and customer.kyc_changed is delivered to your webhook. Every other submission is pending until Neo Wallet's compliance review approves or rejects it (the webhook fires then). An upgrade/downgrade must move the KYC level's maximum balance in the direction it names (422). Only one pending version per customer (409).

Path parameters

Name	Type	Required	Description
uid	string	yes

Request body

Field	Type	Required	Description
tierCode	string	yes	Code of an active KYC level, e.g. tier_1.
reviewType	enum	yes	One of upgrade, downgrade, periodic_review, event_driven_review.
verificationSource	string	yes
sourceReference	string	yes	Opaque reference into your KYC system.
evidence	object	yes	Your verification evidence; never returned — evidenceHash stands in for it.
riskRating	enum	yes	One of low, medium, high, prohibited.

Example (placeholder values)

{
  "tierCode": "string",
  "reviewType": "upgrade",
  "verificationSource": "string",
  "sourceReference": "string",
  "evidence": {},
  "riskRating": "low"
}

Response · 201

Field	Type	Description
uid	string
customerUid	string
tierCode	string	Code of the KYC level this version asserts.
reviewType	enum	One of upgrade, downgrade, periodic_review, event_driven_review.
state	enum	approved when your assertion is accepted outright (a move to Level 1); otherwise pending until Neo Wallet's compliance review decides, announced by the customer.kyc_changed webhook. One of pending, approved, rejected, expired, superseded.
verificationSource	string
sourceReference	string | null
riskRating	enum | null	One of low, medium, high, prohibited.
evidenceHash	string	SHA-256 of the canonical evidence JSON.
effectiveFrom	string | null	Set when the version is approved.
createdAt	string

Example (placeholder values)

{
  "uid": "01J9Z3K5X8QW2R4T6V8Y0B1C3D",
  "customerUid": "01J9Z3K5X8QW2R4T6V8Y0B1C3D",
  "tierCode": "string",
  "reviewType": "upgrade",
  "state": "pending",
  "verificationSource": "string",
  "sourceReference": "string",
  "riskRating": "low",
  "evidenceHash": "string",
  "effectiveFrom": "string",
  "createdAt": "2026-09-03T10:15:30.000Z"
}

Errors

400 401 403 404 409 422 429 500 503 — one body shape for all of them, see Errors.