Contacts API

Create and update contacts from your server, backfill up to 500 at a time, and attach your own records such as subscriptions or orders.

7 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. Custom objects need a paid plan: Build allows 2 per project, Launch 5, Accelerate 20 and Enterprise has no limit.
Use the Contacts API to keep contacts up to date from your backend, even when people don't open your app. Plan changes, revenue and account details you send here show on the contact and their company under Customers, Contacts.
Base URL and authentication
Plain text
https://api.rectify.so/v1/contacts
Send your write key as a bearer token, and send JSON:
Plain text
Authorization: Bearer YOUR_WRITE_KEY
Content-Type: application/json
To find the write key:
1.
Open Customers, then Analytics.
2.
Select the settings button at the top right.
3.
Under Setup, copy the Write Key.
Customers, Contacts, Setup guide also shows these calls with your write key filled in. Keep the key in an environment variable on your server, not in your code.
Sync from your backend, in the Contacts setup guide. The write key is hidden here.
Sync from your backend, in the Contacts setup guide. The write key is hidden here.
Endpoints
MethodPathWhat it does
POST/v1/contacts/identifyCreates or updates one contact.
POST/v1/contacts/bulkCreates or updates up to 500 contacts.
POST/v1/contacts/objects/{objectKey}Creates or updates one custom object record.
POST/v1/contacts/objects/{objectKey}/bulkCreates or updates up to 500 records.
DELETE/v1/contacts/objects/{objectKey}/{externalId}Deletes one record.
Create or update a contact
POST /v1/contacts/identify
FieldTypeNotes
userIdstringYour own ID for the person.
emailstringSaved in lowercase.
namestringOptional.
companyobjectOptional. id, name, domain, plan, mrr, seats and status group the person into a company.
attributesobjectOptional. Any other traits, such as plan, mrr or status.
Send userId, email or both. Rectify looks for an existing contact by userId first, then by email, and creates one if neither matches. Each attribute is saved on its own, so fields you leave out keep their values.
curl -X POST https://api.rectify.so/v1/contacts/identify \
  -H "Authorization: Bearer $RECTIFY_WRITE_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "userId": "user_123",
    "email": "[email protected]",
    "name": "Jane Doe",
    "company": { "id": "acct_42", "name": "Acme", "plan": "pro", "mrr": 490 },
    "attributes": { "plan": "pro", "role": "admin" }
  }'
The response:
JSON
{
  "ok": true,
  "contact": {
    "visitorId": "srv_6f1c2a90-3b1e-4d0a-9a51-2f7c8e4b1d33",
    "userId": "user_123",
    "email": "[email protected]",
    "name": "Jane Doe"
  }
}
The plan, mrr and status attributes set the contact's stage, the same as traits sent from the browser. Identify users and send events explains stages and companies.
Backfill many contacts
POST /v1/contacts/bulk takes a contacts array of 1 to 500 items. Each item has the same fields as /identify.
Bash
curl -X POST https://api.rectify.so/v1/contacts/bulk \
  -H "Authorization: Bearer $RECTIFY_WRITE_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "contacts": [
      { "userId": "user_123", "email": "[email protected]", "attributes": { "plan": "pro" } },
      { "email": "[email protected]", "name": "Sam Lee" }
    ]
  }'
JSON
{ "ok": true, "processed": 2, "failed": 0 }
An item with neither userId nor email counts as failed. The others are still saved.
Attach your own records
Custom objects put records from your own database on a contact or company: subscriptions, orders, tickets, anything. Each field you define becomes something you can filter segments by.
Define the object
1.
Open Customers, then Contacts, and select the Objects tab.
2.
Select Let's GO!, or New Object if you already have one.
3.
Enter a Name, such as Subscription, and its Plural.
4.
Add a row under Fields for each field. Pick its Type: Text, Number, Yes / no, Date or One of a list. Turn on Required for fields every record must have.
5.
Select Create.
Create Custom Object, under Customers, Contacts, Objects.
Create Custom Object, under Customers, Contacts, Objects.
The object's key is its name in lowercase, with underscores for spaces: Subscription becomes subscription. Field keys are made the same way from their labels, so Renews on becomes renews_on. The key shows next to the object's name in the Objects list. An object can have up to 50 fields.
Send records
POST /v1/contacts/objects/{objectKey}
FieldTypeNotes
externalIdstringRequired. Your own ID for the record. id works too.
userId or emailstringThe person the record belongs to.
companyId or companyDomainstringThe company it belongs to, when it isn't a person's.
dataobjectThe record's fields, by field key.
Bash
curl -X POST https://api.rectify.so/v1/contacts/objects/subscription \
  -H "Authorization: Bearer $RECTIFY_WRITE_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "externalId": "sub_123",
    "email": "[email protected]",
    "data": { "plan": "pro", "seats": 20, "renews_on": "2026-12-01" }
  }'
JSON
{ "ok": true, "contactLinked": true, "companyLinked": true }
How records are saved:
•
Sending the same externalId again updates that record instead of making a second one.
•
Each write replaces the record's data, so send every field each time.
•
Values are checked against the field type. Numbers must be numbers, dates must be valid dates, and One of a list values must match an option. Text is cut at 2,000 characters.
•
Fields you didn't define are dropped.
•
A record that belongs to a person also counts for their company.
If you name an owner and Rectify can't find them, the record is still saved, but it isn't attached to anyone. The response then includes a warning. Identify the contact first, then send the record again.
Backfill and delete records
POST /v1/contacts/objects/{objectKey}/bulk takes a records array of 1 to 500 items, each shaped like a single record.
JSON
{ "ok": true, "processed": 499, "failed": 1, "failures": [{ "index": 12, "error": "Field \"seats\" must be a number" }] }
One bad record doesn't stop the rest. failures lists up to 20 of them, by position in your array.
To delete a record:
Bash
curl -X DELETE https://api.rectify.so/v1/contacts/objects/subscription/sub_123 \
  -H "Authorization: Bearer $RECTIFY_WRITE_KEY"
JSON
{ "ok": true, "deleted": 1 }
Errors and limits
Errors come back as JSON with an error message, for example { "error": "userId or email is required" }.
StatusWhen
400A required field is missing, a value doesn't fit the field type, or an array has more than 500 items.
401The write key is missing or wrong. The key the Rectify script uses on your site doesn't work here.
403Analytics is off for the project.
404No custom object with that key exists in the project.
429Too many requests. Wait a minute and try again.
Each IP address can make up to 120 Contacts API requests a minute. Across the whole API, each IP address can also make up to 500 requests every 15 minutes. Use the bulk endpoints for large imports.
Get a new write key
If the key gets out, open the Write Key under Analytics Settings and select the regenerate button next to it. Only Owners and Admins can do this. Your old key stops working at once, so update your server straight away. The Rectify script on your site uses a different key, so it keeps working.
Check it worked
Open Customers, then Contacts, and search for the email you sent. The contact shows your name, stage and company. Records you sent show on the contact's profile.
Troubleshooting
I get 403 "Analytics is disabled for this project"
Open Customers, Analytics, select the settings button and turn the switch On.
My record came back with a warning
No contact or company matched the userId, email, companyId or companyDomain you sent. Send the contact with /v1/contacts/identify first, then send the record again with the same externalId.
I get 404 Custom object is not defined
Check the object key in the path. It's lowercase with underscores, and shows next to the object's name under Objects.

Was this helpful?

Your feedback shapes what we write next.

Related articles