Ramp User Management API Guide

Auth method: OAuth 2.0 (client credentials flow for server-to-server; authorization code flow for user-delegated access)

Setup steps

1. Log in to Ramp and navigate to Settings > Developer > API.
2. Create an OAuth application to obtain a client_id and client_secret.
3. Request an access token via POST to https://api.ramp.com/developer/v1/token using client_credentials grant type.
4. Include the returned Bearer token in the Authorization header for all API requests.
5. Select required scopes during app creation; tokens are scoped to the permissions granted.

Required scopes

List users

• Method: GET
• URL: https://api.ramp.com/developer/v1/users
• Watch out for: Pagination uses a cursor token in page.next; pass as ?next= on subsequent requests.

Request example

GET /developer/v1/users?page_size=100
Authorization: Bearer {token}

Response example

{
  "data": [{"id":"uuid","email":"user@co.com","first_name":"Jane","status":"ACTIVE"}],
  "page": {"next": "cursor_token"}
}

Get user by ID

• Method: GET
• URL: https://api.ramp.com/developer/v1/users/{id}
• Watch out for: Returns 404 if user is deactivated and not found; deactivated users may still be retrievable depending on API version.

Request example

GET /developer/v1/users/user-uuid
Authorization: Bearer {token}

Response example

{
  "id": "user-uuid",
  "email": "user@co.com",
  "role": "CARDHOLDER",
  "status": "ACTIVE"
}

Create user (invite)

• Method: POST
• URL: https://api.ramp.com/developer/v1/users/deferred
• Watch out for: Ramp uses a deferred user creation model; the user receives an invite email and must accept before becoming fully ACTIVE.

Request example

POST /developer/v1/users/deferred
{
  "first_name": "Jane",
  "last_name": "Doe",
  "email": "jane@co.com",
  "role": "CARDHOLDER",
  "department_id": "dept-uuid"
}

Response example

{
  "id": "new-user-uuid",
  "email": "jane@co.com",
  "status": "INVITE_PENDING"
}

Update user

• Method: PATCH
• URL: https://api.ramp.com/developer/v1/users/{id}
• Watch out for: Cannot change user status via PATCH; use the dedicated deactivate endpoint.

Request example

PATCH /developer/v1/users/user-uuid
{
  "department_id": "new-dept-uuid",
  "manager_id": "mgr-uuid"
}

Response example

{
  "id": "user-uuid",
  "department_id": "new-dept-uuid",
  "manager_id": "mgr-uuid"
}

Deactivate user

• Method: POST
• URL: https://api.ramp.com/developer/v1/users/{id}/deactivate
• Watch out for: Deactivation cancels associated cards. Ensure card offboarding is handled before or after this call.

Request example

POST /developer/v1/users/user-uuid/deactivate
Authorization: Bearer {token}

Response example

{
  "id": "user-uuid",
  "status": "INACTIVE"
}

List departments

• Method: GET
• URL: https://api.ramp.com/developer/v1/departments
• Watch out for: Department IDs are required when assigning users to departments; fetch this list before user creation.

Request example

GET /developer/v1/departments
Authorization: Bearer {token}

Response example

{
  "data": [{"id":"dept-uuid","name":"Engineering"}]
}

List locations

• Method: GET
• URL: https://api.ramp.com/developer/v1/locations
• Watch out for: Location IDs must be pre-fetched; invalid IDs on user create/update return a 400 error.

Request example

GET /developer/v1/locations
Authorization: Bearer {token}

Response example

{
  "data": [{"id":"loc-uuid","name":"New York HQ"}]
}

Get current user (token introspection)

• Method: GET
• URL: https://api.ramp.com/developer/v1/users/me
• Watch out for: Only valid for authorization_code flow tokens; client_credentials tokens are not user-bound.

Request example

GET /developer/v1/users/me
Authorization: Bearer {token}

Response example

{
  "id": "uuid",
  "email": "admin@co.com",
  "role": "ADMIN"
}

• Rate limits: Ramp enforces rate limits on API requests. Official docs note a limit of 100 requests per minute per client.
• Rate-limit headers: Unknown
• Retry-After header: Unknown
• Rate-limit notes: Official docs specify 100 req/min. Behavior of rate-limit response headers and Retry-After is not explicitly documented; treat as unknown.
• Pagination method: cursor
• Default page size: 100
• Max page size: 100
• Pagination pointer: next

