First Document Verification

This guide walks you through your first end-to-end document verification using the Dataspike API:

Create an Applicant
Create a Verification
Submit Documents (via hosted link, Web SDK, or your own upload flow)
Retrieve the result (via webhook or polling)

🔐 Environments: Use Sandbox while integrating. Sandbox https://sandboxapi.dataspike.io • Production https://api.dataspike.io Each environment has its own API key and data. Switch in Dashboard → API.

Prerequisites

Your API key from the dashboard (Dashboard → API).
Sandbox selected while testing (recommended).
A server environment capable of making HTTPS requests.

Set your key (example):

export API_KEY="<YOUR_API_KEY>"

1) Create an Applicant

Create a new applicant record. You can include optional metadata like external_id, name, or contact details.

cURL
Python

curl -X POST "https://api.dataspike.io/api/v3/applicants"   -H "Content-Type: application/json"   -H "ds-api-token: $API_KEY"   --data '{"external_id": "12345678"}'

import requests, os

API_KEY = os.environ["API_KEY"]
BASE = "https://api.dataspike.io"  # use https://sandboxapi.dataspike.io for Sandbox

r = requests.post(
    f"{BASE}/api/v3/applicants",
    headers={
        "ds-api-token": API_KEY,
        "Content-Type": "application/json",
    },
    json={"external_id": "12345678"},
)
r.raise_for_status()
print(r.json())

Example response

{
  "id": "01827ed4-c928-7a3c-9a30-7ab7cc169d11",
  "external_id": "12345678"
}

2) Create a Verification

Create a verification linked to your applicant.
If you don’t specify a profile_id, the default verification profile is used. You can manage profiles via API or Dashboard.

cURL
Python

curl -X POST "https://api.dataspike.io/api/v3/verifications"   -H "Content-Type: application/json"   -H "ds-api-token: $API_KEY"   --data '{"applicant_id": "01827ed4-c928-7a3c-9a30-7ab7cc169d11"}'

import requests, os

API_KEY = os.environ["API_KEY"]
BASE = "https://api.dataspike.io"  # use sandbox base for testing

payload = {
    "applicant_id": "01827ed4-c928-7a3c-9a30-7ab7cc169d11",
    # "profile_id": "prof_xxx"  # optional: choose a specific profile
}

r = requests.post(
    f"{BASE}/api/v3/verifications",
    headers={"ds-api-token": API_KEY, "Content-Type": "application/json"},
    json=payload,
)
r.raise_for_status()
data = r.json()
print(data)

You’ll receive a payload that includes a verification_url and short verification_url_id:

{
  "id": "01827ed4-c928-7a3c-9a30-7ab7cc169d12",
  "verification_url": "https://am.dataspike.io/VF57124F182867E0",
  "verification_url_id": "VF57124F182867E0",
  "applicant_id": "01827ed4-c928-7a3c-9a30-7ab7cc169d11",
  "profile_id": "default"
}

3) Submit Documents (choose one)

You have three options for collecting documents and completing the flow:

A) Hosted link (fastest)

Send the verification_url to the user and wait for the webhook event when verification completes.

B) Web SDK (embedded, recommended)

Embed the widget in your app and initialize it with verification_url_id (safe to expose).

DocsVerificationWidget({
  id: 'VF57124F182867E0',     // verification_url_id
  elementId: 'root',          // container element
  apiUrl: 'https://api.dataspike.io'
});

⚠️ Never expose your API key in frontend code. Create the verification on your backend and only return verification_url_id to the client.

C) Your own upload flow (advanced)

If you already have a document capture UX, you can upload files via File management API using the verification ID/URL ID or applicant ID. (See API reference for endpoints and content types.)

4) Proceed (optional, for custom flows)

If you built a manual capture/upload flow, call proceed once all docs are submitted to start the verification.

cURL
Python

