Clients

Clients are the core object of the Partner API — every trade, deposit, withdrawal, and balance lookup is scoped to a client. This page explains what a client is, how it moves through its lifecycle, and the rules that govern it.

What Is a Client

A client is an end user of your product, registered under your partner account on CoinMENA. You create clients on their behalf using the Partner API, and from that point forward every trading or funding action is performed for a specific client.

Key points:

• Clients created through the Partner API are auto-verified — they skip the standard user-facing KYC flow and are immediately eligible to trade and be funded.
• Only personal accounts can be created through the API. Corporate accounts are onboarded through a separate, out-of-band process — contact [email protected] for corporate onboarding.
• Each client has two identifiers: CoinMENA's internal id and your own partner_client_id. You use your partner_client_id across every client-scoped endpoint.

Client Lifecycle at a Glance

A typical client moves through these stages:

1. Create — You submit the client's personal, address, employment, and compliance details. The client is created with status: verified and active: true.
2. Upload KYC documents — Upload the KYC documents required for the client as part of onboarding. Required document types depend on your setup with CoinMENA.
3. Fund and trade — The client can now be funded via deposits and can trade.
4. Update over time — Client details can be updated. Some fields are immutable after creation (see Immutable Fields).
5. Activate or deactivate — Temporarily disable a client's ability to trade or be funded without deleting the record.

Create vs Update Behavior

The create and update endpoints behave differently. Understand both before integrating:

⚠️

Update is not a patch

There is no partial update. If you send only the fields you want to change, the other required fields will fail validation. Always re-send the full client payload on every update, minus the three immutable fields.

Required Fields Summary

These fields must be provided when creating a client. There is no shorter minimum — the API will reject a create request missing any of them.

On update, the same fields are required except partner_client_id, account_type, birth_date, and place_of_birth_id (the last three are immutable; partner_client_id is in the URL path).

Optional fields: national_number, residency_visa_number, residency_visa_doe. Residency visa fields become conditionally required — see Countries.

The Client Object

Every client endpoint returns the same client shape. Fields are grouped below for readability.

Identity

Contact

Residency & Legal

Address

All address subfields are required strings, maximum 255 characters each.

Employment

See Employment — Validation Rules for the conditional requirements.

Compliance Metadata

Timestamps

Example

{
  "id": 12345,
  "partner_client_id": "user_12345",
  "account_type": "personal",
  "status": "verified",
  "active": true,
  "name": "John Doe",
  "email": "[email protected]",
  "phone": "+97312345678",
  "residency_id": "bh",
  "citizenship_id": "bh",
  "place_of_birth_id": "bh",
  "birth_date": "1990-01-15",
  "government_id_number": "1234567890",
  "government_id_doe": "2028-01-15",
  "address": {
    "street": "123 Main St",
    "city": "Manama",
    "postal_code": "12345",
    "unit": "4A"
  },
  "employment": {
    "status": "employed",
    "company": "Acme Corp",
    "job_industry": "information_technology_telco",
    "job_level": "senior",
    "job_title": "Software Engineer"
  },
  "trading_volume": "10001_25000",
  "account_purpose": ["short_term_trading", "converting_crypto_to_fiat"],
  "created_at": "2024-06-01T10:00:00Z",
  "verified_at": "2024-06-01T10:00:00Z"
}

Account Types

The API supports two account types, but only one is creatable through the Partner API:

If you submit any value other than personal to the create endpoint, the request is rejected with a validation error.

Client Identity — Two IDs

Every client has two identifiers that serve different purposes:

📘

Always use partner_client_id in request paths

Every client-scoped endpoint — GET /v1/partner/clients/{partner_client_id}/, PUT /v1/partner/clients/{partner_client_id}/activation, GET /v1/partner/clients/{partner_client_id}/documents, etc. — takes your partner_client_id in the path, not CoinMENA's internal id. Store partner_client_id in your system as the primary client reference.

Your partner_client_id must be unique across your partner account. Reusing an existing partner_client_id on create returns error 2026 — it does not return or overwrite the existing client. See the Error Codes guide.

KYC Status Model

The status field reflects a client's KYC verification state. Partner-created clients start at verified and stay there unless CoinMENA's compliance team changes the state.

📘

Partner-created clients are verified on creation

Clients created through POST /v1/partner/clients are assigned status: verified automatically — they do not need to go through the standard user-facing KYC flow. The other statuses are included for completeness and may appear on client records managed by CoinMENA's compliance team. Partners cannot trigger status transitions through the API.

Active vs Inactive

The active flag controls whether a client can trade or be funded. It is independent of status:

• active: true — Client can calculate quotes, execute trades, deposit, and withdraw.
• active: false — Client is blocked from all trading and funding actions. Requests return error 2010 — The client is deactivated.

Toggle a client's active state using PUT /v1/partner/clients/{partner_client_id}/activation with {"active": true} or {"active": false}.

