> ## Documentation Index
> Fetch the complete documentation index at: https://docs.dataspike.io/llms.txt
> Use this file to discover all available pages before exploring further.

# First Verification

> Create an applicant, start a verification, submit documents, and retrieve results via webhook or API.

# 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):

```bash theme={null}
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.

<Tabs>
  <Tab title="cURL">
    ```bash theme={null}
    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"}'
    ```
  </Tab>

  <Tab title="Python">
    ```python theme={null}
    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())
    ```
  </Tab>
</Tabs>

**Example response**

```json theme={null}
{
  "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.

<Tabs>
  <Tab title="cURL">
    ```bash theme={null}
    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"}'
    ```
  </Tab>

  <Tab title="Python">
    ```python theme={null}
    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)
    ```
  </Tab>
</Tabs>

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

```json theme={null}
{
  "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).

```javascript theme={null}
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](/api-reference/file-management/upload-document) 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.

<Tabs>
  <Tab title="cURL">
    ```bash theme={null}
    curl -X POST "https://api.dataspike.io/api/v3/verifications/$VERIFICATION_UUID/proceed"   -H "ds-api-token: $API_KEY"
    ```
  </Tab>

  <Tab title="Python">
    ```python theme={null}
    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())
    ```
  </Tab>
</Tabs>

> 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**

```json theme={null}
{
  "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.

<Tabs>
  <Tab title="cURL">
    ```bash theme={null}
    curl -X GET "https://api.dataspike.io/api/v3/verifications/verif_9a30_7ab7cc169d11"   -H "ds-api-token: $API_KEY"
    ```
  </Tab>

  <Tab title="Python">
    ```python theme={null}
    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())
    ```
  </Tab>
</Tabs>

***

## 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](https://docs.dataspike.io/web-sdk)
* Run an [AML Screening](https://docs.dataspike.io/aml-screening)