Skip to content

Ramp: User schemas

11 Ramp schemas with complete fields and constraints.

← User operations · All schemas

Create a user invite — request body — body

FieldTypePresenceDescription and constraints
$objectRoot
department_idstringOptionalUnique identifier of the employee's department
Format: uuid
direct_manager_idstringOptionalUnique identifier of the employee's direct manager
Format: uuid
emailstringRequired within parentThe employee's email address
Format: email
first_namestringRequired within parentFirst name of the employee
Maximum length: 255
idempotency_keystringRequired within parentan idempotency key is a unique value generated by the client which the server uses to recognize subsequent retries of the same request. To avoid collisions, we encourage clients to use random generated UUIDs.
is_draftbooleanOptionalWhen set to true, the user will be created as a draft. Draft users are not sent an invite email and must be explicitly activated later, which can be accomplished in-app or via the `POST /users/<string:user_id>/invite` resource.
is_managerbooleanOptionalWhether the employee is a manager
last_namestringRequired within parentLast name of the employee
Maximum length: 255
location_idstringOptionalUnique identifier of the employee's location
Format: uuid
rolestringRequired within parentThe employee's role; It could be one of the following values: Admin, Cardholder, Bookkeeper; Note that Owner is not a invitable role.
One of: AUDITOR, BUSINESS_ADMIN, BUSINESS_BOOKKEEPER, BUSINESS_OWNER, BUSINESS_USER, GUEST_USER, IT_ADMIN
scheduled_deactivation_dateJSONOptional
scheduled_deactivation_date (anyOf 1)stringAlternativeThe date when the user is scheduled to be deactivated. For guest users, this will automatically be set to 6 months from the invite creation date unless explicitly set to null. Cannot be set for admins or owners.
Format: date
scheduled_deactivation_date (anyOf 2)nullAlternative

Create a user invite — response body

FieldTypePresenceDescription and constraints
$objectRoot
idstringRequired within parentID of the deferred task.
Format: uuid

Deactivate a user — response body

FieldTypePresenceDescription and constraints
$objectRootAdditional keys: not allowed

Fetch a user — response body

FieldTypePresenceDescription and constraints
$objectRoot
business_idJSONRequired within parent
business_id (anyOf 1)stringAlternativeUnique identifier of the company that the employee's working for.
Format: uuid
business_id (anyOf 2)nullAlternative
custom_fieldsarrayRequired within parentA list of custom fields of the user.
Read only: true
custom_fields[]ModelEach itemExpand Fetch a user — response body — custom fields item
department_idJSONRequired within parent
department_id (anyOf 1)stringAlternativeUnique identifier of the employee's department
Format: uuid
department_id (anyOf 2)nullAlternative
emailstringOptionalThe employee's email address
employee_idJSONRequired within parent
employee_id (anyOf 1)stringAlternativeAn alternative identifier for an employee, coming from external systems, which can be used in place of an email.
employee_id (anyOf 2)nullAlternative
entity_idJSONRequired within parent
entity_id (anyOf 1)stringAlternativeUnique identifier of business entity user is associated with.
Format: uuid
entity_id (anyOf 2)nullAlternative
first_namestringOptionalFirst name of the employee
idstringOptionalUnique employee identifier
Format: uuid
is_managerbooleanRequired within parentWhether the employee is a manager
Read only: true
last_namestringOptionalLast name of the employee
location_idJSONRequired within parent
location_id (anyOf 1)stringAlternativeUnique identifier of the employee's location
Format: uuid
location_id (anyOf 2)nullAlternative
manager_idJSONRequired within parent
manager_id (anyOf 1)stringAlternativeUnique identifier of the employee's manager
Format: uuid
manager_id (anyOf 2)nullAlternative
phoneJSONRequired within parent
phone (anyOf 1)stringAlternativeThe employee's phone number
Read only: true
phone (anyOf 2)nullAlternative
rolestringOptionalThe employee's role
Known values: AUDITOR, BUSINESS_ADMIN, BUSINESS_BOOKKEEPER, BUSINESS_OWNER, BUSINESS_USER, GUEST_USER, IT_ADMIN, UNBUNDLED_ADMIN, UNBUNDLED_BOOKKEEPER, UNBUNDLED_OWNER, UNBUNDLED_USER
scheduled_deactivation_dateJSONRequired within parent
scheduled_deactivation_date (anyOf 1)stringAlternativeThe date when the user is scheduled to be deactivated. Presented in ISO8601 format.
Format: date-time
scheduled_deactivation_date (anyOf 2)nullAlternative
scheduled_invitation_dateJSONRequired within parent
scheduled_invitation_date (anyOf 1)stringAlternativeThe date when the user (currently in USER_DRAFT status) is scheduled to be invited to Ramp. Presented in ISO8601 format. Null if no invitation is scheduled.
Format: date-time
scheduled_invitation_date (anyOf 2)nullAlternative
statusstringRequired within parentKnown values: INVITE_EXPIRED, INVITE_PENDING, USER_ACTIVE, USER_DRAFT, USER_INACTIVE, USER_ONBOARDING, USER_SUSPENDED
Read only: true

