Trainual User Management API Guide

Auth method: API Key (Bearer token in Authorization header)

Setup steps

1. Log in to Trainual as an account owner or admin.
2. Navigate to Settings > Integrations > API.
3. Generate an API key from the API settings page.
4. Include the key in all requests as: Authorization: Bearer

List Users

• Method: GET
• URL: https://app.trainual.com/api/v1/users
• Watch out for: Exact field names and response envelope structure are not fully confirmed from public docs; treat as approximate.

Request example

GET /api/v1/users?page=1
Authorization: Bearer <api_key>
Accept: application/json

Response example

{
  "users": [
    {"id": 101, "email": "jane@example.com", "first_name": "Jane", "last_name": "Doe"}
  ],
  "meta": {"page": 1, "total": 50}
}

Get User

• Method: GET
• URL: https://app.trainual.com/api/v1/users/{id}
• Watch out for: Endpoint path and response structure not fully confirmed from public documentation.

Request example

GET /api/v1/users/101
Authorization: Bearer <api_key>

Response example

{
  "user": {
    "id": 101,
    "email": "jane@example.com",
    "first_name": "Jane",
    "last_name": "Doe",
    "status": "active"
  }
}

Create User (Invite)

• Method: POST
• URL: https://app.trainual.com/api/v1/users
• Watch out for: Creating a user likely triggers an invitation email. Seat limits apply based on plan.

Request example

POST /api/v1/users
Authorization: Bearer <api_key>
Content-Type: application/json

{"email":"new@example.com","first_name":"New","last_name":"User"}

Response example

{
  "user": {
    "id": 202,
    "email": "new@example.com",
    "status": "invited"
  }
}

Update User

• Method: PATCH
• URL: https://app.trainual.com/api/v1/users/{id}
• Watch out for: PUT vs PATCH behavior not confirmed; use PATCH for partial updates if supported.

Request example

PATCH /api/v1/users/101
Authorization: Bearer <api_key>
Content-Type: application/json

{"title":"Manager","department":"Ops"}

Response example

{
  "user": {
    "id": 101,
    "title": "Manager",
    "department": "Ops"
  }
}

Deactivate/Delete User

• Method: DELETE
• URL: https://app.trainual.com/api/v1/users/{id}
• Watch out for: Whether DELETE hard-deletes or deactivates the user is not confirmed from public docs.

Request example

DELETE /api/v1/users/101
Authorization: Bearer <api_key>

Response example

{
  "message": "User deactivated successfully."
}

• Rate limits: Rate limit details are not publicly documented by Trainual.

• Rate-limit headers: No

• Retry-After header: No

• Rate-limit notes: No official rate limit documentation found. Contact Trainual support for current limits.

• Pagination method: offset

• Default page size: Not documented

• Max page size: Not documented

• Pagination pointer: page

• Webhooks available: No

• Webhook notes: No webhook support is documented in Trainual's official developer or help center documentation as of the research date.

• Alternative event strategy: Poll the List Users endpoint periodically to detect changes.

• SCIM available: Yes

• SCIM version: 2.0

• Plan required: Enterprise (custom pricing; contact Trainual sales)

• Endpoint: Not documented

• Supported operations: Create user, Deactivate user, Update user attributes

Limitations:

• SCIM endpoint URL is provisioned per-account and not publicly documented; obtained from Trainual admin settings after enabling SCIM.
• Supported only with Okta and Microsoft Entra ID (Azure AD) as IdPs.
• SSO must be configured on the account before SCIM provisioning is available.
• Group/team sync support not confirmed from public documentation.
• Requires Enterprise plan; not available on Small, Medium, or Growth tiers.

Three primary automation scenarios are supported with caveats.

For provisioning, POST /api/v1/users with email, first_name, last_name, title, and department;

the call triggers an invitation email and immediately consumes a seat - verify headroom before bulk runs.

For deprovisioning, resolve the user's internal id via GET /api/v1/users filtered by email, then call DELETE /api/v1/users/{id};

whether DELETE performs a soft deactivation or a hard delete is not confirmed in public docs, so audit the behavior in a test account before automating offboarding.

For attribute updates, use PATCH /api/v1/users/{id};

PUT vs.

PATCH semantics are unconfirmed.

Rate limits are entirely undocumented - aggressive polling may result in throttling without clear error guidance or Retry-After headers.

Provision a new employee on hire

1. POST /api/v1/users with email, first_name, last_name, title, and department.
2. Trainual sends an invitation email to the new user.
3. Optionally assign the user to groups or subjects via additional API calls if supported.

Watch out for: Verify available seat count before bulk provisioning; exceeding plan seat limits will cause failures.

Deprovision a departing employee

1. Retrieve the user's Trainual ID via GET /api/v1/users filtered by email.
2. Call DELETE /api/v1/users/{id} to deactivate the account.
3. Confirm deactivation status via GET /api/v1/users/{id}.

Watch out for: Deactivation vs. hard delete behavior is not confirmed; audit before automating offboarding.

Automated provisioning via SCIM with Okta

1. Upgrade to Trainual Enterprise plan.
2. Enable SCIM in Trainual Settings > Integrations > SCIM; copy the tenant URL and bearer token.
3. In Okta, add the Trainual SCIM app and configure the base URL and API token.
4. Map Okta profile attributes to Trainual SCIM attributes (userName, name.givenName, name.familyName).
5. Assign users or groups in Okta to trigger provisioning to Trainual.

Watch out for: SCIM endpoint URL is account-specific; do not use a generic URL. SSO must be active on the account first.

Integrating Trainual into an identity graph via the native REST API carries meaningful risk: no versioning deprecation policy is published beyond /v1, API keys are account-scoped with no per-user OAuth flow, and the absence of webhooks means any event-driven architecture must fall back to polling with undefined rate-limit boundaries.

For teams already running an identity graph that needs authoritative, low-latency user state from Trainual, SCIM 2.0 on the Enterprise tier is the more reliable path

but it is locked to Okta and Microsoft Entra ID as IdPs, the endpoint URL is account-specific (not a public static URL), and SSO must be active on the account before SCIM can be enabled.

Teams on sub-Enterprise plans have no SCIM path and must accept the REST API's documentation gaps as a structural constraint of the integration.