How-To: Ingest a Fingerprint Request and Initiate Prefetch
This guide explains the steps required to submit a fingerprint identification request to the service deployed in the Idenza sandbox environment coral-app-2-4y6qg.ondigitalocean.app.
Prerequisites
To execute the ingestion request successfully, you must ensure the following are in place:
-
API Key: An active API key is required for authentication. This key must be provided via a custom HTTP header for every request.
-
Request Identifiers: You must have the necessary identifiers for the payload:
-
The request_id (the FingerprintJS request identifier).
-
A valid subscriber_id.
-
A session_id to correlate the user's session.
-
A user_id identifying the end user.
-
Procedure
1. Obtain and set the Authorization header.
The API requires authorization using an API Key. Supply your service key in the X-API-Key HTTP header. If this key is missing or invalid, the request will immediately fail with a 401 Unauthorized response.
API Overview
Fingerprint
Transaction Scoring
Customer Management
Header
Value
Description
X-API-KEY
<YOUR_API_KEY>
The key assigned to your service account.
2. Construct the JSON Request Body
The request body must be a JSON object (application/json) containing four mandatory fields. Failure to include any of these fields will result in a 400 Bad Request.
Field
Type
Required
Description
request_id
string
Yes
The unique identifier generated by the fingerprinting service.
subscriber_id
integer
Yes
The internal ID for your client/organization.
session_id
string
Yes
A unique identifier for the current user session.
user_id
string
Yes
The identifier for the end user (e.g., user email or UUID).
Example Request Body
JSON
{
"request_id": "1A2B3C4D5E",
"subscriber_id": 12,
"session_id": "DEV-SESSION-XYZ",
"user_id": "user@example.com"
}
3. Execute the POST Request
Send the fully constructed payload using an HTTP POST method to the target endpoint.
Endpoint URL: https://coral-app-2-4y6qg.ondigitalocean.app/fingerprint/ingest
Example Using cURL
Bash
curl -X POST \
https://coral-app-2-4y6qg.ondigitalocean.app/fingerprint/ingest \
-H "X-API-Key: <YOUR_API_KEY>" \
-H "Content-Type: application/json" \
-d '{
"request_id": "1A2B3C4D5E",
"subscriber_id": 12,
"session_id": "DEV-SESSION-XYZ",
"user_id": "user@example.com"
}'
4. Handle the Acceptance Response (202)
Upon successful ingestion, the API immediately returns a 202 Accepted status code. This confirms that the request was validated and the prefetching task has been initiated. The task runs asynchronously, and the client receives the identifiers necessary for subsequent retrieval.
Example Success Response (202 Accepted)
JSON
{
"status": "accepted",
"mode": "prefetch_pipeline",
"redis_keys":["fp:prefetch:1A2B3C4D5E"],
"user_id": "user@example.com",
"session_id": "DEV-SESSION-XYZ"
}