curl -X POST "https://api.dataspike.io/api/v3/verifications/$VERIFICATION_UUID/proceed"   -H "ds-api-token: $API_KEY"

import requests, os
API_KEY = os.environ["API_KEY"]
BASE = "https://api.dataspike.io"
VERIFICATION_UUID = "verif_9a30_7ab7cc169d11"

r = requests.post(
    f"{BASE}/api/v3/verifications/{VERIFICATION_UUID}/proceed",
    headers={"ds-api-token": API_KEY},
)
r.raise_for_status()
print(r.json())

The Web SDK handles this automatically; you don’t need to call proceed when using the widget.

5) Get Results (webhook or poll)

Option 1 — Webhook (recommended)

Configure webhooks in Dashboard → API → Webhooks.
Enable the endpoint and use Test to send a dummy event.
Requests include an identifying header with the webhook internal ID, so you can trace deliveries and verify origin. Example webhook payload

{
  "event": "DOCVER_EVENT",
  "verification_id": "verif_9a30_7ab7cc169d11",
  "applicant_id": "01827ed4-c928-7a3c-9a30-7ab7cc169d11",
  "status": "approved",
  "scores": {
    "document_authenticity": 0.98,
    "face_match": 0.97,
    "liveness": 0.99
  },
  "occurred_at": "2025-01-01T12:00:00Z"
}

Option 2 — Poll via API

You can query verification status directly if you prefer polling or are still setting up webhooks.

cURL
Python

curl -X GET "https://api.dataspike.io/api/v3/verifications/verif_9a30_7ab7cc169d11"   -H "ds-api-token: $API_KEY"

import requests, os
API_KEY = os.environ["API_KEY"]
BASE = "https://api.dataspike.io"
VERIFICATION_UUID = "verif_9a30_7ab7cc169d11"

r = requests.get(
    f"{BASE}/api/v3/verifications/{VERIFICATION_UUID}",
    headers={"ds-api-token": API_KEY},
)
r.raise_for_status()
print(r.json())

Notes & Best Practices

Sandbox first: Use https://sandboxapi.dataspike.io and your Sandbox API key while integrating.
Profiles: To customize the verification flow, pass a specific profile_id when creating the verification.
Security: Keep applicantId, profileId, and API keys on your backend only.
Widget: Prefer the Web SDK for fastest integration (it also calls proceed for you).
Stateless checks: You can run isolated checks without storing Applicants if you need a lightweight flow.

Next Steps

Integrate the Web SDK
Run an AML Screening

Getting started

Web SDK

KYC Mobile SDK

Deepfake Detection

Document Verification

KYB Verification

AML Screening

MCP Server

Webhooks

First Verification

First Document Verification

Prerequisites

1) Create an Applicant

2) Create a Verification

3) Submit Documents (choose one)

A) Hosted link (fastest)

B) Web SDK (embedded, recommended)

C) Your own upload flow (advanced)

4) Proceed (optional, for custom flows)

5) Get Results (webhook or poll)

Option 1 — Webhook (recommended)

Option 2 — Poll via API

Notes & Best Practices

Next Steps

​First Document Verification

​Prerequisites

​1) Create an Applicant

​2) Create a Verification

​3) Submit Documents (choose one)

​A) Hosted link (fastest)

​B) Web SDK (embedded, recommended)

​C) Your own upload flow (advanced)

​4) Proceed (optional, for custom flows)

​5) Get Results (webhook or poll)

​Option 1 — Webhook (recommended)

​Option 2 — Poll via API

​Notes & Best Practices

​Next Steps

First Document Verification

Prerequisites

1) Create an Applicant

2) Create a Verification

3) Submit Documents (choose one)

A) Hosted link (fastest)

B) Web SDK (embedded, recommended)

C) Your own upload flow (advanced)

4) Proceed (optional, for custom flows)

5) Get Results (webhook or poll)

Option 1 — Webhook (recommended)

Option 2 — Poll via API

Notes & Best Practices

Next Steps