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

# Run a verification

> POST /v1/{scope} runs a check and returns the result.

<div>
  `POST` `/v1/{scope}`
</div>

Runs the scope named in the path and returns the verification. The request body is that scope's inputs, sent directly as JSON.

## Path parameters

<ParamField path="scope" type="string" required>
  The scope to run, for example `nin`, `bvn`, or `face_match`. The scope must be active for your organization and allowed by your key. See [Scopes and activation](/concepts/scopes-and-activation).
</ParamField>

## Body

The body is the scope's inputs. There is no wrapper object; the fields you send are the fields the scope expects. For a NIN lookup:

<ParamField body="nin" type="string" required>
  The 11 digit NIN to look up.
</ParamField>

<Note>
  Each scope defines its own inputs. The fields above are for `nin`; see the scope's page under [Verification scopes](/scopes/overview) for the inputs it takes.
</Note>

## Request

<CodeGroup>
  ```bash cURL theme={null}
  curl https://api.pruva.africa/v1/nin \
    -X POST \
    -H "X-Pruva-Key: pruva_live_YOUR_KEY" \
    -H "Content-Type: application/json" \
    -d '{ "nin": "12345678901" }'
  ```

  ```javascript Node theme={null}
  const res = await fetch("https://api.pruva.africa/v1/nin", {
    method: "POST",
    headers: {
      "X-Pruva-Key": "pruva_live_YOUR_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ nin: "12345678901" }),
  });

  const verification = await res.json();
  ```

  ```python Python theme={null}
  import requests

  res = requests.post(
      "https://api.pruva.africa/v1/nin",
      headers={"X-Pruva-Key": "pruva_live_YOUR_KEY"},
      json={"nin": "12345678901"},
  )

  verification = res.json()
  ```
</CodeGroup>

## Response

Returns `201` with the verification in `data`.

```json theme={null}
{
  "status": true,
  "data": {
    "reference": "43817179a3dc8c341d358432b0590924",
    "scope": "nin",
    "category": "kyc",
    "countryCode": "NG",
    "status": "found",
    "request": { "nin": "12345678901" },
    "result": {
      "firstName": "Ada",
      "lastName": "Okafor",
      "dateOfBirth": "1990-04-12"
    },
    "errorMessage": null,
    "priceKobo": 5000,
    "charged": true,
    "createdAt": "2026-07-27T08:50:00+01:00"
  }
}
```

### Response fields

<ResponseField name="reference" type="string">
  Unique id for this verification. Use it to [retrieve the result later](/api-reference/get-verification).
</ResponseField>

<ResponseField name="scope" type="string">
  The scope that ran.
</ResponseField>

<ResponseField name="status" type="string">
  `found`, `not_found`, or `failed`. See [the three outcomes](/concepts/how-verification-works).
</ResponseField>

<ResponseField name="result" type="object">
  The details found, shaped by the scope. `{}` when nothing was found.
</ResponseField>

<ResponseField name="priceKobo" type="integer">
  What the check cost, in kobo.
</ResponseField>

<ResponseField name="charged" type="boolean">
  Whether your wallet was debited.
</ResponseField>

<ResponseField name="createdAt" type="string">
  When the check ran, ISO 8601.
</ResponseField>

## Billing

A `found` or `not_found` result is charged; a `failed` result is not. The wallet is checked against the scope's price before the provider is called. See [Wallet and billing](/concepts/billing).

## Errors

| Code  | When                                                                                             |
| ----- | ------------------------------------------------------------------------------------------------ |
| `402` | Wallet balance too low. `error.details` carries the `reference`, `priceKobo`, and `balanceKobo`. |
| `403` | Scope not active for your organization, or not allowed by your key.                              |
| `403` | Organization not approved or suspended.                                                          |
| `422` | Missing or invalid inputs, or no scope in the path.                                              |
| `502` | The provider could not complete the check. Not charged. `error.details` carries the `reference`. |

See [Errors](/api-reference/errors) for the full list and the error shape.