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/Back off
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 |
|
Authentication
Please email integrations@togetherplatform.com to request your credentials.
Methods
Create or update user(s)
POST https://api.togetherplatform.com/public/user
Body
Supply an application/json
body with a schema matching the 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.