> ## Documentation Index
> Fetch the complete documentation index at: https://docs.thedecard.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Create a user
> How-to task page: how a partner creates a user (customer), the first business action after integration. It sets out what DCS and the partner each do, then gives the minimum request/response and the next step.
## 📄 Guide
Creating a user is the first step of a Partner-Managed integration. Whether your end users come from an exchange, a wallet or a project's own app, a single call registers them in DCS and lays the foundation for the KYC verification and card issuance that follow. As a licensed issuer with its own BIN, DCS assigns every user a globally unique user ID (`customerId`) at this step and stores their basic contact details securely.
### Mental model: the user is the anchor for everything that follows
Under Partner-Managed the partner owns the limits and makes the authorization decision, but the user as an identity is still managed centrally by DCS. Once a user is created, the `customerId` you receive runs through every action afterwards:
Store the `customerId` returned on success carefully: it is the required key that ties the later endpoints together.
### Who does what
| Step | Who | Action |
| ---- | --- | ------------------------------------------------------------------------------------------------------ |
| 1 | You | Prepare the user's mobile number and email, and generate a `customerRef` that is unique on your side |
| 2 | You | Call the create-user endpoint with that information |
| 3 | DCS | Validate completeness and format, enforce uniqueness, assign the `customerId`, store the data securely |
| 4 | You | Save the returned `customerId` and move on to KYC and card issuance |
### Prerequisites
* You hold the Enterprise `ApiKey` / `SecretKey` and build the request headers as required by the authentication rules (including the HMAC-SHA256 signature and the nonce). If that is not set up yet, start with [First steps](../../getting-started/first-steps) and [Authentication](../../integration-resources/authentication).
* You send the request with `Content-Type: application/json`.
### Endpoint
**`POST /open-api/customer/v1/create-customer`**
#### Request parameters
| Field | Type | Required | Description |
| ------------------ | ------ | ----------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `phoneCountryCode` | string | Required | Country code of the mobile number as a 2-letter ISO country code (such as `SG`, `MY`, `KR`, `TH`, `AU`, `JP`, `TW`, `VN`, `PH`). Length is fixed at 2 |
| `customerRef` | string | Required | Your idempotency key for the user; you generate it and it must be unique on your side. Maximum length 50. Submitting the same `customerRef` again resolves to the same user instead of creating a duplicate |
| `phone` | string | Either/or | Mobile number in plaintext, with the country prefix and starting with `+`, length 6-30, for example `+6591234567`. Supply either this or `phoneEncryption` |
| `phoneEncryption` | string | Either/or | Mobile number as ciphertext (AES-GCM). Supply either this or `phone`; if both are sent, **the ciphertext takes precedence** |
| `email` | string | Either/or | Email in plaintext, valid email format, maximum length 100. Supply either this or `emailEncryption` |
| `emailEncryption` | string | Either/or | Email as ciphertext (AES-GCM). Supply either this or `email`; if both are sent, **the ciphertext takes precedence** |
| `encryptionIV` | string | Conditional | IV for AES-GCM, used to decrypt `phoneEncryption` / `emailEncryption`. Required whenever you use either ciphertext field |
> **Plaintext vs ciphertext (please read)**
> The mobile number and the email are each a choice between plaintext and ciphertext:
>
> * To send them in plaintext, fill in `phone` / `email` directly.
> * To add a layer of encryption on top of the transport (recommended if you are sensitive about PII), fill in `phoneEncryption` / `emailEncryption` instead and supply `encryptionIV` along with them. The algorithm is **AES-GCM**.
> * If you send both the plaintext and the ciphertext of the same field, the system **uses the ciphertext**.
> **Field note**
> `phoneCountryCode` (the country code) and `phone` (which starts with `+` and carries the country prefix) both convey the country. Both are currently required: `phoneCountryCode` acts as the 2-letter ISO region for libphonenumber and `phone` is the full E.164 number, and the two must refer to the same country.
#### Minimum request example (plaintext)
```json theme={null}
{
"phoneCountryCode": "SG",
"phone": "+6591234567",
"email": "user@example.com",
"customerRef": "ext-user-0001"
}
```
#### Minimum request example (ciphertext)
```json theme={null}
{
"phoneCountryCode": "SG",
"encryptionIV": "",
"phoneEncryption": "",
"emailEncryption": "",
"customerRef": "ext-user-0001"
}
```
#### Response example
```json theme={null}
{
"code": "SYS_SUCCESS",
"message": "success",
"messageDetail": null,
"data": {
"customerId": "C1234567890",
"status": "SUCCEED",
"createTime": "2026-06-17T10:00:00+08:00",
"modifyTime": "2026-06-17T10:00:00+08:00"
}
}
```
#### Response fields (`data`)
| Field | Type | Description |
| ------------ | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `customerId` | string | Unique user ID assigned by DCS; it is the key that links the later KYC and card issuance endpoints, so store it carefully |
| `status` | string | Creation status, for example `SUCCEED`. ⚠️ The literal spelling is `SUCCEED` (not the conventional `SUCCESS`/`SUCCEEDED`), so match on the value as returned |
| `createTime` | string | Creation time in the format `yyyy-MM-dd'T'HH:mm:ssXXX` (with the time zone offset, such as `+08:00`) |
| `modifyTime` | string | Time of the last update, same format |
#### Common response envelope
Every endpoint returns the same envelope, `{ code, message, messageDetail, data }`:
| Field | Description |
| --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `code` | Business status code; `SYS_SUCCESS` on success, otherwise see the error code page |
| `message` | Short status description |
| `messageDetail` | Structured prompt object (may carry `title` / `message` / `type` / `icon` / `action` / `linkTitle` / `linkUrl`), meant mainly for front-end guidance; usually `null` on success |
| `data` | Business payload; its shape depends on the endpoint |
**How to read success**: treat `code == "SYS_SUCCESS"` as the single source of truth for success, rather than inferring it from whether `messageDetail` is populated or from the wording of `data.status`. For error codes and troubleshooting, see [Authorization declines and error codes](../transactions/decline-codes).
## Next steps
Once the user is created and you hold the `customerId`, the next step is to [apply for KYC](../kyc/apply-kyc) for that user. After KYC passes you can [apply for a card](../cards/card-issuing).