Get contacts in: identify, the Contacts API and forms

Put names on your visitors from your site, send people and companies from your server, and let forms and portal sign-ins identify people for you.

5 min readUpdated 24 days ago
Before you start. Every visitor to a page with the Rectify script is already a contact. These steps tell Rectify who they are. You need the script on your site, and for the Contacts API, your project's write key. Analytics collection must be on (Analytics, Settings, switch at the top reads On).
There are three ways to identify people. You can use any mix of them, and they all land on the same contact.
WayBest for
Identify in the browserSigned-in users of your app. Their earlier anonymous visits join their contact.
The Contacts APISyncing people and companies from your server, including people who never visit your site.
Forms and sign-insVisitors who give you their email in a form on your site or sign in to your portal.
Identify in the browser
Add userInfo to the Rectify snippet on pages where someone is signed in. Use your own user ID, which never changes, and their email and name:
HTML
<script type="text/javascript">
  (function (w, d, s, o) {
    var js = d.createElement(s);
    js.src = o.widgetSrc;
    js.async = true;
    js.onload = function () {
      if (typeof w.Rectify === 'function') {
        w.RectifyInstance = new w.Rectify();
        w.RectifyInstance.init(o.projectId, o.userInfo, o.config);
      }
    };
    d.head.appendChild(js);
  }(window, document, 'script', {
    widgetSrc: 'https://api.rectify.so/widget/widget.umd.js',
    projectId: 'YOUR_PROJECT_ID',
    userInfo: { userId: 'usr_1001', email: '[email protected]', name: 'Jordan Lee' },
  }));
</script>
To add more about the person, such as their plan and their company, call identify once the page has loaded, for example after sign-in:
JavaScript
window.RectifyInstance?.identify('usr_1001', {
  email: '[email protected]',
  name: 'Jordan Lee',
  plan: 'business',
  mrr: 1200,
  company: {
    id: 'acct_northwind',
    name: 'Northwind Labs',
    domain: 'northwind.com',
    plan: 'business',
    mrr: 1200,
    seats: 40,
  },
});
•
The first value is the user ID. Every other key is saved on the contact, and you can segment on Plan and MRR.
•
company puts the person in a company on the Companies tab. id matters most: people with the same company ID are grouped together. Send status: 'trialing' for a trial, or status: 'canceled' for a company that left.
•
Sending plan (anything but free) or mrr marks the contact as a Customer.
Call identify after the page has loaded, not in the same moment as the snippet. A call made before Rectify is ready is skipped. The ?. keeps your page safe if the script hasn't loaded at all.
For safety, identify calls only count from your own site: the project's Website address, its subdomains, or localhost while you test. If the project has no website set, any site counts.
If you use the React, Vue, Nuxt, Svelte or Angular snippet, change init('YOUR_PROJECT_ID') to init('YOUR_PROJECT_ID', { userId: ..., email: ..., name: ... }) to pass the same userInfo.
Send people from your server
The Contacts API creates or updates a contact by user ID or email. Get your project's write key from Analytics, Settings, Setup, under Write Key. Select the copy button next to it.
The Write Key in the Setup tab of the analytics settings.
The Write Key in the Setup tab of the analytics settings.
Bash
curl -X POST https://api.rectify.so/v1/contacts/identify \
  -H "Authorization: Bearer YOUR_WRITE_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "userId": "usr_1001",
    "email": "[email protected]",
    "name": "Jordan Lee",
    "company": { "id": "acct_northwind", "name": "Northwind Labs", "plan": "business", "mrr": 1200, "seats": 40 },
    "attributes": { "plan": "business", "role": "admin" }
  }'
•
Send userId, email or both. Rectify finds the contact by user ID first, then by email, and creates one if neither matches.
•
Put everything else about the person in attributes. Other top-level keys are ignored.
•
company replaces the company you sent before, so send all its fields each time.
To send many people at once, post { "contacts": [ ... ] } to https://api.rectify.so/v1/contacts/bulk, with up to 500 people per request. The API accepts up to 120 requests a minute.
Let forms and sign-ins identify people
These work without code:
•
Forms on your site: when someone submits a form with an email field, Rectify reads the email and name and identifies them. Switch this off under Analytics, Settings, Capture, Identify people from forms.
•
Portal sign-in: people who sign in to your portal become identified contacts with their email and name.
•
Portal posts, votes and comments: people who take part without signing in are added as contacts too.
Feedback and chats from the widget don't create contacts on their own. They join a contact whose email matches.
Check it worked
Open Contacts and search for the person's name or email. They show with their Stage, and their profile shows Identified themselves in their activity. A company you sent appears on the Companies tab.
The person still shows as Anonymous
Check identify runs after the page has loaded and that you're testing on your project's website address or localhost. Then visit a page and wait a minute.
The API says "Analytics write key required" or "Invalid analytics write key"
Send the key as Authorization: Bearer YOUR_WRITE_KEY. If someone regenerated the key, copy the new one from Write Key.
The API says "Analytics is disabled for this project"
Analytics collection is paused for this project. An Owner or Admin can switch it back on at the top of Analytics, Settings.
The API says "userId or email is required"
Every contact needs a userId, an email or both.

Was this helpful?

Your feedback shapes what we write next.

Related articles