KYC flow

import requests
from polymarket_auth import PolymarketClient  # canonical client from /connect#authentication

pmx = PolymarketClient()

BASE_URL = "https://api.preprod.polymarketexchange.com"  # preprod; prod is https://api.prod.polymarketexchange.com
EXTERNAL_ID = "u-8f21c4a9"  # your own user key. Max 49 characters.
SESSION_TOKEN = "dit-..."   # Socure Digital Intelligence token from your front end

# VERIFY: exact field names for legal name, date of birth, national ID / SSN, email,
# phone and address lines are not published. Get the schema from your integration lead.
IDENTITY = {}

def store_participant_id(external_id, participant_id):
    print(f"store participantId={participant_id} against {external_id}")

def open_docv(url):
    print(f"redirect the user to {url}")

def mark_pending(external_id):
    print(f"{external_id} is not terminal — poll GET /v1/kyc/status and wait for a webhook")

r = requests.post(
    f"{BASE_URL}/v1/kyc/start",
    headers={
        "Authorization": f"Bearer {pmx.access_token()}",
        "Content-Type": "application/json",
    },
    json={
        "external_id": EXTERNAL_ID,
        "postal_code": "10013",   # five digits, no ZIP+4
        "docv_eligible": True,    # omit this and review cases take 1-2 business days
        "session_token": SESSION_TOKEN,
        **IDENTITY,
    },
    timeout=30,
)
if r.status_code != 200:
    # A duplicate SSN arrives here as HTTP 400, not the documented 409.
    raise SystemExit(f"HTTP {r.status_code}: {r.text}")

body = r.json()
print("telemetry:", body.get("decision"), body.get("status"), body.get("subStatus"))

if body.get("docv"):
    # Outcome 3: document verification. sdkKey is always empty, so send the user to the URL.
    open_docv(body["docv"]["url"])
elif body.get("decision") == "ACCEPT":
    # Outcome 1: approved. participantId can be empty for up to 26 minutes.
    pid = body.get("participantId") or ""
    if pid:
        store_participant_id(EXTERNAL_ID, pid)
    # Do not enable trading here. Wait for kyc.approved.
else:
    # Outcomes 2 and 4: rejected, or under review. Never branch on the literals.
    mark_pending(EXTERNAL_ID)

import { PolymarketClient } from "./polymarketAuth"; // canonical client from /connect#authentication

const pmx = new PolymarketClient();

const BASE_URL = "https://api.preprod.polymarketexchange.com"; // prod: https://api.prod.polymarketexchange.com
const EXTERNAL_ID = "u-8f21c4a9"; // your own user key. Max 49 characters.
const SESSION_TOKEN = "dit-..."; // Socure Digital Intelligence token from your front end

// VERIFY: exact field names for legal name, date of birth, national ID / SSN, email,
// phone and address lines are not published. Get the schema from your integration lead.
const IDENTITY: Record<string, unknown> = {};

const storeParticipantId = (externalId: string, participantId: string) =>
  console.log(`store participantId=${participantId} against ${externalId}`);
const openDocv = (url: string) => console.log(`redirect the user to ${url}`);
const markPending = (externalId: string) =>
  console.log(`${externalId} is not terminal — poll GET /v1/kyc/status and wait for a webhook`);

const res = await fetch(`${BASE_URL}/v1/kyc/start`, {
  method: "POST",
  headers: {
    authorization: `Bearer ${await pmx.accessToken()}`,
    "content-type": "application/json",
  },
  body: JSON.stringify({
    external_id: EXTERNAL_ID,
    postal_code: "10013", // five digits, no ZIP+4
    docv_eligible: true,  // omit this and review cases take 1-2 business days
    session_token: SESSION_TOKEN,
    ...IDENTITY,
  }),
});

if (res.status !== 200) {
  // A duplicate SSN arrives here as HTTP 400, not the documented 409.
  throw new Error(`HTTP ${res.status}: ${await res.text()}`);
}

const body = await res.json();
console.log("telemetry:", body.decision, body.status, body.subStatus);

if (body.docv) {
  // Outcome 3: document verification. sdkKey is always empty, so send the user to the URL.
  openDocv(body.docv.url);
} else if (body.decision === "ACCEPT") {
  // Outcome 1: approved. participantId can be empty for up to 26 minutes.
  if (body.participantId) storeParticipantId(EXTERNAL_ID, body.participantId);
  // Do not enable trading here. Wait for kyc.approved.
} else {
  // Outcomes 2 and 4: rejected, or under review. Never branch on the literals.
  markPending(EXTERNAL_ID);
}

set -euo pipefail

