Recipients

Register and manage third parties paid by KYC-verified senders

List recipients

get

https://api-staging.unigox.comhttps://api.unigox.com

/api/v1/partner/recipients

Lists third parties registered by the authenticated partner. A recipient is the person or business a KYC-verified sender pays; it is not the sender's own payment profile. Results are tenant-scoped and never expose an unmasked account number.

Authorizations

ApiKeyAuth

X-API-KeystringRequired

Partner API key for authentication. Required for all partner account endpoints.

Query parameters

searchstringOptional

Search by recipient name or partner-visible identifier.

screening_statusstringOptional

recipient_countrystring · min: 2 · max: 2Optional

currencystring · min: 3 · max: 3Optional

railstringOptional

limitinteger · min: 1 · max: 100OptionalDefault: 20

offsetintegerOptionalDefault: 0

Responses

200

Recipients returned

application/json

successbooleanRequired

Indicates if the request was successful

Example: true

401

Partner not authenticated

500

Internal Server Error

get/api/v1/partner/recipients

HTTPcURLJavaScriptPython

GET /api/v1/partner/recipients HTTP/1.1
Host: api-staging.unigox.com
X-API-Key: YOUR_API_KEY
Accept: */*

{
  "success": true,
  "data": {
    "recipients": [
      {
        "id": "123e4567-e89b-12d3-a456-426614174000",
        "kind": "individual",
        "recipient_name": "text",
        "recipient_native_name": "text",
        "recipient_country": "text",
        "recipient_id_type": "text",
        "recipient_id_number": "text",
        "recipient_business_registration_number": "text",
        "lifecycle": "draft",
        "version": 1,
        "screening_status": "pending",
        "screened_at": "2026-08-09T00:38:31.327Z",
        "created_at": "2026-08-09T00:38:31.327Z"
      }
    ],
    "total": 1,
    "limit": 1,
    "offset": 1
  }
}

Register a recipient

post

https://api-staging.unigox.comhttps://api.unigox.com

/api/v1/partner/recipients

Registers a partner-scoped third-party recipient identity. Add payout destinations separately with POST /recipients/{recipient_id}/destinations. Vendor-specific terms such as beneficiary or receiver are intentionally absent.

Authorizations

ApiKeyAuth

X-API-KeystringRequired

Partner API key for authentication. Required for all partner account endpoints.

Body

application/json

recipient_kindstring · enumOptionalDefault: individualPossible values:

recipient_namestringRequired

recipient_native_namestringOptional

recipient_countrystring · min: 2 · max: 2RequiredExample: CN

recipient_id_typestringOptionalExample: national_id

recipient_id_numberstringWrite-onlyOptional

recipient_business_registration_numberstringWrite-onlyOptional

Responses

200

Recipient registered

application/json

successbooleanRequired

Indicates if the request was successful

Example: true

400

Invalid recipient. error.message names what to fix; error.details.reason carries a stable machine slug. Screening runs asynchronously AFTER creation, so it never rejects here — a recipient is created with screening_status: pending and becomes usable for a quote only once it reaches cleared.

401

Partner not authenticated

500

Internal Server Error

503

Recipient directory unreachable. The request was not wrong; retry with backoff.

post/api/v1/partner/recipients

HTTPcURLJavaScriptPython

POST /api/v1/partner/recipients HTTP/1.1
Host: api-staging.unigox.com
X-API-Key: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 222

{
  "recipient_kind": "individual",
  "recipient_name": "text",
  "recipient_native_name": "text",
  "recipient_country": "CN",
  "recipient_id_type": "national_id",
  "recipient_id_number": "text",
  "recipient_business_registration_number": "text"
}

{
  "success": true,
  "data": {
    "recipient": {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "kind": "individual",
      "recipient_name": "text",
      "recipient_native_name": "text",
      "recipient_country": "text",
      "recipient_id_type": "text",
      "recipient_id_number": "text",
      "recipient_business_registration_number": "text",
      "lifecycle": "draft",
      "version": 1,
      "screening_status": "pending",
      "screened_at": "2026-08-09T00:38:31.327Z",
      "created_at": "2026-08-09T00:38:31.327Z"
    },
    "recipient_destination": {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "recipient_id": "123e4567-e89b-12d3-a456-426614174000",
      "payment_method_id": 1,
      "payment_network_id": 1,
      "country_code": "text",
      "currency": "text",
      "details": {
        "ANY_ADDITIONAL_PROPERTY": "anything"
      },
      "version": 1,
      "lifecycle": "active",
      "created_at": "2026-08-09T00:38:31.327Z"
    }
  }
}

Get recipient

get

https://api-staging.unigox.comhttps://api.unigox.com

/api/v1/partner/recipients/{recipient_id}

Authorizations

ApiKeyAuth

X-API-KeystringRequired

Partner API key for authentication. Required for all partner account endpoints.

Path parameters

recipient_idstring · uuidRequired

Responses

200

Recipient returned

application/json

successbooleanRequired

Indicates if the request was successful

Example: true

404

Recipient not found for this partner

get/api/v1/partner/recipients/{recipient_id}

HTTPcURLJavaScriptPython

GET /api/v1/partner/recipients/{recipient_id} HTTP/1.1
Host: api-staging.unigox.com
X-API-Key: YOUR_API_KEY
Accept: */*

