Note: This feature is available on Professional and Enterprise plans. To learn more or upgrade, contact us at support@togetherplatform.com.

Use our JSON HTTPS API to keep the users in your organization up to date.

Overview

You can sync your user directory by pushing data into Together. We recommend calling the API:

• Once per day for each user
• Whenever a user's details change

Base URL

Together hosts the API in several regions. Send your requests to the host that matches your organization's data residency. If you are not sure which one applies to you, ask your Together contact.

The examples below use https://api.<region>.togetherplatform.com. Replace <region> with eu, au, ca, or us to match your organization.

Rate limit

To avoid having your key revoked, keep your requests to:

• 1 request per second
• 1 request at a time

These limits are about how often you call the API, not how many users you send. A single request can contain an array of many users, so you do not need a separate request per person. See Create or update users below.

Error handling and backoff

If you receive a 429, 500, 502, or 503, back off exponentially and try again later.

Request spec

Required headers:

application/json

Authentication

Email support@togetherplatform.com to request your credentials. Credentials are available on Professional (optional) and Enterprise plans.

Once our team confirms your credentials have been issued, you can find them on your Integrations page, near the bottom under API Keys:

We strongly recommend a secrets manager. Plain text files like dotenv lead to accidental, costly leaks. Doppler is a developer-friendly option, and AWS and Google Cloud have native solutions as well.

Create or update users

POST https://api.<region>.togetherplatform.com/public/user

Supply an application/json body that matches the organizational data spec.

You can send a single user or an array of users in one request. To create or update many people at once, send an array. Each user is processed on its own, so this is how you do a bulk update without looping one request per user.

employeeId must be globally unique within your organization.

{
  "employeeId": "asdhja82jdld02hwp102s",
  "lastUpdated": "2019-01-01T00:00:00.000Z",
  "firstName": "Gary",
  "middleName": "",
  "lastName": "Smith",
  "preferredName": "",
  "email": "gary@example.com",
  "alternateEmails": ["gsmith@example.com", "gary@example2.com"],
  "dateOfBirth": "2019-01-01T00:00:00.000Z",
  "dateOfSeniority": "2019-01-01T00:00:00.000Z",
  "dateInJob": "2019-01-01T00:00:00.000Z",
  "departmentId": "PRIVEQ",
  "departmentName": "Private Equity",
  "lastHireDate": "2019-01-01T00:00:00.000Z",
  "dateOfTermination": "2019-01-01T00:00:00.000Z",
  "employeeStatusCode": "A",
  "employeeTypeCode": "C",
  "fullTimeOrPartTimeCode": "F",
  "gender": "M",
  "officeId": "NOREAST",
  "officeAddress": "1225 Norfolk Dr",
  "originalHireDate": "2019-01-01T00:00:00.000Z",
  "supervisorId": "ashiohfeio",
  "title": "Analyst",
  "remote": false,
  "addressState": "ON",
  "addressCountry": "CA"
}

To send several users, wrap the objects in an array:

[
  { "employeeId": "1001", "firstName": "Gary", "lastName": "Smith", "email": "gary@example.com" },
  { "employeeId": "1002", "firstName": "Jane", "lastName": "Doe", "email": "jane@example.com" }
]

How matching works

We match each user you send to an existing record by employeeId first, then by email. If we find a match, we patch that record and overwrite only the fields you included. If we don't find a match, we create a new user.

Custom fields

Alongside the standard fields above, you can sync custom HR fields, for example a Management Area or Cost Center value from your HRIS. Two things need to line up:

• The custom field has to be set up on your organization in Together first. Ask your Together contact to configure it. Each field has a key, for example managementArea.
• In your request body, send the value with the hrisFields. prefix followed by that key.

{
  "employeeId": "asdhja82jdld02hwp102s",
  "email": "gary@example.com",
  "hrisFields.managementArea": "North America - Cement"
}

The key after hrisFields. must match the field configured on your organization. Until that field is set up, the value won't appear anywhere in Together, including profiles, matching, and reports.

List all users

GET https://api.<region>.togetherplatform.com/public/user

Update a user

POST https://api.<region>.togetherplatform.com/public/user/:userId

Get a user

GET https://api.<region>.togetherplatform.com/public/user/:userId

Responses

*For 429, 500, 502, and 503, back off and try again later.

Have more questions? Submit a request here and let us know how we can help.