WorkRamp User Management API Guide

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

Setup steps

1. Log in to WorkRamp as an Admin.
2. Navigate to Settings → Integrations → API.
3. Generate an API key; copy and store it securely.
4. Include the key in all requests as: Authorization: Bearer

List Users

• Method: GET
• URL: https://app.workramp.com/api/v1/users
• Watch out for: Pagination is required for large user sets; omitting page/per_page may return only the first page.

Request example

GET /api/v1/users?page=1&per_page=25
Authorization: Bearer <api_key>

Response example

{
  "users": [
    {"id":"uuid","email":"user@example.com","first_name":"Jane","last_name":"Doe","active":true}
  ],
  "total": 120,
  "page": 1
}

Get User

• Method: GET
• URL: https://app.workramp.com/api/v1/users/{user_id}
• Watch out for: Use the WorkRamp UUID, not email, in the path parameter.

Request example

GET /api/v1/users/abc-uuid-123
Authorization: Bearer <api_key>

Response example

{
  "user": {
    "id": "abc-uuid-123",
    "email": "user@example.com",
    "first_name": "Jane",
    "last_name": "Doe",
    "role": "learner",
    "active": true
  }
}

Create User

• Method: POST
• URL: https://app.workramp.com/api/v1/users
• Watch out for: Duplicate email addresses return an error; check for existing users before creating.

Request example

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

{"email":"new@example.com","first_name":"John","last_name":"Smith","role":"learner"}

Response example

{
  "user": {
    "id": "new-uuid-456",
    "email": "new@example.com",
    "first_name": "John",
    "last_name": "Smith",
    "active": true
  }
}

Update User

• Method: PUT
• URL: https://app.workramp.com/api/v1/users/{user_id}
• Watch out for: Omitted fields may be cleared depending on implementation; send all desired field values.

Request example

PUT /api/v1/users/abc-uuid-123
Authorization: Bearer <api_key>
Content-Type: application/json

{"title":"Senior Engineer","department":"Engineering"}

Response example

{
  "user": {
    "id": "abc-uuid-123",
    "title": "Senior Engineer",
    "department": "Engineering"
  }
}

Deactivate User

• Method: PUT
• URL: https://app.workramp.com/api/v1/users/{user_id}
• Watch out for: Deactivation preserves completion records; hard-delete is not exposed via the public API.

Request example

PUT /api/v1/users/abc-uuid-123
Authorization: Bearer <api_key>
Content-Type: application/json

{"active": false}

Response example

{
  "user": {
    "id": "abc-uuid-123",
    "active": false
  }
}

List Groups

• Method: GET
• URL: https://app.workramp.com/api/v1/groups
• Watch out for: Group IDs are required when assigning users to groups via the user create/update payload.

Request example

GET /api/v1/groups
Authorization: Bearer <api_key>

Response example

{
  "groups": [
    {"id": "grp-uuid-1", "name": "Sales Team"}
  ]
}

Add User to Group

• Method: POST
• URL: https://app.workramp.com/api/v1/groups/{group_id}/users
• Watch out for: Group membership drives content assignment; verify group ID before posting.

Request example

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

{"user_id": "abc-uuid-123"}

Response example

{
  "success": true
}

Get User Training Progress

• Method: GET
• URL: https://app.workramp.com/api/v1/users/{user_id}/progress
• Watch out for: Only returns progress for content the user has been assigned; unassigned content is excluded.

Request example

GET /api/v1/users/abc-uuid-123/progress
Authorization: Bearer <api_key>

Response example

{
  "progress": [
    {"content_id": "cid-1", "status": "completed", "completed_at": "2024-06-01T10:00:00Z"}
  ]
}

• Rate limits: WorkRamp's public documentation does not explicitly publish rate-limit thresholds or tier-based limits as of the last known documentation review.

• Rate-limit headers: Unknown

• Retry-After header: Unknown

• Rate-limit notes: No official rate-limit figures, headers, or Retry-After behavior documented publicly. Contact WorkRamp support for current limits.

• Pagination method: offset

• Default page size: 25

• Max page size: 100

• Pagination pointer: page / per_page

• Webhooks available: No

• Webhook notes: WorkRamp's public developer documentation does not describe a native outbound webhook system for user-management events as of the last known documentation review.

