KYC Module Endpoint

POI, POA, AML, and liveness operations use the following endpoint:

POST /common/initiateKyc

The requested operation is selected through the module field.

Common Request Structure

{
  "emailId": "[e-mail]",
  "module": "<MODULE>",
  "payload": {}
}

Common Parameters

Field	Type	Required	Description
emailId	String	Yes	Email address of the user being verified
module	String	Yes	Verification operation to perform
payload	Object	Conditional	Module-specific information

Supported Modules

Module	Purpose
POI	Submit proof-of-identity documents
POA	Submit a proof-of-address document
AML	Run AML screening
Liveness	Generate a liveness-verification link

1. Update Proof of Identity

Submits the front and, where applicable, back images of the user’s identity document.

Endpoint

POST /common/initiateKyc

Module

POI

Request Body

{
  "emailId": "[e-mail]",
  "module": "POI",
  "payload": {
    "poiImageFrontUrl": "https://merchant.example.com/documents/id-front.jpg",
    "poiImageBackUrl": "https://merchant.example.com/documents/id-back.jpg"
  }
}

Request Parameters

Field	Type	Required	Description
emailId	String	Yes	Email address of the user
module	String	Yes	Must be POI
payload	Object	Yes	Proof-of-identity document information
payload.poiImageFrontUrl	String	Yes	Secure URL of the front of the identity document
payload.poiImageBackUrl	String	Conditional	Secure URL of the back of the identity document

The back image may not be required for single-sided documents such as passports. This should be confirmed against the configured document-verification workflow.

JavaScript Example

const requestBody = {
  emailId: "[e-mail]",
  module: "POI",
  payload: {
    poiImageFrontUrl:
      "https://merchant.example.com/documents/id-front.jpg",
    poiImageBackUrl:
      "https://merchant.example.com/documents/id-back.jpg"
  }
};

Document URL Requirements

The document URLs should:

• Use HTTPS

• Be accessible by Tylt’s verification service

• Point directly to the document image

• Remain valid long enough for processing

• Not require an interactive login

• Not expose unrelated user documents

• Use short-lived or restricted access URLs where supported

The merchant must not use public image-hosting services for production identity documents.

Response

{
"msg": "Didit POI initiation started.",
"data": {
"userId": 20413,
"module": "POI",
"status": "approved",
"sessionUrl": null,
"requestId": "512f270b-e604-40ce-84df-db3063a5c72a",
"overallKycStatus": "incomplete"
}
}

---

2. Update Proof of Address

Submits the user’s proof-of-address document.

Endpoint

POST /common/initiateKyc

Module

POA

Request Body

{
  "emailId": "[e-mail]",
  "module": "POA",
  "payload": {
    "poaDocumentUrl": "https://merchant.example.com/documents/address-document.jpg"
  }
}

Request Parameters

Field	Type	Required	Description
emailId	String	Yes	Email address of the user
module	String	Yes	Must be POA
payload	Object	Yes	Proof-of-address document information
payload.poaDocumentUrl	String	Yes	Secure URL of the proof-of-address document

Common Proof-of-Address Documents

Subject to the configured verification policy, acceptable documents may include:

• Bank statement

• Utility bill

• Government-issued residence document

• Tax document

• Credit-card statement

• Official correspondence showing the user’s residential address

The supported document types and document-age requirements are determined by the applicable KYC policy.

JavaScript Example

const requestBody = {
  emailId: "[e-mail]",
  module: "POA",
  payload: {
    poaDocumentUrl:
      "https://merchant.example.com/documents/address-document.jpg"
  }
};

Response

{
"msg": "Didit POA initiation started.",
"data": {
"userId": 20413,
"module": "POA",
"status": "approved",
"sessionUrl": null,
"requestId": "25eb2bf7-3bba-49e3-afa7-bab12d9c5531",
"overallKycStatus": "incomplete"
}
}

---

3. Run AML Check

Runs an AML screening check for the identified user.

Endpoint

POST /common/initiateKyc

Module

AML

Request Body

{
  "emailId": "[e-mail]",
  "module": "AML"
}

The AML module does not require a payload object in the current request structure.

Request Parameters

Field	Type	Required	Description
emailId	String	Yes	Email address of the user to screen
module	String	Yes	Must be AML

Prerequisites

Before initiating AML screening, the merchant should ensure that the user’s profile contains the identifying information required for screening, including:

• Legal first name

• Legal last name

• Date of birth

• Country information

The AML check uses the information already associated with the user’s account.

JavaScript Example

const requestBody = {
  emailId: "[e-mail]",
  module: "AML"
};

Response

The endpoint returns the result or status of the AML screening operation.