{
  "success": true,
  "data": {
    "recipient": {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "kind": "individual",
      "recipient_name": "text",
      "recipient_native_name": "text",
      "recipient_country": "text",
      "recipient_id_type": "text",
      "recipient_id_number": "text",
      "recipient_business_registration_number": "text",
      "lifecycle": "draft",
      "version": 1,
      "screening_status": "pending",
      "screened_at": "2026-08-09T00:38:31.327Z",
      "created_at": "2026-08-09T00:38:31.327Z"
    },
    "recipient_destination": {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "recipient_id": "123e4567-e89b-12d3-a456-426614174000",
      "payment_method_id": 1,
      "payment_network_id": 1,
      "country_code": "text",
      "currency": "text",
      "details": {
        "ANY_ADDITIONAL_PROPERTY": "anything"
      },
      "version": 1,
      "lifecycle": "active",
      "created_at": "2026-08-09T00:38:31.327Z"
    }
  }
}

Archive recipient

delete

https://api-staging.unigox.comhttps://api.unigox.com

/api/v1/partner/recipients/{recipient_id}

Archives the recipient for future use. Existing immutable order snapshots remain auditable.

Authorizations

ApiKeyAuth

X-API-KeystringRequired

Partner API key for authentication. Required for all partner account endpoints.

Path parameters

recipient_idstring · uuidRequired

Responses

200

Recipient archived

No content

404

Recipient not found for this partner

delete/api/v1/partner/recipients/{recipient_id}

HTTPcURLJavaScriptPython

DELETE /api/v1/partner/recipients/{recipient_id} HTTP/1.1
Host: api-staging.unigox.com
X-API-Key: YOUR_API_KEY
Accept: */*

No content

Update recipient identity

patch

https://api-staging.unigox.comhttps://api.unigox.com

/api/v1/partner/recipients/{recipient_id}

Updates recipient identity by creating a new immutable version. Existing quotes and orders keep their original snapshot; request a new quote to use the updated data.

Authorizations

ApiKeyAuth

X-API-KeystringRequired

Partner API key for authentication. Required for all partner account endpoints.

Path parameters

recipient_idstring · uuidRequired

Body

application/json

recipient_namestringOptional

recipient_native_namestringOptional

recipient_countrystring · min: 2 · max: 2Optional

recipient_id_typestringOptional

recipient_id_numberstringWrite-onlyOptional

recipient_business_registration_numberstringWrite-onlyOptional

Responses

200

Updated recipient returned

application/json

successbooleanRequired

Indicates if the request was successful

Example: true

400

Invalid update

404

Recipient not found for this partner

patch/api/v1/partner/recipients/{recipient_id}

HTTPcURLJavaScriptPython

PATCH /api/v1/partner/recipients/{recipient_id} HTTP/1.1
Host: api-staging.unigox.com
X-API-Key: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 187

{
  "recipient_name": "text",
  "recipient_native_name": "text",
  "recipient_country": "text",
  "recipient_id_type": "text",
  "recipient_id_number": "text",
  "recipient_business_registration_number": "text"
}

{
  "success": true,
  "data": {
    "recipient": {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "kind": "individual",
      "recipient_name": "text",
      "recipient_native_name": "text",
      "recipient_country": "text",
      "recipient_id_type": "text",
      "recipient_id_number": "text",
      "recipient_business_registration_number": "text",
      "lifecycle": "draft",
      "version": 1,
      "screening_status": "pending",
      "screened_at": "2026-08-09T00:38:31.327Z",
      "created_at": "2026-08-09T00:38:31.327Z"
    },
    "recipient_destination": {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "recipient_id": "123e4567-e89b-12d3-a456-426614174000",
      "payment_method_id": 1,
      "payment_network_id": 1,
      "country_code": "text",
      "currency": "text",
      "details": {
        "ANY_ADDITIONAL_PROPERTY": "anything"
      },
      "version": 1,
      "lifecycle": "active",
      "created_at": "2026-08-09T00:38:31.327Z"
    }
  }
}

List recipient destinations

get

https://api-staging.unigox.comhttps://api.unigox.com

/api/v1/partner/recipients/{recipient_id}/destinations

Returns masked payout destinations belonging to this recipient and partner.

Authorizations

ApiKeyAuth

X-API-KeystringRequired

Partner API key for authentication. Required for all partner account endpoints.

Path parameters

recipient_idstring · uuidRequired

Responses

200

Masked destinations returned

application/json

successbooleanRequired

Indicates if the request was successful

Example: true

404

Recipient not found for this partner

get/api/v1/partner/recipients/{recipient_id}/destinations

HTTPcURLJavaScriptPython

GET /api/v1/partner/recipients/{recipient_id}/destinations HTTP/1.1
Host: api-staging.unigox.com
X-API-Key: YOUR_API_KEY
Accept: */*

