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


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


As supplied by Together


As supplied by Together


As supplied by Together




Please email 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:


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)




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": "", "alternateEmails": ["", ""], "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


Update a user


Get a user



Response Code


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


Temporary service outage

*For 429/500/502/503 please back-off and try again later.




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.