We are dedicated to providing the best and cleanest APIs possible. Our existing Server API (v3) and Webhooks formats had inconsistencies and legacy baggage from our rapid growth. That's why we are introducing a new major iteration of our Server API and Webhooks. Read on to learn about the most important changes.

What's new

• Removed excessive nesting in responses. Payloads are no longer nested under top-level data and products, including at individual Smart Signals level (removed result). This makes the format and generated documentation clearer and easier to consume.
• Unified Webhooks and Server API (events format). All Server API responses now share the same data format described in our public documentation. Sealed Client Results will be upgraded to the same iteration with the v4 JS agent release.
• Deprecated the /visitors search endpoint in favor of /v4/events (which provides the same and more functionality). This legacy endpoint will be removed on Oct 31, 2026.
• Introduced more descriptive error codes and messages. Errors now include suggestions and links to relevant documentation where applicable.
• Removed the possibility of partial payloads when an internal service fails (previously it was possible to receive Identification data with Smart Signals errors). Unreliable partial responses are replaced with a clear error instead.
• Replaced the Auth-Api-Key header and apiKey parameter with the standard Authorization: Bearer header. Existing secret API keys work with this header without issues.
• Upgraded the OpenAPI version and started using an OpenAPI definition for Webhooks alongside the rest of the Server API documentation.
• Removed the Retry-After header as it did not work well with our rate limiting logic.
• Renamed request_id to event_id.
• Unified usage of snake_case across URLs and request/response payload fields.

Migration Overview

How to migrate from v3 to v4

Migration needs depend on which deprecated endpoints you are using. If you are not using Server API or Webhooks, there is nothing to migrate today. Breaking changes related to the JavaScript agent are coming soon.

Migrating GET /visitors

The GET /visitors endpoint is fully replaced by /v4/events, which is an extended version of the v3 /events/search endpoint.

• In v4, use filters such as visitor_id, linked_id, suspect, start, and end to get the same results.
• Latency differences: /visitors had latency independent of event age. In /v4/events, most recent events (≤24h) are served from cache and are very fast. Older events may take longer to load from archival storage.
• To minimize latency, always pass a time window with start and end.

curl --request GET \
+    --url "https://api.fpjs.io/v4/events?start=1725148800&end=1727731199" \
-    --url "https://api.fpjs.io/visitors?limit=100" \
     --header 'Accept: application/json' \
+    --header 'Authorization: Bearer <secret key>'
-    --header 'Auth-Api-Key: <secret key>' 

Migrating GET /events

The current version of GET /events uses the old nested event format and the old Auth-Api-Key header. To migrate to the new /v4/event endpoint, you have to

1. Start using the Authorization: Bearer <secret key> header for authorization
2. Migrate to the new format, either by using our Server SDKs or adopting the model to the v4 specification

Migrating GET /events/search

The current version of GET /events/search uses the old nested event format and the old Auth-Api-Key header. To migrate to the new /v4/events endpoint, you have to

1. Start using the Authorization: Bearer <secret key> header for authorization
2. Migrate to the new format, either by using our Server SDKs or adopting the model to the v4 specification

Migrating UPDATE /events

The update operation remains conceptually the same, but method, path, auth header, and some field names have changed.

1. Exchange the Auth-Api-Key: <secret key> header for Authorization: Bearer <secret key>
2. Change the method from PUT to PATCH
3. Update the path to /v4/event/:event_id
4. Rename fields to snake_case (e.g., linkedId -> linked_id)
5. (optional) Check the documentation for new error codes and adapt your implementation to handle them

+ curl --request PATCH \
- curl --request PUT \
+     --url https://api.fpjs.io/v4/event/:event_id \
-     --url https://api.fpjs.io/events \
     --header 'Accept: application/json' \
     --header 'Content-type: application/json' \
+     --header 'Authorization: Bearer <secret key>' \
-     --header 'Auth-Api-Key: <secret key>' \

     --data '
    {
+      "linked_id": "<user_id>"
-      "linkedId": "<user_id>"
    }'

Migrating Webhooks

The deprecated version of Webhooks can still be configured through the Dashboard.

Webhooks v4 follow the same format as /v4/events, so you can reuse most of the code used with other Server API endpoints.

The new Webhook format is not available through the Dashboard yet, but the Webhooks MGMT-API supports it by default (it is not possible to create legacy Webhook format with it). Follow this basic example to create a Webhook:

curl --request POST \
     --url https://management-api.fpjs.io/webhooks \
     --header 'Accept: application/json' \
     --header 'Content-type: application/json' \
     --header 'Authorization: Bearer <secret key>' \
     --data '
    {
    "url": "https://example.com",
    "description": "My example v4 webhook",
    "status": "enabled"
    }'

Review the Webhook MGMT-API documentation for more detail about how to manage the new version of webhooks. Dashboard support (UI) is coming soon.

📘

Set up the old and the new webhook side by side

We recommend setting up a new webhook alongside the old one. Create a new webhook through the Management API mentioned above, integrate it, test that it delivers the new information correctly, and then remove the old one without any loss of data.