Consent Handling
Before a user can upload media or submit a verification, they must accept the current consent text. This is required for GDPR compliance and ensures informed consent for biometric data processing.
Why Consent Is Required
ProofAge processes biometric data (facial images, identity documents) on behalf of your users. Under GDPR and similar data protection regulations, explicit and informed consent is required before this processing can begin.
The consent flow ensures that:
- The user has been shown the exact legal text governing how their data will be processed.
- Your integration can prove which version of the consent text was accepted.
- The acceptance is cryptographically tied to a specific text via SHA-256 hash verification.
WARNING
Media uploads and submission are blocked until consent is accepted. Any attempt to call POST /v1/verifications/{id}/media or POST /v1/verifications/{id}/submit before consent is recorded returns 403 Forbidden with error code CONSENT_REQUIRED.
Step-by-Step Flow
1. Fetch the Active Consent Version
Retrieve the current consent text and its metadata:
curl -X GET https://api.proofage.com/v1/consent \
-H "X-API-Key: YOUR_API_KEY" \
-H "X-HMAC-Signature: YOUR_HMAC_SIGNATURE"Response (200 OK):
{
"data": {
"id": 42,
"version": "2026-01-15",
"text_sha256": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
"url": "https://proofage.com/legal/consent/2026-01-15"
}
}| Field | Description |
|---|---|
id | The numeric identifier of this consent version. Pass this when accepting consent. |
version | A human-readable version label (typically a date). |
text_sha256 | The SHA-256 hash of the full consent text. You must send this back when accepting to prove the correct text was shown. |
url | A URL where the full consent text can be retrieved and displayed to the user. |
2. Display the Consent Text
Fetch the consent text from the url returned above and display it to your user. The text must be shown in its entirety — do not summarize or paraphrase it.
3. Accept Consent
Once the user agrees, record their acceptance on the verification:
curl -X POST https://api.proofage.com/v1/verifications/ver_abc123def456/consent \
-H "Content-Type: application/json" \
-H "X-API-Key: YOUR_API_KEY" \
-H "X-HMAC-Signature: YOUR_HMAC_SIGNATURE" \
-d '{
"consent_version_id": 42,
"text_sha256": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855"
}'Request body:
| Field | Type | Required | Description |
|---|---|---|---|
consent_version_id | integer | Yes | The id of the consent version from GET /v1/consent. |
text_sha256 | string (64 hex chars) | Yes | The SHA-256 hash of the consent text. Must match the active consent version. |
Response (200 OK):
{
"data": {
"id": "ver_abc123def456",
"consent": {
"version_id": 42,
"version": "2026-01-15",
"accepted_at": "2026-03-19T12:01:00Z"
}
}
}After this, the verification is unblocked and you can proceed to upload media.
SHA-256 Verification
The text_sha256 field serves as a tamper-proof receipt. When you accept consent, the API verifies that the hash you send matches the hash of the active consent version's text.
This guarantees that:
- Your integration fetched the real consent text (not a cached or modified version).
- The user was shown the exact text that ProofAge published for that version.
You do not need to compute the SHA-256 yourself. Simply pass back the text_sha256 value you received from GET /v1/consent. If you want to verify it independently, compute SHA-256 over the raw UTF-8 bytes of the consent text retrieved from the url.
Idempotency
Consent acceptance is idempotent. If you call POST /v1/verifications/{id}/consent a second time with the same consent_version_id and text_sha256, the API returns the existing consent record without creating a duplicate.
This means it is safe to retry the consent call if a network error occurs — you will not create inconsistent state.
Error Cases
| HTTP Status | Error Code | Cause | Resolution |
|---|---|---|---|
| 409 | CONSENT_VERSION_INACTIVE | The consent_version_id refers to a consent version that is no longer active. | Call GET /v1/consent again to fetch the current active version and re-display the text to the user. |
| 409 | CONSENT_SHA256_MISMATCH | The text_sha256 you sent does not match the active consent version. | This usually means the consent text was updated between when you fetched it and when the user accepted. Fetch the latest version and try again. |
| 422 | VALIDATION_ERROR | Missing or invalid fields (e.g., consent_version_id is not an integer, or text_sha256 is not 64 hex characters). | Fix the request body per the field requirements above. |
| 403 | CONSENT_REQUIRED | Returned on media upload or submit endpoints when consent has not been accepted. | Accept consent first, then retry the blocked operation. |
Complete Example
This example shows the full consent flow from fetch to acceptance, then proceeds to upload a selfie.
# 1. Fetch the active consent version
curl -s -X GET https://api.proofage.com/v1/consent \
-H "X-API-Key: YOUR_API_KEY" \
-H "X-HMAC-Signature: YOUR_HMAC_SIGNATURE"
# Response:
# {
# "data": {
# "id": 42,
# "version": "2026-01-15",
# "text_sha256": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
# "url": "https://proofage.com/legal/consent/2026-01-15"
# }
# }
# 2. Display the text from the URL to your user and obtain their agreement.
# 3. Record the user's consent
curl -s -X POST https://api.proofage.com/v1/verifications/ver_abc123def456/consent \
-H "Content-Type: application/json" \
-H "X-API-Key: YOUR_API_KEY" \
-H "X-HMAC-Signature: YOUR_HMAC_SIGNATURE" \
-d '{
"consent_version_id": 42,
"text_sha256": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855"
}'
# Response:
# {
# "data": {
# "id": "ver_abc123def456",
# "consent": {
# "version_id": 42,
# "version": "2026-01-15",
# "accepted_at": "2026-03-19T12:01:00Z"
# }
# }
# }
# 4. Now media uploads are unblocked
curl -s -X POST https://api.proofage.com/v1/verifications/ver_abc123def456/media \
-H "X-API-Key: YOUR_API_KEY" \
-H "X-HMAC-Signature: YOUR_HMAC_SIGNATURE" \
-F "type=selfie" \
-F "[email protected]"Next Steps
- Uploading Media — File requirements and validation errors for the next step after consent.
- Verification Flow — The full verification lifecycle.
- Authentication — How to compute HMAC signatures for these requests.