Retorio
API docs by Redocly

Retorio API (1.0.0)

Download OpenAPI specification:

Retorio is an AI coaching platform for enterprise sales, service, and leadership teams. This reference documents the admin-facing REST API behind an integration: inviting users into Retorio, removing them, receiving outbound result events, and single sign-on.

Every request and response body is JSON (the one exception is the token spreadsheet download on GET /cohorts/{id}/participants with onlyTokens, onlyAvailableTokens and format=xlsx), over HTTPS, against https://api.retorio.com/be/v2.

Authentication

Every call except GET /auth/auth_details, which is public, is authenticated with a bearer token in the Authorization header:

Authorization: Bearer <your-access-key>

For system-to-system integrations (an HR system, an LMS, identity tooling), that token is an access key. A key is scoped to your organization: it can only ever read or change data that belongs to it. The Single Sign-On endpoints do not take an access key: the Retorio coaching app calls POST /auth/coaching_sso_signup with the coaching user's own Retorio sign-in token, issued once they sign in through your identity provider.

Setting up an access key

  1. An Owner, or an admin whose role allows managing access keys, opens Integrations under Organization in the Retorio admin app's sidebar and selects Create access key.
  2. Name the key after the system that will use it, so other admins know what revoking it affects.
  3. Choose its expiry: 30, 90 or 180 days, 1 year, or a custom date. The date is at most one year ahead, and every key you create expires.
  4. Copy the key from the dialog. It is shown only this once: it cannot be retrieved through the admin app or the API afterwards, and Retorio stores only a hash of it. If you lose a key, revoke it and create a new one.
  5. Hand it to the system that calls the API through a secrets manager or password manager, never email or chat.

Treat the key as a full administrative credential for your organization. It acts with the permissions of the admin who created it. Store it in a secrets manager, never in source code or a browser, and give it only to the systems that call the API.

A key belongs to the admin who created it. When that admin is removed from your organization, every key they created stops working, and its calls get 401 with a message saying so. Changing that admin's roles changes what the key can do from its next request. Create keys from an account that will outlive any one person, such as a dedicated integration admin, holding roles that cover the calls your integration makes. The Owner role covers every Cohorts and Webhooks endpoint below. The Admin role covers the Cohorts ones but not the Webhooks ones, which need the Owner role or a custom role that allows managing webhooks. That account creates its own keys, so it also needs to be an Owner or hold a role that allows managing access keys.

Using an access key

Send the key on every request:

curl https://api.retorio.com/be/v2/cohorts \
  -H "Authorization: Bearer $RETORIO_ACCESS_KEY"
Response Meaning
400 The request failed validation, or its body is not valid JSON
401 The key is missing, malformed, expired or revoked, the admin who created it was removed, or your organization is deactivated
403 The key is valid, but its admin's roles do not allow this call
403 Cohorts endpoints: your organization does not have the coaching product. This body is { "error": "..." }
404 An id in the path does not exist in your organization
413 The request body is larger than 10 MB
415 The Content-Type charset or the Content-Encoding is one the API cannot decode. Send UTF-8 JSON without a content encoding

Each operation lists the error responses it can return, with their bodies.

A key cannot manage access keys, invite or remove admins, or change roles: those calls answer 403 whatever its admin holds. Each key's details in the admin app show when it was first and last used, and how many calls it has made.

Expiry, revocation and rotation

A key you create works until the end of the expiry date you chose, in UTC. An admin allowed to manage access keys can also revoke it on the Integrations page, and it stops working from the next request. Revoked keys stay in the list under Show revoked.

To rotate a key, create a new one before the old one expires, move your systems over to it, then revoke the old one.

Keys your organization created before access keys were managed in the admin app appear in the list as legacy keys. They stop at the date and time shown, so replace them the same way before then.

Single Sign-On setup

SSO federates sign-in only. Coaching users invited by email authenticate with your corporate identity provider instead of a Retorio password. Coaching users invited through a token cohort sign in with the Retorio password they set at sign-up, even when SSO is enabled. Admin accounts sign in with email and password, except a Microsoft Marketplace admin, who signs in with their Microsoft account.

Access needs both sides. Enabling SSO on the identity-provider side grants no access by itself. A user must also have been invited into a cohort (see the Cohorts endpoints below) with the email address your IdP asserts (compared ignoring case and surrounding whitespace). There is no SCIM or other automatic provisioning: membership is managed entirely through cohort invites, by an admin or through this API.

