Server-to-Server Integration
Learn how to use the Ours server-to-server API to track events and send data directly to the platform from your backend systems, including Test Mode functionality.
Server-to-Server Integration
The Ours Server-to-Server API allows you to track events directly from your backend systems. This is particularly useful for situations where the Ours JavaScript tracking script cannot be used, such as server-side applications, CRMs, or other backend-only workflows.
Why Use Server-to-Server Tracking?
Server-to-server tracking enables you to:
- Capture Offline or Backend Events:
- Track interactions and events that occur outside of the client-side, such as form submissions, database updates, or external system interactions.
- Ensure Data Completeness:
- Maintain data accuracy even when users have disabled JavaScript or blocked tracking scripts.
- Enhance Privacy Compliance:
- Collect and process data securely without client-side exposure.
Getting Started with the Server-to-Server API
You first need to add the Server to Server source to your account. To do this, go to Sources > Add Source. Then, select the Server to Server source. You will then see your API token and a simple CURL command you can copy/paste to try out the integration.
For detailed instructions, refer to the Server-to-Server API Reference.
At a high level, we expect you to send events to Ours and include either a ours_user_id
, an email
, or an external_id
in the request body. Ideally, you would have already identified your user in the web browser with the same external_id
or email
. This way, we can associate the server-to-server event with the existing user.
Test Mode in Server-to-Server Integration
When using the Server-to-Server API, you have the option to test your integration with a Test Mode Token. Test Mode allows you to debug and validate your setup without dispatching events to configured destinations.
Setting Up Test Mode
-
Retrieve a Test Token:
- Navigate to the Install page in your dashboard.
- Copy the Test Mode Token.
-
Use the Test Token in API Requests:
- Include the Test Token in your API requests as part of the headers or body.
How Test Mode Works for Server-to-Server
-
Event Storage:
- Events sent using the Test Token are stored in your dashboard for review.
- These events are processed, and dispatch objects are created, but they are not sent to the destinations.
-
Dashboard View:
- Test Mode events appear in your Recent Events view with a distinct visual tag (e.g., "Test").
- This enables you to verify that events are firing correctly and that dispatches are set up as expected.
-
Switching to Live:
- After validating your setup in Test Mode, replace the Test Token with your live token to begin dispatching events to their destinations.
Debugging and Troubleshooting
If you encounter issues with the Server-to-Server API:
-
Check the API Response:
- The API returns clear error messages and status codes. Common issues include:
401 Unauthorized
: Check your token.400 Bad Request
: Verify required fields and JSON structure.
- The API returns clear error messages and status codes. Common issues include:
-
Verify Events in the Dashboard:
- Use the Recent Events Dashboard to see if your events are being ingested and processed.
-
Contact Support:
- If you’re unable to resolve an issue, reach out to [email protected] for assistance.
Use Cases for Server-to-Server Tracking
CRM or Backend Workflows
Track events such as:
- User status changes (e.g.,
LeadConverted
). - Data imports from external systems.
Offline Conversions
Capture offline interactions like:
- In-person purchases.
- Call center activity.
Secure Event Processing
Send sensitive data (e.g., medical or financial) directly from a secure backend environment.
Updated 3 months ago