Referenced models: Fetch a user — response body — custom fields item

Fetch a user — response body — custom fields item

FieldTypePresenceDescription and constraints
$objectRoot
namestringRequired within parentName of the custom field
valuestringRequired within parentValue of the custom field

Fetch deferred task status — response body

FieldTypePresenceDescription and constraints
$objectRoot
contextModelOptionalExpand Fetch deferred task status — response body — context
Further context for the deferred task.
dataModelOptionalExpand Fetch deferred task status — response body — data
Detailed data of the deferred task.
idstringOptionalUnique identifier of the deferred task.
Format: uuid
statusstringOptionalStatus of the deferred task. It could be one of the following values: STARTED, IN_PROGRESS, ERROR, SUCCESS

Referenced models: Fetch deferred task status — response body — context, Fetch deferred task status — response body — data

Fetch deferred task status — response body — context

FieldTypePresenceDescription and constraints
$objectRoot
acting_user_idstringOptionalUnique identifier of the acting user that initiated the deferred task.
Format: uuid

Fetch deferred task status — response body — data

FieldTypePresenceDescription and constraints
$objectRoot
errorstringOptionalAn error message if the deferred task fails
user_idstringOptionalThe subject employee's ID of the deferred task.
Format: uuid

List users — response body

FieldTypePresenceDescription and constraints
$objectRoot
dataarrayRequired within parentResources returned in this page.
data[]ModelEach itemExpand Fetch a user — response body
pageModelRequired within parentExpand List bills — response body — page
Pagination details for this response.

Referenced models: List bills — response body — page, Fetch a user — response body

Manage a user's invite lifecycle — request body — body

FieldTypePresenceDescription and constraints
$objectRoot
actionstringRequired within parentThe invite action to perform. SCHEDULE creates or updates a scheduled invitation (requires `invitation_time`). DESCHEDULE cancels any pending scheduled invitation. SEND_NOW immediately sends the user's invite.
One of: DESCHEDULE, SCHEDULE, SEND_NOW
invitation_timestringOptionalThe datetime at which the user should be invited. Required when `action` is SCHEDULE; ignored otherwise. Must be an ISO 8601 datetime with a timezone offset.
Format: date-time

Update a user — request body — body

FieldTypePresenceDescription and constraints
$objectRoot
auto_promotebooleanOptionalWhether to automatically promote the users manager to manager.
department_idstringOptionalUnique identifier of the employee's department
Format: uuid
direct_manager_idJSONOptional
direct_manager_id (anyOf 1)stringAlternativeUnique identifier of the employee's direct manager
Format: uuid
direct_manager_id (anyOf 2)nullAlternative
first_namestringOptionalMinimum length: 1
is_managerbooleanOptionalWhether the employee is a manager
last_namestringOptionalMinimum length: 1
location_idstringOptionalUnique identifier of the employee's location
Format: uuid
rolestringOptionalThe employee's role; It could be one of the following values: Admin, Cardholder, Bookkeeper; Note that Owner is not a permissible value.
One of: AUDITOR, BUSINESS_ADMIN, BUSINESS_BOOKKEEPER, BUSINESS_OWNER, BUSINESS_USER, GUEST_USER, IT_ADMIN
scheduled_deactivation_dateJSONOptional
scheduled_deactivation_date (anyOf 1)stringAlternativeThe date when the user is scheduled to be deactivated. Set to null to clear. Cannot be set for admins or owners.
Format: date
scheduled_deactivation_date (anyOf 2)nullAlternative

Report an issue with this page

Necessary

Required for sign-in, security, authorization, and remembering your choices.

Always active

Analytics

Helps us understand which product and documentation features are useful.

Performance diagnostics

Uses performance tracing and privacy-masked session replay to diagnose problems.

You can change these choices at any time from Cookie settings.