API reference
RDCPASS exposes eight services over one HTTP API. They share the same authentication, request fields, response envelope, request modes and error format, documented once on this page; each service page then covers its own fields and outcomes in full.
Base URLs
| Environment | Base URL |
|---|---|
| Production | https://api.rdcpass.cd |
| Sandbox | https://gateway.staging.rdcpass.cd |
Credentials are issued per environment and never work across them — see Sandbox & environments.
Authentication
Every endpoint requires the full RDCPASS authentication stack — HMAC request signing, mutual TLS in production and AES-256-GCM payload encryption — with one exception: the OpenID Connect endpoints of Login with RDCPASS use standard OAuth/OIDC client authentication, so off-the-shelf OIDC libraries work unmodified. Read Authentication before your first request.
Services and endpoints
| Service | Single | Batch | Object |
|---|---|---|---|
| KYC Validation | POST /v1/kyc/validations | POST /v1/kyc/validations/batches | kyc_validation |
| Face Recognition | POST /v1/face/recognitions | POST /v1/face/recognitions/batches | face_recognition |
| Age Verification | POST /v1/age/verifications | POST /v1/age/verifications/batches | age_verification |
| KYB Verification | POST /v1/kyb/verifications | POST /v1/kyb/verifications/batches | kyb_verification |
| AML & CTF Screening | POST /v1/aml/screenings | POST /v1/aml/screenings/batches | aml_screening |
| Credit Scoring | POST /v1/credit/scores | POST /v1/credit/scores/batches | credit_score |
| Fraud Reporting | POST /v1/fraud/reports | POST /v1/fraud/reports/batches | fraud_report |
| Login with RDCPASS | GET /v1/oidc/authorize · POST /v1/oidc/token | — | — |
Common request fields
Identity services accept the following fields. Service pages note any service-specific additions or restrictions.
| Field | Type | Required | Description |
|---|---|---|---|
| identifier | object | Yes* | { "type", "value" } — type is rdcpass_id (primary, e.g. COD-2103-0214-4937), passport, ceni, driving_licence or national_id. KYB uses rccm, id_nat or nif. |
| match | object | No | Claims to compare: full_name, date_of_birth (YYYY-MM-DD), age. Each returns match, partial_match, no_match or not_provided. |
| purpose | string | Yes | One of your application’s approved purposes: customer_onboarding, account_recovery, transaction_authorization, age_gating, regulatory_compliance, fraud_prevention, credit_assessment, employment_screening. |
| scopes | string[] | No | Subset of the scopes granted to your application; defaults to all granted scopes. A scope not granted returns 403 scope_not_granted. |
| document_delivery | string | No | signed_url (default) or base64 for document images and biometric files. |
| reference | string | No | Your own identifier, echoed back. Required on every batch item. |
* Face Recognition makes identifier optional (1:N identification); Fraud Reporting and AML & CTF Screening take a subject instead.
Common headers
| Header | Description |
|---|---|
| Idempotency-Key | Optional on every POST. A UUID; a retry with the same key within 24 hours returns the original response. |
| Prefer | Optional. respond-async runs the request asynchronously and returns 202 with a job or batch object. |
Response envelope
Every service result shares this envelope. Service-specific fields (match, similarity, risk_level, score, …) sit alongside it.
| Field | Type | Description |
|---|---|---|
| id | string | Unique result identifier, prefixed by service (kyc_, face_, age_, kyb_, aml_, crs_, frd_). |
| object | string | The object type, e.g. kyc_validation. |
| livemode | boolean | true in production, false in sandbox. |
| status | string | completed for synchronous results; asynchronous and batch items can be failed. |
| result | string | The service outcome, e.g. verified, not_found, not_certified, match, no_match. |
| account | object | The RDCPASS account: rdcpass_id, status, certified, created_at, level_of_assurance. Absent when no identity was resolved. |
| kyc | object | basic (always, when resolved) plus one block per scope applied. |
| scopes_applied | string[] | Scopes whose data is included in this response. |
| scopes_withheld | string[] | Scopes requested and granted but with no data on record — omitted, not an error. |
| created_at | string | RFC 3339 timestamp of the result. |
{
"id": "kyc_8d2f6a1c93",
"object": "kyc_validation",
"livemode": true,
"reference": "cust-0001",
"status": "completed",
"result": "verified",
"account": {
"rdcpass_id": "COD-2103-0214-4937",
"status": "active",
"certified": true,
"created_at": "2025-03-14T09:22:41Z",
"level_of_assurance": "LOA3"
},
"kyc": {
"basic": {
"full_name": "Kabeya Mwamba Tshisekedi",
"first_name": "Kabeya",
"last_name": "Tshisekedi",
"date_of_birth": "1988-04-12",
"age": 38,
"gender": "male",
"nationality": "COD"
},
"phone_numbers": [
{ "number": "+243812345678", "operator": "Vodacom", "is_primary": true, "verified": true }
]
},
"scopes_applied": ["kyc.basic", "kyc.phone_numbers"],
"scopes_withheld": ["kyc.addresses"],
"purpose": "customer_onboarding",
"created_at": "2026-09-26T10:15:02Z"
}Errors
Errors use one format across the API, with the HTTP status and a stable code. The full list is in Errors.
{
"error": "scope_not_granted",
"message": "Scope kyc.biometrics.selfie is not granted to this application."
}Request modes
Every verification service supports single and batch requests, each synchronously or asynchronously: up to 50 items in a synchronous batch and 10,000 in an asynchronous one, with results by webhook or from GET /v1/jobs/{job_id} and GET /v1/batches/{batch_id}/results. See Single, batch & async.
Versioning
The API version is part of the path (/v1). Within a version RDCPASS only makes backward-compatible changes: new endpoints, new optional request fields, new response fields, new enum values and new webhook event types. Build clients that ignore unknown fields and handle unknown enum values gracefully. Breaking changes ship as a new version, announced at least 12 months before the previous version is retired.