User Management

Endpoints to create and manage user accounts

Verify API key authentication

get

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

/api/v1/partner/verify-auth

Verifies that the provided API key is valid and authentication is working correctly.

Authorizations

ApiKeyAuth

X-API-KeystringRequired

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

Responses

200

Authentication successful

application/json

successbooleanRequired

Indicates if the request was successful

Example: true

401

Unauthorized - invalid or missing API key

application/json

get

/api/v1/partner/verify-auth

HTTPcURLJavaScriptPython

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

{
  "success": true,
  "data": {
    "message": "Authentication successful",
    "authenticated": true
  }
}

Create or get partner user

post

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

/api/v1/partner/users

Creates a new user relation or returns existing if already created. Returns user_ref (same as input) for subsequent API calls. Partners can only access their own users.

Authorizations

ApiKeyAuth

X-API-KeystringRequired

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

Body

application/json

user_refstringRequired

Partner's unique user ID (usually primary key or UUID)

Example: partner_unique_id_123

emailstring · emailRequired

User's email address

Example: [email protected]

Responses

200

User already exists

application/json

successbooleanRequired

Indicates if the request was successful

Example: true

201

Successfully created user

application/json

400

Bad Request

401

Unauthorized (missing or invalid X-API-Key)

500

Internal Server Error

post

/api/v1/partner/users

HTTPcURLJavaScriptPython

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

{
  "user_ref": "partner_unique_id_123",
  "email": "[email protected]"
}

{
  "success": true,
  "data": {
    "user_uuid": "550e8400-e29b-41d4-a716-446655440000",
    "email": "[email protected]",
    "kyc_status": "NOT_INITIATED",
    "created_at": "2026-01-06T14:30:00Z"
  }
}

Partner user by ID

get

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

/api/v1/partner/users/{user_uuid}

Get user details including KYC status and payment profiles using the user_uuid returned during user creation. Partners can only access their own users.

Authorizations

ApiKeyAuth

X-API-KeystringRequired

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

Path parameters

user_uuidstring · uuidRequired

The user_uuid returned by POST /partner/users. Partners can only access their own users.

Example: 550e8400-e29b-41d4-a716-446655440000

Responses

200

User found

application/json

successbooleanRequired

Indicates if the request was successful

Example: true

401

Unauthorized

404

User not found

get

/api/v1/partner/users/{user_uuid}

HTTPcURLJavaScriptPython

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

{
  "success": true,
  "data": {
    "user_uuid": "550e8400-e29b-41d4-a716-446655440000",
    "email": "[email protected]",
    "created_at": "2026-01-06T14:30:00Z",
    "kyc": {
      "status": "IN_PROGRESS",
      "kyc_method": "direct_data",
      "first_name": "John",
      "last_name": "Doe",
      "country_code": "NG",
      "rejection_reason": "Verification declined by AiPrise",
      "updated_at": "2026-01-06T14:30:00Z"
    },
    "payment_profiles": [
      {
        "id": "987",
        "rail": "nip-nigeria",
        "currency": "NGN",
        "institution_name": "Guaranty Trust Bank",
        "institution_id": "guaranty-trust-bank",
        "details": {
          "account_number": "0123456789"
        }
      }
    ]
  }
}

Submit KYC data for a partner user

post

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

/api/v1/partner/users/{user_uuid}/kyc-submissions

Submit KYC (Know Your Customer) data for a partner user. Supports three methods:

• direct_data: Partner submits PII data directly, user is verified

• external_token: Partner provides external KYC provider credentials (SumSub token or Persona inquiry_id)

• handoff: Unigox handles KYC verification and generates verification URL

Important for EUR/AUD/GBP off-ramp: EUR, AUD, and GBP payouts require the user's physical address. Include address, city, and postal_code in the PII data when submitting KYC. If not provided at submission time, you can add them later with PATCH /partner/users/{user_uuid}/kyc. Without address, EUR/AUD/GBP orders will be created with status pending_address until the address is provided.

Authorizations

ApiKeyAuth

X-API-KeystringRequired

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