{
  "success": true,
  "data": {
    "recipient_destinations": [
      {
        "id": "123e4567-e89b-12d3-a456-426614174000",
        "recipient_id": "123e4567-e89b-12d3-a456-426614174000",
        "payment_method_id": 1,
        "payment_network_id": 1,
        "country_code": "text",
        "currency": "text",
        "details": {
          "ANY_ADDITIONAL_PROPERTY": "anything"
        },
        "version": 1,
        "lifecycle": "active",
        "created_at": "2026-08-09T00:38:31.327Z"
      }
    ]
  }
}

Add a recipient destination

post

https://api-staging.unigox.comhttps://api.unigox.com

/api/v1/partner/recipients/{recipient_id}/destinations

Adds a payout route for this recipient. rail and institution_id are resolved to the platform payment-network and payment-method IDs. details is validated against the selected rail configuration. Relationship and purpose are supplied later on the quote.

Authorizations

ApiKeyAuth

X-API-KeystringRequired

Partner API key for authentication. Required for all partner account endpoints.

Path parameters

recipient_idstring · uuidRequired

Body

application/json

country_codestring · min: 2 · max: 2RequiredExample: CN

currencystring · min: 3 · max: 3RequiredExample: CNY

railstringRequiredExample: cnaps

institution_idstringRequired

Institution identifier returned by the supported-institutions endpoint.

Responses

200

Destination created

application/json

successbooleanRequired

Indicates if the request was successful

Example: true

400

The destination was rejected. error.message is the validator's own diagnostic and names the offending field — e.g. unknown field 'company_name' is not allowed for this payment network when details.beneficiary_type was omitted for a company, or field 'mobile_number' does not match required pattern.

404

Recipient not found for this partner

503

Recipient directory unreachable. The request was not wrong; retry with backoff.

post/api/v1/partner/recipients/{recipient_id}/destinations

HTTPcURLJavaScriptPython

POST /api/v1/partner/recipients/{recipient_id}/destinations HTTP/1.1
Host: api-staging.unigox.com
X-API-Key: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 126

{
  "country_code": "CN",
  "currency": "CNY",
  "rail": "cnaps",
  "institution_id": "text",
  "details": {
    "ANY_ADDITIONAL_PROPERTY": "anything"
  }
}

{
  "success": true,
  "data": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "recipient_id": "123e4567-e89b-12d3-a456-426614174000",
    "payment_method_id": 1,
    "payment_network_id": 1,
    "country_code": "text",
    "currency": "text",
    "details": {
      "ANY_ADDITIONAL_PROPERTY": "anything"
    },
    "version": 1,
    "lifecycle": "active",
    "created_at": "2026-08-09T00:38:31.327Z"
  }
}