Integrating with your System
Wire your backend to the cidaas ID validator: authorize with OAuth2, create validation processes, pass reference data, and read results.
Request/response schemas, scopes, and error codes live in the OpenAPI reference: cidaas id-validator (also under APIs in the sidebar). This guide covers the integration path — app setup, when to send which fields, and how Document Data Matching uses custom_attributes.
1. App & scopes
Non-interactive app with process and result scopes.
2. Create process
POST /id-val-srv/processes — start a case and get a user task URL.
3. Read result
Webhook + GET …/idcases/{caseID}/result.
Complete Prerequisites (configuration, theme, webhook) before integrating.
Enabling communication
cidaas uses applications for API authorization. In the Admin UI open Apps → App Settings → + Create New App.
Set App Type to Non-Interactive.
Choose a descriptive App Name (e.g. ID Validation Backoffice Application), then under App Settings → Scope select:
| Scope | Purpose |
|---|---|
cidaas:idval_process_start | Create processes |
cidaas:idval_process_read | Read process status |
cidaas:idval_result_read | Read case results |
Optional — manage configurations via API:
| Scope | Purpose |
|---|---|
cidaas:idval_settings_write | Create / update settings |
cidaas:idval_settings_read | Read settings |
cidaas:idval_settings_delete | Delete settings |
Fill Company Details and submit. Every secured ID validator request must include a valid Bearer token.
Obtaining an OAuth2 token
Edit your app in the overview and copy Client ID and Client Secret.
Never publish Client ID + Client Secret. Anyone with both can mint valid tokens.
{
"client_id": "{{client_id}}",
"client_secret": "{{client_secret}}",
"grant_type": "client_credentials",
"provider": "self"
}
{
"access_token": "eyJhbGciO...",
"expires_in": 86400,
"token_type": "Bearer",
"sub": "ANONYMOUS",
"sid": "8d3ce52a-906f-4308-9c6c-f3782cbffe38"
}
Use access_token as Authorization: Bearer … on ID validator calls. expires_in is in seconds (86400 ≈ 24h).
Creating an ID validation
You need:
- An ID validation setting (
validation_settings_id) - A post-completion
redirect_url - Clarity on consent (in-flow vs. already obtained)
Full request/response contract: Create ID validation (POST /id-val-srv/processes, operation create-process).
Minimal payload
{
"validation_settings_id": "61df0ecd-dcc1-4025-8d35-d67d4bf14553",
"external_reference": "YourExternalReference",
"redirect_url": "https://example-eshop.com/age-verification",
"user_id_type": "email"
}
Depending on your setting you may also need custom_attributes and/or consents — see below. On success, redirect the user to data.user_task_url from the response (field details in the API reference).
Custom attributes
custom_attributes is a key–value object. Keys must match the field_key values configured for Prevalidation and/or Document Data Matching. If either feature is enabled, every required field key must be present in the create-process payload.
How document data matching uses them
Ground truth: values you send in custom_attributes are the reference.
After the scan, the ID validator extracts the mapped document fields and compares them to your payload. A mismatch fails or flags that matching step.
This is not face matching (selfie vs. document photo). Data matching is textual / MRZ attributes you already hold.
Configure fields in the Admin UI: Document data matching · mode guidance: Verification Modes.
Example — Document Data Matching only
Only Family Name (surname) and Given Names (given_names) are enabled → supply those keys:
{
"validation_settings_id": "61df0ecd-dcc1-4025-8d35-d67d4bf14553",
"external_reference": "YourExternalReference",
"redirect_url": "https://example-eshop.com/age-verification",
"user_id_type": "email",
"custom_attributes": {
"given_names": "Hans",
"surname": "Hansemann"
}
}
Example — plus Prevalidation
Add the Prevalidation key (e.g. customer_number) to the same object:
{
"validation_settings_id": "61df0ecd-dcc1-4025-8d35-d67d4bf14553",
"external_reference": "YourExternalReference",
"redirect_url": "https://example-eshop.com/age-verification",
"user_id_type": "email",
"custom_attributes": {
"given_names": "Hans",
"surname": "Hansemann",
"customer_number": "DE42018769"
}
}
Consent(s)
Consent can be collected inside the ID validator UI, or earlier in your product.
If consent capture is disabled in the setting, include consents (at least one entry with name + url):
{
"validation_settings_id": "61df0ecd-dcc1-4025-8d35-d67d4bf14553",
"external_reference": "YourExternalReference",
"redirect_url": "https://example-eshop.com/age-verification",
"user_id_type": "email",
"custom_attributes": {
"given_names": "Hans",
"surname": "Hansemann",
"customer_number": "DE42018769"
},
"consents": [
{
"name": "processing-consent",
"url": "https://www.example.com/consents/id-validation"
}
]
}
Schema details: Consents in the API reference.
Obtaining the result
After your webhook signals completion:
Full result schema: API reference.
Most important: result.status
| Value | Meaning |
|---|---|
SUCCESS | Approved — jwt_signature is also present |
FAILED | Rejected / failed |
Media files
Some result.task_results entries include image_urls (direct image URLs). Currently iddocanalysis and idfaceanalysis.
Review in Admin UI
ID Validator → ID Validation Cases lists cases with status, document, history, and media.
Next steps
Verification Modes — security depth and document expectations.
Configuration — theme, consent, prevalidation, data matching.
cidaas id-validator — endpoints, schemas, scopes, errors.