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

POST /common/initiateUser

Request Headers

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

Request Body

{
  "emailId": "[e-mail]",
  "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": "[phone]" //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

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: "[e-mail]",
  externalUserId: "merchant-user-10021",
  firstName: "Joe",
  lastName: "Doe",
  dob: "2001-04-25",
  countryOfResidence: "BRA",
  countryOfCitizenship: "BRA",
  countryOfBirth: "BRA",
  taxId: "3100299900",
  phone: "[phone]"
};

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

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