API Details

Data Access

Verifa provides granular controls over which personally identifiable information (PII) is accessible through the API and for how long.

PII field whitelist

Each organization can configure which PII fields are returned in API responses via the api_pii_fields setting. Only whitelisted fields appear in extracted_data — all other fields are omitted.

Available fields

FieldDescription
first_nameFirst name from the identity document.
last_nameLast name / surname.
date_of_birthDate of birth (ISO 8601).
addressStructured address (line1, line2, city, state, zip).
document_numberDocument number (e.g. driver’s license number).
nationalityNationality or country of citizenship.
genderGender as printed on the document.
ssnSocial Security Number (US documents only).
document_typeType of document (e.g. drivers_license, passport).
document_expiration_dateDocument expiration date (ISO 8601).
document_issuing_stateIssuing state or jurisdiction.

If api_pii_fields is not configured, all fields are returned by default.

Signed document URLs

Document images (ID front, ID back, selfie) are served through HMAC-signed URLs with a configurable expiration time.

When you call GET /api/v1/sessions/\{session_id\}/documents, each document includes:

1{
2  "doc_type": "id_front",
3  "mime_type": "image/jpeg",
4  "url": "https://api.withverifa.com/api/v1/sessions/session_abc123/documents/id_front?expires=1738368300&sig=abc123...",
5  "expires_in": 300
6}

The expires_in value (in seconds) is controlled by the organization’s image_url_expiry_seconds setting (default: 300 seconds / 5 minutes).

Signed URLs are single-use from a security perspective — the signature is tied to the specific session, document type, and expiration timestamp.

Sensitive data window

Organizations can set a sensitive_data_retention_days value that limits how long PII and documents are accessible after a session completes.

Once the window elapses:

  • GET /api/v1/sessions/\{session_id\}/result returns an empty extracted_data object and sets sensitive_data_expired: true.
  • GET /api/v1/sessions/\{session_id\}/documents returns an empty list.
  • Non-PII fields (status, face_match_passed, age_check_passed) remain accessible.

Example response after window expiry

1{
2  "session_id": "session_abc123",
3  "status": "approved",
4  "is_sandbox": false,
5  "face_match_passed": true,
6  "face_match_score": 0.94,
7  "extracted_data": {},
8  "sensitive_data_expired": true,
9  "created_at": "2026-01-01T12:00:00Z"
10}

The window is measured from when the session enters a terminal status (completed, approved, rejected, or declined). Pending or in-progress sessions are not affected.

Data subject access (Art. 15) export

To satisfy GDPR Article 15 access requests, Verifa provides full export endpoints that return every piece of decrypted PII associated with a session or identity in a single JSON document.

EndpointScope
GET /api/v1/sessions/\{session_id\}/exportAll PII, extracted fields, verification results, and document URLs for one session.
GET /api/v1/identities/\{identity_id\}/exportSame payload aggregated across every session linked to the identity.

Both endpoints:

  • Return all decrypted PII Verifa holds for the subject — no fields filtered by the api_pii_fields whitelist.
  • Include 24-hour TTL signed download URLs for each document image so the exported bundle can be retained alongside other DSAR evidence.
  • Are recorded in the audit log as api.session.export and api.identity.export for compliance proof.

The output of either endpoint is sufficient on its own to fulfill an Article 15 access request.