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

# POST /verifications

> POST /verifications: submit a verification request with confirmed consent and an idempotency key.

Submit a verification request after obtaining the data subject's lawful authorisation and confirming the exact consent text. Include an `Idempotency-Key` header on every submission. Store the returned `sessionId` and poll it, or wait for a signed webhook.

```text theme={null}
POST https://masterid.me/api/public/v1/verifications
```

## Authentication

**X-API-Key** `string` *required*

Your workspace API key.

**X-API-Secret** `string` *required*

Your workspace API secret.

**Content-Type** `string` *required*

Must be `application/json`.

**Idempotency-Key** `string` *required*

Unique request identifier, 8-100 characters: letters, digits, or `._:-`. Retry with the same key and identical body to avoid duplicates. See [Idempotency](https://docs.masterid.co.ug/concepts/idempotency.md).

## Request body

**product** `string` *required*

Product code from [GET /catalog](https://docs.masterid.co.ug/api-reference/catalog/get-catalog.md). Examples: `nin`, `tin`, `business`, `phone`.

**fields** `object` *required*

Identity fields required by the chosen product. Use exact selection values and date fields in `YYYY-MM-DD` format. See the [Products](https://docs.masterid.co.ug/products.md) reference for per-product field lists.

**consentConfirmed** `boolean` *required*

Must be `true`. Confirms that the data subject has been presented with the exact consent text and has genuinely confirmed.

**consentText** `string` *required*

The exact consent text returned by [POST /verifications/consent](https://docs.masterid.co.ug/api-reference/verifications/request-consent.md) for the same product and fields.

## Response fields

**id** `string` *required*

API request ID.

**data** `object`

**properties**

**sessionId** `string` *required*

The verification session ID. Store this value. It is different from the API request ID.

**product** `string`

The product code submitted.

**status** `string`

One of: `pending`, `legitimate`, `fake`, `failed`.

**charged** `integer`

Amount charged in UGX at the catalog price. Pending checks have no charge until a final result is returned, and failed checks are not charged.

**details** `array`

Formatted integration results as an array of `{label, value}` objects. These are formatted results, not raw source responses.

**shareholding** `object | null`

Additional structured data when available. Structure is not documented.

## Status codes

| Status | Meaning |
| - | - |
| 200 | Completed result returned immediately. |
| 202 | Accepted. Verification is pending; poll GET /verifications/:sessionId. |
| 400 | Invalid input, consent or idempotency header. |
| 401 | Missing, invalid or revoked credentials. |
| 403 | Suspended account. |
| 409 | Idempotency conflict. |
| 413 | Body too large. |
| 422 | Required funds, merchant activation or other validation failed. |
| 429 | API request limit reached. Check `Retry-After`. |
| 500/503 | Temporary processing error or unavailability. |

> [!WARNING]
>
> Do not create another check while a session is pending. Poll the saved session no more frequently than every 15 seconds.

```bash cURL theme={null}
curl -X POST "https://masterid.me/api/public/v1/verifications" \
  -H "X-API-Key: $MASTERID_API_KEY" \
  -H "X-API-Secret: $MASTERID_API_SECRET" \
  -H "Idempotency-Key: your-unique-request-id" \
  -H "Content-Type: application/json" \
  --data '{
    "product": "nin",
    "fields": {
      "nin": "<APPROVED_NIN>",
      "cardNumber": "<CARD_NUMBER>",
      "surname": "<SURNAME>",
      "givenNames": "<GIVEN_NAMES>",
      "dateOfBirth": "1990-01-01"
    },
    "consentConfirmed": true,
    "consentText": "<EXACT_CONFIRMED_TEXT>"
  }'
```

```javascript Node.js theme={null}
const response = await fetch(
  "https://masterid.me/api/public/v1/verifications",
  {
    method: "POST",
    headers: {
      "X-API-Key": process.env.MASTERID_API_KEY,
      "X-API-Secret": process.env.MASTERID_API_SECRET,
      "Idempotency-Key": "your-unique-request-id",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      product: "nin",
      fields: {
        nin: "<APPROVED_NIN>",
        cardNumber: "<CARD_NUMBER>",
        surname: "<SURNAME>",
        givenNames: "<GIVEN_NAMES>",
        dateOfBirth: "1990-01-01",
      },
      consentConfirmed: true,
      // Exact data.consentText returned by POST /verifications/consent
      consentText: "<EXACT_CONFIRMED_TEXT>",
    }),
  }
);
const body = await response.json();
console.log(body.data.sessionId);
```

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

r = requests.post(
    "https://masterid.me/api/public/v1/verifications",
    headers={
        "X-API-Key": os.environ["MASTERID_API_KEY"],
        "X-API-Secret": os.environ["MASTERID_API_SECRET"],
        "Idempotency-Key": "your-unique-request-id",
        "Content-Type": "application/json",
    },
    json={
        "product": "nin",
        "fields": {
            "nin": "<APPROVED_NIN>",
            "cardNumber": "<CARD_NUMBER>",
            "surname": "<SURNAME>",
            "givenNames": "<GIVEN_NAMES>",
            "dateOfBirth": "1990-01-01",
        },
        "consentConfirmed": True,
        # Exact data.consentText returned by POST /verifications/consent
        "consentText": "<EXACT_CONFIRMED_TEXT>",
    },
)
print(r.json()["data"]["sessionId"])
```

```json 200 theme={null}
{
  "id": "<REQUEST_ID>",
  "data": {
    "sessionId": "<SESSION_ID>",
    "product": "nin",
    "status": "legitimate",
    "charged": 2500,
    "details": [
      { "label": "Result", "value": "Verified" }
    ],
    "shareholding": null
  }
}
```

```json 202 theme={null}
{
  "id": "<REQUEST_ID>",
  "data": {
    "sessionId": "<SESSION_ID>",
    "product": "nin",
    "status": "pending"
  }
}
```

> [!TIP]
>
> A 202 response means the verification is still processing. Store the `sessionId` and poll [GET /verifications/:sessionId](https://docs.masterid.co.ug/api-reference/verifications/get-verification.md) at most every 15 seconds, or rely on `verification.completed` webhooks.


## Related topics

- [POST /verifications/consent](https://docs.masterid.co.ug/api-reference/verifications/request-consent.md)
- [Run a verification](https://docs.masterid.co.ug/guides/verifications.md)
- [API Overview](https://docs.masterid.co.ug/api-reference/overview.md)
- [Products and fields](https://docs.masterid.co.ug/products.md)
- [Responses and status codes](https://docs.masterid.co.ug/concepts/responses.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.