Use our JSON HTTPS API to add users to your organization! 

Overview

You can integrate your User Directory information by pushing data into Together. It is recommended you call the API:

  • For each user once per day
  • When things change

Rate Limit

In order to avoid your key being revoked, you must send requests at the less frequent rate of:

  • 1 request per second
  • 1 request at a time 

Error Handling/Backoff

If receiving 429/500/502/503's you are expected to exponentially back off 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

Please email support@togetherplatform.com & CC integrations@togetherplatform.com to request your credentials. 

Note: credentials are only available for Professional (optional) and Enterprise plans. 

Once our team has confirmed that your credentials have been issued, you will be able to find them on your Integrations page near the bottom under API Keys:

api_keys.png

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

Create or update user(s)

POST https://api.togetherplatform.com/public/user

 

Body

Supply an application/json body with a schema matching the organizational data spec.

 

You can supply an array of users or one single user.

{ "employeeId": "asdhja82jdld02hwp102s", // This must be globally unique for your org, "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", }

 

If you provide either an employeeID or a employeeNumber, a patch will be made to the existing record. Only supplied fields will be overwritten. Otherwise, a new record will be created.

List all users

GET https://api.togetherplatform.com/public/user

Update a user

POST https://api.togetherplatform.com/public/user/:userId

Get a user

GET https://api.togetherplatform.com/public/user/:userId

Responses

Response Code

Description

200 - OK

User fields were updated

201 - Created

New user was created

204 - No content

Attempted to update user but user is already up to date

400 - Bad Request

Missing required information, see response body

401 - Unauthenticated

Please attach valid authentication credentials

409 - Conflict

The system cannot update the user as it has been modified permanently on Together's side

410 - Gone

This user account has been 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/503 please back-off and try again later.

 

 

Share

Was this article helpful?

0 out of 0 found this helpful
Have more questions? Submit a request

Articles in this section

Comments (0 comments)

Article is closed for comments.