Send server events

Record signups, payments and other events from your backend, and see them on the right contact next to what they did in the browser.

5 min readUpdated 5 days ago
Before you start. You need your project's write key and access to your server's code. Analytics must be on for the project. Server events count toward your plan's monthly analytics events, shown in Compare plans.
Some events only your server knows about for sure: a payment that cleared, a renewal, a plan change from your billing system. Send them to the same place the Rectify script sends browser events, and they show up in your analytics and on the contact's timeline.
Get your write key
1.
Open Customers, then Analytics.
2.
Select the settings button at the top right.
3.
Under Setup, copy the Write Key.
3 Copy the Write Key, under Analytics Settings, Setup. The key is hidden here.
3 Copy the Write Key, under Analytics Settings, Setup. The key is hidden here.
Keep the key in an environment variable on your server, such as RECTIFY_WRITE_KEY.
The request
POST https://api.rectify.so/v1/analytics/ingest
HeaderValue
AuthorizationBearer YOUR_WRITE_KEY
Content-Typeapplication/json
The body holds one visitor, one session and up to 100 events:
FieldTypeNotes
visitorIdstringRequired. 1 to 128 characters. Can't start with pv_ or portal_.
sessionIdstringRequired. 1 to 128 characters.
eventsarrayRequired. 1 to 100 events.
Each event:
FieldTypeNotes
typestringUse custom for your own events.
namestringThe event name, up to 200 characters.
timestampnumberRequired. When it happened, in milliseconds since 1970 (Date.now()).
userIdstringYour own ID for the person. Shows the event on their contact.
propertiesobjectOptional details, such as { "plan": "pro" }.
Send an event
Send userId on each event so it lands on the right contact. For visitorId, use the contact's visitorId. The Contacts API returns it when you identify the person, and identifying first also makes sure the contact exists.
curl -X POST https://api.rectify.so/v1/analytics/ingest \
  -H "Authorization: Bearer $RECTIFY_WRITE_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "visitorId": "srv_6f1c2a90-3b1e-4d0a-9a51-2f7c8e4b1d33",
    "sessionId": "billing-server",
    "events": [{
      "type": "custom",
      "name": "plan_upgraded",
      "userId": "user_123",
      "timestamp": 1793091600000,
      "properties": { "from": "free", "to": "pro" }
    }]
  }'
A saved batch returns:
JSON
{ "ok": true, "accepted": 1 }
accepted is the number of events stored.
Use one sessionId per job or process, such as billing-server. A new visitorId that Rectify hasn't seen before creates a new anonymous contact, which is why the contact's own visitorId works best.
Send a payment
Name the event revenue and put the amount, as a number, in properties.amount. The currency defaults to USD.
JSON
{
  "type": "custom",
  "name": "revenue",
  "userId": "user_123",
  "timestamp": 1793091600000,
  "properties": { "amount": 49, "currency": "USD", "plan": "pro" }
}
Revenue goals and the Revenue alert count these payments, the same as revenue() in the browser.
Who the event belongs to
•
The userId on an event shows it on the contact with that user ID, next to their browser activity.
•
Sending an event doesn't change a contact's name, email, plan or company. Use POST /v1/contacts/identify from the Contacts API for that.
•
identify events sent here from a server are stored, but they don't update the contact when your project has a website address. Rectify only takes identity from your own site.
Errors and limits
StatusBodyWhat to do
400{ "error": "..." }A field is missing or the wrong type. Check visitorId, sessionId, events and each timestamp.
401{ "error": "Invalid analytics write key" }Copy the write key again.
403{ "error": "Analytics is disabled for this project" }Turn Analytics Settings On.
429{ "ok": false, "error": "Monthly event quota exceeded", "used": ..., "limit": ... }Your plan's monthly events are used up. Upgrade or wait for next month.
429{ "error": "Too many ingest requests, please slow down" }Wait a minute and retry.
Each write key can send up to 120 requests a minute, and each IP address up to 500 requests to the API every 15 minutes. Put up to 100 events in one request instead of sending them one by one.
Check it worked
1.
Send a test event with your own user ID.
2.
Open Customers, Contacts, then your contact. The event shows on the timeline.
3.
Or open Customers, Activity and look for the event name.
Troubleshooting
The event doesn't show on the contact
Check that the event's userId matches the user ID on the contact exactly. If the contact has no user ID, identify it first with the Contacts API.
I see new anonymous contacts after sending events
Each new visitorId creates a visitor. Use the visitorId the Contacts API returns for the person instead of making one up.

Was this helpful?

Your feedback shapes what we write next.

Related articles