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

Use our JSON HTTPS API to export your organization's reporting data.

Overview

You can export the following reports for your organization:

User data
Matching data
Session data
Group matches data
Group session data

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`

The examples below use https://api.<region>.togetherplatform.com. Replace <region> with eu, au, ca, or us to match your organization.

Rate limit

Each report endpoint accepts 1 request per minute from the same IP address. The limit is counted separately for each report, so you can export the user report and the session report in the same minute.

A second request to the same report within the minute gets a 400 response with the message Too many requests, please try again later.
The minute starts with your first request. Requests made while you are over the limit do not extend the wait.
The limit applies per IP address. If several of your systems call the API from the same network address, they share it.
Please send one request at a time.

Error handling and backoff

If you receive a 400, wait a full minute before calling that report again. If you receive a 500, 502, or 503, back off exponentially and try again later.

Reports are streamed back as they are generated. If something goes wrong partway through a large report, you still receive a 200, but the JSON is cut off and will not parse. If a response does not parse, request the report again.

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

Email [email protected] to request your credentials. Credentials are available on Professional (optional) and Enterprise plans.

Once our team confirms your credentials have been issued, you can find them on your Integrations page, near the bottom under API Keys. Your credentials need the reports permission to use this API.

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.

Export reports

Every report uses the same request shape. {organizationId} is your organization ID as supplied by Together. It must be the organization your API key belongs to.

Export user data

GET https://api.<region>.togetherplatform.com/public/{organizationId}/reports/export/userReport

Export matching data

GET https://api.<region>.togetherplatform.com/public/{organizationId}/reports/export/pairingReport

Export session data

GET https://api.<region>.togetherplatform.com/public/{organizationId}/reports/export/sessionReport

Export group matches data

GET https://api.<region>.togetherplatform.com/public/{organizationId}/reports/export/groupMatchesReport

Export group session data

GET https://api.<region>.togetherplatform.com/public/{organizationId}/reports/export/groupSessionReport

Response

{"report": "<CSV text>"}

The report string can be parsed into a CSV file.

Responses

Response code	Description
200 - OK	The report was returned
400 - Bad Request	Too many requests. You called this report more than once in a minute from the same IP address
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
500 - Internal Server Error	Your credentials do not have the reports permission (message `"Client does not have access to these resources"`), or a temporary problem on our side
502 / 503	Temporary service outage

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 reports permission added.

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

Reports API