{ "item": [ { "id": "3db6223f-79d7-4422-adfc-9865caeaa96c", "name": "Identity", "description": { "content": "People's identity records: national ID, alien ID and passport (IPRS), and driving licences and PSV badges (NTSA).", "type": "text/plain" }, "item": [ { "id": "23048a55-2374-4f73-bc7d-4ac9b451aa95", "name": "National ID, alien ID or passport (IPRS)", "request": { "name": "National ID, alien ID or passport (IPRS)", "description": { "content": "Looks up a national ID, alien ID or passport in IPRS by its document type and number, and returns the holder's registered names, date of birth, gender and citizenship.\n\n**Price:** set by your bundle; one charge per call. \"Not found\" answers (`result.found: false`) are charged. Source failures return `502` and are refunded.\n\n**Try it:** choose a scenario from the example menu under the code sample and press **Test Request**. Paste your test key into **Authentication** in the window that opens (it is remembered); test keys return sandbox sample data, free.", "type": "text/plain" }, "url": { "path": [ "v1", "verifications", "identity.national-id" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [] }, "header": [ { "disabled": true, "description": "Makes retries safe: a repeat with the same key and body returns the original verification without charging again. Up to 255 characters.", "key": "Idempotency-Key", "value": "" }, { "key": "Content-Type", "value": "application/json" }, { "key": "Accept", "value": "application/json" } ], "method": "POST", "auth": null, "body": { "mode": "raw", "raw": "{\n \"idType\": \"\",\n \"idNumber\": \"\"\n}", "options": { "raw": { "language": "json" } } } }, "response": [ { "id": "072250b6-c021-4618-b5b7-2cfd35f4b1a3", "name": "Verification completed; see `result`.", "originalRequest": { "url": { "path": [ "v1", "verifications", "identity.national-id" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [] }, "header": [ { "description": { "content": "Added as a part of security scheme: bearer", "type": "text/plain" }, "key": "Authorization", "value": "Bearer " }, { "disabled": true, "description": "Makes retries safe: a repeat with the same key and body returns the original verification without charging again. Up to 255 characters.", "key": "Idempotency-Key", "value": "6f1c2a90-order-1042" }, { "key": "Accept", "value": "application/json" } ], "method": "POST", "body": { "mode": "raw", "raw": "{\n \"idType\": \"NATIONAL_ID\",\n \"idNumber\": \"12345678\"\n}", "options": { "raw": { "language": "json" } } } }, "status": "OK", "code": 200, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"id\": \"cmhd2k7q80001s60h3x9f2a1b\",\n \"api\": \"identity.national-id\",\n \"status\": \"COMPLETED\",\n \"environment\": \"LIVE\",\n \"result\": {\n \"found\": true,\n \"idType\": \"NATIONAL_ID\",\n \"person\": {\n \"idNumber\": \"12345678\",\n \"firstName\": \"JANE\",\n \"middleName\": \"WANJIKU\",\n \"lastName\": \"DOE\",\n \"dateOfBirth\": \"1990-01-15\",\n \"gender\": \"F\",\n \"citizenship\": \"KENYAN\"\n }\n },\n \"error\": null,\n \"cost\": \"50\",\n \"latencyMs\": 412,\n \"createdAt\": \"2026-10-30T09:15:02.118Z\",\n \"completedAt\": \"2026-10-30T09:15:02.530Z\"\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "ef49cfce-a563-4642-a182-20cef3c664c8", "name": "The input failed validation; `issues` lists each problem.", "originalRequest": { "url": { "path": [ "v1", "verifications", "identity.national-id" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [] }, "header": [ { "description": { "content": "Added as a part of security scheme: bearer", "type": "text/plain" }, "key": "Authorization", "value": "Bearer " }, { "disabled": true, "description": "Makes retries safe: a repeat with the same key and body returns the original verification without charging again. Up to 255 characters.", "key": "Idempotency-Key", "value": "6f1c2a90-order-1042" }, { "key": "Accept", "value": "application/json" } ], "method": "POST", "body": { "mode": "raw", "raw": "{\n \"idType\": \"NATIONAL_ID\",\n \"idNumber\": \"12345678\"\n}", "options": { "raw": { "language": "json" } } } }, "status": "Bad Request", "code": 400, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"statusCode\": 400,\n \"message\": \"Validation failed\",\n \"issues\": [\n {\n \"code\": \"invalid_value\",\n \"values\": [\n \"NATIONAL_ID\",\n \"ALIEN_ID\",\n \"PASSPORT\"\n ],\n \"path\": [\n \"idType\"\n ],\n \"message\": \"Invalid option: expected one of \\\"NATIONAL_ID\\\"|\\\"ALIEN_ID\\\"|\\\"PASSPORT\\\"\"\n },\n {\n \"expected\": \"string\",\n \"code\": \"invalid_type\",\n \"path\": [\n \"idNumber\"\n ],\n \"message\": \"Invalid input: expected string, received undefined\"\n }\n ]\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "a1f12fd4-1577-4204-a66c-8dddf703e7d0", "name": "Missing, unknown or revoked API key.", "originalRequest": { "url": { "path": [ "v1", "verifications", "identity.national-id" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [] }, "header": [ { "description": { "content": "Added as a part of security scheme: bearer", "type": "text/plain" }, "key": "Authorization", "value": "Bearer " }, { "disabled": true, "description": "Makes retries safe: a repeat with the same key and body returns the original verification without charging again. Up to 255 characters.", "key": "Idempotency-Key", "value": "6f1c2a90-order-1042" }, { "key": "Accept", "value": "application/json" } ], "method": "POST", "body": { "mode": "raw", "raw": "{\n \"idType\": \"NATIONAL_ID\",\n \"idNumber\": \"12345678\"\n}", "options": { "raw": { "language": "json" } } } }, "status": "Unauthorized", "code": 401, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"statusCode\": 401,\n \"message\": \"Invalid API key\"\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "c706312a-a632-4b84-96d3-b342829b3e04", "name": "The wallet can't cover this call (live keys only). Nothing was charged.", "originalRequest": { "url": { "path": [ "v1", "verifications", "identity.national-id" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [] }, "header": [ { "description": { "content": "Added as a part of security scheme: bearer", "type": "text/plain" }, "key": "Authorization", "value": "Bearer " }, { "disabled": true, "description": "Makes retries safe: a repeat with the same key and body returns the original verification without charging again. Up to 255 characters.", "key": "Idempotency-Key", "value": "6f1c2a90-order-1042" }, { "key": "Accept", "value": "application/json" } ], "method": "POST", "body": { "mode": "raw", "raw": "{\n \"idType\": \"NATIONAL_ID\",\n \"idNumber\": \"12345678\"\n}", "options": { "raw": { "language": "json" } } } }, "status": "Payment Required", "code": 402, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"statusCode\": 402,\n \"code\": \"INSUFFICIENT_FUNDS\",\n \"message\": \"Insufficient wallet balance\"\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "9f462a06-7cdd-47d2-a71b-d86543a538fe", "name": "This API isn't in your organization's bundle.", "originalRequest": { "url": { "path": [ "v1", "verifications", "identity.national-id" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [] }, "header": [ { "description": { "content": "Added as a part of security scheme: bearer", "type": "text/plain" }, "key": "Authorization", "value": "Bearer " }, { "disabled": true, "description": "Makes retries safe: a repeat with the same key and body returns the original verification without charging again. Up to 255 characters.", "key": "Idempotency-Key", "value": "6f1c2a90-order-1042" }, { "key": "Accept", "value": "application/json" } ], "method": "POST", "body": { "mode": "raw", "raw": "{\n \"idType\": \"NATIONAL_ID\",\n \"idNumber\": \"12345678\"\n}", "options": { "raw": { "language": "json" } } } }, "status": "Forbidden", "code": 403, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"statusCode\": 403,\n \"code\": \"API_NOT_IN_PLAN\",\n \"message\": \"Your plan does not include identity.national-id\"\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "67baaa6a-2a4d-4440-a89c-3f234bbf6d86", "name": "The `Idempotency-Key` was used for a different request, or that request is still running.", "originalRequest": { "url": { "path": [ "v1", "verifications", "identity.national-id" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [] }, "header": [ { "description": { "content": "Added as a part of security scheme: bearer", "type": "text/plain" }, "key": "Authorization", "value": "Bearer " }, { "disabled": true, "description": "Makes retries safe: a repeat with the same key and body returns the original verification without charging again. Up to 255 characters.", "key": "Idempotency-Key", "value": "6f1c2a90-order-1042" }, { "key": "Accept", "value": "application/json" } ], "method": "POST", "body": { "mode": "raw", "raw": "{\n \"idType\": \"NATIONAL_ID\",\n \"idNumber\": \"12345678\"\n}", "options": { "raw": { "language": "json" } } } }, "status": "Conflict", "code": 409, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"statusCode\": 409,\n \"message\": \"Idempotency-Key was already used for a different request\"\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "3a51fb94-134f-46ea-ba42-7c8c53fe9d3b", "name": "Monthly quota reached, or more than 120 requests a minute.", "originalRequest": { "url": { "path": [ "v1", "verifications", "identity.national-id" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [] }, "header": [ { "description": { "content": "Added as a part of security scheme: bearer", "type": "text/plain" }, "key": "Authorization", "value": "Bearer " }, { "disabled": true, "description": "Makes retries safe: a repeat with the same key and body returns the original verification without charging again. Up to 255 characters.", "key": "Idempotency-Key", "value": "6f1c2a90-order-1042" }, { "key": "Accept", "value": "application/json" } ], "method": "POST", "body": { "mode": "raw", "raw": "{\n \"idType\": \"NATIONAL_ID\",\n \"idNumber\": \"12345678\"\n}", "options": { "raw": { "language": "json" } } } }, "status": "Too Many Requests", "code": 429, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"statusCode\": 429,\n \"code\": \"QUOTA_EXCEEDED\",\n \"message\": \"Monthly quota of 1000 calls reached\"\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "9e168169-9839-4097-8fb0-7e654ee9b281", "name": "The source failed or didn't answer. The charge was refunded.", "originalRequest": { "url": { "path": [ "v1", "verifications", "identity.national-id" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [] }, "header": [ { "description": { "content": "Added as a part of security scheme: bearer", "type": "text/plain" }, "key": "Authorization", "value": "Bearer " }, { "disabled": true, "description": "Makes retries safe: a repeat with the same key and body returns the original verification without charging again. Up to 255 characters.", "key": "Idempotency-Key", "value": "6f1c2a90-order-1042" }, { "key": "Accept", "value": "application/json" } ], "method": "POST", "body": { "mode": "raw", "raw": "{\n \"idType\": \"NATIONAL_ID\",\n \"idNumber\": \"12345678\"\n}", "options": { "raw": { "language": "json" } } } }, "status": "Bad Gateway", "code": 502, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"statusCode\": 502,\n \"code\": \"PROVIDER_UNAVAILABLE\",\n \"message\": \"IPRS is unavailable (sandbox simulation)\",\n \"retryable\": true,\n \"requestId\": \"cmhd2k7q80001s60h3x9f2a1b\"\n}", "cookie": [], "_postman_previewlanguage": "json" } ], "event": [], "protocolProfileBehavior": { "disableBodyPruning": true } }, { "id": "4acca397-1ce0-46a1-91f0-982bf2ed041d", "name": "Driving licence & PSV badge (NTSA)", "request": { "name": "Driving licence & PSV badge (NTSA)", "description": { "content": "Looks up the driving licence held under a Kenyan national ID number in NTSA: holder name, licence number, status, classes and expiry date, plus the PSV badge (number, status, expiry, licensed for) when the holder has one (`psvLicence`, otherwise null).\n\n**Price:** set by your bundle; one charge per call. \"Not found\" answers (`result.found: false`) are charged. Source failures return `502` and are refunded.\n\n**Try it:** choose a scenario from the example menu under the code sample and press **Test Request**. Paste your test key into **Authentication** in the window that opens (it is remembered); test keys return sandbox sample data, free.", "type": "text/plain" }, "url": { "path": [ "v1", "verifications", "identity.driving-licence" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [] }, "header": [ { "disabled": true, "description": "Makes retries safe: a repeat with the same key and body returns the original verification without charging again. Up to 255 characters.", "key": "Idempotency-Key", "value": "" }, { "key": "Content-Type", "value": "application/json" }, { "key": "Accept", "value": "application/json" } ], "method": "POST", "auth": null, "body": { "mode": "raw", "raw": "{\n \"idNumber\": \"\"\n}", "options": { "raw": { "language": "json" } } } }, "response": [ { "id": "9630d4b9-41a9-4d2e-a881-239f7d8983ad", "name": "Verification completed; see `result`.", "originalRequest": { "url": { "path": [ "v1", "verifications", "identity.driving-licence" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [] }, "header": [ { "description": { "content": "Added as a part of security scheme: bearer", "type": "text/plain" }, "key": "Authorization", "value": "Bearer " }, { "disabled": true, "description": "Makes retries safe: a repeat with the same key and body returns the original verification without charging again. Up to 255 characters.", "key": "Idempotency-Key", "value": "6f1c2a90-order-1042" }, { "key": "Accept", "value": "application/json" } ], "method": "POST", "body": { "mode": "raw", "raw": "{\n \"idNumber\": \"12345678\"\n}", "options": { "raw": { "language": "json" } } } }, "status": "OK", "code": 200, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"id\": \"cmhd2k7q80001s60h3x9f2a1b\",\n \"api\": \"identity.driving-licence\",\n \"status\": \"COMPLETED\",\n \"environment\": \"LIVE\",\n \"result\": {\n \"found\": true,\n \"idNumber\": \"12345678\",\n \"holderName\": \"JANE WANJIKU DOE\",\n \"drivingLicence\": {\n \"referenceNumber\": \"DL-0000001\",\n \"status\": \"valid\",\n \"classes\": [\n \"B\",\n \"C1\"\n ],\n \"expiryDate\": \"2030-01-15\"\n },\n \"psvLicence\": {\n \"referenceNumber\": \"PSV-0000001\",\n \"status\": \"valid\",\n \"expiryDate\": \"2027-06-30\",\n \"licensedFor\": \"PSV DRIVER\"\n }\n },\n \"error\": null,\n \"cost\": \"50\",\n \"latencyMs\": 412,\n \"createdAt\": \"2026-10-30T09:15:02.118Z\",\n \"completedAt\": \"2026-10-30T09:15:02.530Z\"\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "d56c003a-f810-4817-a384-b116bc51fb50", "name": "The input failed validation; `issues` lists each problem.", "originalRequest": { "url": { "path": [ "v1", "verifications", "identity.driving-licence" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [] }, "header": [ { "description": { "content": "Added as a part of security scheme: bearer", "type": "text/plain" }, "key": "Authorization", "value": "Bearer " }, { "disabled": true, "description": "Makes retries safe: a repeat with the same key and body returns the original verification without charging again. Up to 255 characters.", "key": "Idempotency-Key", "value": "6f1c2a90-order-1042" }, { "key": "Accept", "value": "application/json" } ], "method": "POST", "body": { "mode": "raw", "raw": "{\n \"idNumber\": \"12345678\"\n}", "options": { "raw": { "language": "json" } } } }, "status": "Bad Request", "code": 400, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"statusCode\": 400,\n \"message\": \"Validation failed\",\n \"issues\": [\n {\n \"expected\": \"string\",\n \"code\": \"invalid_type\",\n \"path\": [\n \"idNumber\"\n ],\n \"message\": \"Invalid input: expected string, received undefined\"\n }\n ]\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "82c61e15-7537-49cb-ab83-ebafd1a5106c", "name": "Missing, unknown or revoked API key.", "originalRequest": { "url": { "path": [ "v1", "verifications", "identity.driving-licence" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [] }, "header": [ { "description": { "content": "Added as a part of security scheme: bearer", "type": "text/plain" }, "key": "Authorization", "value": "Bearer " }, { "disabled": true, "description": "Makes retries safe: a repeat with the same key and body returns the original verification without charging again. Up to 255 characters.", "key": "Idempotency-Key", "value": "6f1c2a90-order-1042" }, { "key": "Accept", "value": "application/json" } ], "method": "POST", "body": { "mode": "raw", "raw": "{\n \"idNumber\": \"12345678\"\n}", "options": { "raw": { "language": "json" } } } }, "status": "Unauthorized", "code": 401, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"statusCode\": 401,\n \"message\": \"Invalid API key\"\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "af8853b7-0905-47f4-8d53-72c949c5c08e", "name": "The wallet can't cover this call (live keys only). Nothing was charged.", "originalRequest": { "url": { "path": [ "v1", "verifications", "identity.driving-licence" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [] }, "header": [ { "description": { "content": "Added as a part of security scheme: bearer", "type": "text/plain" }, "key": "Authorization", "value": "Bearer " }, { "disabled": true, "description": "Makes retries safe: a repeat with the same key and body returns the original verification without charging again. Up to 255 characters.", "key": "Idempotency-Key", "value": "6f1c2a90-order-1042" }, { "key": "Accept", "value": "application/json" } ], "method": "POST", "body": { "mode": "raw", "raw": "{\n \"idNumber\": \"12345678\"\n}", "options": { "raw": { "language": "json" } } } }, "status": "Payment Required", "code": 402, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"statusCode\": 402,\n \"code\": \"INSUFFICIENT_FUNDS\",\n \"message\": \"Insufficient wallet balance\"\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "6246eab8-f92e-4d37-aba2-c4b362ffb23f", "name": "This API isn't in your organization's bundle.", "originalRequest": { "url": { "path": [ "v1", "verifications", "identity.driving-licence" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [] }, "header": [ { "description": { "content": "Added as a part of security scheme: bearer", "type": "text/plain" }, "key": "Authorization", "value": "Bearer " }, { "disabled": true, "description": "Makes retries safe: a repeat with the same key and body returns the original verification without charging again. Up to 255 characters.", "key": "Idempotency-Key", "value": "6f1c2a90-order-1042" }, { "key": "Accept", "value": "application/json" } ], "method": "POST", "body": { "mode": "raw", "raw": "{\n \"idNumber\": \"12345678\"\n}", "options": { "raw": { "language": "json" } } } }, "status": "Forbidden", "code": 403, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"statusCode\": 403,\n \"code\": \"API_NOT_IN_PLAN\",\n \"message\": \"Your plan does not include identity.national-id\"\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "4fa420f0-f18a-4bfc-82be-4233ffe4071d", "name": "The `Idempotency-Key` was used for a different request, or that request is still running.", "originalRequest": { "url": { "path": [ "v1", "verifications", "identity.driving-licence" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [] }, "header": [ { "description": { "content": "Added as a part of security scheme: bearer", "type": "text/plain" }, "key": "Authorization", "value": "Bearer " }, { "disabled": true, "description": "Makes retries safe: a repeat with the same key and body returns the original verification without charging again. Up to 255 characters.", "key": "Idempotency-Key", "value": "6f1c2a90-order-1042" }, { "key": "Accept", "value": "application/json" } ], "method": "POST", "body": { "mode": "raw", "raw": "{\n \"idNumber\": \"12345678\"\n}", "options": { "raw": { "language": "json" } } } }, "status": "Conflict", "code": 409, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"statusCode\": 409,\n \"message\": \"Idempotency-Key was already used for a different request\"\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "ecba8646-5a64-401c-8513-3e04dfafae9e", "name": "Monthly quota reached, or more than 120 requests a minute.", "originalRequest": { "url": { "path": [ "v1", "verifications", "identity.driving-licence" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [] }, "header": [ { "description": { "content": "Added as a part of security scheme: bearer", "type": "text/plain" }, "key": "Authorization", "value": "Bearer " }, { "disabled": true, "description": "Makes retries safe: a repeat with the same key and body returns the original verification without charging again. Up to 255 characters.", "key": "Idempotency-Key", "value": "6f1c2a90-order-1042" }, { "key": "Accept", "value": "application/json" } ], "method": "POST", "body": { "mode": "raw", "raw": "{\n \"idNumber\": \"12345678\"\n}", "options": { "raw": { "language": "json" } } } }, "status": "Too Many Requests", "code": 429, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"statusCode\": 429,\n \"code\": \"QUOTA_EXCEEDED\",\n \"message\": \"Monthly quota of 1000 calls reached\"\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "673750d1-8ee2-4798-a925-9e9766a43c6b", "name": "The source failed or didn't answer. The charge was refunded.", "originalRequest": { "url": { "path": [ "v1", "verifications", "identity.driving-licence" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [] }, "header": [ { "description": { "content": "Added as a part of security scheme: bearer", "type": "text/plain" }, "key": "Authorization", "value": "Bearer " }, { "disabled": true, "description": "Makes retries safe: a repeat with the same key and body returns the original verification without charging again. Up to 255 characters.", "key": "Idempotency-Key", "value": "6f1c2a90-order-1042" }, { "key": "Accept", "value": "application/json" } ], "method": "POST", "body": { "mode": "raw", "raw": "{\n \"idNumber\": \"12345678\"\n}", "options": { "raw": { "language": "json" } } } }, "status": "Bad Gateway", "code": 502, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"statusCode\": 502,\n \"code\": \"PROVIDER_UNAVAILABLE\",\n \"message\": \"NTSA is unavailable (sandbox simulation)\",\n \"retryable\": true,\n \"requestId\": \"cmhd2k7q80001s60h3x9f2a1b\"\n}", "cookie": [], "_postman_previewlanguage": "json" } ], "event": [], "protocolProfileBehavior": { "disableBodyPruning": true } } ], "event": [] }, { "id": "1286e0db-6af1-48f1-b387-86b9bc2a4da9", "name": "Vehicles", "description": { "content": "Vehicle records from NTSA: make, model, owners and caveats for a number plate.", "type": "text/plain" }, "item": [ { "id": "d233e022-23c1-4e71-9044-9a0c4989eca2", "name": "Vehicle registration search (NTSA via Pesaflow)", "request": { "name": "Vehicle registration search (NTSA via Pesaflow)", "description": { "content": "Returns the NTSA record for a number plate: make, model, year, body, colour, chassis and engine numbers, registration status, owner names and any caveats. Pass `ownerIdNumber` to check whether that person is a registered owner (`checks.isOwner`); owner ID numbers are never returned.\n\n**Price:** set by your bundle; one charge per call. \"Not found\" answers (`result.found: false`) are charged. Source failures return `502` and are refunded.\n\n**Try it:** choose a scenario from the example menu under the code sample and press **Test Request**. Paste your test key into **Authentication** in the window that opens (it is remembered); test keys return sandbox sample data, free.", "type": "text/plain" }, "url": { "path": [ "v1", "verifications", "vehicle.registration" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [] }, "header": [ { "disabled": true, "description": "Makes retries safe: a repeat with the same key and body returns the original verification without charging again. Up to 255 characters.", "key": "Idempotency-Key", "value": "" }, { "key": "Content-Type", "value": "application/json" }, { "key": "Accept", "value": "application/json" } ], "method": "POST", "auth": null, "body": { "mode": "raw", "raw": "{\n \"registrationNumber\": \"\",\n \"ownerIdNumber\": \"\"\n}", "options": { "raw": { "language": "json" } } } }, "response": [ { "id": "71a70e4c-3b8a-40f7-8153-7f74c1077fa9", "name": "Verification completed; see `result`.", "originalRequest": { "url": { "path": [ "v1", "verifications", "vehicle.registration" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [] }, "header": [ { "description": { "content": "Added as a part of security scheme: bearer", "type": "text/plain" }, "key": "Authorization", "value": "Bearer " }, { "disabled": true, "description": "Makes retries safe: a repeat with the same key and body returns the original verification without charging again. Up to 255 characters.", "key": "Idempotency-Key", "value": "6f1c2a90-order-1042" }, { "key": "Accept", "value": "application/json" } ], "method": "POST", "body": { "mode": "raw", "raw": "{\n \"registrationNumber\": \"KDA 123A\",\n \"ownerIdNumber\": \"12345678\"\n}", "options": { "raw": { "language": "json" } } } }, "status": "OK", "code": 200, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"id\": \"cmhd2k7q80001s60h3x9f2a1b\",\n \"api\": \"vehicle.registration\",\n \"status\": \"COMPLETED\",\n \"environment\": \"LIVE\",\n \"result\": {\n \"found\": true,\n \"vehicle\": {\n \"registrationNumber\": \"KDA123A\",\n \"make\": \"TOYOTA\",\n \"model\": \"FIELDER\",\n \"yearOfManufacture\": 2015,\n \"bodyType\": \"STATION WAGON\",\n \"color\": \"SILVER\",\n \"fuelType\": \"PETROL\",\n \"chassisNumber\": \"NZE161-0123456\",\n \"engineNumber\": \"1NZ-1234567\",\n \"registrationStatus\": \"REGISTERED\",\n \"registrationDate\": \"2019-03-04\"\n },\n \"owners\": [\n {\n \"name\": \"JANE WANJIKU DOE\",\n \"type\": \"INDIVIDUAL\"\n }\n ],\n \"caveats\": [],\n \"hasCaveats\": false,\n \"checks\": {\n \"isOwner\": true\n }\n },\n \"error\": null,\n \"cost\": \"50\",\n \"latencyMs\": 412,\n \"createdAt\": \"2026-10-30T09:15:02.118Z\",\n \"completedAt\": \"2026-10-30T09:15:02.530Z\"\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "8e5abe65-1af8-452c-93d7-cc352d25ade4", "name": "The input failed validation; `issues` lists each problem.", "originalRequest": { "url": { "path": [ "v1", "verifications", "vehicle.registration" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [] }, "header": [ { "description": { "content": "Added as a part of security scheme: bearer", "type": "text/plain" }, "key": "Authorization", "value": "Bearer " }, { "disabled": true, "description": "Makes retries safe: a repeat with the same key and body returns the original verification without charging again. Up to 255 characters.", "key": "Idempotency-Key", "value": "6f1c2a90-order-1042" }, { "key": "Accept", "value": "application/json" } ], "method": "POST", "body": { "mode": "raw", "raw": "{\n \"registrationNumber\": \"KDA 123A\",\n \"ownerIdNumber\": \"12345678\"\n}", "options": { "raw": { "language": "json" } } } }, "status": "Bad Request", "code": 400, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"statusCode\": 400,\n \"message\": \"Validation failed\",\n \"issues\": [\n {\n \"expected\": \"string\",\n \"code\": \"invalid_type\",\n \"path\": [\n \"registrationNumber\"\n ],\n \"message\": \"Invalid input: expected string, received undefined\"\n }\n ]\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "7eb4bfd6-02b4-42f4-b833-971b05c117ba", "name": "Missing, unknown or revoked API key.", "originalRequest": { "url": { "path": [ "v1", "verifications", "vehicle.registration" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [] }, "header": [ { "description": { "content": "Added as a part of security scheme: bearer", "type": "text/plain" }, "key": "Authorization", "value": "Bearer " }, { "disabled": true, "description": "Makes retries safe: a repeat with the same key and body returns the original verification without charging again. Up to 255 characters.", "key": "Idempotency-Key", "value": "6f1c2a90-order-1042" }, { "key": "Accept", "value": "application/json" } ], "method": "POST", "body": { "mode": "raw", "raw": "{\n \"registrationNumber\": \"KDA 123A\",\n \"ownerIdNumber\": \"12345678\"\n}", "options": { "raw": { "language": "json" } } } }, "status": "Unauthorized", "code": 401, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"statusCode\": 401,\n \"message\": \"Invalid API key\"\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "5d0e93bd-34d6-497e-9e19-334b770b170f", "name": "The wallet can't cover this call (live keys only). Nothing was charged.", "originalRequest": { "url": { "path": [ "v1", "verifications", "vehicle.registration" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [] }, "header": [ { "description": { "content": "Added as a part of security scheme: bearer", "type": "text/plain" }, "key": "Authorization", "value": "Bearer " }, { "disabled": true, "description": "Makes retries safe: a repeat with the same key and body returns the original verification without charging again. Up to 255 characters.", "key": "Idempotency-Key", "value": "6f1c2a90-order-1042" }, { "key": "Accept", "value": "application/json" } ], "method": "POST", "body": { "mode": "raw", "raw": "{\n \"registrationNumber\": \"KDA 123A\",\n \"ownerIdNumber\": \"12345678\"\n}", "options": { "raw": { "language": "json" } } } }, "status": "Payment Required", "code": 402, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"statusCode\": 402,\n \"code\": \"INSUFFICIENT_FUNDS\",\n \"message\": \"Insufficient wallet balance\"\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "741c8aa1-0060-4a31-9acf-6929429d4474", "name": "This API isn't in your organization's bundle.", "originalRequest": { "url": { "path": [ "v1", "verifications", "vehicle.registration" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [] }, "header": [ { "description": { "content": "Added as a part of security scheme: bearer", "type": "text/plain" }, "key": "Authorization", "value": "Bearer " }, { "disabled": true, "description": "Makes retries safe: a repeat with the same key and body returns the original verification without charging again. Up to 255 characters.", "key": "Idempotency-Key", "value": "6f1c2a90-order-1042" }, { "key": "Accept", "value": "application/json" } ], "method": "POST", "body": { "mode": "raw", "raw": "{\n \"registrationNumber\": \"KDA 123A\",\n \"ownerIdNumber\": \"12345678\"\n}", "options": { "raw": { "language": "json" } } } }, "status": "Forbidden", "code": 403, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"statusCode\": 403,\n \"code\": \"API_NOT_IN_PLAN\",\n \"message\": \"Your plan does not include identity.national-id\"\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "6e2e62ff-8c9e-47d4-be44-8e430f6e45db", "name": "The `Idempotency-Key` was used for a different request, or that request is still running.", "originalRequest": { "url": { "path": [ "v1", "verifications", "vehicle.registration" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [] }, "header": [ { "description": { "content": "Added as a part of security scheme: bearer", "type": "text/plain" }, "key": "Authorization", "value": "Bearer " }, { "disabled": true, "description": "Makes retries safe: a repeat with the same key and body returns the original verification without charging again. Up to 255 characters.", "key": "Idempotency-Key", "value": "6f1c2a90-order-1042" }, { "key": "Accept", "value": "application/json" } ], "method": "POST", "body": { "mode": "raw", "raw": "{\n \"registrationNumber\": \"KDA 123A\",\n \"ownerIdNumber\": \"12345678\"\n}", "options": { "raw": { "language": "json" } } } }, "status": "Conflict", "code": 409, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"statusCode\": 409,\n \"message\": \"Idempotency-Key was already used for a different request\"\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "e6f09ca8-d20e-49b2-b0fd-331fe22ca79c", "name": "Monthly quota reached, or more than 120 requests a minute.", "originalRequest": { "url": { "path": [ "v1", "verifications", "vehicle.registration" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [] }, "header": [ { "description": { "content": "Added as a part of security scheme: bearer", "type": "text/plain" }, "key": "Authorization", "value": "Bearer " }, { "disabled": true, "description": "Makes retries safe: a repeat with the same key and body returns the original verification without charging again. Up to 255 characters.", "key": "Idempotency-Key", "value": "6f1c2a90-order-1042" }, { "key": "Accept", "value": "application/json" } ], "method": "POST", "body": { "mode": "raw", "raw": "{\n \"registrationNumber\": \"KDA 123A\",\n \"ownerIdNumber\": \"12345678\"\n}", "options": { "raw": { "language": "json" } } } }, "status": "Too Many Requests", "code": 429, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"statusCode\": 429,\n \"code\": \"QUOTA_EXCEEDED\",\n \"message\": \"Monthly quota of 1000 calls reached\"\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "1a170d18-8622-4519-b29d-265f4771f4e2", "name": "The source failed or didn't answer. The charge was refunded.", "originalRequest": { "url": { "path": [ "v1", "verifications", "vehicle.registration" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [] }, "header": [ { "description": { "content": "Added as a part of security scheme: bearer", "type": "text/plain" }, "key": "Authorization", "value": "Bearer " }, { "disabled": true, "description": "Makes retries safe: a repeat with the same key and body returns the original verification without charging again. Up to 255 characters.", "key": "Idempotency-Key", "value": "6f1c2a90-order-1042" }, { "key": "Accept", "value": "application/json" } ], "method": "POST", "body": { "mode": "raw", "raw": "{\n \"registrationNumber\": \"KDA 123A\",\n \"ownerIdNumber\": \"12345678\"\n}", "options": { "raw": { "language": "json" } } } }, "status": "Bad Gateway", "code": 502, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"statusCode\": 502,\n \"code\": \"PROVIDER_UNAVAILABLE\",\n \"message\": \"PESAFLOW is unavailable (sandbox simulation)\",\n \"retryable\": true,\n \"requestId\": \"cmhd2k7q80001s60h3x9f2a1b\"\n}", "cookie": [], "_postman_previewlanguage": "json" } ], "event": [], "protocolProfileBehavior": { "disableBodyPruning": true } } ], "event": [] }, { "id": "dff3ace1-0831-4519-a2e6-91fe2c87be46", "name": "Tax", "description": { "content": "KRA PIN lookups.", "type": "text/plain" }, "item": [ { "id": "18ae8e0f-58fe-4945-8db7-10f92845d616", "name": "KRA PIN by ID number (KRA)", "request": { "name": "KRA PIN by ID number (KRA)", "description": { "content": "Returns the KRA PIN registered to a Kenyan national ID number and the taxpayer name on it.\n\n**Price:** set by your bundle; one charge per call. \"Not found\" answers (`result.found: false`) are charged. Source failures return `502` and are refunded.\n\n**Try it:** choose a scenario from the example menu under the code sample and press **Test Request**. Paste your test key into **Authentication** in the window that opens (it is remembered); test keys return sandbox sample data, free.", "type": "text/plain" }, "url": { "path": [ "v1", "verifications", "tax.kra-pin" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [] }, "header": [ { "disabled": true, "description": "Makes retries safe: a repeat with the same key and body returns the original verification without charging again. Up to 255 characters.", "key": "Idempotency-Key", "value": "" }, { "key": "Content-Type", "value": "application/json" }, { "key": "Accept", "value": "application/json" } ], "method": "POST", "auth": null, "body": { "mode": "raw", "raw": "{\n \"idNumber\": \"\"\n}", "options": { "raw": { "language": "json" } } } }, "response": [ { "id": "ca72ac10-3d12-4569-b320-2942e54216cc", "name": "Verification completed; see `result`.", "originalRequest": { "url": { "path": [ "v1", "verifications", "tax.kra-pin" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [] }, "header": [ { "description": { "content": "Added as a part of security scheme: bearer", "type": "text/plain" }, "key": "Authorization", "value": "Bearer " }, { "disabled": true, "description": "Makes retries safe: a repeat with the same key and body returns the original verification without charging again. Up to 255 characters.", "key": "Idempotency-Key", "value": "6f1c2a90-order-1042" }, { "key": "Accept", "value": "application/json" } ], "method": "POST", "body": { "mode": "raw", "raw": "{\n \"idNumber\": \"12345678\"\n}", "options": { "raw": { "language": "json" } } } }, "status": "OK", "code": 200, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"id\": \"cmhd2k7q80001s60h3x9f2a1b\",\n \"api\": \"tax.kra-pin\",\n \"status\": \"COMPLETED\",\n \"environment\": \"LIVE\",\n \"result\": {\n \"found\": true,\n \"idNumber\": \"12345678\",\n \"taxpayer\": {\n \"pin\": \"A000000000S\",\n \"name\": \"JANE WANJIKU DOE\"\n }\n },\n \"error\": null,\n \"cost\": \"50\",\n \"latencyMs\": 412,\n \"createdAt\": \"2026-10-30T09:15:02.118Z\",\n \"completedAt\": \"2026-10-30T09:15:02.530Z\"\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "3dc42322-2bc2-40a4-9569-30931de6f5cf", "name": "The input failed validation; `issues` lists each problem.", "originalRequest": { "url": { "path": [ "v1", "verifications", "tax.kra-pin" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [] }, "header": [ { "description": { "content": "Added as a part of security scheme: bearer", "type": "text/plain" }, "key": "Authorization", "value": "Bearer " }, { "disabled": true, "description": "Makes retries safe: a repeat with the same key and body returns the original verification without charging again. Up to 255 characters.", "key": "Idempotency-Key", "value": "6f1c2a90-order-1042" }, { "key": "Accept", "value": "application/json" } ], "method": "POST", "body": { "mode": "raw", "raw": "{\n \"idNumber\": \"12345678\"\n}", "options": { "raw": { "language": "json" } } } }, "status": "Bad Request", "code": 400, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"statusCode\": 400,\n \"message\": \"Validation failed\",\n \"issues\": [\n {\n \"expected\": \"string\",\n \"code\": \"invalid_type\",\n \"path\": [\n \"idNumber\"\n ],\n \"message\": \"Invalid input: expected string, received undefined\"\n }\n ]\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "702d4224-5946-4f2d-849d-272ba6172395", "name": "Missing, unknown or revoked API key.", "originalRequest": { "url": { "path": [ "v1", "verifications", "tax.kra-pin" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [] }, "header": [ { "description": { "content": "Added as a part of security scheme: bearer", "type": "text/plain" }, "key": "Authorization", "value": "Bearer " }, { "disabled": true, "description": "Makes retries safe: a repeat with the same key and body returns the original verification without charging again. Up to 255 characters.", "key": "Idempotency-Key", "value": "6f1c2a90-order-1042" }, { "key": "Accept", "value": "application/json" } ], "method": "POST", "body": { "mode": "raw", "raw": "{\n \"idNumber\": \"12345678\"\n}", "options": { "raw": { "language": "json" } } } }, "status": "Unauthorized", "code": 401, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"statusCode\": 401,\n \"message\": \"Invalid API key\"\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "3cfc2f66-3d12-4104-9660-b5217442e134", "name": "The wallet can't cover this call (live keys only). Nothing was charged.", "originalRequest": { "url": { "path": [ "v1", "verifications", "tax.kra-pin" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [] }, "header": [ { "description": { "content": "Added as a part of security scheme: bearer", "type": "text/plain" }, "key": "Authorization", "value": "Bearer " }, { "disabled": true, "description": "Makes retries safe: a repeat with the same key and body returns the original verification without charging again. Up to 255 characters.", "key": "Idempotency-Key", "value": "6f1c2a90-order-1042" }, { "key": "Accept", "value": "application/json" } ], "method": "POST", "body": { "mode": "raw", "raw": "{\n \"idNumber\": \"12345678\"\n}", "options": { "raw": { "language": "json" } } } }, "status": "Payment Required", "code": 402, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"statusCode\": 402,\n \"code\": \"INSUFFICIENT_FUNDS\",\n \"message\": \"Insufficient wallet balance\"\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "e894ecbc-037a-47dd-88cf-5a02f3dbf85d", "name": "This API isn't in your organization's bundle.", "originalRequest": { "url": { "path": [ "v1", "verifications", "tax.kra-pin" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [] }, "header": [ { "description": { "content": "Added as a part of security scheme: bearer", "type": "text/plain" }, "key": "Authorization", "value": "Bearer " }, { "disabled": true, "description": "Makes retries safe: a repeat with the same key and body returns the original verification without charging again. Up to 255 characters.", "key": "Idempotency-Key", "value": "6f1c2a90-order-1042" }, { "key": "Accept", "value": "application/json" } ], "method": "POST", "body": { "mode": "raw", "raw": "{\n \"idNumber\": \"12345678\"\n}", "options": { "raw": { "language": "json" } } } }, "status": "Forbidden", "code": 403, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"statusCode\": 403,\n \"code\": \"API_NOT_IN_PLAN\",\n \"message\": \"Your plan does not include identity.national-id\"\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "16005794-20bd-4cf7-b163-85b690317e99", "name": "The `Idempotency-Key` was used for a different request, or that request is still running.", "originalRequest": { "url": { "path": [ "v1", "verifications", "tax.kra-pin" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [] }, "header": [ { "description": { "content": "Added as a part of security scheme: bearer", "type": "text/plain" }, "key": "Authorization", "value": "Bearer " }, { "disabled": true, "description": "Makes retries safe: a repeat with the same key and body returns the original verification without charging again. Up to 255 characters.", "key": "Idempotency-Key", "value": "6f1c2a90-order-1042" }, { "key": "Accept", "value": "application/json" } ], "method": "POST", "body": { "mode": "raw", "raw": "{\n \"idNumber\": \"12345678\"\n}", "options": { "raw": { "language": "json" } } } }, "status": "Conflict", "code": 409, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"statusCode\": 409,\n \"message\": \"Idempotency-Key was already used for a different request\"\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "94a75eb5-f627-4da9-89e5-80d2ff5b990f", "name": "Monthly quota reached, or more than 120 requests a minute.", "originalRequest": { "url": { "path": [ "v1", "verifications", "tax.kra-pin" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [] }, "header": [ { "description": { "content": "Added as a part of security scheme: bearer", "type": "text/plain" }, "key": "Authorization", "value": "Bearer " }, { "disabled": true, "description": "Makes retries safe: a repeat with the same key and body returns the original verification without charging again. Up to 255 characters.", "key": "Idempotency-Key", "value": "6f1c2a90-order-1042" }, { "key": "Accept", "value": "application/json" } ], "method": "POST", "body": { "mode": "raw", "raw": "{\n \"idNumber\": \"12345678\"\n}", "options": { "raw": { "language": "json" } } } }, "status": "Too Many Requests", "code": 429, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"statusCode\": 429,\n \"code\": \"QUOTA_EXCEEDED\",\n \"message\": \"Monthly quota of 1000 calls reached\"\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "d2bd7cf0-b90f-4f4a-932a-bba96e83ea9c", "name": "The source failed or didn't answer. The charge was refunded.", "originalRequest": { "url": { "path": [ "v1", "verifications", "tax.kra-pin" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [] }, "header": [ { "description": { "content": "Added as a part of security scheme: bearer", "type": "text/plain" }, "key": "Authorization", "value": "Bearer " }, { "disabled": true, "description": "Makes retries safe: a repeat with the same key and body returns the original verification without charging again. Up to 255 characters.", "key": "Idempotency-Key", "value": "6f1c2a90-order-1042" }, { "key": "Accept", "value": "application/json" } ], "method": "POST", "body": { "mode": "raw", "raw": "{\n \"idNumber\": \"12345678\"\n}", "options": { "raw": { "language": "json" } } } }, "status": "Bad Gateway", "code": 502, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"statusCode\": 502,\n \"code\": \"PROVIDER_UNAVAILABLE\",\n \"message\": \"KRA is unavailable (sandbox simulation)\",\n \"retryable\": true,\n \"requestId\": \"cmhd2k7q80001s60h3x9f2a1b\"\n}", "cookie": [], "_postman_previewlanguage": "json" } ], "event": [], "protocolProfileBehavior": { "disableBodyPruning": true } } ], "event": [] }, { "id": "e16c29c8-48df-4a50-af40-67d24c069843", "name": "Businesses", "description": { "content": "Company and business-name records from the Business Registration Service.", "type": "text/plain" }, "item": [ { "id": "6f21ac29-82fc-43b1-9de4-901c8fe87142", "name": "Business registration search (BRS via Pesaflow)", "request": { "name": "Business registration search (BRS via Pesaflow)", "description": { "content": "Returns the Business Registration Service record: name, status, registration date, KRA PIN, addresses and partners/directors.\n\n**Price:** set by your bundle; one charge per call. \"Not found\" answers (`result.found: false`) are charged. Source failures return `502` and are refunded.\n\n**Try it:** choose a scenario from the example menu under the code sample and press **Test Request**. Paste your test key into **Authentication** in the window that opens (it is remembered); test keys return sandbox sample data, free.", "type": "text/plain" }, "url": { "path": [ "v1", "verifications", "business.registration" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [] }, "header": [ { "disabled": true, "description": "Makes retries safe: a repeat with the same key and body returns the original verification without charging again. Up to 255 characters.", "key": "Idempotency-Key", "value": "" }, { "key": "Content-Type", "value": "application/json" }, { "key": "Accept", "value": "application/json" } ], "method": "POST", "auth": null, "body": { "mode": "raw", "raw": "{\n \"registrationNumber\": \"\"\n}", "options": { "raw": { "language": "json" } } } }, "response": [ { "id": "ccd71d32-d0b3-4e13-b904-84a9350891fb", "name": "Verification completed; see `result`.", "originalRequest": { "url": { "path": [ "v1", "verifications", "business.registration" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [] }, "header": [ { "description": { "content": "Added as a part of security scheme: bearer", "type": "text/plain" }, "key": "Authorization", "value": "Bearer " }, { "disabled": true, "description": "Makes retries safe: a repeat with the same key and body returns the original verification without charging again. Up to 255 characters.", "key": "Idempotency-Key", "value": "6f1c2a90-order-1042" }, { "key": "Accept", "value": "application/json" } ], "method": "POST", "body": { "mode": "raw", "raw": "{\n \"registrationNumber\": \"PVT-ABC123\"\n}", "options": { "raw": { "language": "json" } } } }, "status": "OK", "code": 200, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"id\": \"cmhd2k7q80001s60h3x9f2a1b\",\n \"api\": \"business.registration\",\n \"status\": \"COMPLETED\",\n \"environment\": \"LIVE\",\n \"result\": {\n \"found\": true,\n \"business\": {\n \"registrationNumber\": \"PVT-ABC123\",\n \"name\": \"SANDBOX TRADERS LIMITED\",\n \"status\": \"Registered\",\n \"registered\": true,\n \"kraPin\": \"P000000000Z\",\n \"registrationDate\": \"2018-06-01\",\n \"physicalAddress\": \"NAIROBI\",\n \"postalAddress\": \"P.O. BOX 1-00100\",\n \"partners\": [\n {\n \"name\": \"JANE WANJIKU DOE\",\n \"shares\": 1000\n }\n ]\n }\n },\n \"error\": null,\n \"cost\": \"50\",\n \"latencyMs\": 412,\n \"createdAt\": \"2026-10-30T09:15:02.118Z\",\n \"completedAt\": \"2026-10-30T09:15:02.530Z\"\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "3ff7dba1-6c6e-4a66-aa7e-cc2fe7138bda", "name": "The input failed validation; `issues` lists each problem.", "originalRequest": { "url": { "path": [ "v1", "verifications", "business.registration" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [] }, "header": [ { "description": { "content": "Added as a part of security scheme: bearer", "type": "text/plain" }, "key": "Authorization", "value": "Bearer " }, { "disabled": true, "description": "Makes retries safe: a repeat with the same key and body returns the original verification without charging again. Up to 255 characters.", "key": "Idempotency-Key", "value": "6f1c2a90-order-1042" }, { "key": "Accept", "value": "application/json" } ], "method": "POST", "body": { "mode": "raw", "raw": "{\n \"registrationNumber\": \"PVT-ABC123\"\n}", "options": { "raw": { "language": "json" } } } }, "status": "Bad Request", "code": 400, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"statusCode\": 400,\n \"message\": \"Validation failed\",\n \"issues\": [\n {\n \"expected\": \"string\",\n \"code\": \"invalid_type\",\n \"path\": [\n \"registrationNumber\"\n ],\n \"message\": \"Invalid input: expected string, received undefined\"\n }\n ]\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "bcc3d03e-0ee7-4ed7-8b22-5e4bbe2adc09", "name": "Missing, unknown or revoked API key.", "originalRequest": { "url": { "path": [ "v1", "verifications", "business.registration" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [] }, "header": [ { "description": { "content": "Added as a part of security scheme: bearer", "type": "text/plain" }, "key": "Authorization", "value": "Bearer " }, { "disabled": true, "description": "Makes retries safe: a repeat with the same key and body returns the original verification without charging again. Up to 255 characters.", "key": "Idempotency-Key", "value": "6f1c2a90-order-1042" }, { "key": "Accept", "value": "application/json" } ], "method": "POST", "body": { "mode": "raw", "raw": "{\n \"registrationNumber\": \"PVT-ABC123\"\n}", "options": { "raw": { "language": "json" } } } }, "status": "Unauthorized", "code": 401, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"statusCode\": 401,\n \"message\": \"Invalid API key\"\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "4d731c36-e618-498c-a668-32b03bf64ff5", "name": "The wallet can't cover this call (live keys only). Nothing was charged.", "originalRequest": { "url": { "path": [ "v1", "verifications", "business.registration" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [] }, "header": [ { "description": { "content": "Added as a part of security scheme: bearer", "type": "text/plain" }, "key": "Authorization", "value": "Bearer " }, { "disabled": true, "description": "Makes retries safe: a repeat with the same key and body returns the original verification without charging again. Up to 255 characters.", "key": "Idempotency-Key", "value": "6f1c2a90-order-1042" }, { "key": "Accept", "value": "application/json" } ], "method": "POST", "body": { "mode": "raw", "raw": "{\n \"registrationNumber\": \"PVT-ABC123\"\n}", "options": { "raw": { "language": "json" } } } }, "status": "Payment Required", "code": 402, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"statusCode\": 402,\n \"code\": \"INSUFFICIENT_FUNDS\",\n \"message\": \"Insufficient wallet balance\"\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "35024db9-2f6b-48d5-ac8f-16c97c14e87c", "name": "This API isn't in your organization's bundle.", "originalRequest": { "url": { "path": [ "v1", "verifications", "business.registration" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [] }, "header": [ { "description": { "content": "Added as a part of security scheme: bearer", "type": "text/plain" }, "key": "Authorization", "value": "Bearer " }, { "disabled": true, "description": "Makes retries safe: a repeat with the same key and body returns the original verification without charging again. Up to 255 characters.", "key": "Idempotency-Key", "value": "6f1c2a90-order-1042" }, { "key": "Accept", "value": "application/json" } ], "method": "POST", "body": { "mode": "raw", "raw": "{\n \"registrationNumber\": \"PVT-ABC123\"\n}", "options": { "raw": { "language": "json" } } } }, "status": "Forbidden", "code": 403, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"statusCode\": 403,\n \"code\": \"API_NOT_IN_PLAN\",\n \"message\": \"Your plan does not include identity.national-id\"\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "cac4ba60-1739-4df7-b2bb-8ccda02b4c03", "name": "The `Idempotency-Key` was used for a different request, or that request is still running.", "originalRequest": { "url": { "path": [ "v1", "verifications", "business.registration" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [] }, "header": [ { "description": { "content": "Added as a part of security scheme: bearer", "type": "text/plain" }, "key": "Authorization", "value": "Bearer " }, { "disabled": true, "description": "Makes retries safe: a repeat with the same key and body returns the original verification without charging again. Up to 255 characters.", "key": "Idempotency-Key", "value": "6f1c2a90-order-1042" }, { "key": "Accept", "value": "application/json" } ], "method": "POST", "body": { "mode": "raw", "raw": "{\n \"registrationNumber\": \"PVT-ABC123\"\n}", "options": { "raw": { "language": "json" } } } }, "status": "Conflict", "code": 409, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"statusCode\": 409,\n \"message\": \"Idempotency-Key was already used for a different request\"\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "091aed86-4e6a-45e0-97bb-d059b5c3b482", "name": "Monthly quota reached, or more than 120 requests a minute.", "originalRequest": { "url": { "path": [ "v1", "verifications", "business.registration" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [] }, "header": [ { "description": { "content": "Added as a part of security scheme: bearer", "type": "text/plain" }, "key": "Authorization", "value": "Bearer " }, { "disabled": true, "description": "Makes retries safe: a repeat with the same key and body returns the original verification without charging again. Up to 255 characters.", "key": "Idempotency-Key", "value": "6f1c2a90-order-1042" }, { "key": "Accept", "value": "application/json" } ], "method": "POST", "body": { "mode": "raw", "raw": "{\n \"registrationNumber\": \"PVT-ABC123\"\n}", "options": { "raw": { "language": "json" } } } }, "status": "Too Many Requests", "code": 429, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"statusCode\": 429,\n \"code\": \"QUOTA_EXCEEDED\",\n \"message\": \"Monthly quota of 1000 calls reached\"\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "ec29ebd9-a983-4954-ba33-6840a4d799cc", "name": "The source failed or didn't answer. The charge was refunded.", "originalRequest": { "url": { "path": [ "v1", "verifications", "business.registration" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [] }, "header": [ { "description": { "content": "Added as a part of security scheme: bearer", "type": "text/plain" }, "key": "Authorization", "value": "Bearer " }, { "disabled": true, "description": "Makes retries safe: a repeat with the same key and body returns the original verification without charging again. Up to 255 characters.", "key": "Idempotency-Key", "value": "6f1c2a90-order-1042" }, { "key": "Accept", "value": "application/json" } ], "method": "POST", "body": { "mode": "raw", "raw": "{\n \"registrationNumber\": \"PVT-ABC123\"\n}", "options": { "raw": { "language": "json" } } } }, "status": "Bad Gateway", "code": 502, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"statusCode\": 502,\n \"code\": \"PROVIDER_UNAVAILABLE\",\n \"message\": \"PESAFLOW is unavailable (sandbox simulation)\",\n \"retryable\": true,\n \"requestId\": \"cmhd2k7q80001s60h3x9f2a1b\"\n}", "cookie": [], "_postman_previewlanguage": "json" } ], "event": [], "protocolProfileBehavior": { "disableBodyPruning": true } } ], "event": [] }, { "id": "bfe29bd2-3ccf-4550-a3e6-a41babc724f4", "name": "Phone numbers", "description": { "content": "Safaricom mobile number checks: who a number is registered to, recent SIM swaps and how long a number has been on the network. Numbers on other networks can't be checked.", "type": "text/plain" }, "item": [ { "id": "3777bec3-b453-40c9-b348-6d2c5ee4f9d5", "name": "Phone number ownership (Safaricom)", "request": { "name": "Phone number ownership (Safaricom)", "description": { "content": "Checks with Safaricom whether a Safaricom mobile number is registered to the holder of the given ID. Safaricom answers only yes or no (`matched`); no subscriber details are returned. Numbers on other networks, or ported away from Safaricom, can't be checked.\n\n**Price:** set by your bundle; one charge per call. \"Not found\" answers (`result.found: false`) are charged. Source failures return `502` and are refunded.\n\n**Try it:** choose a scenario from the example menu under the code sample and press **Test Request**. Paste your test key into **Authentication** in the window that opens (it is remembered); test keys return sandbox sample data, free.", "type": "text/plain" }, "url": { "path": [ "v1", "verifications", "phone.ownership" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [] }, "header": [ { "disabled": true, "description": "Makes retries safe: a repeat with the same key and body returns the original verification without charging again. Up to 255 characters.", "key": "Idempotency-Key", "value": "" }, { "key": "Content-Type", "value": "application/json" }, { "key": "Accept", "value": "application/json" } ], "method": "POST", "auth": null, "body": { "mode": "raw", "raw": "{\n \"phoneNumber\": \"\",\n \"idNumber\": \"\",\n \"idType\": \"NATIONAL_ID\"\n}", "options": { "raw": { "language": "json" } } } }, "response": [ { "id": "b61a8808-b53b-48d6-bb47-b03c124da24b", "name": "Verification completed; see `result`.", "originalRequest": { "url": { "path": [ "v1", "verifications", "phone.ownership" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [] }, "header": [ { "description": { "content": "Added as a part of security scheme: bearer", "type": "text/plain" }, "key": "Authorization", "value": "Bearer " }, { "disabled": true, "description": "Makes retries safe: a repeat with the same key and body returns the original verification without charging again. Up to 255 characters.", "key": "Idempotency-Key", "value": "6f1c2a90-order-1042" }, { "key": "Accept", "value": "application/json" } ], "method": "POST", "body": { "mode": "raw", "raw": "{\n \"phoneNumber\": \"0712345678\",\n \"idNumber\": \"12345678\"\n}", "options": { "raw": { "language": "json" } } } }, "status": "OK", "code": 200, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"id\": \"cmhd2k7q80001s60h3x9f2a1b\",\n \"api\": \"phone.ownership\",\n \"status\": \"COMPLETED\",\n \"environment\": \"LIVE\",\n \"result\": {\n \"found\": true,\n \"phoneNumberEndsWith\": \"678\",\n \"idType\": \"NATIONAL_ID\",\n \"matched\": true\n },\n \"error\": null,\n \"cost\": \"50\",\n \"latencyMs\": 412,\n \"createdAt\": \"2026-10-30T09:15:02.118Z\",\n \"completedAt\": \"2026-10-30T09:15:02.530Z\"\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "baa7a7cb-7d99-4b66-b612-7d124deaee4d", "name": "The input failed validation; `issues` lists each problem.", "originalRequest": { "url": { "path": [ "v1", "verifications", "phone.ownership" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [] }, "header": [ { "description": { "content": "Added as a part of security scheme: bearer", "type": "text/plain" }, "key": "Authorization", "value": "Bearer " }, { "disabled": true, "description": "Makes retries safe: a repeat with the same key and body returns the original verification without charging again. Up to 255 characters.", "key": "Idempotency-Key", "value": "6f1c2a90-order-1042" }, { "key": "Accept", "value": "application/json" } ], "method": "POST", "body": { "mode": "raw", "raw": "{\n \"phoneNumber\": \"0712345678\",\n \"idNumber\": \"12345678\"\n}", "options": { "raw": { "language": "json" } } } }, "status": "Bad Request", "code": 400, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"statusCode\": 400,\n \"message\": \"Validation failed\",\n \"issues\": [\n {\n \"expected\": \"string\",\n \"code\": \"invalid_type\",\n \"path\": [\n \"phoneNumber\"\n ],\n \"message\": \"Invalid input: expected string, received undefined\"\n },\n {\n \"expected\": \"string\",\n \"code\": \"invalid_type\",\n \"path\": [\n \"idNumber\"\n ],\n \"message\": \"Invalid input: expected string, received undefined\"\n }\n ]\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "11cb52c3-3a7d-48e1-8eb5-650a79a88934", "name": "Missing, unknown or revoked API key.", "originalRequest": { "url": { "path": [ "v1", "verifications", "phone.ownership" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [] }, "header": [ { "description": { "content": "Added as a part of security scheme: bearer", "type": "text/plain" }, "key": "Authorization", "value": "Bearer " }, { "disabled": true, "description": "Makes retries safe: a repeat with the same key and body returns the original verification without charging again. Up to 255 characters.", "key": "Idempotency-Key", "value": "6f1c2a90-order-1042" }, { "key": "Accept", "value": "application/json" } ], "method": "POST", "body": { "mode": "raw", "raw": "{\n \"phoneNumber\": \"0712345678\",\n \"idNumber\": \"12345678\"\n}", "options": { "raw": { "language": "json" } } } }, "status": "Unauthorized", "code": 401, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"statusCode\": 401,\n \"message\": \"Invalid API key\"\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "e2560de9-be94-408b-9a9a-a8d8fa931357", "name": "The wallet can't cover this call (live keys only). Nothing was charged.", "originalRequest": { "url": { "path": [ "v1", "verifications", "phone.ownership" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [] }, "header": [ { "description": { "content": "Added as a part of security scheme: bearer", "type": "text/plain" }, "key": "Authorization", "value": "Bearer " }, { "disabled": true, "description": "Makes retries safe: a repeat with the same key and body returns the original verification without charging again. Up to 255 characters.", "key": "Idempotency-Key", "value": "6f1c2a90-order-1042" }, { "key": "Accept", "value": "application/json" } ], "method": "POST", "body": { "mode": "raw", "raw": "{\n \"phoneNumber\": \"0712345678\",\n \"idNumber\": \"12345678\"\n}", "options": { "raw": { "language": "json" } } } }, "status": "Payment Required", "code": 402, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"statusCode\": 402,\n \"code\": \"INSUFFICIENT_FUNDS\",\n \"message\": \"Insufficient wallet balance\"\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "efff8d01-7894-467a-a2d5-fa5a48f379ae", "name": "This API isn't in your organization's bundle.", "originalRequest": { "url": { "path": [ "v1", "verifications", "phone.ownership" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [] }, "header": [ { "description": { "content": "Added as a part of security scheme: bearer", "type": "text/plain" }, "key": "Authorization", "value": "Bearer " }, { "disabled": true, "description": "Makes retries safe: a repeat with the same key and body returns the original verification without charging again. Up to 255 characters.", "key": "Idempotency-Key", "value": "6f1c2a90-order-1042" }, { "key": "Accept", "value": "application/json" } ], "method": "POST", "body": { "mode": "raw", "raw": "{\n \"phoneNumber\": \"0712345678\",\n \"idNumber\": \"12345678\"\n}", "options": { "raw": { "language": "json" } } } }, "status": "Forbidden", "code": 403, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"statusCode\": 403,\n \"code\": \"API_NOT_IN_PLAN\",\n \"message\": \"Your plan does not include identity.national-id\"\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "9c4f8dfe-7f25-44cb-bdda-71fd7d2d0fcb", "name": "The `Idempotency-Key` was used for a different request, or that request is still running.", "originalRequest": { "url": { "path": [ "v1", "verifications", "phone.ownership" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [] }, "header": [ { "description": { "content": "Added as a part of security scheme: bearer", "type": "text/plain" }, "key": "Authorization", "value": "Bearer " }, { "disabled": true, "description": "Makes retries safe: a repeat with the same key and body returns the original verification without charging again. Up to 255 characters.", "key": "Idempotency-Key", "value": "6f1c2a90-order-1042" }, { "key": "Accept", "value": "application/json" } ], "method": "POST", "body": { "mode": "raw", "raw": "{\n \"phoneNumber\": \"0712345678\",\n \"idNumber\": \"12345678\"\n}", "options": { "raw": { "language": "json" } } } }, "status": "Conflict", "code": 409, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"statusCode\": 409,\n \"message\": \"Idempotency-Key was already used for a different request\"\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "a84690f2-cf27-450e-9425-8af722afa484", "name": "Monthly quota reached, or more than 120 requests a minute.", "originalRequest": { "url": { "path": [ "v1", "verifications", "phone.ownership" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [] }, "header": [ { "description": { "content": "Added as a part of security scheme: bearer", "type": "text/plain" }, "key": "Authorization", "value": "Bearer " }, { "disabled": true, "description": "Makes retries safe: a repeat with the same key and body returns the original verification without charging again. Up to 255 characters.", "key": "Idempotency-Key", "value": "6f1c2a90-order-1042" }, { "key": "Accept", "value": "application/json" } ], "method": "POST", "body": { "mode": "raw", "raw": "{\n \"phoneNumber\": \"0712345678\",\n \"idNumber\": \"12345678\"\n}", "options": { "raw": { "language": "json" } } } }, "status": "Too Many Requests", "code": 429, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"statusCode\": 429,\n \"code\": \"QUOTA_EXCEEDED\",\n \"message\": \"Monthly quota of 1000 calls reached\"\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "82dd6d0b-9044-4ba8-b46a-43f7be2f91ab", "name": "The source failed or didn't answer. The charge was refunded.", "originalRequest": { "url": { "path": [ "v1", "verifications", "phone.ownership" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [] }, "header": [ { "description": { "content": "Added as a part of security scheme: bearer", "type": "text/plain" }, "key": "Authorization", "value": "Bearer " }, { "disabled": true, "description": "Makes retries safe: a repeat with the same key and body returns the original verification without charging again. Up to 255 characters.", "key": "Idempotency-Key", "value": "6f1c2a90-order-1042" }, { "key": "Accept", "value": "application/json" } ], "method": "POST", "body": { "mode": "raw", "raw": "{\n \"phoneNumber\": \"0712345678\",\n \"idNumber\": \"12345678\"\n}", "options": { "raw": { "language": "json" } } } }, "status": "Bad Gateway", "code": 502, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"statusCode\": 502,\n \"code\": \"PROVIDER_UNAVAILABLE\",\n \"message\": \"SAFARICOM is unavailable (sandbox simulation)\",\n \"retryable\": true,\n \"requestId\": \"cmhd2k7q80001s60h3x9f2a1b\"\n}", "cookie": [], "_postman_previewlanguage": "json" } ], "event": [], "protocolProfileBehavior": { "disableBodyPruning": true } }, { "id": "4d801f5c-60cf-464c-b34f-d640e95c24d3", "name": "Last SIM swap (Safaricom)", "request": { "name": "Last SIM swap (Safaricom)", "description": { "content": "When the SIM behind a Safaricom number was last swapped. Safaricom only looks back about three months: `lastSwapDate` is null when there was no swap in that window. `daysSinceSwap` helps flag recent swaps, a common sign of account takeover.\n\n**Price:** set by your bundle; one charge per call. \"Not found\" answers (`result.found: false`) are charged. Source failures return `502` and are refunded.\n\n**Try it:** choose a scenario from the example menu under the code sample and press **Test Request**. Paste your test key into **Authentication** in the window that opens (it is remembered); test keys return sandbox sample data, free.", "type": "text/plain" }, "url": { "path": [ "v1", "verifications", "phone.sim-swap" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [] }, "header": [ { "disabled": true, "description": "Makes retries safe: a repeat with the same key and body returns the original verification without charging again. Up to 255 characters.", "key": "Idempotency-Key", "value": "" }, { "key": "Content-Type", "value": "application/json" }, { "key": "Accept", "value": "application/json" } ], "method": "POST", "auth": null, "body": { "mode": "raw", "raw": "{\n \"phoneNumber\": \"\"\n}", "options": { "raw": { "language": "json" } } } }, "response": [ { "id": "63479a18-14ec-474d-b826-b5741cd57b8b", "name": "Verification completed; see `result`.", "originalRequest": { "url": { "path": [ "v1", "verifications", "phone.sim-swap" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [] }, "header": [ { "description": { "content": "Added as a part of security scheme: bearer", "type": "text/plain" }, "key": "Authorization", "value": "Bearer " }, { "disabled": true, "description": "Makes retries safe: a repeat with the same key and body returns the original verification without charging again. Up to 255 characters.", "key": "Idempotency-Key", "value": "6f1c2a90-order-1042" }, { "key": "Accept", "value": "application/json" } ], "method": "POST", "body": { "mode": "raw", "raw": "{\n \"phoneNumber\": \"0712345678\"\n}", "options": { "raw": { "language": "json" } } } }, "status": "OK", "code": 200, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"id\": \"cmhd2k7q80001s60h3x9f2a1b\",\n \"api\": \"phone.sim-swap\",\n \"status\": \"COMPLETED\",\n \"environment\": \"LIVE\",\n \"result\": {\n \"found\": true,\n \"phoneNumberEndsWith\": \"678\",\n \"lastSwapDate\": \"2026-10-21\",\n \"daysSinceSwap\": 12\n },\n \"error\": null,\n \"cost\": \"50\",\n \"latencyMs\": 412,\n \"createdAt\": \"2026-10-30T09:15:02.118Z\",\n \"completedAt\": \"2026-10-30T09:15:02.530Z\"\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "f3433fc4-3752-4dc0-ab4b-f75f1235daae", "name": "The input failed validation; `issues` lists each problem.", "originalRequest": { "url": { "path": [ "v1", "verifications", "phone.sim-swap" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [] }, "header": [ { "description": { "content": "Added as a part of security scheme: bearer", "type": "text/plain" }, "key": "Authorization", "value": "Bearer " }, { "disabled": true, "description": "Makes retries safe: a repeat with the same key and body returns the original verification without charging again. Up to 255 characters.", "key": "Idempotency-Key", "value": "6f1c2a90-order-1042" }, { "key": "Accept", "value": "application/json" } ], "method": "POST", "body": { "mode": "raw", "raw": "{\n \"phoneNumber\": \"0712345678\"\n}", "options": { "raw": { "language": "json" } } } }, "status": "Bad Request", "code": 400, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"statusCode\": 400,\n \"message\": \"Validation failed\",\n \"issues\": [\n {\n \"expected\": \"string\",\n \"code\": \"invalid_type\",\n \"path\": [\n \"phoneNumber\"\n ],\n \"message\": \"Invalid input: expected string, received undefined\"\n }\n ]\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "f43c8e86-8cd8-4667-ab10-c5bded59fd37", "name": "Missing, unknown or revoked API key.", "originalRequest": { "url": { "path": [ "v1", "verifications", "phone.sim-swap" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [] }, "header": [ { "description": { "content": "Added as a part of security scheme: bearer", "type": "text/plain" }, "key": "Authorization", "value": "Bearer " }, { "disabled": true, "description": "Makes retries safe: a repeat with the same key and body returns the original verification without charging again. Up to 255 characters.", "key": "Idempotency-Key", "value": "6f1c2a90-order-1042" }, { "key": "Accept", "value": "application/json" } ], "method": "POST", "body": { "mode": "raw", "raw": "{\n \"phoneNumber\": \"0712345678\"\n}", "options": { "raw": { "language": "json" } } } }, "status": "Unauthorized", "code": 401, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"statusCode\": 401,\n \"message\": \"Invalid API key\"\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "cb9730e4-ae81-4b47-aca8-f4e0087e7268", "name": "The wallet can't cover this call (live keys only). Nothing was charged.", "originalRequest": { "url": { "path": [ "v1", "verifications", "phone.sim-swap" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [] }, "header": [ { "description": { "content": "Added as a part of security scheme: bearer", "type": "text/plain" }, "key": "Authorization", "value": "Bearer " }, { "disabled": true, "description": "Makes retries safe: a repeat with the same key and body returns the original verification without charging again. Up to 255 characters.", "key": "Idempotency-Key", "value": "6f1c2a90-order-1042" }, { "key": "Accept", "value": "application/json" } ], "method": "POST", "body": { "mode": "raw", "raw": "{\n \"phoneNumber\": \"0712345678\"\n}", "options": { "raw": { "language": "json" } } } }, "status": "Payment Required", "code": 402, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"statusCode\": 402,\n \"code\": \"INSUFFICIENT_FUNDS\",\n \"message\": \"Insufficient wallet balance\"\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "f785e640-91f1-4988-909e-1541f8529b0c", "name": "This API isn't in your organization's bundle.", "originalRequest": { "url": { "path": [ "v1", "verifications", "phone.sim-swap" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [] }, "header": [ { "description": { "content": "Added as a part of security scheme: bearer", "type": "text/plain" }, "key": "Authorization", "value": "Bearer " }, { "disabled": true, "description": "Makes retries safe: a repeat with the same key and body returns the original verification without charging again. Up to 255 characters.", "key": "Idempotency-Key", "value": "6f1c2a90-order-1042" }, { "key": "Accept", "value": "application/json" } ], "method": "POST", "body": { "mode": "raw", "raw": "{\n \"phoneNumber\": \"0712345678\"\n}", "options": { "raw": { "language": "json" } } } }, "status": "Forbidden", "code": 403, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"statusCode\": 403,\n \"code\": \"API_NOT_IN_PLAN\",\n \"message\": \"Your plan does not include identity.national-id\"\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "1ba4a054-afc7-4baa-9ecd-d1dfb8eaa99c", "name": "The `Idempotency-Key` was used for a different request, or that request is still running.", "originalRequest": { "url": { "path": [ "v1", "verifications", "phone.sim-swap" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [] }, "header": [ { "description": { "content": "Added as a part of security scheme: bearer", "type": "text/plain" }, "key": "Authorization", "value": "Bearer " }, { "disabled": true, "description": "Makes retries safe: a repeat with the same key and body returns the original verification without charging again. Up to 255 characters.", "key": "Idempotency-Key", "value": "6f1c2a90-order-1042" }, { "key": "Accept", "value": "application/json" } ], "method": "POST", "body": { "mode": "raw", "raw": "{\n \"phoneNumber\": \"0712345678\"\n}", "options": { "raw": { "language": "json" } } } }, "status": "Conflict", "code": 409, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"statusCode\": 409,\n \"message\": \"Idempotency-Key was already used for a different request\"\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "da82f1f9-6d04-47f3-9c22-b0dcf3578e2d", "name": "Monthly quota reached, or more than 120 requests a minute.", "originalRequest": { "url": { "path": [ "v1", "verifications", "phone.sim-swap" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [] }, "header": [ { "description": { "content": "Added as a part of security scheme: bearer", "type": "text/plain" }, "key": "Authorization", "value": "Bearer " }, { "disabled": true, "description": "Makes retries safe: a repeat with the same key and body returns the original verification without charging again. Up to 255 characters.", "key": "Idempotency-Key", "value": "6f1c2a90-order-1042" }, { "key": "Accept", "value": "application/json" } ], "method": "POST", "body": { "mode": "raw", "raw": "{\n \"phoneNumber\": \"0712345678\"\n}", "options": { "raw": { "language": "json" } } } }, "status": "Too Many Requests", "code": 429, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"statusCode\": 429,\n \"code\": \"QUOTA_EXCEEDED\",\n \"message\": \"Monthly quota of 1000 calls reached\"\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "39ce9e67-18ef-4535-a371-dfacf4514496", "name": "The source failed or didn't answer. The charge was refunded.", "originalRequest": { "url": { "path": [ "v1", "verifications", "phone.sim-swap" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [] }, "header": [ { "description": { "content": "Added as a part of security scheme: bearer", "type": "text/plain" }, "key": "Authorization", "value": "Bearer " }, { "disabled": true, "description": "Makes retries safe: a repeat with the same key and body returns the original verification without charging again. Up to 255 characters.", "key": "Idempotency-Key", "value": "6f1c2a90-order-1042" }, { "key": "Accept", "value": "application/json" } ], "method": "POST", "body": { "mode": "raw", "raw": "{\n \"phoneNumber\": \"0712345678\"\n}", "options": { "raw": { "language": "json" } } } }, "status": "Bad Gateway", "code": 502, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"statusCode\": 502,\n \"code\": \"PROVIDER_UNAVAILABLE\",\n \"message\": \"SAFARICOM is unavailable (sandbox simulation)\",\n \"retryable\": true,\n \"requestId\": \"cmhd2k7q80001s60h3x9f2a1b\"\n}", "cookie": [], "_postman_previewlanguage": "json" } ], "event": [], "protocolProfileBehavior": { "disableBodyPruning": true } }, { "id": "9f1e5598-ef4a-4976-999e-030daed93a78", "name": "Age on network (Safaricom)", "request": { "name": "Age on network (Safaricom)", "description": { "content": "When a Safaricom number was registered on the network. Safaricom only looks back so far: `registeredOn` is null (`olderThanLookback: true`) for numbers registered before that. A very new number is a common fraud signal.\n\n**Price:** set by your bundle; one charge per call. \"Not found\" answers (`result.found: false`) are charged. Source failures return `502` and are refunded.\n\n**Try it:** choose a scenario from the example menu under the code sample and press **Test Request**. Paste your test key into **Authentication** in the window that opens (it is remembered); test keys return sandbox sample data, free.", "type": "text/plain" }, "url": { "path": [ "v1", "verifications", "phone.age-on-network" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [] }, "header": [ { "disabled": true, "description": "Makes retries safe: a repeat with the same key and body returns the original verification without charging again. Up to 255 characters.", "key": "Idempotency-Key", "value": "" }, { "key": "Content-Type", "value": "application/json" }, { "key": "Accept", "value": "application/json" } ], "method": "POST", "auth": null, "body": { "mode": "raw", "raw": "{\n \"phoneNumber\": \"\"\n}", "options": { "raw": { "language": "json" } } } }, "response": [ { "id": "38453530-dd43-4bd6-9c24-ce457f17f2b6", "name": "Verification completed; see `result`.", "originalRequest": { "url": { "path": [ "v1", "verifications", "phone.age-on-network" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [] }, "header": [ { "description": { "content": "Added as a part of security scheme: bearer", "type": "text/plain" }, "key": "Authorization", "value": "Bearer " }, { "disabled": true, "description": "Makes retries safe: a repeat with the same key and body returns the original verification without charging again. Up to 255 characters.", "key": "Idempotency-Key", "value": "6f1c2a90-order-1042" }, { "key": "Accept", "value": "application/json" } ], "method": "POST", "body": { "mode": "raw", "raw": "{\n \"phoneNumber\": \"0712345678\"\n}", "options": { "raw": { "language": "json" } } } }, "status": "OK", "code": 200, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"id\": \"cmhd2k7q80001s60h3x9f2a1b\",\n \"api\": \"phone.age-on-network\",\n \"status\": \"COMPLETED\",\n \"environment\": \"LIVE\",\n \"result\": {\n \"found\": true,\n \"phoneNumberEndsWith\": \"678\",\n \"registeredOn\": \"2016-08-20\",\n \"olderThanLookback\": false\n },\n \"error\": null,\n \"cost\": \"50\",\n \"latencyMs\": 412,\n \"createdAt\": \"2026-10-30T09:15:02.118Z\",\n \"completedAt\": \"2026-10-30T09:15:02.530Z\"\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "77dd57c4-b317-441c-9f2a-7fdb6ca9860f", "name": "The input failed validation; `issues` lists each problem.", "originalRequest": { "url": { "path": [ "v1", "verifications", "phone.age-on-network" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [] }, "header": [ { "description": { "content": "Added as a part of security scheme: bearer", "type": "text/plain" }, "key": "Authorization", "value": "Bearer " }, { "disabled": true, "description": "Makes retries safe: a repeat with the same key and body returns the original verification without charging again. Up to 255 characters.", "key": "Idempotency-Key", "value": "6f1c2a90-order-1042" }, { "key": "Accept", "value": "application/json" } ], "method": "POST", "body": { "mode": "raw", "raw": "{\n \"phoneNumber\": \"0712345678\"\n}", "options": { "raw": { "language": "json" } } } }, "status": "Bad Request", "code": 400, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"statusCode\": 400,\n \"message\": \"Validation failed\",\n \"issues\": [\n {\n \"expected\": \"string\",\n \"code\": \"invalid_type\",\n \"path\": [\n \"phoneNumber\"\n ],\n \"message\": \"Invalid input: expected string, received undefined\"\n }\n ]\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "305fe8c9-080d-4971-b0a4-716a08c3f099", "name": "Missing, unknown or revoked API key.", "originalRequest": { "url": { "path": [ "v1", "verifications", "phone.age-on-network" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [] }, "header": [ { "description": { "content": "Added as a part of security scheme: bearer", "type": "text/plain" }, "key": "Authorization", "value": "Bearer " }, { "disabled": true, "description": "Makes retries safe: a repeat with the same key and body returns the original verification without charging again. Up to 255 characters.", "key": "Idempotency-Key", "value": "6f1c2a90-order-1042" }, { "key": "Accept", "value": "application/json" } ], "method": "POST", "body": { "mode": "raw", "raw": "{\n \"phoneNumber\": \"0712345678\"\n}", "options": { "raw": { "language": "json" } } } }, "status": "Unauthorized", "code": 401, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"statusCode\": 401,\n \"message\": \"Invalid API key\"\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "71ae1ea5-02d6-46f5-87d2-0777b559694b", "name": "The wallet can't cover this call (live keys only). Nothing was charged.", "originalRequest": { "url": { "path": [ "v1", "verifications", "phone.age-on-network" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [] }, "header": [ { "description": { "content": "Added as a part of security scheme: bearer", "type": "text/plain" }, "key": "Authorization", "value": "Bearer " }, { "disabled": true, "description": "Makes retries safe: a repeat with the same key and body returns the original verification without charging again. Up to 255 characters.", "key": "Idempotency-Key", "value": "6f1c2a90-order-1042" }, { "key": "Accept", "value": "application/json" } ], "method": "POST", "body": { "mode": "raw", "raw": "{\n \"phoneNumber\": \"0712345678\"\n}", "options": { "raw": { "language": "json" } } } }, "status": "Payment Required", "code": 402, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"statusCode\": 402,\n \"code\": \"INSUFFICIENT_FUNDS\",\n \"message\": \"Insufficient wallet balance\"\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "6336edd0-a396-45a3-922b-c6e7014ae668", "name": "This API isn't in your organization's bundle.", "originalRequest": { "url": { "path": [ "v1", "verifications", "phone.age-on-network" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [] }, "header": [ { "description": { "content": "Added as a part of security scheme: bearer", "type": "text/plain" }, "key": "Authorization", "value": "Bearer " }, { "disabled": true, "description": "Makes retries safe: a repeat with the same key and body returns the original verification without charging again. Up to 255 characters.", "key": "Idempotency-Key", "value": "6f1c2a90-order-1042" }, { "key": "Accept", "value": "application/json" } ], "method": "POST", "body": { "mode": "raw", "raw": "{\n \"phoneNumber\": \"0712345678\"\n}", "options": { "raw": { "language": "json" } } } }, "status": "Forbidden", "code": 403, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"statusCode\": 403,\n \"code\": \"API_NOT_IN_PLAN\",\n \"message\": \"Your plan does not include identity.national-id\"\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "6d7dee0a-8ccc-464a-9664-b1f931d6c2e5", "name": "The `Idempotency-Key` was used for a different request, or that request is still running.", "originalRequest": { "url": { "path": [ "v1", "verifications", "phone.age-on-network" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [] }, "header": [ { "description": { "content": "Added as a part of security scheme: bearer", "type": "text/plain" }, "key": "Authorization", "value": "Bearer " }, { "disabled": true, "description": "Makes retries safe: a repeat with the same key and body returns the original verification without charging again. Up to 255 characters.", "key": "Idempotency-Key", "value": "6f1c2a90-order-1042" }, { "key": "Accept", "value": "application/json" } ], "method": "POST", "body": { "mode": "raw", "raw": "{\n \"phoneNumber\": \"0712345678\"\n}", "options": { "raw": { "language": "json" } } } }, "status": "Conflict", "code": 409, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"statusCode\": 409,\n \"message\": \"Idempotency-Key was already used for a different request\"\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "1a51a30c-88cb-4c41-8ee9-9be2f5d76180", "name": "Monthly quota reached, or more than 120 requests a minute.", "originalRequest": { "url": { "path": [ "v1", "verifications", "phone.age-on-network" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [] }, "header": [ { "description": { "content": "Added as a part of security scheme: bearer", "type": "text/plain" }, "key": "Authorization", "value": "Bearer " }, { "disabled": true, "description": "Makes retries safe: a repeat with the same key and body returns the original verification without charging again. Up to 255 characters.", "key": "Idempotency-Key", "value": "6f1c2a90-order-1042" }, { "key": "Accept", "value": "application/json" } ], "method": "POST", "body": { "mode": "raw", "raw": "{\n \"phoneNumber\": \"0712345678\"\n}", "options": { "raw": { "language": "json" } } } }, "status": "Too Many Requests", "code": 429, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"statusCode\": 429,\n \"code\": \"QUOTA_EXCEEDED\",\n \"message\": \"Monthly quota of 1000 calls reached\"\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "61febfde-b514-4c4a-a9fa-9eb04643b830", "name": "The source failed or didn't answer. The charge was refunded.", "originalRequest": { "url": { "path": [ "v1", "verifications", "phone.age-on-network" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [] }, "header": [ { "description": { "content": "Added as a part of security scheme: bearer", "type": "text/plain" }, "key": "Authorization", "value": "Bearer " }, { "disabled": true, "description": "Makes retries safe: a repeat with the same key and body returns the original verification without charging again. Up to 255 characters.", "key": "Idempotency-Key", "value": "6f1c2a90-order-1042" }, { "key": "Accept", "value": "application/json" } ], "method": "POST", "body": { "mode": "raw", "raw": "{\n \"phoneNumber\": \"0712345678\"\n}", "options": { "raw": { "language": "json" } } } }, "status": "Bad Gateway", "code": 502, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"statusCode\": 502,\n \"code\": \"PROVIDER_UNAVAILABLE\",\n \"message\": \"SAFARICOM is unavailable (sandbox simulation)\",\n \"retryable\": true,\n \"requestId\": \"cmhd2k7q80001s60h3x9f2a1b\"\n}", "cookie": [], "_postman_previewlanguage": "json" } ], "event": [], "protocolProfileBehavior": { "disableBodyPruning": true } } ], "event": [] }, { "id": "ca3776fc-c8d5-494a-bd67-3063b27eeb9b", "name": "Background checks", "description": { "content": "Police clearance (certificate of good conduct) verification against the DCI portal.", "type": "text/plain" }, "item": [ { "id": "8c10dccc-75ad-417e-a9ec-5abc4422cde2", "name": "Police clearance certificate (DCI)", "request": { "name": "Police clearance certificate (DCI)", "description": { "content": "Verifies a DCI police clearance (certificate of good conduct) against the DCI portal, using its reference number and the holder's ID number. Returns the verdict, holder name, issue and expiry dates (valid one year from issue) and any recorded offences. `found: false` with `reason` CERTIFICATE_NOT_FOUND or ID_MISMATCH is DCI's own answer. Checks can take up to a minute.\n\n**Price:** set by your bundle; one charge per call. \"Not found\" answers (`result.found: false`) are charged. Source failures return `502` and are refunded.\n\n**Try it:** choose a scenario from the example menu under the code sample and press **Test Request**. Paste your test key into **Authentication** in the window that opens (it is remembered); test keys return sandbox sample data, free.", "type": "text/plain" }, "url": { "path": [ "v1", "verifications", "background.police-clearance" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [] }, "header": [ { "disabled": true, "description": "Makes retries safe: a repeat with the same key and body returns the original verification without charging again. Up to 255 characters.", "key": "Idempotency-Key", "value": "" }, { "key": "Content-Type", "value": "application/json" }, { "key": "Accept", "value": "application/json" } ], "method": "POST", "auth": null, "body": { "mode": "raw", "raw": "{\n \"refNumber\": \"\",\n \"idNumber\": \"\"\n}", "options": { "raw": { "language": "json" } } } }, "response": [ { "id": "2c8012d1-256c-47ba-8124-51158a1eef1d", "name": "Verification completed; see `result`.", "originalRequest": { "url": { "path": [ "v1", "verifications", "background.police-clearance" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [] }, "header": [ { "description": { "content": "Added as a part of security scheme: bearer", "type": "text/plain" }, "key": "Authorization", "value": "Bearer " }, { "disabled": true, "description": "Makes retries safe: a repeat with the same key and body returns the original verification without charging again. Up to 255 characters.", "key": "Idempotency-Key", "value": "6f1c2a90-order-1042" }, { "key": "Accept", "value": "application/json" } ], "method": "POST", "body": { "mode": "raw", "raw": "{\n \"refNumber\": \"PCC-6QSLJEYKG\",\n \"idNumber\": \"12345678\"\n}", "options": { "raw": { "language": "json" } } } }, "status": "OK", "code": 200, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"id\": \"cmhd2k7q80001s60h3x9f2a1b\",\n \"api\": \"background.police-clearance\",\n \"status\": \"COMPLETED\",\n \"environment\": \"LIVE\",\n \"result\": {\n \"found\": true,\n \"refNumber\": \"PCC-6QSLJEYKG\",\n \"certificate\": {\n \"verdict\": \"VALID\",\n \"valid\": true,\n \"holderName\": \"JANE WANJIKU DOE\",\n \"issuedOn\": \"2026-02-10, 09:14:03\",\n \"expiresOn\": \"2027-02-10\",\n \"status\": \"Approved\",\n \"offencesRecorded\": false,\n \"offenceCount\": \"NIL\",\n \"offences\": []\n }\n },\n \"error\": null,\n \"cost\": \"50\",\n \"latencyMs\": 412,\n \"createdAt\": \"2026-10-30T09:15:02.118Z\",\n \"completedAt\": \"2026-10-30T09:15:02.530Z\"\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "3f05194d-56cb-4713-9871-f81b3e605e29", "name": "The input failed validation; `issues` lists each problem.", "originalRequest": { "url": { "path": [ "v1", "verifications", "background.police-clearance" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [] }, "header": [ { "description": { "content": "Added as a part of security scheme: bearer", "type": "text/plain" }, "key": "Authorization", "value": "Bearer " }, { "disabled": true, "description": "Makes retries safe: a repeat with the same key and body returns the original verification without charging again. Up to 255 characters.", "key": "Idempotency-Key", "value": "6f1c2a90-order-1042" }, { "key": "Accept", "value": "application/json" } ], "method": "POST", "body": { "mode": "raw", "raw": "{\n \"refNumber\": \"PCC-6QSLJEYKG\",\n \"idNumber\": \"12345678\"\n}", "options": { "raw": { "language": "json" } } } }, "status": "Bad Request", "code": 400, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"statusCode\": 400,\n \"message\": \"Validation failed\",\n \"issues\": [\n {\n \"expected\": \"string\",\n \"code\": \"invalid_type\",\n \"path\": [\n \"refNumber\"\n ],\n \"message\": \"Invalid input: expected string, received undefined\"\n },\n {\n \"expected\": \"string\",\n \"code\": \"invalid_type\",\n \"path\": [\n \"idNumber\"\n ],\n \"message\": \"Invalid input: expected string, received undefined\"\n }\n ]\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "e570c4ee-be52-42aa-992f-aec9357576eb", "name": "Missing, unknown or revoked API key.", "originalRequest": { "url": { "path": [ "v1", "verifications", "background.police-clearance" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [] }, "header": [ { "description": { "content": "Added as a part of security scheme: bearer", "type": "text/plain" }, "key": "Authorization", "value": "Bearer " }, { "disabled": true, "description": "Makes retries safe: a repeat with the same key and body returns the original verification without charging again. Up to 255 characters.", "key": "Idempotency-Key", "value": "6f1c2a90-order-1042" }, { "key": "Accept", "value": "application/json" } ], "method": "POST", "body": { "mode": "raw", "raw": "{\n \"refNumber\": \"PCC-6QSLJEYKG\",\n \"idNumber\": \"12345678\"\n}", "options": { "raw": { "language": "json" } } } }, "status": "Unauthorized", "code": 401, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"statusCode\": 401,\n \"message\": \"Invalid API key\"\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "db2ec00d-c7aa-41cd-900d-1e26c218da2e", "name": "The wallet can't cover this call (live keys only). Nothing was charged.", "originalRequest": { "url": { "path": [ "v1", "verifications", "background.police-clearance" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [] }, "header": [ { "description": { "content": "Added as a part of security scheme: bearer", "type": "text/plain" }, "key": "Authorization", "value": "Bearer " }, { "disabled": true, "description": "Makes retries safe: a repeat with the same key and body returns the original verification without charging again. Up to 255 characters.", "key": "Idempotency-Key", "value": "6f1c2a90-order-1042" }, { "key": "Accept", "value": "application/json" } ], "method": "POST", "body": { "mode": "raw", "raw": "{\n \"refNumber\": \"PCC-6QSLJEYKG\",\n \"idNumber\": \"12345678\"\n}", "options": { "raw": { "language": "json" } } } }, "status": "Payment Required", "code": 402, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"statusCode\": 402,\n \"code\": \"INSUFFICIENT_FUNDS\",\n \"message\": \"Insufficient wallet balance\"\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "964e5f11-ec50-440e-9f94-ea120dbb2c5a", "name": "This API isn't in your organization's bundle.", "originalRequest": { "url": { "path": [ "v1", "verifications", "background.police-clearance" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [] }, "header": [ { "description": { "content": "Added as a part of security scheme: bearer", "type": "text/plain" }, "key": "Authorization", "value": "Bearer " }, { "disabled": true, "description": "Makes retries safe: a repeat with the same key and body returns the original verification without charging again. Up to 255 characters.", "key": "Idempotency-Key", "value": "6f1c2a90-order-1042" }, { "key": "Accept", "value": "application/json" } ], "method": "POST", "body": { "mode": "raw", "raw": "{\n \"refNumber\": \"PCC-6QSLJEYKG\",\n \"idNumber\": \"12345678\"\n}", "options": { "raw": { "language": "json" } } } }, "status": "Forbidden", "code": 403, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"statusCode\": 403,\n \"code\": \"API_NOT_IN_PLAN\",\n \"message\": \"Your plan does not include identity.national-id\"\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "eb56133b-507e-4511-8111-9c3f4c824a10", "name": "The `Idempotency-Key` was used for a different request, or that request is still running.", "originalRequest": { "url": { "path": [ "v1", "verifications", "background.police-clearance" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [] }, "header": [ { "description": { "content": "Added as a part of security scheme: bearer", "type": "text/plain" }, "key": "Authorization", "value": "Bearer " }, { "disabled": true, "description": "Makes retries safe: a repeat with the same key and body returns the original verification without charging again. Up to 255 characters.", "key": "Idempotency-Key", "value": "6f1c2a90-order-1042" }, { "key": "Accept", "value": "application/json" } ], "method": "POST", "body": { "mode": "raw", "raw": "{\n \"refNumber\": \"PCC-6QSLJEYKG\",\n \"idNumber\": \"12345678\"\n}", "options": { "raw": { "language": "json" } } } }, "status": "Conflict", "code": 409, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"statusCode\": 409,\n \"message\": \"Idempotency-Key was already used for a different request\"\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "689a87d9-3b6e-43c4-8236-08c6e6dd0083", "name": "Monthly quota reached, or more than 120 requests a minute.", "originalRequest": { "url": { "path": [ "v1", "verifications", "background.police-clearance" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [] }, "header": [ { "description": { "content": "Added as a part of security scheme: bearer", "type": "text/plain" }, "key": "Authorization", "value": "Bearer " }, { "disabled": true, "description": "Makes retries safe: a repeat with the same key and body returns the original verification without charging again. Up to 255 characters.", "key": "Idempotency-Key", "value": "6f1c2a90-order-1042" }, { "key": "Accept", "value": "application/json" } ], "method": "POST", "body": { "mode": "raw", "raw": "{\n \"refNumber\": \"PCC-6QSLJEYKG\",\n \"idNumber\": \"12345678\"\n}", "options": { "raw": { "language": "json" } } } }, "status": "Too Many Requests", "code": 429, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"statusCode\": 429,\n \"code\": \"QUOTA_EXCEEDED\",\n \"message\": \"Monthly quota of 1000 calls reached\"\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "5e28b0f5-0cf4-40ad-9353-4467124f5cad", "name": "The source failed or didn't answer. The charge was refunded.", "originalRequest": { "url": { "path": [ "v1", "verifications", "background.police-clearance" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [] }, "header": [ { "description": { "content": "Added as a part of security scheme: bearer", "type": "text/plain" }, "key": "Authorization", "value": "Bearer " }, { "disabled": true, "description": "Makes retries safe: a repeat with the same key and body returns the original verification without charging again. Up to 255 characters.", "key": "Idempotency-Key", "value": "6f1c2a90-order-1042" }, { "key": "Accept", "value": "application/json" } ], "method": "POST", "body": { "mode": "raw", "raw": "{\n \"refNumber\": \"PCC-6QSLJEYKG\",\n \"idNumber\": \"12345678\"\n}", "options": { "raw": { "language": "json" } } } }, "status": "Bad Gateway", "code": 502, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"statusCode\": 502,\n \"code\": \"PROVIDER_UNAVAILABLE\",\n \"message\": \"DCI is unavailable (sandbox simulation)\",\n \"retryable\": true,\n \"requestId\": \"cmhd2k7q80001s60h3x9f2a1b\"\n}", "cookie": [], "_postman_previewlanguage": "json" } ], "event": [], "protocolProfileBehavior": { "disableBodyPruning": true } } ], "event": [] }, { "id": "4dd7c025-f24d-4b0d-87f3-8f059d0bf93c", "name": "Verification records", "description": { "content": "Look up verifications you've already made, and summarise usage.", "type": "text/plain" }, "item": [ { "id": "c8d4292b-1fe0-47c1-a413-32259c19b5c7", "name": "List verifications", "request": { "name": "List verifications", "description": { "content": "Your organization's verifications, newest first. A key sees only its own environment (test keys see test verifications).", "type": "text/plain" }, "url": { "path": [ "v1", "verifications" ], "host": [ "{{baseUrl}}" ], "query": [ { "disabled": true, "key": "limit", "value": "20", "description": "Page size, 1 to 100." }, { "disabled": true, "key": "cursor", "value": "", "description": "`nextCursor` from the previous page." }, { "disabled": true, "key": "apiCode", "value": "", "description": "Only this API, e.g. `identity.national-id`." }, { "disabled": true, "key": "status", "value": "" } ], "variable": [] }, "header": [ { "key": "Accept", "value": "application/json" } ], "method": "GET", "auth": null }, "response": [ { "id": "a2f909d1-c3ef-422a-8e35-609ab5f4b3e0", "name": "One page of verifications.", "originalRequest": { "url": { "path": [ "v1", "verifications" ], "host": [ "{{baseUrl}}" ], "query": [ { "key": "limit", "value": "20" }, { "key": "cursor", "value": "" }, { "key": "apiCode", "value": "" }, { "key": "status", "value": "" } ], "variable": [] }, "header": [ { "description": { "content": "Added as a part of security scheme: bearer", "type": "text/plain" }, "key": "Authorization", "value": "Bearer " }, { "key": "Accept", "value": "application/json" } ], "method": "GET", "body": {} }, "status": "OK", "code": 200, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"data\": [\n {\n \"id\": \"cmhd2k7q80001s60h3x9f2a1b\",\n \"api\": \"tax.kra-pin\",\n \"status\": \"COMPLETED\",\n \"environment\": \"LIVE\",\n \"result\": {\n \"found\": true,\n \"idNumber\": \"12345678\",\n \"taxpayer\": {\n \"pin\": \"A000000000S\",\n \"name\": \"JANE WANJIKU DOE\"\n }\n },\n \"error\": null,\n \"cost\": \"50\",\n \"latencyMs\": 412,\n \"createdAt\": \"2026-10-30T09:15:02.118Z\",\n \"completedAt\": \"2026-10-30T09:15:02.530Z\"\n }\n ],\n \"nextCursor\": null\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "a475fdf9-07b4-4b15-9d92-a693b5f496ab", "name": "Missing, unknown or revoked API key.", "originalRequest": { "url": { "path": [ "v1", "verifications" ], "host": [ "{{baseUrl}}" ], "query": [ { "key": "limit", "value": "20" }, { "key": "cursor", "value": "" }, { "key": "apiCode", "value": "" }, { "key": "status", "value": "" } ], "variable": [] }, "header": [ { "description": { "content": "Added as a part of security scheme: bearer", "type": "text/plain" }, "key": "Authorization", "value": "Bearer " }, { "key": "Accept", "value": "application/json" } ], "method": "GET", "body": {} }, "status": "Unauthorized", "code": 401, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"statusCode\": 401,\n \"message\": \"Invalid API key\"\n}", "cookie": [], "_postman_previewlanguage": "json" } ], "event": [], "protocolProfileBehavior": { "disableBodyPruning": true } }, { "id": "217c91e8-f976-42db-82c7-882f09b0d3a3", "name": "Usage summary", "request": { "name": "Usage summary", "description": { "content": "Calls, success rate and cost per API over a period (default: the last 30 days).", "type": "text/plain" }, "url": { "path": [ "v1", "verifications", "summary" ], "host": [ "{{baseUrl}}" ], "query": [ { "disabled": true, "key": "from", "value": "", "description": "Start (inclusive), ISO 8601." }, { "disabled": true, "key": "to", "value": "", "description": "End (exclusive), ISO 8601." } ], "variable": [] }, "header": [ { "key": "Accept", "value": "application/json" } ], "method": "GET", "auth": null }, "response": [ { "id": "579211c3-542b-4ea9-a3dd-85622df198ac", "name": "The summary.", "originalRequest": { "url": { "path": [ "v1", "verifications", "summary" ], "host": [ "{{baseUrl}}" ], "query": [ { "key": "from", "value": "2026-10-01T00:00:00Z" }, { "key": "to", "value": "2026-11-01T00:00:00Z" } ], "variable": [] }, "header": [ { "description": { "content": "Added as a part of security scheme: bearer", "type": "text/plain" }, "key": "Authorization", "value": "Bearer " }, { "key": "Accept", "value": "application/json" } ], "method": "GET", "body": {} }, "status": "OK", "code": 200, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"from\": \"2026-10-01T00:00:00.000Z\",\n \"to\": \"2026-11-01T00:00:00.000Z\",\n \"environment\": \"LIVE\",\n \"calls\": 128,\n \"completed\": 126,\n \"successRate\": 0.984375,\n \"totalCost\": \"6300\",\n \"byApi\": [\n {\n \"apiCode\": \"identity.national-id\",\n \"calls\": 100,\n \"completed\": 99,\n \"failed\": 1,\n \"cost\": \"4950\"\n },\n {\n \"apiCode\": \"tax.kra-pin\",\n \"calls\": 28,\n \"completed\": 27,\n \"failed\": 1,\n \"cost\": \"1350\"\n }\n ]\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "b65da9a0-5fce-4d21-bdd0-8087c7842049", "name": "Invalid period.", "originalRequest": { "url": { "path": [ "v1", "verifications", "summary" ], "host": [ "{{baseUrl}}" ], "query": [ { "key": "from", "value": "2026-10-01T00:00:00Z" }, { "key": "to", "value": "2026-11-01T00:00:00Z" } ], "variable": [] }, "header": [ { "description": { "content": "Added as a part of security scheme: bearer", "type": "text/plain" }, "key": "Authorization", "value": "Bearer " }, { "key": "Accept", "value": "application/json" } ], "method": "GET", "body": {} }, "status": "Bad Request", "code": 400, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"statusCode\": 400,\n \"message\": \"Validation failed\",\n \"issues\": [\n {\n \"path\": [],\n \"message\": \"`from` must be before `to`\"\n }\n ]\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "3f3c2cc9-4400-4c6f-8e35-62a8d1560d2f", "name": "Missing, unknown or revoked API key.", "originalRequest": { "url": { "path": [ "v1", "verifications", "summary" ], "host": [ "{{baseUrl}}" ], "query": [ { "key": "from", "value": "2026-10-01T00:00:00Z" }, { "key": "to", "value": "2026-11-01T00:00:00Z" } ], "variable": [] }, "header": [ { "description": { "content": "Added as a part of security scheme: bearer", "type": "text/plain" }, "key": "Authorization", "value": "Bearer " }, { "key": "Accept", "value": "application/json" } ], "method": "GET", "body": {} }, "status": "Unauthorized", "code": 401, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"statusCode\": 401,\n \"message\": \"Invalid API key\"\n}", "cookie": [], "_postman_previewlanguage": "json" } ], "event": [], "protocolProfileBehavior": { "disableBodyPruning": true } }, { "id": "d06bc466-b75c-4113-b477-4690a990e37a", "name": "Get a verification", "request": { "name": "Get a verification", "description": { "content": "Fetch a verification again by its `id`, e.g. after a timeout or to show a past result.", "type": "text/plain" }, "url": { "path": [ "v1", "verifications", ":id" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [ { "disabled": false, "type": "any", "value": "", "key": "id", "description": "(Required) " } ] }, "header": [ { "key": "Accept", "value": "application/json" } ], "method": "GET", "auth": null }, "response": [ { "id": "1ddd4187-0030-4d07-b388-1955ae459e7a", "name": "The verification.", "originalRequest": { "url": { "path": [ "v1", "verifications", ":id" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [ { "disabled": false, "type": "any", "value": "", "key": "id", "description": "(Required) " } ] }, "header": [ { "description": { "content": "Added as a part of security scheme: bearer", "type": "text/plain" }, "key": "Authorization", "value": "Bearer " }, { "key": "Accept", "value": "application/json" } ], "method": "GET", "body": {} }, "status": "OK", "code": 200, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"id\": \"cmhd2k7q80001s60h3x9f2a1b\",\n \"api\": \"tax.kra-pin\",\n \"status\": \"COMPLETED\",\n \"environment\": \"LIVE\",\n \"result\": {\n \"found\": true,\n \"idNumber\": \"12345678\",\n \"taxpayer\": {\n \"pin\": \"A000000000S\",\n \"name\": \"JANE WANJIKU DOE\"\n }\n },\n \"error\": null,\n \"cost\": \"50\",\n \"latencyMs\": 412,\n \"createdAt\": \"2026-10-30T09:15:02.118Z\",\n \"completedAt\": \"2026-10-30T09:15:02.530Z\"\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "bcb7f3f6-1445-4beb-9178-5574268da4a4", "name": "Missing, unknown or revoked API key.", "originalRequest": { "url": { "path": [ "v1", "verifications", ":id" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [ { "disabled": false, "type": "any", "value": "", "key": "id", "description": "(Required) " } ] }, "header": [ { "description": { "content": "Added as a part of security scheme: bearer", "type": "text/plain" }, "key": "Authorization", "value": "Bearer " }, { "key": "Accept", "value": "application/json" } ], "method": "GET", "body": {} }, "status": "Unauthorized", "code": 401, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"statusCode\": 401,\n \"message\": \"Invalid API key\"\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "11e1c093-d833-4143-b52e-4e64156d2303", "name": "No such verification in this key's environment.", "originalRequest": { "url": { "path": [ "v1", "verifications", ":id" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [ { "disabled": false, "type": "any", "value": "", "key": "id", "description": "(Required) " } ] }, "header": [ { "description": { "content": "Added as a part of security scheme: bearer", "type": "text/plain" }, "key": "Authorization", "value": "Bearer " }, { "key": "Accept", "value": "application/json" } ], "method": "GET", "body": {} }, "status": "Not Found", "code": 404, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"statusCode\": 404,\n \"message\": \"Verification not found\"\n}", "cookie": [], "_postman_previewlanguage": "json" } ], "event": [], "protocolProfileBehavior": { "disableBodyPruning": true } } ], "event": [] }, { "id": "a17b68cd-823a-4b24-bb72-57106a4dbce0", "name": "Billing and usage", "description": { "content": "Live verifications are paid from your organization's **prepaid wallet**, in Kenyan shillings (KES).\n\n**Bundles and prices**\n\nYour organization is on a bundle. The bundle sets which verification APIs you can call, the price of each, and optionally a monthly call quota. You can see your bundle and prices in the dashboard under **Billing**.\n\n**How a call is charged**\n\n1. When a live call starts, its price is reserved from your wallet. If the balance is too low, the call is rejected with `402 INSUFFICIENT_FUNDS` and no lookup is made.\n2. If the source answers, whether \"found\" or \"not found\", the charge stands. The amount is in the verification's `cost` field.\n3. If the source fails (`502`), **the charge is refunded automatically** before the response is sent.\n4. A retry with the same `Idempotency-Key` is never charged twice.\n\nTest-key calls cost nothing (`cost: \"0\"`).\n\n**Topping up**\n\nTop up from the dashboard's billing page, using M-Pesa (STK push to your phone). The wallet is credited as soon as the payment is confirmed. Wallet statements, payment receipts and CSV exports are also in the dashboard.\n\n**Checking from code**\n\nAn API key can read your balance and this month's usage with the two endpoints below. Use them to alert your team before the balance runs out.", "type": "text/plain" }, "item": [ { "id": "4dc139e5-6312-47d3-b4cf-fd55c00a0e76", "name": "Get wallet balance", "request": { "name": "Get wallet balance", "description": { "content": "Your organization's prepaid balance. Top-ups are made in the dashboard.", "type": "text/plain" }, "url": { "path": [ "v1", "wallet" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [] }, "header": [ { "key": "Accept", "value": "application/json" } ], "method": "GET", "auth": null }, "response": [ { "id": "33f27538-4171-4cf4-8114-0ef838328136", "name": "The wallet.", "originalRequest": { "url": { "path": [ "v1", "wallet" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [] }, "header": [ { "description": { "content": "Added as a part of security scheme: bearer", "type": "text/plain" }, "key": "Authorization", "value": "Bearer " }, { "key": "Accept", "value": "application/json" } ], "method": "GET", "body": {} }, "status": "OK", "code": 200, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"id\": \"cmh8w1a2b0000s60hwallet01\",\n \"organizationId\": \"cmh8w0z9y0000s60horg00001\",\n \"balance\": \"12450\",\n \"currency\": \"KES\",\n \"createdAt\": \"2026-09-02T07:30:00.000Z\",\n \"updatedAt\": \"2026-10-30T09:15:02.530Z\"\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "fd98a44c-fa55-4b82-b37c-2ffaccd01c33", "name": "Missing, unknown or revoked API key.", "originalRequest": { "url": { "path": [ "v1", "wallet" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [] }, "header": [ { "description": { "content": "Added as a part of security scheme: bearer", "type": "text/plain" }, "key": "Authorization", "value": "Bearer " }, { "key": "Accept", "value": "application/json" } ], "method": "GET", "body": {} }, "status": "Unauthorized", "code": 401, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"statusCode\": 401,\n \"message\": \"Invalid API key\"\n}", "cookie": [], "_postman_previewlanguage": "json" } ], "event": [], "protocolProfileBehavior": { "disableBodyPruning": true } }, { "id": "0b963307-6e05-4224-9429-7d7afc3ea03e", "name": "Get monthly usage", "request": { "name": "Get monthly usage", "description": { "content": "Verifications made this calendar month against your bundle's monthly quota.", "type": "text/plain" }, "url": { "path": [ "v1", "usage", "quota" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [] }, "header": [ { "key": "Accept", "value": "application/json" } ], "method": "GET", "auth": null }, "response": [ { "id": "b48e54d0-6c7c-41c6-84b9-c66d8c1a0880", "name": "This month's usage.", "originalRequest": { "url": { "path": [ "v1", "usage", "quota" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [] }, "header": [ { "description": { "content": "Added as a part of security scheme: bearer", "type": "text/plain" }, "key": "Authorization", "value": "Bearer " }, { "key": "Accept", "value": "application/json" } ], "method": "GET", "body": {} }, "status": "OK", "code": 200, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"period\": \"2026-10\",\n \"calls\": 128,\n \"quota\": 1000\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "4f7fb1b1-6496-4f4d-86ca-8c724997bc81", "name": "Missing, unknown or revoked API key.", "originalRequest": { "url": { "path": [ "v1", "usage", "quota" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [] }, "header": [ { "description": { "content": "Added as a part of security scheme: bearer", "type": "text/plain" }, "key": "Authorization", "value": "Bearer " }, { "key": "Accept", "value": "application/json" } ], "method": "GET", "body": {} }, "status": "Unauthorized", "code": 401, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"statusCode\": 401,\n \"message\": \"Invalid API key\"\n}", "cookie": [], "_postman_previewlanguage": "json" } ], "event": [], "protocolProfileBehavior": { "disableBodyPruning": true } } ], "event": [] } ], "event": [], "variable": [ { "key": "base_url", "value": "https://api.dpaverify.com", "type": "string" }, { "key": "api_key", "value": "", "type": "string", "description": "Your Dpaverify API key (dpv_test_... or dpv_live_...)" } ], "auth": { "type": "bearer", "bearer": [ { "key": "token", "value": "{{api_key}}", "type": "string" } ] }, "info": { "_postman_id": "7152388d-7988-481b-b886-362389da42f1", "name": "Dpaverify API", "schema": "https://schema.getpostman.com/json/collection/v2.1.0/collection.json", "description": { "content": "# Introduction\n\nThe Dpaverify API gives you one integration for Kenyan identity, vehicle, business, tax, phone and background checks. Behind it, Dpaverify connects to the official sources, including IPRS, NTSA, KRA, the Business Registration Service, Safaricom and the DCI. It returns their answers in one consistent JSON format.\n\n**Base URL**\n\n```\nhttps://restapi.dpaverify.com\n```\n\n**How it works**\n\n1. **Get API keys** from the Dpaverify dashboard. Test keys (`sk_test_…`) return sample data for free. Live keys (`sk_live_…`) query the real sources.\n2. **Fund your wallet.** Live calls are paid from a prepaid wallet in Kenyan shillings, at the price set in your bundle.\n3. **Call a verification API**, e.g. `POST /v1/verifications/identity.national-id`. The answer comes back in the same request.\n4. **Optionally receive webhooks** for every completed or failed verification.\n\n**API conventions**\n\n- All requests and responses are JSON (`Content-Type: application/json`) over HTTPS.\n- Timestamps are ISO 8601 in UTC, e.g. `2026-10-30T09:15:02.118Z`.\n- Money amounts are decimal strings in KES, e.g. `\"50\"` or `\"1250.50\"`, so they never lose precision.\n- IDs are opaque strings. Store them as given.\n- New fields may be added to responses at any time, so ignore fields you don't recognise. Breaking changes only ship under a new version prefix (`/v2`).\n\n# Quickstart\n\nMake your first verification in under five minutes, using the sandbox.\n\n**1. Create a test key**\n\nSign in to the Dpaverify dashboard and open **API keys**. Choose **Create test key** and copy the key. It starts with `sk_test_` and is shown only once.\n\n**2. Verify a national ID**\n\n```bash\ncurl https://restapi.dpaverify.com/v1/verifications/identity.national-id \\\n -H \"Authorization: Bearer sk_test_your_key\" \\\n -H \"Content-Type: application/json\" \\\n -H \"Idempotency-Key: 6f1c2a90-order-1042\" \\\n -d '{ \"idType\": \"NATIONAL_ID\", \"idNumber\": \"12345678\" }'\n```\n\n**3. Read the answer**\n\n```json\n{\n \"id\": \"cmhd2k7q80001s60h3x9f2a1b\",\n \"api\": \"identity.national-id\",\n \"status\": \"COMPLETED\",\n \"environment\": \"TEST\",\n \"result\": {\n \"found\": true,\n \"idType\": \"NATIONAL_ID\",\n \"person\": { \"idNumber\": \"12345678\", \"firstName\": \"JANE\", \"lastName\": \"DOE\", \"dateOfBirth\": \"1990-01-15\", \"...\": \"...\" }\n },\n \"error\": null,\n \"cost\": \"0\",\n \"latencyMs\": 412,\n \"createdAt\": \"2026-10-30T09:15:02.118Z\",\n \"completedAt\": \"2026-10-30T09:15:02.530Z\"\n}\n```\n\n`result.found` tells you whether the source holds a record; when it does, the record's details are returned.\n\n**4. Try the other outcomes**\n\nThe sandbox has fixed inputs that return \"not found\" or simulate an outage. See **Sandbox and test data**. Every API in this reference also has these scenarios as examples, so you can run them from the **Test Request** button.\n\n**5. Go live**\n\nOnce your organization is activated, an administrator issues your live key (`sk_live_…`). Top up your wallet, then swap the key. Nothing else changes.\n\n# Authentication\n\nEvery request carries an API key as a bearer token:\n\n```\nAuthorization: Bearer sk_live_…\n```\n\nThere are two kinds of key:\n\n- **Test keys (`sk_test_…`)** return fixed sample data from the sandbox. Real sources are never contacted, and calls are never charged. Any member of your organization can create one in the dashboard under **API keys**.\n- **Live keys (`sk_live_…`)** return real answers from IPRS, NTSA, KRA, BRS, Safaricom and the DCI. Every call is charged to your wallet. Dpaverify issues them when your organization is activated.\n\nA key belongs to your organization, not to a person. A key can only see verifications made in its own environment, so a test key never sees live results.\n\n**What an API key can call**\n\n- All verification APIs, and the verification records (list, fetch, summary).\n- Your wallet balance (`GET /v1/wallet`) and monthly usage (`GET /v1/usage/quota`).\n\nEverything else is managed in the dashboard and needs a user sign-in: creating and revoking keys, top-ups, wallet statements and exports, team members, and webhook settings. If you call those endpoints with an API key, you get `403`.\n\n**Keeping keys safe**\n\n- Use keys only from your servers. Never put a key in a mobile app, a browser or a public repository.\n- Store keys in a secrets manager or environment variables.\n- Use a separate test key per developer or environment, so each can be revoked on its own.\n- **Rotate** without downtime: create the new key, deploy it, then revoke the old one in the dashboard.\n- If a key leaks, revoke it immediately. Revoked keys fail with `401` straight away.\n\n# Sandbox and test data\n\nRequests made with a **test key** (`sk_test_…`) run in the sandbox:\n\n- They never reach IPRS, NTSA, KRA, BRS, Safaricom or the DCI.\n- They are never charged.\n- The data that comes back is **fixed sample data**, e.g. the person *JANE WANJIKU DOE* or a 2015 Toyota Fielder. It is not real data.\n- It has exactly the same shape as live responses, so code written against the sandbox works unchanged with a live key.\n\nInput validation, idempotency, rate limits, records and webhooks all behave exactly as they do live.\n\n**Inputs that trigger each outcome**\n\nAny valid input returns a match. Use these values to reproduce the other outcomes:\n\n**National ID, alien ID or passport (IPRS)** (`identity.national-id`)\n\n- No such person: `{\"idType\":\"NATIONAL_ID\",\"idNumber\":\"00000000\"}`\n- IPRS unavailable (502, refunded): `{\"idType\":\"NATIONAL_ID\",\"idNumber\":\"99999999\"}`\n\n**Driving licence & PSV badge (NTSA)** (`identity.driving-licence`)\n\n- No licence under this ID: `{\"idNumber\":\"00000000\"}`\n- NTSA unavailable (502, refunded): `{\"idNumber\":\"99999999\"}`\n\n**Vehicle registration search (NTSA via Pesaflow)** (`vehicle.registration`)\n\n- Not a registered owner (`checks.isOwner: false`): `{\"registrationNumber\":\"KDA 123A\",\"ownerIdNumber\":\"87654321\"}`\n- No such vehicle: `{\"registrationNumber\":\"KZZ 000Z\"}`\n- NTSA unavailable (502, refunded): `{\"registrationNumber\":\"KZZ 999Z\"}`\n\n**KRA PIN by ID number (KRA)** (`tax.kra-pin`)\n\n- No PIN for this ID: `{\"idNumber\":\"00000000\"}`\n- KRA unavailable (502, refunded): `{\"idNumber\":\"99999999\"}`\n\n**Business registration search (BRS via Pesaflow)** (`business.registration`)\n\n- No such business: `{\"registrationNumber\":\"PVT-00000000\"}`\n- BRS unavailable (502, refunded): `{\"registrationNumber\":\"PVT-99999999\"}`\n\n**Phone number ownership (Safaricom)** (`phone.ownership`)\n\n- Registered to someone else (`matched: false`; any ID ending in 1): `{\"phoneNumber\":\"0712345678\",\"idNumber\":\"12345671\"}`\n- Safaricom unavailable (502, refunded): `{\"phoneNumber\":\"0799999999\",\"idNumber\":\"12345678\"}`\n\n**Last SIM swap (Safaricom)** (`phone.sim-swap`)\n\n- Safaricom unavailable (502, refunded): `{\"phoneNumber\":\"0799999999\"}`\n\n**Age on network (Safaricom)** (`phone.age-on-network`)\n\n- Safaricom unavailable (502, refunded): `{\"phoneNumber\":\"0799999999\"}`\n\n**Police clearance certificate (DCI)** (`background.police-clearance`)\n\n- Certificate not found: `{\"refNumber\":\"PCC-6QSLJEYKG\",\"idNumber\":\"00000000\"}`\n- DCI portal unavailable (502, refunded): `{\"refNumber\":\"PCC-6QSLJEYKG\",\"idNumber\":\"99999999\"}`\n\n**General rules**\n\n- Any value containing `00000000` returns **not found**.\n- Any value containing `99999999` returns **`502 PROVIDER_UNAVAILABLE`**, a simulated outage at the source.\n- Number plates use `KZZ 000Z` (not found) and `KZZ 999Z` (outage).\n- For phone ownership, an ID number ending in `1` returns `matched: false`.\n\n# Errors\n\nDpaverify uses standard HTTP status codes. Every error body has this shape:\n\n```json\n{\n \"statusCode\": 402,\n \"code\": \"INSUFFICIENT_FUNDS\",\n \"message\": \"Insufficient wallet balance\"\n}\n```\n\n| Field | Present | Meaning |\n| --- | --- | --- |\n| `statusCode` | always | The HTTP status, repeated in the body |\n| `message` | always | A human-readable explanation; may change, so don't parse it |\n| `code` | when there is one | A stable, machine-readable code; branch on this |\n| `retryable` | on `502` | `true` when retrying the same request later can succeed |\n| `requestId` | on `502` | The failed verification's id, to look it up or quote to support |\n| `issues` | on `400` | One entry per invalid field, each with a `path` and a `message` |\n\n**Status codes**\n\n| Status | Code | Meaning | What to do |\n| --- | --- | --- | --- |\n| `200` | | Verification completed, including \"not found\" answers | Read `result` |\n| `400` | | The input failed validation | Fix the fields listed in `issues` |\n| `401` | | Missing, unknown or revoked API key | Check the `Authorization` header |\n| `402` | `INSUFFICIENT_FUNDS` | The wallet can't cover this call (live keys only) | Top up in the dashboard |\n| `403` | `API_NOT_IN_PLAN` | Your bundle doesn't include this API | Contact Dpaverify to add it |\n| `403` | `NO_ACTIVE_SUBSCRIPTION` | Your organization has no active bundle | Contact Dpaverify |\n| `404` | | No such verification, or it belongs to another environment | Check the id and key |\n| `409` | | The `Idempotency-Key` was used for a different request, or is still running | Use a new key, or wait and retry |\n| `429` | `QUOTA_EXCEEDED` | Your bundle's monthly call quota is used up | Wait for the next month or upgrade |\n| `429` | | Rate limit exceeded | Back off and retry (see **Rate limits and quota**) |\n| `502` | `PROVIDER_UNAVAILABLE`, `PROVIDER_ERROR`, `PROVIDER_BAD_RESPONSE`, … | The source failed or didn't answer. **You are not charged**; the charge is refunded automatically | Retry later if `retryable` is `true` |\n\n**\"Not found\" is not an error.** If a source answers that it has no record, the verification completes with `200`, `status: \"COMPLETED\"` and `result.found: false`. It is charged, because the source was queried and answered.\n\n# Idempotency and retries\n\nNetworks fail. If a request times out, you can't tell whether the verification ran, or whether you were charged. To retry safely, send an `Idempotency-Key` header:\n\n```\nIdempotency-Key: 6f1c2a90-order-1042\n```\n\n- **Same key, same body:** you get the original verification back with the same `id`, and you are not charged again.\n- **Same key while the first attempt is still running:** you get `409`. Wait a moment, then retry with the same key.\n- **Same key, different body:** you get `409`. A key is tied to the request it was first used with.\n- **Failed verification (`502`):** the key is released, so retrying with the same key runs the check again.\n- Keys are scoped to your organization. A key is up to 255 characters; a UUID or your own order or reference number works well.\n\n**Recommended retry policy**\n\n| Response | Retry? |\n| --- | --- |\n| Timeout or connection error | Yes, with the same `Idempotency-Key` |\n| `502` with `retryable: true` | Yes, after a back-off (e.g. 2 s, 10 s, 60 s) |\n| `429` | Yes, after a back-off |\n| `400`, `401`, `402`, `403`, `409` | No; fix the cause first |\n\n# Rate limits and quota\n\n**Rate limit:** each API key can make up to **120 requests per minute**. Requests beyond that get `429 Too Many Requests` until the minute window resets. Spread out bulk work, or contact Dpaverify for a higher limit.\n\n**Monthly quota:** some bundles include a monthly number of calls. Once it's used up, verification calls get `429` with `code: \"QUOTA_EXCEEDED\"` until the next calendar month. Check where you stand with `GET /v1/usage/quota` (under **Billing and usage**). Your organization's admins are also emailed when the quota is reached.\n\n**Response times:** most verifications return in under two seconds. Police clearance checks run against the DCI portal and can take up to a minute. Set your HTTP client timeout to at least 90 seconds for those.\n\n# Pagination\n\nList endpoints return one page at a time:\n\n```json\n{\n \"data\": [ { \"id\": \"cmhd2k7q80001s60h3x9f2a1b\", \"...\": \"...\" } ],\n \"nextCursor\": \"cmhd2k7q80001s60h3x9f2a1b\"\n}\n```\n\n- `limit` sets the page size, from 1 to 100 (default 20).\n- To get the next page, pass the `nextCursor` value as `cursor`. When `nextCursor` is `null`, you have reached the last page.\n- Results are newest first.\n\n# Webhooks\n\nWebhooks tell your server about every finished verification, including ones started from the dashboard or a bulk CSV upload. To turn them on, an organization admin sets your HTTPS endpoint in the dashboard's webhook settings. The dashboard then shows a signing secret (`whsec_…`) once; store it securely.\n\n**Events**\n\n| Type | Sent when |\n| --- | --- |\n| `verification.completed` | A verification completed, including \"not found\" answers |\n| `verification.failed` | A verification failed at the source (and was refunded) |\n\n**Payload**\n\n```json\n{\n \"id\": \"cmhd2k9a20004s60hb7c1d2e3\",\n \"type\": \"verification.completed\",\n \"createdAt\": \"2026-10-30T09:15:02.530Z\",\n \"data\": {\n \"id\": \"cmhd2k7q80001s60h3x9f2a1b\",\n \"api\": \"identity.national-id\",\n \"status\": \"COMPLETED\",\n \"environment\": \"LIVE\",\n \"result\": { \"found\": true, \"...\": \"...\" },\n \"error\": null,\n \"cost\": \"50\",\n \"latencyMs\": 412,\n \"createdAt\": \"2026-10-30T09:15:02.118Z\",\n \"completedAt\": \"2026-10-30T09:15:02.530Z\"\n }\n}\n```\n\n`data` is the same object that `GET /v1/verifications/{id}` returns.\n\n**Delivery and retries**\n\n- Your endpoint has 10 seconds to reply with any `2xx` status. Do slow work after you reply.\n- Failed deliveries are retried with exponential back-off (from 2 seconds up to an hour between tries), up to 10 attempts.\n- Redirects are not followed.\n- An event can arrive more than once, and events can arrive out of order. **Deduplicate on the event `id`.**\n\n**Verifying the signature**\n\nEvery delivery is signed with your secret. The signature is in this header:\n\n```\nX-Dpaverify-Signature: t=1793351702,v1=5257a869e7ecebeda32affa62cdca3fa51cad7e77a0e56ff536d0ce8e108d8bd\n```\n\nTo check it:\n\n1. Take `t` (Unix seconds) and `v1` from the header.\n2. Compute HMAC-SHA256 of `\".\"` using your secret, as lowercase hex.\n3. Compare it with `v1` in constant time.\n4. Reject the request if they differ, or if `t` is more than 5 minutes old, which stops replays.\n\nUse the raw body bytes exactly as received, not re-serialized JSON.\n\nNode.js (Express):\n\n```js\nconst crypto = require(\"crypto\");\n\napp.post(\"/webhooks/dpaverify\", express.raw({ type: \"application/json\" }), (req, res) => {\n const header = req.get(\"X-Dpaverify-Signature\") ?? \"\";\n const { t, v1 } = Object.fromEntries(header.split(\",\").map((part) => part.split(\"=\")));\n const expected = crypto.createHmac(\"sha256\", process.env.NILINDE_WEBHOOK_SECRET).update(`${t}.${req.body}`).digest(\"hex\");\n const valid = v1?.length === expected.length && crypto.timingSafeEqual(Buffer.from(v1), Buffer.from(expected));\n if (!valid || Math.abs(Date.now() / 1000 - Number(t)) > 300) return res.sendStatus(400);\n\n const event = JSON.parse(req.body);\n // dedupe on event.id, then handle event.type\n res.sendStatus(200);\n});\n```\n\nPython (Flask):\n\n```python\nimport hashlib, hmac, os, time\nfrom flask import request, abort\n\n@app.post(\"/webhooks/dpaverify\")\ndef dpaverify_webhook():\n parts = dict(p.split(\"=\", 1) for p in request.headers.get(\"X-Dpaverify-Signature\", \"\").split(\",\"))\n body = request.get_data()\n expected = hmac.new(os.environ[\"NILINDE_WEBHOOK_SECRET\"].encode(), f\"{parts.get('t')}.\".encode() + body, hashlib.sha256).hexdigest()\n if not hmac.compare_digest(expected, parts.get(\"v1\", \"\")) or abs(time.time() - int(parts.get(\"t\", 0))) > 300:\n abort(400)\n event = request.get_json()\n # dedupe on event[\"id\"], then handle event[\"type\"]\n return \"\", 200\n```", "type": "text/plain" } } }