Path parameters

user_uuidstring · uuidRequired

The user_uuid returned by POST /partner/users. Partners can only access their own users.

Example: 550e8400-e29b-41d4-a716-446655440000

Body

application/json

or

or

Responses

200

KYC submitted successfully

application/json

successbooleanRequired

Indicates if the request was successful

Example: true

400

Bad Request - invalid method or missing required data

401

Unauthorized

404

User not found

500

Internal Server Error

post

/api/v1/partner/users/{user_uuid}/kyc-submissions

HTTPcURLJavaScriptPython

POST /api/v1/partner/users/{user_uuid}/kyc-submissions HTTP/1.1
Host: api-staging.unigox.com
X-API-Key: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 176

{
  "method": "direct_data",
  "data": {
    "pii": {
      "first_name": "John",
      "last_name": "Doe",
      "dob": "1990-01-01",
      "country_code": "NG",
      "address": "123 Street Name, Lagos",
      "postal_code": "100001"
    }
  }
}

Direct data submissionExternal token (SumSub)External token (Persona)Handoff to Unigox

{
  "success": true,
  "data": {
    "kyc_status": "IN_PROGRESS",
    "message": "PII data accepted",
    "verification_url": "https://verify.aiprise.com/?verification_session_id=4fd410c9-ba9b-46cf-a4f0-132204a9a564"
  }
}

Upload KYC document for a partner user

post

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

/api/v1/partner/users/{user_uuid}/kyc/documents

Upload a KYC document for a partner user. Choose one of two upload methods:

---

Method 1: File Upload

Send the document as a file attachment.

POST /api/v1/partner/users/{user_uuid}/kyc/documents
Content-Type: multipart/form-data

document: <file>
document_type: identity_front

Method 2: Single URL Upload

Send a URL pointing to one document image.

{
  "upload_method": "url_link",
  "document_type": "identity_front",
  "url": "https://example.com/id-front.jpg"
}

Method 3: Batch URL Upload

Upload multiple documents in one call (up to 10).

{
  "upload_method": "url_link",
  "documents": [
    { "document_type": "identity_front", "url": "https://example.com/id-front.jpg" },
    { "document_type": "selfie", "url": "https://example.com/selfie.jpg" }
  ]
}

URL requirements: HTTPS only, 10MB per file, JPEG/PNG/GIF/PDF.

---

Supported document types: identity_front (required), selfie (required), identity_back, passport, national_id, driver_license, and more.

Automatic Verification: After uploading all required documents (selfie + identity_front), verification starts automatically.

Authorizations

ApiKeyAuth

X-API-KeystringRequired

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

Path parameters

user_uuidstring · uuidRequired

Public UUID of the user

Example: 550e8400-e29b-41d4-a716-446655440000

Body

application/json

or

or

Responses

200

Document uploaded successfully

application/json

successbooleanOptionalExample: true

400

Bad Request - invalid file type, missing document, or user not ready for uploads

401

Unauthorized

404

User not found or no active KYC session

500

Internal Server Error

post

/api/v1/partner/users/{user_uuid}/kyc/documents

HTTPcURLJavaScriptPython

POST /api/v1/partner/users/{user_uuid}/kyc/documents HTTP/1.1
Host: api-staging.unigox.com
X-API-Key: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 102

{
  "upload_method": "url_link",
  "document_type": "identity_front",
  "url": "https://example.com/id-front.jpg"
}

Single document via URLBatch upload (multiple documents)

{
  "success": true,
  "data": {
    "document_id": "f1d5f922-bee2-4c7e-88ef-18022958c4c2",
    "document_type": "identity_front",
    "file_name": "passport_photo.jpg",
    "message": "Document uploaded successfully",
    "verification_session_id": "4fd410c9-ba9b-46cf-a4f0-132204a9a564",
    "verification_status": "IN_PROGRESS"
  }
}

Update KYC data for a partner user

patch

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

/api/v1/partner/users/{user_uuid}/kyc

Update optional PII fields on existing KYC data. The user stays verified. Only optional fields can be updated. Required fields (first_name, last_name, country_code) cannot be changed.

