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.