How it works, end to end:

  1. The user opens the Retorio coaching app and enters your organization's name.
  2. Retorio looks up how that organization signs in (see GET /auth/auth_details) and, if SSO is configured, redirects to your identity provider in a sign-in popup.
  3. Your IdP authenticates the user and asserts their email address (see below for where).
  4. Retorio matches that email against an already-invited user. On their first sign-in the user accepts the Terms of Service and privacy policy once before reaching the app. Their name comes from your identity provider. After that they are signed in directly. An asserted email that was never invited, or whose invitation expired before the user completed sign-up, is turned away, not auto-provisioned.

Supported methods: SAML 2.0 and OIDC against any enterprise identity provider (Entra ID / Azure AD, Okta, Keycloak, Ping, and similar), plus Google Workspace and Microsoft Entra ID as built-in providers, for which you register an OAuth client (Google) or an app registration (Entra ID) and share its client ID and secret. Sign-in is SP-initiated only: users start at the Retorio login page. Identity-provider-initiated sign-in, such as an app tile in your IdP dashboard, is not supported.

Setting it up is a conversation, not a self-serve API call. There is no endpoint to configure an identity provider. Tell your Retorio contact which method you use, and Retorio provisions an identity tenant (GCIP) for your organization (several organizations of one company can share it), and shares the ACS URL / redirect URI and entity ID for your environment. Your IdP must send the user's email address as the SAML assertion's NameID, or as the OIDC email claim, or the sign-in fails. By default that address is the one Retorio matches against the invite. If the invited address is in another attribute of the assertion, Retorio can match on that attribute instead, but the NameID or email claim must still carry an email address.

Webhook delivery

Webhooks push events to your systems, so your LMS or CRM learns a result is available without polling. Configure one with the endpoints below. Retorio then posts a signed JSON event to the HTTPS URL you give it. See the Callbacks on POST /organization_webhooks for the exact payload shape and the headers Retorio sets on every delivery.

  • Not instant. A coaching.result.available event is first sent at least five and a half minutes after the result is ready, so that its session times are final, at the next delivery run after that delay.
  • Signed. Every delivery carries X-Retorio-Signature: v1,<base64 HMAC-SHA256>, computed over <timestamp>.<raw body>, where <timestamp> is the X-Retorio-Timestamp header (unix seconds). The HMAC key is the full signingSecret string exactly as returned, whsec_ prefix included, taken as UTF-8 bytes. Do not strip the prefix or base64-decode it. The signature format is Retorio's own, so verify it with your own HMAC code rather than a generic webhook verification library. The secret is returned in plaintext only by create and by an update that rotates it. Verify the signature against the raw request bytes, before any JSON re-serialization, or it will never match. Compare signatures with a constant-time comparison, and reject a timestamp more than a few minutes old: every attempt, retries included, is signed with a fresh timestamp.
  • At-least-once. Deduplicate deliveries on the stable X-Retorio-Delivery-Id header. A retry carries the identical body and id.
  • Retried with backoff. A 5xx, 408, 429, or no response is retried up to 7 times (8 attempts in total) over roughly a day. Redirects are not followed: a 3xx, like any 4xx other than 408 and 429, is a failure that is not retried. Respond with a 2xx quickly (within 10 seconds) and process asynchronously. Each retry is sent with the webhook's current URL, custom headers and signing secret.
  • Disabling and deleting. No event is created for a webhook while it is disabled. A delivery already pending when you disable or delete a webhook is cancelled when it next comes due, if the webhook is still disabled or deleted then. Re-enabling a webhook before that lets the delivery go out. A cancelled delivery is never resent.
  • Capped at 5 per organization, disabled ones included, each with up to 10 custom headers (for your own credential, for example a header named Authorization). Header values are stored encrypted and never returned once saved. Their names are returned.
  • Validated when saved. The URL must use https, be at most 2048 characters, and carry no credentials. Header names must be unique (ignoring case) and may not be Content-Type, Content-Length, Content-Encoding, User-Agent, Host, Expect, a hop-by-hop name such as Connection or Proxy-Authorization, or start with X-Retorio-. Each value is at most 4096 characters of printable ASCII or tab, and all custom headers together at most 8192 bytes, counting each as <name>: <value> plus a line break. A host that resolves to a private or otherwise non-routable address is accepted when saved and fails at delivery.

Cohorts

