Skip to main content

​
KYC API

The KYC (Know Your Customer) API enables identity verification for user onboarding. This API supports a streamlined verification flow with optional prefill capabilities to reduce friction for users.

​
Verification Workflow

The KYC process follows this general flow:

​
Endpoints

MethodEndpointDescription
POST/v1/kyc/prefillStart KYC prefill process
POST/v1/kyc/prefill/otpSubmit OTP for prefill verification
POST/v1/kyc/startStart KYC verification
GET/v1/kyc/statusGet current KYC status
POST/v1/kyc/webhookRegister webhook URL for status notifications
POST/v1/kyc/referral-codesCreate partner referral code
GET/v1/kyc/referral-codesList referral codes
GET/v1/kyc/referral-codes/{code}Validate a referral code

​
Quick Start

Prefill allows users to auto-populate their information using their phone number, reducing manual data entry.
  1. Start Prefill
curl -X POST "https://api.polymarketexchange.com/rest/api/v1/kyc/prefill" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "phoneNumber": "+15551234567",
    "dateOfBirth": "1990-01-15",
    "userId": "user_123",
    "sessionToken": "session_abc"
  }'
  1. Submit OTP (sent to user’s phone)
curl -X POST "https://api.polymarketexchange.com/rest/api/v1/kyc/prefill/otp" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "otp": "123456",
    "externalId": "ext_id_from_prefill_response"
  }'
  1. Start Verification (with prefilled data)
curl -X POST "https://api.polymarketexchange.com/rest/api/v1/kyc/start" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "userId": "user_123",
    "firstName": "John",
    "lastName": "Doe",
    "email": "john@example.com",
    "phoneNumber": "+15551234567",
    "dateOfBirth": "1990-01-15",
    "ssn": "***-**-1234",
    "address": {
      "addressLine1": "123 Main St",
      "city": "New York",
      "state": "NY",
      "postalCode": "10001",
      "country": "US"
    },
    "sessionToken": "session_abc",
    "agreementTime": "2024-01-15T10:30:00Z"
  }'

​
Option 2: Direct Verification

Skip prefill and go directly to verification: 
curl -X POST "https://api.polymarketexchange.com/rest/api/v1/kyc/start" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "userId": "user_123",
    "firstName": "John",
    "lastName": "Doe",
    ...
  }'

​
Check Status

Use the user_id you provided in the start request: 
curl -X GET "https://api.polymarketexchange.com/rest/api/v1/kyc/status?externalId=user_123" \
  -H "Authorization: Bearer YOUR_TOKEN"

​
KYC Status

The status response contains:
FieldDescription
decisionFinal decision: ACCEPT, REJECT, REVIEW, or empty (not started)
statusCurrent status: NOT_STARTED, OPEN, ON_HOLD, CLOSED
subStatusDetailed sub-status (e.g., Document Request Initiated)
externalIdThe user_id you provided
participantIdEP3 participant ID (populated after approval)
accountEP3 account ID (populated after approval)

​
Document Verification (DocV)

If additional document verification is required, the StartKYCVerification response will include DocV details:
FieldDescription
docvTransactionTokenToken for document verification
eventIdEvent identifier
qrCodeQR code for mobile document capture
urlURL for web-based document capture

​
Next Steps