User API

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:

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:

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

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