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

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

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": {
    "id": "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/{id}

Get user details including KYC status and payment profiles using the id (public_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

idstring · uuidRequired

Public UUID token (public_uuid) returned during user creation as id field. Partners can only access their own users.

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

Responses

200

User found

application/json

401

Unauthorized

404

User not found

get

/api/v1/partner/users/{id}

HTTPcURLJavaScriptPython

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

{
  "success": true,
  "data": {
    "id": "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/{id}/kyc-submissions

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

• direct_data: Partner submits PII data directly, Unigox initiates verification

• external_token: Partner provides external KYC provider token (e.g., SumSub)

• handoff: Unigox handles KYC verification and generates verification URL

Authorizations

ApiKeyAuth

X-API-KeystringRequired

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

Path parameters

idstring · uuidRequired

Public UUID token (public_uuid) returned during user creation as id field. 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

400

Bad Request - invalid method or missing required data

401

Unauthorized

404

User not found

500

Internal Server Error

post

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

HTTPcURLJavaScriptPython

POST /api/v1/partner/users/{id}/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)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/{id}/kyc/documents

Upload a document (ID, passport, proof of address, etc.) for a partner user's KYC verification. Used after submitting KYC with direct_data method to provide supporting documents. Requires partner API key authentication and multipart/form-data.

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

Authorizations

ApiKeyAuth

X-API-KeystringRequired

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

Path parameters

idstring · uuidRequired

Public UUID token (public_uuid) returned during user creation as id field. Partners can only access their own users.

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

Body

multipart/form-data

documentstring · binaryRequired

Document file to upload (image or PDF)

document_typestring · enumRequired

Type of document being uploaded. Supported document types:

Required documents:

• selfie - Selfie photo for liveness verification (required)
• identity_front - Front side of identity document (required)

Optional documents:

• identity_back - Back side of identity document

Generic identity document types:

• identity_front - Front side of any identity document
• identity_back - Back side of any identity document

Passport:

• passport_front - Front page of passport
• passport - Alias for passport_front

National ID:

• national_id_front - Front side of national ID
• national_id_back - Back side of national ID
• national_id - Alias for national_id_front

Driver License:

• driver_license_front - Front side of driver license
• driver_license_back - Back side of driver license
• driver_license - Alias for driver_license_front

Voter ID:

• voter_id_front - Front side of voter ID card
• voter_id_back - Back side of voter ID card
• voter_id - Alias for voter_id_front

Resident Card:

• resident_card_front - Front side of resident card
• resident_card_back - Back side of resident card
• resident_card - Alias for resident_card_front

ID Card:

• id_card_front - Front side of ID card
• id_card_back - Back side of ID card
• id_card - Alias for id_card_front

Country-specific documents:

• ghana_card_front, ghana_card_back, ghana_card - Ghana Card
• ghana_ssnit_card_front, ghana_ssnit_card_back, ghana_ssnit_card - Ghana SSNIT Card
• kenya_alien_card_front, kenya_alien_card_back, kenya_alien_card - Kenya Alien Card
• green_book_front, green_book_back, green_book - Green Book (South Africa)
• tax_id_front, tax_id_back, tax_id - Tax ID (e.g., India PAN Card)
• colombia_ppt_front, colombia_ppt_back, colombia_ppt - Colombia PPT (Permiso por Protección Temporal)

Note: Verification starts automatically after uploading all required documents (selfie + identity_front).

Example: identity_frontPossible values:

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/{id}/kyc/documents

HTTPcURLJavaScriptPython

POST /api/v1/partner/users/{id}/kyc/documents HTTP/1.1
Host: api-staging.unigox.com
X-API-Key: YOUR_API_KEY
Content-Type: multipart/form-data
Accept: */*
Content-Length: 54

{
  "document": "binary",
  "document_type": "identity_front"
}

{
  "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"
  }
}

Verification status for a partner user

get

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

/api/v1/partner/users/{id}/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.

Authorizations

ApiKeyAuth

X-API-KeystringRequired

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

Path parameters

idstring · uuidRequired

Public UUID token (public_uuid) returned during user creation as id field. 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

401

Unauthorized

404

User not found

500

Internal Server Error

get

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

HTTPcURLJavaScriptPython

GET /api/v1/partner/users/{id}/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/{id}/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

idstring · uuidRequired

Public UUID token (public_uuid) returned during user creation as id field. Partners can only access their own users.

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

Responses

200

Successfully retrieved payment details

application/json

401

Unauthorized

404

User not found

500

Internal Server Error

get

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

HTTPcURLJavaScriptPython

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

{
  "success": true,
  "data": [
    {
      "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/{id}/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.

Authorizations

ApiKeyAuth

X-API-KeystringRequired

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

Path parameters

idstring · uuidRequired

Public UUID token (public_uuid) returned during user creation as id field. Partners can only access their own users.

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

Body

application/json

currencystringRequired

ISO 3-letter fiat currency code (e.g., INR, EUR, USD)

Example: INR

railstringRequired

Payment rail identifier (e.g., "upi-india", "iban-sepa", "imps-india")

Example: iban-sepa

institution_idstringRequired

Institution (payment method) identifier - our internal slug (e.g., "wise", "hdfc-bank", "revolut", "uala", "banco-santander-argentina"). Required for all rails. For rails with multiple formats (e.g., CVU/CBU), the format is automatically determined based on the payment method type of this institution.

Example: wise

country_codestringOptional

Optional ISO 2-letter country code

Example: DE

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/{id}/payment-details

HTTPcURLJavaScriptPython

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

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

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

{
  "success": true,
  "data": {
    "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/{id}/payment-details

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

idstring · uuidRequired

Public UUID token (public_uuid) returned during user creation as id field. Partners can only access their own users.

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

payment_details_idstringRequired

Payment details ID to delete

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/{id}/payment-details

HTTPcURLJavaScriptPython

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

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