{
"msg": "Didit AML initiation started.",
"data": {
"userId": 20413,
"module": "AML",
"status”: "approved",
"sessionUrl": null,
"requestId”: "961e0dc6-d035-4a95-aed0-7027b8bcb968",
"overallKycStatus": "incomplete"
}
}

Depending on the configured screening process, the result may be returned immediately or may remain pending for further review.

The exact AML response fields and possible status values should be confirmed against the deployed API.

Possible AML Outcomes

The response may represent outcomes such as:

Status	Description
approved	No disqualifying match was identified
pending	Screening is still being processed
requires_review	A possible match requires manual review
rejected	The user cannot proceed based on the screening result
failed	The screening request could not be completed

These values are illustrative and must be aligned with the actual API response.

---

4. Initiate Liveness Verification

Initiates a liveness-verification session and returns a link that the user can open to complete the verification.

Endpoint

POST /common/initiateKyc

Request Body

{
  "emailId": "[e-mail]",
  "module": "Liveness"
}

The exact value of the liveness module field must be confirmed before publication.

Expected Response

The endpoint is expected to return a user-specific liveness-verification link.

{
"msg": “Didit LIVENESS initiation started.”,
"data": {
"userId": 20413,
"module": "LIVENESS",
"status": "pending",
"sessionUrl": "https://verify.didit.me/session/uWw0MsTHVPiQ",
"requestId": "f93653d4-510f-490b-8c2e-2631ca60c1ca",
"overallKycStatus": "incomplete"
}
}

Merchant Integration Flow

1. The merchant calls the liveness module from its backend.

2. Tylt creates a liveness-verification session.

3. Tylt returns a user-specific verification link.

4. The merchant redirects the user to the link or displays it in the merchant interface.

5. The user completes the liveness check.

6. The merchant retrieves the resulting KYC status through the applicable status API.

Security Requirements

The merchant should:

• Only provide the link to the relevant user

• Treat the link as sensitive and user-specific

• Avoid logging the complete link

• Avoid sending the link to analytics platforms

• Respect the link’s expiry period

• Request a new link where the existing session has expired

• Prevent one user from accessing another user’s session

---

Java Script Example

The following helper can be used for all supported operations.

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;

async function sendSignedRequest(endpoint, requestBody) {
  if (!merchantApiKey || !merchantApiSecret) {
    throw new Error("Missing TYLT API credentials.");
  }

  const rawPayload = JSON.stringify(requestBody);

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

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

    return response.data;
  } catch (error) {
    const status = error.response?.status;
    const responseData = error.response?.data;

    throw new Error(
      `Tylt API request failed${
        status ? ` with status ${status}` : ""
      }: ${responseData?.msg || error.message}`
    );
  }
}

Create or Update User

const result = await sendSignedRequest(
  "/common/initiateUser",
  {
    emailId: "[e-mail]",
    externalUserId: "merchant-user-10021",
    firstName: "Joe",
    lastName: "Doe",
    phone: "[phone]",
    dob: "1990-01-15",
    countryCode: "CAN"
  }
);

Submit POI

const result = await sendSignedRequest(
  "/common/initiateKyc",
  {
    emailId: "[e-mail]",
    module: "POI",
    payload: {
      poiImageFrontUrl:
        "https://merchant.example.com/documents/id-front.jpg",
      poiImageBackUrl:
        "https://merchant.example.com/documents/id-back.jpg"
    }
  }
);

Submit POA

const result = await sendSignedRequest(
  "/common/initiateKyc",
  {
    emailId: "[e-mail]",
    module: "POA",
    payload: {
      poaDocumentUrl:
        "https://merchant.example.com/documents/address-document.jpg"
    }
  }
);

Run AML Screening

const result = await sendSignedRequest(
  "/common/initiateKyc",
  {
    emailId: "[e-mail]",
    module: "AML"
  }
);

---

Recommended Verification Sequence

A typical verification flow should follow this order:

1. Create or update the user through /common/initiateUser.

2. Submit the user’s proof of identity using the POI module.

3. Submit proof of address using the POA module where required.

4. Run AML screening using the AML module.

5. Request a liveness-verification link.

6. Ask the user to complete the liveness session.

7. Retrieve the user’s final KYC status.

8. Enable regulated wallet or transaction functionality only after the required checks have been approved.

---

Error Handling

A failed request may return:

{
  "msg": "Description of the error",
  "data": null
}

Merchants should handle at least the following categories:

HTTP Status	Description
400	Missing, malformed, or unsupported request parameters
401	Missing or invalid API authentication
403	Merchant, user, or operation is not authorized
404	User or requested resource was not found
409	Conflicting user or verification data
422	Submitted verification data could not be processed
429	Too many requests
500	Unexpected processing error
503	Verification service temporarily unavailable