For EUR/AUD/GBP offramp, provide address, city, and postal_code here. These will auto-populate into payment details for EUR/AUD/GBP payouts.

Authorizations

ApiKeyAuth

X-API-KeystringRequired

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

Path parameters

user_uuidstring · uuidRequired

The user_uuid returned by POST /partner/users.

Example: 550e8400-e29b-41d4-a716-446655440000

Body

application/json

addressstringOptional

Street address

Example: Svitrigailos g 29

citystringOptional

City

Example: Vilnius

postal_codestringOptionalExample: 03229

dobstring · dateOptionalExample: 1990-01-01

phone_numberstringOptional

E.164 format

Example: [phone]

middle_namestringOptional

id_numberstringOptional

id_typestring · enumOptionalPossible values:

Responses

200

KYC data updated successfully

application/json

successbooleanOptionalExample: true

400

Bad request (no valid fields, or trying to change required fields)

401

Unauthorized

404

User not found

patch

/api/v1/partner/users/{user_uuid}/kyc

HTTPcURLJavaScriptPython

PATCH /api/v1/partner/users/{user_uuid}/kyc HTTP/1.1
Host: api-staging.unigox.com
X-API-Key: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 183

{
  "address": "Svitrigailos g 29",
  "city": "Vilnius",
  "postal_code": "03229",
  "dob": "1990-01-01",
  "phone_number": "[phone]",
  "middle_name": "text",
  "id_number": "text",
  "id_type": "NATIONAL_ID"
}

{
  "success": true,
  "data": {
    "updated_fields": [
      "address",
      "city",
      "postal_code"
    ],
    "message": "KYC data updated successfully"
  }
}

Verification status for a partner user

get

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

/api/v1/partner/users/{user_uuid}/verification-status

Get the current verification status for a partner user. This endpoint checks the verification status with the KYC provider (e.g., AiPrise) and returns the current status, verification URL (if available), and other relevant information. Optionally, you can provide a verification_id to check a specific verification session.

Interpretation of terminal states:

• VERIFIED — verification passed and the user is approved

• VERIFICATION_REJECTED — verification completed with a rejection outcome

• FAILED — verification could not be completed due to an error

• COMPLETED — provider workflow finished processing, but partners should still treat VERIFIED as the success state and VERIFICATION_REJECTED / FAILED as terminal non-success states

Authorizations

ApiKeyAuth

X-API-KeystringRequired

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

Path parameters

user_uuidstring · uuidRequired

The user_uuid returned by POST /partner/users. Partners can only access their own users.

Example: 550e8400-e29b-41d4-a716-446655440000

Query parameters

verification_idstringOptional

Optional verification session ID. If not provided, the latest verification session for the user will be checked.

Example: a1b2c3d4-e5f6-7890-abcd-ef1234567890

Responses

200

Successfully retrieved verification status

application/json

successbooleanRequired

Indicates if the request was successful

Example: true

401

Unauthorized

404

User not found

500

Internal Server Error

get

/api/v1/partner/users/{user_uuid}/verification-status

HTTPcURLJavaScriptPython

GET /api/v1/partner/users/{user_uuid}/verification-status HTTP/1.1
Host: api-staging.unigox.com
X-API-Key: YOUR_API_KEY
Accept: */*

{
  "success": true,
  "data": {
    "status": "IN_PROGRESS",
    "verification_url": "https://verify-sandbox.aiprise.com/?verification_session_id=abc123",
    "verification_seconds_left": 3600
  }
}

Payment details for a partner user

get

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

/api/v1/partner/users/{user_uuid}/payment-details

Retrieve all payment details (payment profiles) for a partner user. Returns all saved beneficiary details that can be used for offramp operations. Partners can only access their own users.

Authorizations

ApiKeyAuth

X-API-KeystringRequired

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

Path parameters

user_uuidstring · uuidRequired

The user_uuid returned by POST /partner/users. Partners can only access their own users.

Example: 550e8400-e29b-41d4-a716-446655440000

Responses

200

Successfully retrieved payment details

application/json

successbooleanRequired

Indicates if the request was successful

Example: true

401

Unauthorized

404

User not found

500

Internal Server Error

get

/api/v1/partner/users/{user_uuid}/payment-details

HTTPcURLJavaScriptPython

GET /api/v1/partner/users/{user_uuid}/payment-details HTTP/1.1
Host: api-staging.unigox.com
X-API-Key: YOUR_API_KEY
Accept: */*

