> ## Documentation Index
> Fetch the complete documentation index at: https://docs.chmodlab.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Overview
> The config object you attach to a transaction, and what every field defaults to.
The `config` object on
[Create transaction](/api-reference/transactions/create-transaction) declares what should
be accepted. Every field is optional and has a default, so `"config": {}` is valid — you
only set what you want to change.
Configuration is **per transaction**, not per account. Two verifications for the same
customer can enforce completely different rules, which is what lets you run a strict
onboarding check and a lighter step-up check from the same integration.
## Shape
```json lines theme={null}
{
"transaction_ttl_minutes": 1440,
"webhook": { "url": "https://api.example.com/hooks/chmod" },
"device_policy": { "...": "..." },
"document_policy": { "...": "..." },
"biometric_policy": { "...": "..." },
"blacklist_policy": { "...": "..." }
}
```
Rooted devices, emulators, VPNs and spoofed GPS.
Accepted documents, expiry, and matching against expected data.
Liveness and face-comparison thresholds, age and gender.
Faces on an internal or global blocklist.
## Which policies apply
A policy that does not apply to the transaction type is ignored:
| Policy | `DOCUMENT_AND_BIOMETRIC` | `DOCUMENT_ONLY` | `BIOMETRIC_ONLY` |
| - | :-: | :-: | :-: |
| `device_policy` | Applies | Applies | Applies |
| `document_policy` | Applies | Applies | Ignored |
| `biometric_policy` | Applies | Ignored | Applies |
| `blacklist_policy` | Applies | Applies | Applies |
## Policy actions
Most policy fields take one of three actions. This is the vocabulary that runs through
the whole configuration:
| Action | Effect |
| - | - |
| `REJECT` | Emits a `REJECT` issue. The transaction is `REJECTED`. |
| `WARN` | Emits a `WARN` issue. **The decision is unchanged.** Recorded for your review. |
| `IGNORE` | Emits nothing. The signal is not evaluated. |
`WARN` is how you observe a signal before you start enforcing it. Ship a new rule as
`WARN`, watch how often it fires against real traffic, then move it to `REJECT` once you
know the false-positive rate.
## Defaults
What you get when you omit a field entirely:
| Field | Default |
| - | - |
| `transaction_ttl_minutes` | `1440` (24 hours) |
| `webhook` | none — no notification is sent |
| `device_policy.on_compromised_device` | `REJECT` |
| `device_policy.on_developer_mode` | `WARN` |
| `device_policy.on_emulator` | `REJECT` |
| `device_policy.on_vpn_or_proxy` | `WARN` |
| `device_policy.on_gps_mock_location` | `REJECT` |
| `device_policy.on_gps_ip_location_mismatch` | `WARN` |
| `document_policy.document_eligibility` | every supported document is accepted |
| `document_policy.data_matching` | nothing is matched |
| `biometric_policy.liveness_min_score` | `0.85` |
| `biometric_policy.face_comparison_min_score` | `0.85` |
| `biometric_policy.expected_gender` | `null` (any) |
| `biometric_policy.expected_min_age` / `expected_max_age` | `null` (any) |
| `biometric_policy.require_face_comparison` | `true` |
| `biometric_policy.on_another_customer_repeated_face` | `REJECT` |
| `blacklist_policy.on_internal_face_blacklist_match` | `REJECT` |
| `blacklist_policy.on_global_face_blacklist_match` | `REJECT` |
## Transaction lifetime
How long the user has to complete the flow, counted from creation. Range 1–1440
(24 hours). Once it elapses the transaction moves to `EXPIRED` and the `sdk_token`
stops working.
Match the TTL to how you deliver the flow. A verification the user starts immediately
after tapping a button does not need 24 hours — an hour is plenty, and a short window
limits how long a leaked token is useful. A link sent by email is the case that justifies
a long TTL.
## Webhook
Where chmod notifies you once the decision exists. Must start with `https://`.
See [Webhooks](/results/webhooks) for the payload, the signature and how to verify it.
## A complete example
A strict onboarding check for Argentina, matching against data you already hold:
```json lines theme={null}
{
"transaction_ttl_minutes": 60,
"webhook": {
"url": "https://api.example.com/hooks/chmod"
},
"device_policy": {
"on_compromised_device": "REJECT",
"on_developer_mode": "WARN",
"on_emulator": "REJECT",
"on_vpn_or_proxy": "REJECT",
"on_gps_mock_location": "REJECT",
"on_gps_ip_location_mismatch": "WARN"
},
"document_policy": {
"document_eligibility": {
"filter_mode": "ALLOW",
"target_documents": [
{ "country": "AR", "type": "NATIONAL_ID", "allow_expired": false },
{ "country": "AR", "type": "PASSPORT", "allow_expired": false }
]
},
"data_matching": {
"given_names": { "value": "Ana Maria", "similarity_min_score": 0.85 },
"surnames": { "value": "Perez", "similarity_min_score": 0.85 },
"gender": "F",
"document_type": "NATIONAL_ID",
"document_issuing_country": "AR",
"document_number": "20123456",
"date_of_birth": "1996-01-09"
}
},
"biometric_policy": {
"liveness_min_score": 0.9,
"face_comparison_min_score": 0.9,
"require_face_comparison": true,
"expected_min_age": 18,
"expected_max_age": 120
},
"blacklist_policy": {
"on_internal_face_blacklist_match": "REJECT",
"on_global_face_blacklist_match": "REJECT"
}
}
```
Build the config on your server from your own records. If your mobile app can influence
any of these values, a modified client can weaken its own verification.
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.