Use deactivation to temporarily suspend a client — for example, while investigating suspicious activity or pausing access pending account review. Deactivation is reversible; it does not delete the client record.

Immutable Fields

Three fields cannot be changed after a client is created:

These fields are not accepted in the PUT /v1/partner/clients/{partner_client_id}/ update payload. Submitting them will not update the record; CoinMENA's schema validation ignores immutable fields on update.

⚠️

Get these right on creation

Because these fields are immutable, double-check them before calling POST /v1/partner/clients. A wrong birth_date or place_of_birth_id cannot be corrected through the API — contact [email protected] if a correction is needed.

Employment — Validation Rules

Employment is a required object on client creation and update. The fields you must (or must not) send depend on the status value:

status itself is required for every employment submission.

Some employment subfields accept any string but should be submitted using CoinMENA's recommended enum values to align with the compliance model:

• job_industry — submit one of CoinMENA's recommended industry codes (e.g. information_technology_telco, banking_financial_services)
• job_level — submit one of CoinMENA's recommended seniority levels (e.g. senior, manager, director)

See the API Reference for the full list of recommended values.

Countries — Residency, Citizenship, Place of Birth

Every client has three country fields, and each must resolve to a valid country ID from CoinMENA's supported list.

📘

Country ID format

Country IDs are lowercase short codes returned by GET /v1/public/countries — for example bh (Bahrain), sa (Saudi Arabia), ae (United Arab Emirates). Always fetch the list from the public endpoint rather than hardcoding IDs — the supported list can change. Do not use uppercase ISO codes or 3-letter codes; they will be rejected.

If the country is not supported or unsupported for the given field, creation or update fails:

Residency Visa

When the client's residency country differs from their citizenship country, you must also submit their residency visa details:

• residency_visa_number — residency visa document number
• residency_visa_doe — residency visa expiry date (YYYY-MM-DD)

Missing visa details when required returns error 2025 — Residency visa number and expiry are required.

Trading Volume & Account Purpose

Two compliance-related fields are required on every client create and update:

trading_volume

A string representing the client's expected monthly trading volume. Although the field accepts any string, you should submit one of CoinMENA's recommended volume brackets to align with the compliance model — e.g. 1000_10000, 10001_25000, 25001_100000.

See the API Reference for the full list of recommended bracket values.

account_purpose

An array of one or more strings indicating what the client intends to use the account for. Accepted values:

At least one value must be provided. Multiple values are allowed.

Documents

KYC documents are uploaded per client and are managed through a separate set of endpoints. Documents are part of the client lifecycle — upload the document types required by your setup with CoinMENA for each client you onboard. See the Onboarding a Client guide for the end-to-end walkthrough.

Supported Document Types

Upload Rules

• Front file: required
• Back file: optional — include for two-sided documents like national IDs
• Accepted formats: JPEG, PNG, HEIC, HEIF, PDF
• Maximum size: 5 MB per file

Presigned URLs for Download

When you retrieve a document via GET /v1/partner/clients/{partner_client_id}/documents/{document_id}, the response contains presigned S3 URLs in front_file and back_file. These URLs:

• Are signed and scoped to the document
• Expire after 900 seconds (15 minutes)
• Should be fetched on-demand — do not store the URLs in your database

If a presigned URL expires, re-request the document metadata to get a fresh URL.

Filtering

List documents for a client with GET /v1/partner/clients/{partner_client_id}/documents. The type query parameter accepts multiple values, so you can narrow results to one or several document types in a single request.

Validation Errors (422)

When a create or update request fails schema validation, the API returns 422 with a msg_detail array listing every field-level failure:

{
  "code": 422,
  "msg": "Validation Error",
  "msg_detail": [
    {
      "loc": ["body", "email"],
      "msg": "Input should be a valid email",
      "type": "email_parsing"
    },
    {
      "loc": ["body", "address", "street"],
      "msg": "Field required",
      "type": "missing"
    }
  ]
}

Use the loc array to identify the exact field that failed — it reflects the nested path of the field in your request body. See the Error Codes guide for the full 422 reference.

Common Mistakes

The most frequent issues partners hit when creating or updating clients:

Where Clients Are Used

The partner_client_id is the link between a client and every downstream operation. A client is required for:

• Balances — retrieve partner_client_id-scoped asset balances
• Quotes — calculate a trade quote on behalf of a client
• Orders — execute a quote and retrieve the resulting order
• Deposits — credit fiat to a client's account
• Withdrawals — debit fiat from a client's account
• Documents — upload and retrieve KYC documents for a client

If the client is deactivated (active: false) or not yet verified, these downstream operations return 2010 or 2009 respectively.

Related Error Codes

The most common client-related errors:

See the Error Codes guide for the full reference, including HTTP status codes and affected endpoints.