This guide explains how to integrate with the Identiff Age Verification API, which follows a standard REST API design. You’ll learn how to authenticate, configure webhooks, and handle verification status updates securely.
1. Overview The API enables you to:
Submit verification requests for users.
Retrieve status updates for pending or completed verifications.
Receive automated notifications when a verification status changes.
Key technical points:
RESTful architecture.
Authentication via OAuth 2.0.
API keys generated in the admin dashboard.
Webhook support for asynchronous updates.
2. Base URL & Formats All API requests are made to the base URL provided in your admin dashboard. Requests and responses use JSON with UTF-8 encoding. All timestamps are in ISO 8601 format.
3. API Key Generation Log into the Admin Dashboard.
Go to API Settings.
Select Generate New API Key.
Store this key securely — it will be used to request OAuth access tokens.
4. Authentication & Authorization The API uses OAuth 2.0 client credentials flow:
You exchange your API key and secret for an access token.
The access token must be sent with every API request in the Authorization header.
Tokens have a limited lifespan and must be refreshed periodically.
If your token has expired, requests will return an authorization error until a new token is obtained.
5. Making API Requests All API endpoints follow a predictable REST structure:
POST is used to submit verification requests.
GET is used to retrieve verification status or results.
Each request must include a valid access token in the headers. Requests without valid authentication will be rejected.
6. Webhooks Purpose Webhooks allow the API to notify your system automatically when the status of a verification changes, removing the need for constant polling.
Configuration Steps Open the Admin Dashboard.
Navigate to Integration → Webhook Settings.
Enter your webhook endpoint URL (HTTPS is strongly recommended).
Optionally, define a webhook authorization key for added security.
7. Webhook Security If you configure a webhook authorization key, it will be included in the Authorization header of every webhook request. Your system should verify this key before processing the request to ensure the payload came from the API and not a malicious source.
8. Webhook Event Data When a verification status changes, the API sends:
The event type (e.g., verification updated).
The verification ID.
The new status (e.g., verified, failed, pending).
The timestamp of the change.
Your endpoint should acknowledge receipt by returning a successful HTTP status code.
9. Best Practices Always use HTTPS for API and webhook communications.
Validate and log all webhook requests.
Refresh access tokens before they expire to avoid downtime.
Limit API key and webhook key access to authorized personnel only.
Respond promptly with 2xx HTTP codes when webhook data is processed.
10. Error Handling The API returns structured error messages when:
Required parameters are missing.
Authentication fails (expired or invalid token).
The requested resource is not found.
Internal service errors occur.
Check the error type and message in the response to determine the cause.