Coaching users in Retorio are organized in cohorts, each permanently either email (invited by address) or token (invited with a generated, anonymous access token handed to the coaching user directly). These endpoints create and manage cohorts, and invite, list, disable, and remove the people in them.

List cohorts

Lists your organization's cohorts with aggregate participant and token counts. It is the usual first call before inviting or removing anyone, to find the cohort id and type you need.

Authorizations:
bearer
query Parameters
includeBenchmarkingCohorts
string

true returns only benchmarking cohorts and any other non-empty value only the others. Absent or empty returns both.

includeRecordingSessions
string

true adds programs to each cohort and computes recordingSessions. Any other value or none omits programs and leaves recordingSessions at 0.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Create a cohort

Creates an empty cohort. type is fixed for the lifetime of the cohort: create an email cohort to invite users by address, or a token cohort to generate anonymous access tokens.

Authorizations:
bearer
Request Body schema: application/json
required
name
required
string >= 3 characters

The name of the cohort.

type
required
string
Enum: "email" "token"

Fixed at creation and never changes. An email cohort is invited by address. A token cohort is invited with a generated, anonymous access token.

isForBenchmarking
boolean

Whether this cohort is used for benchmark profiling. Programs are assigned to it like any other cohort, and its coaching users’ attempts in them feed the benchmark profiles.

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "type": "email",
  • "isForBenchmarking": true
}

Response samples

Content type
application/json
{
  • "extId": "string",
  • "name": "string",
  • "createdAt": "2019-08-24T14:15:22Z"
}

List all email participants

Every cohort membership of the email-invited users across the whole organization, not scoped to one cohort: one row per user and cohort, removed memberships included (state: REMOVED). Useful for mapping users from your HR system by email address without knowing each person's cohort ahead of time.

Authorizations:
bearer

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Remove users from the organization

The offboarding call: deletes the given users from your Retorio organization entirely, across every cohort they belong to (both token and email users). Every id must belong to a coaching user in your organization, or the call fails as a whole and nothing is deleted. Their recordings and results are deleted with them. Inviting the same address again later restores the account rather than creating a duplicate, but not those recordings and results.

Authorizations:
bearer
Request Body schema: application/json
required
userExtIds
required
Array of strings [ 1 .. 200 ] items

List of user ext ids

Responses

Request samples

Content type
application/json
{
  • "userExtIds": [
    ]
}

Response samples

Content type
application/json
Example
{
  • "message": "string",
  • "status": "string",
  • "details": null
}

Preview a resend

What an organization-wide resend would actually reach right now, broken down by cohort: only email cohorts (excluding benchmarking ones), and only the addresses currently eligible for a resend.

Authorizations:
bearer

Responses

Response samples

Content type
application/json
{
  • "cohorts": [
    ]
}

Get a cohort

Authorizations:
bearer
path Parameters
id
required
string

Responses

Response samples

Content type
application/json
{
  • "extId": "string",
  • "name": "string",
  • "createdAt": "2019-08-24T14:15:22Z",
  • "isForBenchmarking": true,
  • "type": "email",
  • "participants": 0,
  • "activeTokens": 0,
  • "availableTokens": 0,
  • "programs": 0,
  • "recordingSessions": 0,
  • "activeEmails": 0
}

Rename a cohort

Authorizations:
bearer
path Parameters
id
required
string
Request Body schema: application/json
required
name
required
string >= 3 characters

The new name of the cohort.

Responses

Request samples

Content type
application/json
{
  • "name": "string"
}

Response samples

Content type
application/json
{
  • "extId": "string",
  • "name": "string",
  • "createdAt": "2019-08-24T14:15:22Z"
}

Delete a cohort

Deletes the cohort and its program assignments. For an email cohort this does not remove the users in it from your organization (use DELETE /cohorts/participants for that). For a token cohort, its token users and their tokens are deleted with it, and a token user who had signed up can no longer sign in.

Authorizations:
bearer
path Parameters
id
required
string

Responses

Response samples

Content type
application/json
{
  • "message": "string",
  • "status": "string",
  • "details": null
}

List a cohort’s participants

Lists the participants of one cohort. For a token cohort, each row carries the generated token and its status. For an email cohort, token and status are both null (use emailParticipants below for the full email-invite status instead). Add onlyTokens and onlyAvailableTokens (presence of the query param is enough, any value) to keep only tokens with status AVAILABLE, so not redeemed and not reserved (onlyAvailableTokens has no effect without onlyTokens), and format=xlsx with both of those to download that list as a spreadsheet instead of JSON.

