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. Optionally, the Prefill Flow can auto-populate most of the form from their phone number and date of birth via an SMS one-time passcode.
  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. DocV is coming soon — until it ships, these cases go to manual review.
  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: 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.

​
REST and gRPC

Every KYC action is available over both REST and gRPC. They are the same underlying service — identical fields, semantics, outcomes, and scopes — so choose whichever transport fits your stack and mix freely: Both transports authenticate with the same firm access token — REST in the Authorization header, gRPC as authorization: Bearer <token> metadata on each RPC. These pages use REST for the worked examples; the gRPC message shapes are in Verification Flow → Using gRPC.

​
Field naming

The REST API is a JSON mapping of the same protobuf-defined service, which is why casing differs by direction — 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.
  • gRPC messages use the proto field names (snake_case) natively.
  • 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:

​
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.