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.

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.

Request body

product · string · required

Product code from GET /catalog. 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 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 for the same product and fields.

Response fields

id · string · required

API request ID.

data · object

Show 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.

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

cURL

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>"
  }'

200

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

A 202 response means the verification is still processing. Store the sessionId and poll GET /verifications/:sessionId at most every 15 seconds, or rely on verification.completed webhooks.