Authorizations:
bearer
path Parameters
id
required
string
query Parameters
onlyTokens
string

Presence flag: the filter is on whenever the key is present, whatever its value (false included).

onlyAvailableTokens
string

Presence flag: the filter is on whenever the key is present, whatever its value (false included).

format
string

xlsx, sent together with onlyTokens and onlyAvailableTokens, returns the list as a spreadsheet instead of JSON. Ignored otherwise.

Responses

Response samples

Content type
[
  • {
    }
]

Remove participants from a cohort

Removes the given users from one email cohort, keeping their account and their membership in any other cohort. To remove a user from the organization entirely, see DELETE /cohorts/participants instead.

Authorizations:
bearer
path Parameters
id
required
string
Request Body schema: application/json
required
userExtIds
required
Array of strings [ 1 .. 200 ] items

List of user ext ids

Responses

Request samples

Content type
application/json
{
  • "userExtIds": [
    ]
}

Response samples

Content type
application/json
Example
{
  • "message": "string",
  • "status": "string",
  • "details": null
}

List an email cohort’s invite status

The cohort's email participants with their full invite lifecycle (INVITED, ACTIVATED, DISABLED, REMOVED) rather than the bare participant row participants above returns. One row per user, from their most recent membership in this cohort. Meant for email cohorts: a token cohort is not refused, and lists its token users the same way.

Authorizations:
bearer
path Parameters
id
required
string

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Invite users by email

Adds each address to an email-type cohort and sends an invitation email, in one call. An address that already exists in your organization is added to this cohort rather than duplicated, and a previously deleted user is restored into this cohort. Only users who have not signed up yet are emailed, and an existing one only if they are not disabled and their last invitation is more than 24 hours old. Not idempotent: an address that is already in this cohort fails the whole call with 400, so diff against the participant list before re-sending a batch. Invitations expire after 60 days: the coaching app then refuses to start sign-up.

