Use our JSON HTTPS API to add users into your account
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 integrations@togetherplatform.com to request your credentials.
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.
Comments
0 comments
Article is closed for comments.