Skip to main content
BETA — SUBJECT TO CHANGE. This API is in beta and may change without notice.
Before any Retail Participant can trade, they must pass a KYC (Know Your Customer) identity check. Polymarket US uses Socure as its identity verification (IDV) provider. You collect the participant’s information and submit it; Socure performs the identity evaluation; and on approval Polymarket US provisions the participant’s trading account. You receive the result via a webhook you register in advance.
You don’t talk to Socure for evaluation — Polymarket US does. You call the KYC endpoints on your participant’s behalf, and Polymarket US handles the Socure evaluation and account provisioning. The only time a participant’s device touches Socure directly is the optional Digital Intelligence script and, when required, the document-upload (DocV) UI.

​
What a participant experiences

  1. They complete an identity form on your platform (name, address, SSN, date of birth) and accept the participant agreement.
  2. In most cases, verification is instant — approved or rejected within seconds.
  3. Sometimes Socure asks them to upload a photo ID (document verification, “DocV”) via a web URL or a mobile SDK.
  4. In a small number of cases, the application needs manual review by the Polymarket US compliance team — no action required from the participant.
  5. Once approved, their trading account is ready and you receive a webhook.

​
The four outcomes

Every POST /v1/kyc/start resolves to one of four outcomes:
OutcomeWhat it meansYour next step
Instant approvalThe identity was verified immediatelyAwait the kyc.approved webhook for the provisioned participantId (provisioning is async — see below)
Document verification (DocV)The provider needs a photo IDDirect the participant to docv.url or the Socure SDK
Manual compliance reviewAutomated checks were inconclusiveTell the participant to wait; await the webhook
RejectionVerification or risk assessment failedNotify the participant — they cannot trade
See Verification Flow for the request/response of each outcome and the decision matrix.
Approval is asynchronous even when instant. A successful POST /v1/kyc/start may return a non-terminal status with no participantId yet while provisioning completes in the background. The final participantId arrives via the webhook and a later GET /v1/kyc/status. Don’t assume it’s on the initial response.

​
Integration architecture

Polymarket US sits between your platform and Socure. You never call Socure directly for evaluation; for document verification, the participant’s browser or app connects to Socure’s hosted UI.

​
Endpoints

MethodEndpointDescription
POST/v1/kyc/startSubmit a participant for verification (primary endpoint)
GET/v1/kyc/statusPoll the current status of a participant
POST/v1/kyc/webhookRegister your webhook URL (once per firm)

​
Field naming

The KYC API mixes casing conventions, so map fields by meaning rather than assuming one style across the whole flow:
  • Request bodies and query parameters use snake_case (e.g. external_id, date_of_birth).
  • REST JSON responses use camelCase (e.g. externalId, participantId, subStatus) — they follow protobuf JSON naming.
  • Webhook payloads use snake_case (e.g. external_id, provisioned_participant).
We may align casing across the API in a future version; any change will be announced in the changelog.

​
Prerequisites

Before going live, make sure you have:
ItemProvided by
API credentials (Client ID + private key)Polymarket US onboarding team
Socure Digital Intelligence SDK keyPolymarket US onboarding team
Participant agreement version stringPolymarket US onboarding team
An HTTPS webhook URL, registered via POST /v1/kyc/webhookYou
Socure mobile SDK (only if you have a native app)Socure

​
Next steps

Digital Intelligence

Capture the session_token that keeps your approval rate high.

Verification Flow

Submit a participant and handle each of the four outcomes.

Webhooks

Receive the async decision instead of polling.