• Alternative event strategy: Use polling against the REST API (e.g., GET /users with updated_at filtering) or leverage SCIM provisioning events via your IdP for lifecycle automation.

• SCIM available: Yes

• SCIM version: 2.0

• Plan required: Enterprise

• Endpoint: https://app.workramp.com/scim/v2

• Supported operations: GET /Users, GET /Users/{id}, POST /Users, PUT /Users/{id}, PATCH /Users/{id}, DELETE /Users/{id}, GET /Groups, POST /Groups, PUT /Groups/{id}, PATCH /Groups/{id}, DELETE /Groups/{id}

Limitations:

• Requires Enterprise plan.
• SCIM token is generated within WorkRamp admin settings and must be supplied as a Bearer token to the IdP connector.
• Specific IdP connector configuration (Okta, Azure AD, etc.) must be completed on the IdP side; WorkRamp does not publish per-IdP setup guides in its public developer docs.
• SCIM group sync maps to WorkRamp Groups, which control content assignment; mismatched group names may result in unintended content access changes.
• Hard-delete via SCIM DELETE deactivates the user; historical completion data is retained.

Three integration patterns cover the majority of lifecycle needs.

First, employee onboarding: POST /api/v1/users to create the record, capture the returned UUID, then POST /api/v1/groups/{group_id}/users to trigger content assignment - group membership is what drives training delivery, not role alone.

Second, HRIS profile sync: query GET /api/v1/users with an email filter to resolve the WorkRamp UUID, then PUT /api/v1/users/{user_id} with the full updated payload;

omitting fields on a PUT may clear them, so always send the complete desired state.

Third, termination via SCIM: configure your IdP with the WorkRamp SCIM endpoint and Bearer token;

a PATCH or DELETE from the IdP deactivates the user while preserving completion history.

For non-Enterprise tiers without SCIM, deprovisioning requires a REST PUT with active: false - note that this does not emit a SCIM DELETE event back to connected IdPs.

Onboard a new employee and assign to a group

1. POST /api/v1/users with email, first_name, last_name, role, start_date, and any custom_fields.
2. Capture the returned user id.
3. GET /api/v1/groups to find the target group id (e.g., 'New Hire Onboarding').
4. POST /api/v1/groups/{group_id}/users with the new user's id to trigger content assignment.

Watch out for: Group membership drives automatic content assignment; if the group does not exist yet, create it in the WorkRamp admin UI first-group creation via API may not be supported.

Sync user profile updates from HRIS

1. Receive a profile-change event from your HRIS (e.g., title or department change).
2. Look up the WorkRamp user id by querying GET /api/v1/users?email=user@example.com.
3. PUT /api/v1/users/{user_id} with the updated fields (title, department, manager_email, etc.).
4. Verify the response reflects the updated values.

Watch out for: PUT may overwrite omitted fields; include all current field values in the payload to avoid unintentional data loss.

Deprovision a terminated employee via SCIM

1. Configure your IdP (e.g., Okta or Azure AD) with the WorkRamp SCIM 2.0 endpoint and Bearer token from WorkRamp admin settings.
2. When the employee is deactivated in the IdP, the IdP sends a SCIM PATCH or DELETE to WorkRamp.
3. WorkRamp deactivates the user account; training completion history is preserved.
4. Optionally verify deactivation via GET /api/v1/users/{user_id} and confirm active: false.

Watch out for: SCIM is only available on the Enterprise plan. If on a lower tier, deprovisioning must be done manually via the REST API (PUT active: false) or the admin UI.

The API has several non-obvious failure modes worth flagging before implementation. The REST API base URL and endpoint paths are sourced from the developer portal and should be re-verified against current docs before going to production - WorkRamp does not guarantee public changelog coverage.

Custom fields must be pre-configured in the admin UI before they can be written via API; attempting to write an undeclared custom field will fail silently or error without a clear remediation path.

Group IDs - not names - are required in provisioning payloads, so any integration that resolves groups by display name needs a lookup step against GET /api/v1/groups. Finally, deactivating a user via REST (active: false) and deactivating via SCIM DELETE are not equivalent operations from an IdP sync perspective;

mixing both methods in the same environment risks state drift in your identity graph.