Skip to main content

​
First Document Verification

This guide walks you through your first end-to-end document verification using the Dataspike API:
  1. Create an Applicant
  2. Create a Verification
  3. Submit Documents (via hosted link, Web SDK, or your own upload flow)
  4. 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"}'
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"}'
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: Send the verification_url to the user and wait for the webhook event when verification completes. 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 API using the verification ID/URL 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"
The Web SDK handles this automatically; you don’t need to call proceed when using the widget.

​
5) Get Results (webhook or poll)

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"

​
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