{
  "success": true,
  "data": [
    {
      "payment_details_id": "987",
      "rail": "nip-nigeria",
      "currency": "NGN",
      "institution_name": "Guaranty Trust Bank",
      "institution_id": "guaranty-trust-bank",
      "details": {
        "account_number": "0123456789"
      }
    }
  ]
}

Create payment details for a partner user

post

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

/api/v1/partner/users/{user_uuid}/payment-details

Create payment details (beneficiary details) for a partner user. Used for offramp operations where crypto is converted to fiat and sent to the user's payment account. Partners can only access their own users.

Institution handling:

• for most rails, institution_id must be provided from /api/v1/supported/institutions

• partners may omit institution_id only for the explicitly supported rails below; the backend will assign the generic other-bank payment method automatically

Currently supported omission rails:

• iban-sepa

• nip-nigeria

Authorizations

ApiKeyAuth

X-API-KeystringRequired

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

Path parameters

user_uuidstring · uuidRequired

The user_uuid returned by POST /partner/users. Partners can only access their own users.

Example: 550e8400-e29b-41d4-a716-446655440000

Body

application/json

Conditional request schema for partner payment details. institution_id may be omitted only for iban-sepa and nip-nigeria.

or

Responses

201

Payment details created successfully

application/json

400

Bad Request - invalid payment details or unsupported combination

application/json

401

Unauthorized

404

User not found

500

Internal Server Error

post

/api/v1/partner/users/{user_uuid}/payment-details

HTTPcURLJavaScriptPython

POST /api/v1/partner/users/{user_uuid}/payment-details HTTP/1.1
Host: api-staging.unigox.com
X-API-Key: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 124

{
  "currency": "EUR",
  "rail": "iban-sepa",
  "country_code": "DE",
  "details": {
    "full_name": "John Doe",
    "iban": "DE89370400440532013000"
  }
}

SEPA payment details (Europe, institution optional)CVU payment details (Argentina - Mobile Money/Wallets)CBU payment details (Argentina - Traditional/Digital Banks)

{
  "success": true,
  "data": {
    "payment_details_id": "987",
    "rail": "nip-nigeria",
    "currency": "NGN",
    "institution_name": "Guaranty Trust Bank",
    "institution_id": "guaranty-trust-bank",
    "details": {
      "account_number": "0123456789"
    }
  }
}

Delete payment details for a partner user

delete

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

/api/v1/partner/users/{user_uuid}/payment-details/{payment_details_id}

Delete a specific payment details (payment profile) for a partner user by its ID. Partners can only access their own users.

Authorizations

ApiKeyAuth

X-API-KeystringRequired

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

Path parameters

user_uuidstring · uuidRequired

The user_uuid returned by POST /partner/users. Partners can only access their own users.

Example: 550e8400-e29b-41d4-a716-446655440000

payment_details_idstringRequired

The payment_details_id returned when creating payment details.

Example: 987

Responses

200

Payment details deleted successfully

application/json

successbooleanOptionalExample: true

401

Unauthorized

404

User not found or payment details not found

409

Conflict - payment details linked to active offers

500

Internal Server Error

delete

/api/v1/partner/users/{user_uuid}/payment-details/{payment_details_id}

HTTPcURLJavaScriptPython

DELETE /api/v1/partner/users/{user_uuid}/payment-details/{payment_details_id} HTTP/1.1
Host: api-staging.unigox.com
X-API-Key: YOUR_API_KEY
Accept: */*

{
  "success": true,
  "data": {
    "message": "Payment details deleted successfully"
  }
}