Overview
Use our JSON HTTPS API to register users from your User Table into a program. Call the API when a user needs to be registered in a program without them needing to take any action to do so themselves.
Note: This feature is only available for Professional and Enterprise plans. To learn more or upgrade, please contact us at [email protected].
Authentication
Please email [email protected] to request your credentials.
Credentials are only available for Professional (optional) and Enterprise plans. Once issued, you can find them on your Integrations page near the bottom under API Keys.
We strongly recommend using a secrets manager instead of plain text files. Consider Doppler for a developer-friendly experience. AWS and Google Cloud also have native secret management solutions.
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 |
Request Body
Send a JSON object whose identity section includes exactly one of the following, plus the program specification and roles.
Identity (choose one)
email: The user’s email address.
userId: The internal Together user ID.
employeeId: The external employee identifier from your HRIS/the employeeId on record for the user in Together.
Program
programId (required): The target program’s ID.
matchTypeIds (optional): Array of IDs for the specific match types to enroll the user in. If omitted, the API will attempt to register the user in all match types for the program.
Roles
roles (required): A map indicating at least one role the user should hold in the program. At least one role is required. Keys represent role types; values are booleans.
Register an existing user into a program
POST https://api.togetherplatform.com/public/{{organizationId}}/registerUserExample Request
Responses
Response Code | Description |
200 - OK | Success - the user was registered into the program |
400 - Bad Request | Bad input. Double check missing programId, role, userId or email |
429 - Too many requests | Slow down your request rate |
500/502/503 | Temporary service outage - something is likely wrong with Together’s app internally |
Error Handling/Backoff
For 429/500/502/503, back-off and try again later.
Have more questions? Submit a request here and let us know how we can help!