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.
Region | Base URL |
European data residency |
|
Australian data residency |
|
Canadian data residency |
|
US, or no data residency specified |
|
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:
Header name | Header value |
organization-id | As supplied by Together |
client-id | As supplied by Together |
api-key | As supplied by Together |
content-type | 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
Response code | Description |
200 - OK | User fields were updated |
201 - Created | New user was created |
204 - No content | The user is already up to date, so nothing changed |
400 - Bad Request | Missing required information, see the response body |
401 - Unauthenticated | Attach valid authentication credentials |
409 - Conflict | The user was modified permanently on Together's side and cannot be updated |
410 - Gone | This user account was deleted and cannot be re-added |
*429 - Too many requests | Slow down your request rate |
*500 / 502 / 503 | Temporary service outage |
*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.