# Quickstart

> Create an account and verify a test NIN in about two minutes. No contract, card or approval needed.

> **Sandbox:** Everything on this page uses the sandbox. Sandbox keys start with `sk_test_`, return deterministic test data and are never billed.

### 1. Create an account

[Sign up](https://speedmap-delta.vercel.app/signup) with your work email. A sandbox workspace is created for you straight away, with every product enabled on test data.

### 2. Copy your test key

Your first test key is shown right after you create your account, **once**. Store it in your secret manager or a local `.env` file: Speedmap keeps only a hash and cannot show it again. You can create more keys in **Dashboard → API keys**.

```bash
SPEEDMAP_API_KEY=sk_test_...
```

### 3. Verify a test NIN

Verify the sandbox identity *Clarke Griffin* with her NINAuth share code `SPM001`. The share code is the subject's consent, so this method is open to every business. The `match` object is optional: Speedmap compares each field against the NIMC record and reports the result per field.

_cURL_

```bash
curl -X POST http://localhost:4000/v1/verify/nin \
  -H "Authorization: Bearer sk_test_..." \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "method": "share_code",
  "share_code": "SPM001",
  "reason": "financialProducts",
  "match": {
    "first_name": "Clarke",
    "last_name": "Griffin"
  }
}'
```

_Node.js_

```javascript
const res = await fetch("http://localhost:4000/v1/verify/nin", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.SPEEDMAP_API_KEY}`,
    "Content-Type": "application/json",
    "Idempotency-Key": crypto.randomUUID(),
  },
  body: JSON.stringify({
    "method": "share_code",
    "share_code": "SPM001",
    "reason": "financialProducts",
    "match": {
      "first_name": "Clarke",
      "last_name": "Griffin"
    }
  }),
});

const verification = await res.json();
if (!res.ok) throw new Error(verification.error.message);
console.log(verification.status, verification.match);
```

_Python_

```python
import os, uuid, requests

res = requests.post(
    "http://localhost:4000/v1/verify/nin",
    headers={
        "Authorization": f"Bearer {os.environ['SPEEDMAP_API_KEY']}",
        "Idempotency-Key": str(uuid.uuid4()),
    },
    json={
        "method": "share_code",
        "share_code": "SPM001",
        "reason": "financialProducts",
        "match": {
            "first_name": "Clarke",
            "last_name": "Griffin"
        }
    },
    timeout=30,
)
res.raise_for_status()
verification = res.json()
print(verification["status"], verification["match"])
```

### 4. Read the response

A completed check returns `200` with an assertion. `status` is `verified` (the record exists) or `not_found`; `match` is `true` only when every field you supplied agrees with the record. Names in `summary` are masked, and `subject` is the masked identifier.

```json
{
  "reference_id": "spm_8171f3a87cbe221341f7185f",
  "object": "verification",
  "product": "nin",
  "method": "nin_sharecode",
  "status": "verified",
  "match": true,
  "field_matches": {
    "first_name": true,
    "last_name": true
  },
  "field_confidence": {
    "last_name": 100
  },
  "mode": "sandbox",
  "reason": "financialProducts",
  "subject": null,
  "summary": {
    "first_name": "A*****",
    "last_name": "O*****"
  },
  "consent": {
    "mechanism": "ninauth_share_code",
    "consent_id": null,
    "timestamp": "2026-10-19T09:41:07.512Z"
  },
  "source": "api",
  "error": null,
  "billing": {
    "amount_kobo": 0,
    "currency": "NGN"
  },
  "latency_ms": 412,
  "created_at": "2026-10-19T09:41:07.512Z",
  "updated_at": "2026-10-19T09:41:07.874Z"
}
```

Keep the `reference_id`. It is the permanent handle for this check: use it to [retrieve the verification](https://speedmap-delta.vercel.app/docs/verifications), reconcile [webhooks](https://speedmap-delta.vercel.app/docs/webhooks) and raise disputes.

## Try other outcomes

The sandbox answers specific inputs with specific outcomes. With `method: "nin"` (raw NIN lookup) you can try these:

| NIN | Outcome |
| --- | --- |
| `98765432109` | Verified: Clarke Griffin |
| `09876543210` | Verified: Bellamy Blake |
| `00000000000` | `not_found` (`200`, `match: false`) |
| `99999999999` | Provider timeout: `202` with `status: "pending"`, resolved on the next `GET` |

Raw NIN lookup is restricted by NIMC to financial institutions and government agencies, so it needs the raw-NIN entitlement on your workspace; without it the request fails with `403 not_entitled`. Send the same NINs with `method: "in_person"` and a `selfie_image` instead. The full list for every product is on the [Sandbox](https://speedmap-delta.vercel.app/docs/sandbox) page.

## Next steps

- Choose a NIN [verification method](https://speedmap-delta.vercel.app/docs/products/nin#methods) for production: `in_person` (selfie), `share_code`, or `nin` if you are eligible for raw lookup.
- Add an [`Idempotency-Key`](https://speedmap-delta.vercel.app/docs/idempotency) to every `POST` so retries are safe.
- Subscribe to [webhooks](https://speedmap-delta.vercel.app/docs/webhooks) instead of polling for pending checks.
- When you are ready for real data, request go-live in the dashboard. Live keys (`sk_live_`) are issued after approval. See [Authentication](https://speedmap-delta.vercel.app/docs/authentication).

The base URL for every request is `http://localhost:4000`.

---

Source: https://speedmap-delta.vercel.app/docs/quickstart