User API

Article author
Joey
  • Updated

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.

 

 

Was this article helpful?

0 out of 0 found this helpful

Have more questions? Submit a request

Comments

0 comments

Article is closed for comments.