Skip to main content
POST
/
api
/
v1
/
members
/
{userId}
/
kyc
/
start
Start KYC verification
curl --request POST \
  --url https://app.mlm-platform.com/api/v1/members/{userId}/kyc/start \
  --header 'x-tenant-api-key: <api-key>'
{
  "kycRecordId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "provider": "manual",
  "status": "not_started",
  "uploadUrl": "https://api.mlm-platform.com/api/v1/members/{userId}/kyc/documents",
  "requiredDocuments": [
    {
      "documentType": "government_id_front",
      "label": "Government ID (Front)",
      "description": "Front side of your government-issued ID (driver's license, national ID, or state ID)",
      "required": true,
      "acceptedFormats": [
        "image/jpeg",
        "image/png",
        "application/pdf"
      ]
    },
    {
      "documentType": "government_id_back",
      "label": "Government ID (Back)",
      "description": "Back side of your government-issued ID",
      "required": true,
      "acceptedFormats": [
        "image/jpeg",
        "image/png",
        "application/pdf"
      ]
    },
    {
      "documentType": "selfie",
      "label": "Selfie with ID",
      "description": "A clear photo of yourself holding your ID next to your face",
      "required": true,
      "acceptedFormats": [
        "image/jpeg",
        "image/png"
      ]
    },
    {
      "documentType": "proof_of_address",
      "label": "Proof of Address",
      "description": "Utility bill, bank statement, or official letter dated within the last 3 months",
      "required": false,
      "acceptedFormats": [
        "image/jpeg",
        "image/png",
        "application/pdf"
      ]
    }
  ],
  "sdkConfig": {
    "accessToken": "sbx:eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "expiresAt": "2024-01-15T12:30:00Z",
    "flowName": "basic-kyc-flow",
    "applicantId": "65a1b2c3d4e5f6g7h8i9j0"
  },
  "message": "Please upload the required documents to complete your identity verification."
}

Authorizations

​
x-tenant-api-key
string
header
required

Tenant API key for authentication. Keys are scoped to specific environments (LIVE or SANDBOX). Obtain keys from the admin dashboard.

Path Parameters

​
userId
string<uuid>
required

Response

KYC started

Response returned when starting KYC verification for a member. The response structure varies based on the configured KYC provider (manual or sumsub).

Manual KYC: Returns uploadUrl and requiredDocuments for document upload workflow. Sumsub KYC: Returns sdkConfig for initializing the Sumsub SDK widget.

​
kycRecordId
string<uuid>
required

Unique identifier for this KYC verification record. Use this ID when uploading documents or checking status.

Example:

"3c90c3cc-0d44-4b50-8888-8dd25736052a"

​
provider
enum<string>
required

The KYC provider configured for this tenant.

  • manual: Document upload with admin review
  • sumsub: Automated verification via Sumsub SDK
Available options:
manual,
sumsub
Example:

"manual"

​
status
enum<string>
required

Current status of the KYC verification process.

  • not_started: KYC record created but no documents submitted
  • pending: Documents submitted, awaiting review
  • approved: KYC verification approved
  • rejected: KYC verification rejected
  • resubmit_required: Additional documents or corrections needed
Available options:
not_started,
pending,
approved,
rejected,
resubmit_required
Example:

"not_started"

​
uploadUrl
string

Base URL for document uploads (manual KYC only). Use the /kyc/documents/upload-url endpoint to get a signed upload URL for each document.

Example:

"https://api.mlm-platform.com/api/v1/members/{userId}/kyc/documents"

​
requiredDocuments
object[]

List of documents required to complete KYC verification (manual KYC only). Each document specifies a type that must be uploaded. The member should upload one document for each item in this array.

Example:
[
  {
    "documentType": "government_id_front",
    "label": "Government ID (Front)",
    "description": "Front side of your government-issued ID (driver's license, national ID, or state ID)",
    "required": true,
    "acceptedFormats": [
      "image/jpeg",
      "image/png",
      "application/pdf"
    ]
  },
  {
    "documentType": "government_id_back",
    "label": "Government ID (Back)",
    "description": "Back side of your government-issued ID",
    "required": true,
    "acceptedFormats": [
      "image/jpeg",
      "image/png",
      "application/pdf"
    ]
  },
  {
    "documentType": "selfie",
    "label": "Selfie with ID",
    "description": "A clear photo of yourself holding your ID next to your face",
    "required": true,
    "acceptedFormats": ["image/jpeg", "image/png"]
  },
  {
    "documentType": "proof_of_address",
    "label": "Proof of Address",
    "description": "Utility bill, bank statement, or official letter dated within the last 3 months",
    "required": false,
    "acceptedFormats": [
      "image/jpeg",
      "image/png",
      "application/pdf"
    ]
  }
]
​
sdkConfig
object

Configuration object for initializing the Sumsub SDK widget (Sumsub KYC only). Pass this object to the Sumsub Web SDK or Mobile SDK to launch the verification flow.

Example:
{
  "accessToken": "sbx:eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "expiresAt": "2024-01-15T12:30:00Z",
  "flowName": "basic-kyc-flow",
  "applicantId": "65a1b2c3d4e5f6g7h8i9j0"
}
​
message
string

Human-readable message providing additional context or instructions for the KYC process.

Example:

"Please upload the required documents to complete your identity verification."