Note: This feature is available on Professional and Enterprise plans. To learn more or upgrade, contact us at [email protected].

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 themselves.

The user must already exist in Together. This API does not create users; use the User API for that.

Base URL

Together hosts the API in several regions. Send your requests to the host that matches your organization's data residency. If you are not sure which one applies to you, ask your Together contact.

Region	Base URL
European data residency	`https://api.eu.togetherplatform.com`
Australian data residency	`https://api.au.togetherplatform.com`
Canadian data residency	`https://api.ca.togetherplatform.com`
US, or no data residency specified	`https://api.us.togetherplatform.com`

Authentication

Email [email protected] to request your credentials. Credentials are available on Professional (optional) and Enterprise plans. Once issued, you can find them on your Integrations page, near the bottom under API Keys.

Your credentials need the users permission to use this API, the same permission the User API uses.

We strongly recommend a secrets manager. Plain text files like dotenv lead to accidental, costly leaks. Doppler is a developer-friendly option, and AWS and Google Cloud have native solutions as well.

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`

Register an existing user into a program

POST https://api.<region>.togetherplatform.com/public/{organizationId}/registerUser

{organizationId} is your organization ID as supplied by Together. It must be the organization your API key belongs to.

Request body

Identity (choose one)

email: The user's email address.
userId: The internal Together user ID.
employeeId: The employee ID on record for the user in Together, usually from your HRIS.

Send one of these. If you send more than one, we use userId first, then email, then employeeId, and ignore the rest.

Program

programId (required): The target program's ID.
matchTypeIds (optional): An array of IDs for the specific match types to register the user in. If you leave it out or send an empty array, the user is registered in every match type in the program.

Roles

roles (required): An object with mentor, mentee, and peer keys set to true or false. At least one must be true. The user is registered in each role set to true, in each match type.

Example request

{
  "email": "[email protected]",
  "programId": "yourProgramId",
  "matchTypeIds": [
    "yourMatchTypeId"
  ],
  "roles": {
    "mentor": true,
    "mentee": false,
    "peer": false
  }
}

Responses

Response code	Description
200 - OK	The user was registered into the program
400 - Bad Request	Bad input: no `userId`, `email`, or `employeeId`; no `programId`; no `roles`, or no role set to `true`; or the program has no match types. A 400 with `Failed to register user` means the registration itself did not go through
401 - Unauthenticated	Missing or invalid credentials. Check the api-key, client-id, and organization-id headers
403 - Forbidden	The `organizationId` in the URL is not the organization your API key belongs to
404 - Not Found	No user in your organization matches the userId, email, or employeeId you sent
500 - Internal Server Error	Your credentials do not have the users permission (message `"Client does not have access to these resources"`), or an unexpected problem on our side
502 / 503	Temporary service outage

A 200 confirms the user was registered into the program. If they do not appear in a match type you expected, contact us with the request details.

Error handling and backoff

For 500, 502, and 503, back off and try again later. If a 500 says "Client does not have access to these resources", contact us to have the users permission added.

Have more questions? Submit a request here and let us know how we can help.

Registration API