• Webhooks available: Yes
• Webhook notes: Ramp supports webhooks for real-time event notifications. Webhooks are configured in the Developer settings and deliver POST payloads to a registered HTTPS endpoint.
• Alternative event strategy: Poll GET /users with updated_after filter parameter for environments where webhooks are not feasible.
• Webhook events: user.created, user.updated, user.deactivated, card.activated, card.suspended, transaction.created, reimbursement.created

• SCIM available: Yes

• SCIM version: 2.0

• Plan required: Free (included on all plans)

• Endpoint: https://api.ramp.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, PATCH /Groups/{id}, DELETE /Groups/{id}

Limitations:

• SCIM token is generated from Ramp Settings > Team > SCIM; it is a long-lived bearer token, not an OAuth token.
• Full SCIM provisioning tested and documented for Okta, Azure AD (Entra ID), Rippling, and OneLogin.
• Google Workspace SCIM is not officially supported; Google SSO is available but not SCIM provisioning.
• Group push maps to Ramp departments; department must exist in Ramp or be created via SCIM group push.
• SCIM DELETE deactivates the user; it does not permanently delete the Ramp account or historical spend data.

Onboarding via REST requires pre-fetching department and location UUIDs before POST /users/deferred. The endpoint is invite-based: the user lands in INVITE_PENDING status and cannot be issued a card until they accept the invite and transition to ACTIVE.

Poll GET /users/{id} to detect the transition; there is no synchronous confirmation.

Offboarding via POST /users/{id}/deactivate is a single call that simultaneously sets status to INACTIVE and cancels all associated virtual and physical cards. This is not reversible via the API - reactivation requires manual action in the Ramp admin UI.

Build card offboarding coordination into your workflow before or immediately after this call.

For Okta SCIM sync, configure the base URL as https://api.ramp.com/scim/v2 with the Ramp-generated SCIM bearer token.

Okta group push maps to Ramp Departments, not Roles - role assignment defaults to CARDHOLDER and must be corrected manually or via a follow-up PATCH /users/{id} call through the REST API.

Onboard a new employee via REST API

1. Obtain OAuth 2.0 client_credentials token with users:write, departments:read, locations:read scopes.
2. GET /departments and GET /locations to retrieve valid UUIDs for the employee's department and location.
3. POST /users/deferred with first_name, last_name, email, role, department_id, location_id, manager_id.
4. User receives invite email; poll GET /users/{id} until status transitions from INVITE_PENDING to ACTIVE.
5. Optionally issue a card via POST /cards once user is ACTIVE.

Watch out for: If the invite email is not accepted, the user remains INVITE_PENDING and cannot be issued a card. Resend invite from Ramp UI or via API if supported.

Offboard an employee and suspend cards

1. Obtain token with users:deactivate scope.
2. POST /users/{id}/deactivate - this simultaneously deactivates the user and suspends all associated cards.
3. Verify status is INACTIVE via GET /users/{id}.
4. Reassign any open reimbursements or pending transactions to another user via the Ramp UI or API.

Watch out for: Deactivation is not reversible via the API; reactivation must be done manually in the Ramp admin UI.

Sync users from Okta via SCIM

1. In Ramp Settings > Team, enable SCIM and copy the generated SCIM bearer token.
2. In Okta, add the Ramp application from the Okta Integration Network (OIN).
3. Configure SCIM base URL as https://api.ramp.com/scim/v2 and paste the bearer token.
4. Enable provisioning features: Create Users, Update User Attributes, Deactivate Users, Push Groups.
5. Assign users and groups in Okta; Okta pushes SCIM POST /Users and PATCH /Groups to Ramp.
6. Verify users appear in Ramp with correct department (mapped from Okta group) and role.

Watch out for: Okta group push creates Ramp Departments, not Roles. Role assignment defaults to CARDHOLDER; admin roles must be set manually in Ramp after provisioning.

The deferred creation model is the most common integration trap: callers assume a 201 from POST /users/deferred means the user is ready, but INVITE_PENDING blocks card issuance and any downstream workflow that depends on an ACTIVE user. Build explicit status polling with a timeout and alerting for stuck invites.

Rate limits are set at 100 requests per minute across all plans. Rate-limit response headers and Retry-After behavior are not documented - treat them as unknown and implement exponential backoff unconditionally for bulk operations. Cursor-based pagination uses page.next; offset pagination is not supported, so any integration that assumes offset behavior will silently drop records.

SCIM DELETE deactivates the user and cancels cards but does not remove historical spend data - this is correct behavior for audit retention but should be communicated to finance stakeholders who may expect a clean removal.

Finally, GET /users/me is only valid for authorization_code tokens; calling it with a client_credentials token will not return a user context.