BASE_URL="https://api.preprod.polymarketexchange.com"   # prod: https://api.prod.polymarketexchange.com
EXTERNAL_ID="u-8f21c4a9"                                 # your own user key. Max 49 characters.
TOKEN="$(./token.sh)"                                    # canonical token script from /connect#authentication

# VERIFY: legal name, date of birth, national ID / SSN, email, phone and address field
# names are not published. Add them to this body from the schema your integration lead gives you.
cat > /tmp/kyc-start.json <<JSON
{
  "external_id": "${EXTERNAL_ID}",
  "postal_code": "10013",
  "docv_eligible": true,
  "session_token": "dit-..."
}
JSON

HTTP="$(curl -sS -o /tmp/kyc-resp.json -w '%{http_code}' \
  -X POST "${BASE_URL}/v1/kyc/start" \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "Content-Type: application/json" \
  --data @/tmp/kyc-start.json)"

# A duplicate SSN arrives as HTTP 400, not the documented 409.
[ "${HTTP}" = "200" ] || { echo "HTTP ${HTTP}"; cat /tmp/kyc-resp.json; exit 1; }

jq -r '"telemetry: \(.decision) \(.status) \(.subStatus)"' /tmp/kyc-resp.json

if jq -e '.docv' /tmp/kyc-resp.json >/dev/null; then
  echo "docv required -> $(jq -r '.docv.url' /tmp/kyc-resp.json)"
elif [ "$(jq -r '.decision' /tmp/kyc-resp.json)" = "ACCEPT" ]; then
  echo "accepted, participantId='$(jq -r '.participantId // ""' /tmp/kyc-resp.json)' — wait for kyc.approved"
else
  echo "not terminal — poll GET /v1/kyc/status and wait for a webhook"
fi

package main

import (
	"bytes"
	"encoding/json"
	"fmt"
	"io"
	"net/http"
	"time"

	pmauth "example.com/yourfirm/pmauth" // canonical client from /connect#authentication
)

const (
	baseURL    = "https://api.preprod.polymarketexchange.com" // prod: https://api.prod.polymarketexchange.com
	externalID = "u-8f21c4a9"                                 // your own user key. Max 49 characters.
	sessionTok = "dit-..."                                    // Socure Digital Intelligence token from your front end
)

type startResp struct {
	Decision      string `json:"decision"`
	Status        string `json:"status"`
	SubStatus     string `json:"subStatus"`
	ParticipantID string `json:"participantId"`
	Docv          *struct {
		URL    string `json:"url"`
		SDKKey string `json:"sdkKey"` // always empty
	} `json:"docv"`
}

func main() {
	// VERIFY: legal name, date of birth, national ID / SSN, email, phone and address
	// field names are not published. Get the schema from your integration lead.
	req := map[string]any{
		"external_id":   externalID,
		"postal_code":   "10013", // five digits, no ZIP+4
		"docv_eligible": true,    // omit this and review cases take 1-2 business days
		"session_token": sessionTok,
	}
	body, err := json.Marshal(req)
	if err != nil {
		panic(err)
	}

	token, err := pmauth.New().AccessToken()
	if err != nil {
		panic(err)
	}

	httpReq, err := http.NewRequest(http.MethodPost, baseURL+"/v1/kyc/start", bytes.NewReader(body))
	if err != nil {
		panic(err)
	}
	httpReq.Header.Set("Authorization", "Bearer "+token)
	httpReq.Header.Set("Content-Type", "application/json")

	res, err := (&http.Client{Timeout: 30 * time.Second}).Do(httpReq)
	if err != nil {
		panic(err)
	}
	defer res.Body.Close()
	raw, _ := io.ReadAll(res.Body)
	if res.StatusCode != http.StatusOK {
		// A duplicate SSN arrives here as HTTP 400, not the documented 409.
		panic(fmt.Sprintf("HTTP %d: %s", res.StatusCode, raw))
	}

	var out startResp
	if err := json.Unmarshal(raw, &out); err != nil {
		panic(err)
	}
	fmt.Println("telemetry:", out.Decision, out.Status, out.SubStatus)

	switch {
	case out.Docv != nil:
		// Outcome 3: document verification. sdkKey is always empty, so send the user to the URL.
		fmt.Println("redirect the user to", out.Docv.URL)
	case out.Decision == "ACCEPT":
		// Outcome 1: approved. participantId can be empty for up to 26 minutes.
		fmt.Printf("accepted, participantId=%q — wait for kyc.approved\n", out.ParticipantID)
	default:
		// Outcomes 2 and 4: rejected, or under review. Never branch on the literals.
		fmt.Println("not terminal — poll GET /v1/kyc/status and wait for a webhook")
	}
}