> For the complete documentation index, see [llms.txt](https://docs.tylt.money/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.tylt.money/tylt-crossramp-fiat-crypto-solutions/user-kyc-verification-apis/create-or-update-user.md).

# Create or Update User

Creates a new user or updates the basic information of an existing user. The merchant must provide a stable `externalUserId` for each user. Tylt uses this value as the merchant-specific identifier for locating and updating the user.

### Endpoint

```http
POST https://api.tylt.money/common/initiateUser
```

### Request Headers

```http
Content-Type: application/json
x-tlp-apikey: <merchant-api-key>
x-tlp-signature: <hmac-signature>
```

### Request Body

```json
{
  "emailId": "joe@example.com",
  "externalUserId": "merchant-user-10021",
  "firstName": "Joe",
  "lastName": "Doe",
  "dob": "2001-04-25",
  "countryOfResidence": "BRA",
  "countryOfCitizenship": "BRA", //optional (recommended)
  "countryOfBirth": "BRA", //optional (recommended)
  "taxId": "3100299900", //optional (recommended)
  "phone": "+14165550123" //optional (recommended)
}
```

### Request Parameters

| Field                  | Type   | Required | Description                                                                                                                                           |
| ---------------------- | ------ | -------: | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
| `emailId`              | String |      Yes | User’s valid email address                                                                                                                            |
| `externalUserId`       | String |      Yes | Unique identifier assigned to the user by the merchant                                                                                                |
| `firstName`            | String |      Yes | User’s legal first name                                                                                                                               |
| `lastName`             | String |      Yes | User’s legal last name                                                                                                                                |
| `dob`                  | String |      Yes | User’s date of birth in `YYYY-MM-DD` format                                                                                                           |
| `countryOfResidence`   | String |      Yes | User’s current country of residence, provided as an ISO 3166-1 alpha-3 country code                                                                   |
| `countryOfCitizenship` | String |       No | User’s country of citizenship, provided as an ISO 3166-1 alpha-3 country code. Although optional, this field is recommended for KYC and AML screening |
| `countryOfBirth`       | String |       No | User’s country of birth, provided as an ISO 3166-1 alpha-3 country code. Although optional, this field is recommended for KYC and AML screening       |
| `taxId`                | String |       No | User’s tax identification number. The format varies by country, for example a CPF for users in Brazil                                                 |
| `phone`                | String |       No | User’s telephone number in international format, including the country calling code                                                                   |

### Country Codes

The following fields must use ISO 3166-1 alpha-3 country codes:

* `countryOfResidence`
* `countryOfCitizenship`
* `countryOfBirth`

Examples:

| Country        | Code  |
| -------------- | ----- |
| Brazil         | `BRA` |
| Canada         | `CAN` |
| Portugal       | `PRT` |
| United States  | `USA` |
| United Kingdom | `GBR` |

### Insert or Update Behaviour

The endpoint operates as an insert-or-update operation.

* If the user does not exist, Tylt creates a new user.
* If the user already exists, Tylt updates the submitted basic profile information.
* The merchant should continue using the same `externalUserId` for subsequent requests relating to the user.
* An `externalUserId` must not be reassigned to a different user.
* Fields omitted from an update request may remain unchanged, depending on the deployed API behaviour.
* The merchant should submit the user’s current and accurate information whenever an update is required.

### Recommended Identification Fields

For effective KYC and AML screening, merchants are strongly encouraged to provide:

* Full legal name
* Date of birth
* Country of residence
* Country of citizenship
* Country of birth
* Tax identification number
* Telephone number

Although `countryOfCitizenship` and `countryOfBirth` are optional, providing them may improve identity matching and reduce false-positive AML screening results.

### JavaScript Example

```javascript
const axios = require("axios");
const crypto = require("crypto");

const baseUrl = "https://dev-api.tylt.money";
const merchantApiKey = process.env.TYLT_API_KEY;
const merchantApiSecret = process.env.TYLT_API_SECRET;

const requestBody = {
  emailId: "joe@example.com",
  externalUserId: "merchant-user-10021",
  firstName: "Joe",
  lastName: "Doe",
  dob: "2001-04-25",
  countryOfResidence: "BRA",
  countryOfCitizenship: "BRA",
  countryOfBirth: "BRA",
  taxId: "3100299900",
  phone: "+14165550123"
};

const rawPayload = JSON.stringify(requestBody);

const signature = crypto
  .createHmac("sha256", merchantApiSecret)
  .update(rawPayload)
  .digest("hex");

const response = await axios.post(
  `${baseUrl}/common/initiateUser`,
  rawPayload,
  {
    headers: {
      "Content-Type": "application/json",
      "x-tlp-apikey": merchantApiKey,
      "x-tlp-signature": signature
    }
  }
);

console.log(response.data);
```

### Validation Requirements

The merchant should ensure that:

* `emailId` contains a valid email address.
* `externalUserId` is unique within the merchant’s system.
* `dob` uses the `YYYY-MM-DD` format.
* Country fields contain valid ISO 3166-1 alpha-3 codes.
* `taxId` is submitted as a string so that leading zeros are preserved.
* `phone` includes the international country calling code.
* Names are submitted using the user’s legal identity-document spelling.

### Example Response

```json
{
"msg": "User provisioned successfully.",
"data": {
"endUserId": 20413,
"externalUserId": "merchant-demo-test",
"kycStatus": "incomplete"
}
}
```