Authorizations:
bearer
path Parameters
id
required
string
Request Body schema: application/json
required
emails
required
Array of strings [ 1 .. 200 ] items [ items [ 1 .. 255 ] characters ^[A-Z0-9.!#$%&'*+/=?^_`{|}~-]+@[A-Z0-9.-]+\.[... ]

List of emails to invite into cohort

language
required
string (languageEnum)
Enum: "en-US" "fr-FR" "de-DE" "es-ES" "it-IT" "pt-PT" "cs-CZ" "ru-RU" "el-GR" "nl-NL" "bg-BG" "ko-KR" "tr-TR" "pl-PL"

Responses

Request samples

Content type
application/json
{
  • "emails": [
    ],
  • "language": "en-US"
}

Response samples

Content type
application/json
Example
{
  • "message": "string",
  • "status": "string",
  • "details": null
}

Resend invitation emails

Re-sends the invitation email in an email cohort, in one of two ways. Send { "userExtIds": [...] } to name specific not-yet-registered recipients yourself: this is all-or-nothing, so one ineligible id refuses the whole request before anything is sent, and a successful call returns 204 with no body. Send { "select": "next" } instead to let Retorio pick whoever is next eligible and send to them. That form returns 200 with how many were just sent and how many eligible recipients remain, so you can call it again to work through a large cohort in batches. Both forms reach only users whose last invitation is more than 24 hours old. A user with no recorded invitation is not eligible. Disabled users are never eligible. Each { "select": "next" } call sends at most 20.

Authorizations:
bearer
path Parameters
id
required
string
Request Body schema: application/json
required
Any of
userExtIds
required
Array of strings [ 1 .. 200 ] items

List of user ext ids

Responses

Request samples

Content type
application/json
{
  • "select": "next"
}

Response samples

Content type
application/json
{
  • "sent": 0,
  • "remaining": 0
}

Generate tokens

Generates new access tokens for a token-type cohort, to hand to coaching users directly instead of inviting them by email: through your own LMS, HR system, or in person. The response has no body: fetch the generated tokens with GET /cohorts/{id}/participants right after. A token is meant to be redeemed once and does not expire on its own. Redeeming it replaces the token value, so the participant list then shows a different token for that user than the one handed out. Match on userId, not on the token. Each token has its own user (userId in the participant list). Removing that user with DELETE /cohorts/participants revokes the token.

Authorizations:
bearer
path Parameters
id
required
string
Request Body schema: application/json
required
numberTokens
required
integer [ 1 .. 200 ]

How many new tokens to generate, 1 to 200 per call.

Responses

Request samples

Content type
application/json
{
  • "numberTokens": 1
}

Response samples

Content type
application/json
Example
{
  • "message": "string",
  • "status": "string",
  • "details": null
}

Enable or disable a participant

Enables or disables a user, addressed through an email cohort. The flag belongs to the user, so it applies across every cohort they are in. The coaching app does not let a disabled user who has not signed up yet start sign-up. One who already has can still sign in, but none of their programs can be started. Re-enabling a user who never registered sends them a fresh invitation email, subject to the same 24-hour throttle as POST /cohorts/{id}/participants/emails.

Authorizations:
bearer
path Parameters
id
required
string
userExtId
required
string
Request Body schema: application/json
required
isDisabled
required
boolean

Responses

Request samples

Content type
application/json
{
  • "isDisabled": true
}

Response samples

Content type
application/json
Example
{
  • "message": "string",
  • "status": "string",
  • "details": null
}

List a cohort’s assigned programs

Lists the programs assigned to this cohort, with each assignment’s window, status and per-scenario publish counts, ordered the way the admin app shows them.

Authorizations:
bearer
path Parameters
id
required
string

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Assign programs to a cohort

Assigns one or more programs to this cohort for the given window. Fails the whole call if any of the programs already holds a live assignment in this cohort.

Authorizations:
bearer
path Parameters
id
required
string
Request Body schema: application/json
required
startDate
required
string

When every assigned program becomes visible to the cohort.

endDate
string or null

When the assigned programs stop accepting new attempts. A coaching user keeps seeing an ended assignment they have attempts in. Omit or send null for no end date.

programExtIds
required
Array of strings

Programs to assign, by ext id. A program already holding a live assignment in this cohort fails the whole call. Unassign it first to re-assign with a new period.

Responses

Request samples

Content type
application/json
{
  • "startDate": "string",
  • "endDate": "string",
  • "programExtIds": [
    ]
}

Response samples

Content type
application/json
[
  • {
    }
]

Reorder a cohort’s assigned programs

Sets the display order of this cohort’s assignments. Send exactly one entry per assignment, with order values covering 0 to n - 1. An unknown or repeated ext id, a different number of entries than assignments, or order values that are not exactly 0 to n - 1 (a gap or a repeat) fails the whole call.

Authorizations:
bearer
path Parameters
id
required
string
Request Body schema: application/json
required
Array (non-empty)
extId
required
string

The cohort-program assignment ext id.

order
required
integer

Responses

Request samples

Content type
application/json
[
  • {
    }
]

Response samples

Content type
application/json
Example
{
  • "message": "string",
  • "status": "string",
  • "details": null
}

List programs not yet assigned to a cohort

Lists the organization’s programs holding no assignment in this cohort: the picker for POST /cohorts/{id}/programs. A program whose assignment here has ended does not appear: an ended assignment is edited, not repeated.

Authorizations:
bearer
path Parameters
id
required
string

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get one cohort-program assignment

Authorizations:
bearer
path Parameters
id
required
string
cohortProgramExtId
required
string

Responses

Response samples

Content type
application/json
{
  • "createdAt": "2019-08-24T14:15:22Z",
  • "extId": "string",
  • "startDate": "2019-08-24T14:15:22Z",
  • "endDate": "2019-08-24T14:15:22Z",
  • "order": 0,
  • "programId": "string",
  • "title": "string",
  • "scenarioStatusCounts": {
    },
  • "cohortProgramStatus": "upcoming"
}

Change an assignment’s window

Changes the startDate/endDate of an existing assignment.

Authorizations:
bearer
path Parameters
id
required
string
cohortProgramExtId
required
string
Request Body schema: application/json
required
startDate
required
string
endDate
required
string or null

Responses

Request samples

Content type
application/json
{
  • "startDate": "string",
  • "endDate": "string"
}

Response samples

Content type
application/json
{
  • "createdAt": "2019-08-24T14:15:22Z",
  • "extId": "string",
  • "startDate": "2019-08-24T14:15:22Z",
  • "endDate": "2019-08-24T14:15:22Z",
  • "order": 0,
  • "programId": "string",
  • "title": "string",
  • "scenarioStatusCounts": {
    },
  • "cohortProgramStatus": "upcoming"
}

Unassign a program from a cohort

Removes the assignment and compacts the remaining assignments’ order values. The program itself, and any data already recorded under it, is unaffected.

Authorizations:
bearer
path Parameters
id
required
string
cohortProgramExtId
required
string

Responses

Response samples

Content type
application/json
{
  • "message": "string",
  • "status": "string",
  • "details": null
}

Webhooks

Configure outbound event delivery to your own systems. The Webhook delivery section of the introduction above covers the delivery and signature guarantees. The request and response shapes below cover configuring and inspecting webhooks themselves.

List webhooks

Lists the webhooks configured for your organization, up to the limit of 5. No secret value is returned here: custom headers are listed by name only, and the signing secret is returned only by create and by an update that rotates it.

Authorizations:
bearer

Responses

Response samples

Content type
application/json
{
  • "organizationWebhooks": [
    ]
}

Create a webhook

Creates a webhook and its first configuration version. The response includes the signingSecret in plaintext (returned only here and by an update that rotates it), so store it immediately: it is required to verify the X-Retorio-Signature header on every delivery. An organization may have at most 5 webhooks, disabled ones included.

Authorizations:
bearer
Request Body schema: application/json
required
name
required
string [ 1 .. 255 ] characters [\u0041-\u005A\u0061-\u007A\u00AA\u00B5\u00BA...
url
required
string <= 2048 characters ^https:\/\/

Your endpoint. It must use https, be at most 2048 characters and carry no credentials (no user name or password).

subscribedEvents
required
Array of strings (subscribableWebhookEventType) non-empty
Items Value: "coaching.result.available"
Array of objects (webhookCustomHeaderEntry) <= 10 items

At most 10 headers, sent with every delivery. Together they may take at most 8192 bytes, counting each as <name>: <value>\r\n, stored values included.

isEnabled
boolean
Default: true

Responses

Callbacks

Request samples

Content type
application/json
{
  • "name": "string",
  • "url": "string",
  • "subscribedEvents": [
    ],
  • "customHeaders": [
    ],
  • "isEnabled": true
}

Response samples

Content type
application/json
{
  • "extId": "string",
  • "isEnabled": true,
  • "name": "string",
  • "url": "string",
  • "customHeaderNames": [
    ],
  • "customHeadersUnreadable": true,
  • "subscribedEvents": [
    ],
  • "lastChangedAt": "2019-08-24T14:15:22Z",
  • "lastChangedBy": "string",
  • "hasBeenEdited": true,
  • "signingSecret": "string"
}

Callback payload samples

Callback
POST: A subscribed event is delivered to your endpoint
Content type
application/json
{
  • "version": 1,
  • "eventId": "string",
  • "occurredAt": "2019-08-24T14:15:22Z",
  • "organization": {
    },
  • "eventType": "webhook.test",
  • "data": {
    }
}

Update a webhook

Updates a webhook by appending a new configuration version. The full configuration is restated on every update, not patched: customHeaders omitted keeps the stored set (credential included), [] removes every custom header, and an array that is sent is the whole set going forward. Inside a sent array, an entry with a name and no value keeps the value stored under that name, so you can keep a credential you cannot read back. An entry with no value whose name is not stored is a 400. Pass expectedLastChangedAt (the lastChangedAt you last read) to get a 409 instead of overwriting an edit made since you read it. A 409 can also answer an update that collides with a concurrent one. rotateSigningSecret: true replaces the signing secret and returns the new one once. Every receiver verifying with the old one then fails until updated.

Authorizations:
bearer
path Parameters
extId
required
string
Request Body schema: application/json
required
name
required
string [ 1 .. 255 ] characters [\u0041-\u005A\u0061-\u007A\u00AA\u00B5\u00BA...
url
required
string <= 2048 characters ^https:\/\/

Your endpoint. It must use https, be at most 2048 characters and carry no credentials (no user name or password).

subscribedEvents
required
Array of strings (subscribableWebhookEventType) non-empty
Items Value: "coaching.result.available"
Array of objects (webhookCustomHeaderEntry) <= 10 items

At most 10 headers, sent with every delivery. Together they may take at most 8192 bytes, counting each as <name>: <value>\r\n, stored values included.

rotateSigningSecret
boolean
Default: false
isEnabled
boolean
expectedLastChangedAt
string <date-time>

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "url": "string",
  • "subscribedEvents": [
    ],
  • "customHeaders": [
    ],
  • "rotateSigningSecret": false,
  • "isEnabled": true,
  • "expectedLastChangedAt": "2019-08-24T14:15:22Z"
}

Response samples

Content type
application/json
{
  • "extId": "string",
  • "isEnabled": true,
  • "name": "string",
  • "url": "string",
  • "customHeaderNames": [
    ],
  • "customHeadersUnreadable": true,
  • "subscribedEvents": [
    ],
  • "lastChangedAt": "2019-08-24T14:15:22Z",
  • "lastChangedBy": "string",
  • "hasBeenEdited": true,
  • "signingSecret": "string"
}

Delete a webhook

Soft-deletes a webhook and every configuration version it has had. No further retries are sent: each pending delivery is cancelled when it next comes due, and only a request already on its way at the moment of deletion can still arrive. Its delivery records are retained but no longer readable through this API: GET /organization_webhooks/{extId}/deliveries answers 404 once the webhook is deleted.

Authorizations:
bearer
path Parameters
extId
required
string

Responses

Response samples

Content type
application/json
{
  • "message": "string",
  • "status": "string",
  • "details": null
}

List recent deliveries

The webhook's most recent deliveries (up to 50), newest first, across every configuration version it has ever had. One row per event, summarizing its attempts (attemptCount, lastStatusCode, lastError), useful for diagnosing a receiver that is failing or has gone quiet. lastError holds at most 500 characters. On a cancelled row, and on a failed row Retorio settled without recording a send (a job that ran too many times, a stored event that no longer validates, a test whose outcome could not be recorded), it holds Retorio's reason, which replaces the last error text, while lastStatusCode keeps the code of the last recorded attempt. updatedAt is the creation time and does not track status changes: read status and deliveredAt instead.

Authorizations:
bearer
path Parameters
extId
required
string

Responses

Response samples

Content type
application/json
{
  • "deliveries": [
    ]
}

Send a test event

Sends a synchronous webhook.test event to the webhook, signed exactly like a real delivery, so you can verify your receiver end to end. Sent even when the webhook is disabled, so you can create it with isEnabled: false, test it, then enable it: a webhook created enabled receives its subscribed events right away. Recorded as a delivery, so it also shows up in the delivery log. It is never retried.

Authorizations:
bearer
path Parameters
extId
required
string

Responses

Response samples

Content type
application/json
{
  • "succeeded": true,
  • "statusCode": 0,
  • "error": "string"
}

Single Sign-On

The SSO endpoints of this API, called by the Retorio coaching app during sign-in and sign-up, not by an integration. See the Single Sign-On setup section of the introduction above for the end-to-end flow and how to set it up.

Look up sign-in method for an organization

Public, unauthenticated lookup used by a login page before the user has signed in: given an organization's name, it says whether that organization signs in by SSO or by email and password, and returns the organization and company name and the logo to render on the sign-in screen, plus, for an SSO organization, the tenant id and (for a SAML or OIDC provider) the provider id the login page starts sign-in with. The organization's privacy policy is not part of this response. This is a read of existing configuration. See the Single Sign-On setup section above for how SSO is set up.

query Parameters
organizationName
required
string [ 1 .. 255 ] characters

Responses

Response samples

Content type
application/json
{
  • "organizationName": "string",
  • "organizationExtId": "string",
  • "companyName": "string",
  • "logoUrl": null,
  • "samlProviderId": null,
  • "tenantId": null,
  • "SSOType": "google"
}

Finalize sign-up for an SSO user

Called by the coaching app after your identity provider authenticates an invited user who has not completed sign-up yet, to record their name and consent and mark them registered. When Retorio is configured to read the name from your IdP's attributes and the token carries one, that name is used instead of displayedName. legalConsent and privacyPolicyConsent must be true. A user whose invitation has expired is refused and must be invited again. The user itself already exists from the cohort invite. There is nothing for an integrator to call here directly: a user reaches this only by signing in through the coaching app once they have been invited into a cohort with the email their IdP asserts.

Authorizations:
bearer
Request Body schema: application/json
required
displayedName
string or null [ 1 .. 255 ] characters
Default: null
legalConsent
required
boolean
privacyPolicyConsent
required
boolean
contactConsent
required
boolean

Responses

Request samples

Content type
application/json
{
  • "displayedName": null,
  • "legalConsent": true,
  • "privacyPolicyConsent": true,
  • "contactConsent": true
}

Response samples

Content type
application/json
Example
{
  • "message": "string",
  • "status": "string",
  • "details": null
}