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:

1. Your integration fetched the real consent text (not a cached or modified version).
2. 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.