Ocrolus User management API
The User management API from Ocrolus — 2 operation(s) for user management.
OpenAPI Specification
openapi: 3.0.0
info:
title: Account Level Webhooks Book Commands User management API
version: 1.0.0
servers:
- url: https://api.ocrolus.com
security:
- oauth: []
tags:
- name: User management
paths:
/v1/invitations:
post:
summary: Create invitation
operationId: create-invitation
tags:
- User management
description: "This API invites a new user to your organization by email. If the email has been invited before, the existing invitation is refreshed with a new expiration date.\n\n> \U0001F44D Tip: \n > The invitation is valid for 7 days. If the user does not accept the invitation within that time frame, they will need to be re-invited.\n"
x-readme:
samples-languages:
- curl
- python
explorer-enabled: false
requestBody:
description: Invitation payload. Provide the email address of the user to invite.
required: true
content:
application/json:
schema:
type: object
required:
- email
- first_name
- last_name
properties:
email:
type: string
format: email
description: Email address of the invitee.
example: jane.doe@example.com
first_name:
type: string
minLength: 1
description: Invitee's first name.
example: Jane
last_name:
type: string
minLength: 1
description: Invitee's last name.
example: Doe
is_manager:
type: boolean
title: Is Manager
description: Whether to invite as a manager. Managers have additional permissions in the system, such as the ability to view and manage users and invitations. Defaults to `false`.
example: false
responses:
'201':
description: Invitation created (or refreshed) successfully
content:
application/json:
schema:
$ref: '#/components/schemas/SuccessCreateInvitationsSchema'
examples:
Success:
$ref: '#/components/examples/SuccessCreateInvitationsResponse'
'400':
description: Bad request
content:
application/json:
schema:
$ref: '#/components/schemas/NewClientErrorSchema'
examples:
Bad request:
$ref: '#/components/examples/BadRequestError'
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/NewClientErrorSchema'
examples:
Invalid Authentication:
$ref: '#/components/examples/InvalidAuthError'
'403':
description: Forbidden
content:
application/json:
schema:
$ref: '#/components/schemas/NewClientErrorSchema'
examples:
Forbidden:
$ref: '#/components/examples/ForbiddenError'
'412':
description: Precondition failed
content:
application/json:
schema:
$ref: '#/components/schemas/NewClientErrorSchema'
examples:
Precondition failed:
$ref: '#/components/examples/PreconditionFailedError'
'500':
description: Internal server error
content:
application/json:
schema:
$ref: '#/components/schemas/NewClientErrorSchema'
examples:
Internal Server Error:
$ref: '#/components/examples/InternalServerError'
get:
summary: List invitations
operationId: list-invitations
tags:
- User management
description: This API returns a paginated list of pending invitations for your organization. Use this endpoint to review outstanding invitations before sending reminders or re-inviting users whose invitations have expired.
parameters:
- name: offset
in: query
description: Number of records to skip from the beginning of the result set. Use this with `limit` for pagination.
example: 0
required: false
schema:
type: integer
format: int32
minimum: 0
default: 0
example: 0
- name: limit
in: query
description: Maximum number of records to return per page, starting from the specified `offset` value.
example: 50
required: false
schema:
type: integer
format: int32
minimum: 1
maximum: 50
default: 50
example: 50
x-readme:
samples-languages:
- curl
- python
explorer-enabled: false
responses:
'200':
description: Invitations retrieved successfully
content:
application/json:
schema:
$ref: '#/components/schemas/SuccessListInvitationsSchema'
examples:
Success:
$ref: '#/components/examples/SuccessListInvitationsResponse'
'400':
description: Bad request
content:
application/json:
schema:
$ref: '#/components/schemas/NewClientErrorSchema'
examples:
Bad request:
$ref: '#/components/examples/BadRequestError'
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/NewClientErrorSchema'
examples:
Invalid Authentication:
$ref: '#/components/examples/InvalidAuthError'
'403':
description: Forbidden
content:
application/json:
schema:
$ref: '#/components/schemas/NewClientErrorSchema'
examples:
Forbidden:
$ref: '#/components/examples/ForbiddenError'
'412':
description: Precondition failed
content:
application/json:
schema:
$ref: '#/components/schemas/NewClientErrorSchema'
examples:
Precondition failed:
$ref: '#/components/examples/PreconditionFailedError'
'500':
description: Internal server error
content:
application/json:
schema:
$ref: '#/components/schemas/NewClientErrorSchema'
examples:
Internal Server Error:
$ref: '#/components/examples/InternalServerError'
/v1/users:
get:
summary: List users
operationId: list-users
tags:
- User management
description: This API returns a paginated list of Dashboard members in your organization. Use this endpoint to review existing users, filter by manager status, or sort results by ID or email.
parameters:
- name: offset
in: query
description: The number of records to skip before returning results. Used for pagination. Defaults to 0 if not specified.
example: 0
required: false
schema:
type: integer
minimum: 0
default: 0
example: 0
- name: limit
in: query
description: The maximum number of records to return per page, starting from the specified `offset` value. Defaults to 50 if not specified.
example: 50
required: false
schema:
type: integer
minimum: 1
maximum: 50
default: 50
example: 50
- name: is_manager
in: query
description: Use this parameter to narrow results by manager status. Set to `true` to return only users with manager permissions, or `false` to return only standard users. If not provided, all users in your organization are returned regardless of their manager status.
example: true
required: false
schema:
type: boolean
example: true
- name: sort
in: query
description: The field to use when sorting the list of users. Use `id` to sort by the user's unique identifier, or `email` to sort alphabetically by email address. Defaults to `id` if not specified.
example: email
required: false
schema:
type: string
enum:
- id
- email
default: id
example: id
- name: order
in: query
description: The sort direction for the results. Use `asc` for ascending order or `desc` for descending order. Defaults to `asc` if not specified.
example: asc
required: false
schema:
type: string
enum:
- asc
- desc
default: asc
example: asc
x-readme:
samples-languages:
- curl
- python
explorer-enabled: false
responses:
'200':
description: Users retrieved successfully
content:
application/json:
schema:
$ref: '#/components/schemas/SuccessListUsersSchema'
examples:
Success:
$ref: '#/components/examples/SuccessListUsersResponse'
'400':
description: Bad request
content:
application/json:
schema:
$ref: '#/components/schemas/NewClientErrorSchema'
examples:
Bad request:
$ref: '#/components/examples/BadRequestError'
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/NewClientErrorSchema'
examples:
Invalid Authentication:
$ref: '#/components/examples/InvalidAuthError'
'403':
description: Forbidden
content:
application/json:
schema:
$ref: '#/components/schemas/NewClientErrorSchema'
examples:
Forbidden:
$ref: '#/components/examples/ForbiddenError'
'412':
description: Precondition failed
content:
application/json:
schema:
$ref: '#/components/schemas/NewClientErrorSchema'
examples:
Precondition failed:
$ref: '#/components/examples/PreconditionFailedError'
'500':
description: Internal server error
content:
application/json:
schema:
$ref: '#/components/schemas/NewClientErrorSchema'
examples:
Internal Server Error:
$ref: '#/components/examples/InternalServerError'
components:
examples:
SuccessCreateInvitationsResponse:
value:
email: jane.doe@example.com
first_name: Jane
last_name: Doe
is_manager: false
invited_by_account_pk: 1042
created_at: '2026-06-08T10:30:00Z'
expires_at: '2026-06-15T10:30:00Z'
SuccessListInvitationsResponse:
value:
invitations:
- email: jane.doe@example.com
first_name: Jane
last_name: Doe
is_manager: false
invited_by_account_pk: 1042
created_at: '2026-06-08T10:30:00Z'
expires_at: '2026-06-15T10:30:00Z'
- email: john.smith@example.com
first_name: John
last_name: Smith
is_manager: true
invited_by_account_pk: null
created_at: '2026-06-07T08:00:00Z'
expires_at: '2026-06-14T08:00:00Z'
total: 2
offset: 0
limit: 50
ForbiddenError:
summary: Forbidden
value:
status: 403
message: Forbidden
code: 4030
InternalServerError:
summary: Internal server error
value:
status: 500
message: An internal server error occurred.
code: 5000
SuccessListUsersResponse:
value:
users:
- id: 1042
email: jane.doe@example.com
first_name: Jane
last_name: Doe
is_manager: false
- id: 1043
email: john.smith@example.com
first_name: John
last_name: Smith
is_manager: true
total: 2
offset: 0
limit: 50
PreconditionFailedError:
summary: Precondition Failed
value:
status: 412
message: Precondition Failed
code: 4120
BadRequestError:
summary: Bad request
value:
status: 400
message: Bad Request
code: 4000
InvalidAuthError:
summary: Unauthorized - Invalid Authentication
value:
status: 401
message: Authentication failed
code: 1200
schemas:
SuccessListInvitationsSchema:
title: Success
type: object
description: Schema for the successful response of listing invitations.
properties:
invitations:
type: array
description: Pending invitations on the current page.
items:
type: object
description: A pending invitation in your organization.
properties:
email:
type: string
format: email
example: jane.doe@example.com
description: Email address of the invited user whose invitation is pending.
first_name:
type: string
nullable: true
example: Jane
description: First name of the invited user.
last_name:
type: string
nullable: true
example: Doe
description: Last name of the invited user.
is_manager:
type: boolean
example: false
description: Indicates whether the invited user was granted manager permissions.
invited_by_account_pk:
type: integer
nullable: true
example: 1042
description: A unique identifier of the user who sent the invitation.
created_at:
type: string
format: date-time
example: '2026-06-08T10:30:00Z'
description: Timestamp indicating when the invitation was created.
expires_at:
type: string
format: date-time
example: '2026-06-15T10:30:00Z'
description: Timestamp indicating when the invitation expires.
total:
type: integer
example: 2
description: Total number of pending invitations in your organization.
offset:
type: integer
example: 0
description: The number of records skipped for this page. Reflects the offset value submitted in the request.
limit:
type: integer
example: 50
description: The maximum number of records returned for this page. Reflects the limit value submitted in the request.
NewClientErrorSchema:
properties:
status:
type: integer
description: A numerical code that indicates the status of the request.
example: 400
message:
type: string
description: A human-readable message providing details about the response status.
example: Book not found
code:
type: integer
description: A numerical code that indicates the nature of an error. To learn more about error codes, see [here](https://docs.ocrolus.com/reference/ocrolus-status-codes-api).
example: 1401
SuccessListUsersSchema:
title: Success
type: object
description: Schema for the successful response of listing users.
properties:
users:
type: array
description: Users on the current page.
items:
type: object
description: A dashboard member of the caller's organization.
properties:
id:
type: integer
example: 1042
description: A unique identifier of the user.
email:
type: string
format: email
example: jane.doe@example.com
description: Email address of the user.
first_name:
type: string
example: Jane
description: First name of the user.
last_name:
type: string
example: Doe
description: Last name of the user.
is_manager:
type: boolean
example: false
description: Indicates whether the user has manager permissions.
total:
type: integer
example: 2
description: Total number of users in the organization matching the query.
offset:
type: integer
example: 0
description: The number of records skipped for this page. Reflects the offset value submitted in the request.
limit:
type: integer
example: 50
description: The maximum number of records returned for this page. Reflects the limit value submitted in the request.
SuccessCreateInvitationsSchema:
title: Success
type: object
description: Schema for the successful response of creating an invitation.
properties:
email:
type: string
format: email
example: jane.doe@example.com
description: Email address of the invited user.
first_name:
type: string
nullable: true
example: Jane
description: First name of the invited user.
last_name:
type: string
nullable: true
example: Doe
description: Last name of the invited user.
is_manager:
type: boolean
example: false
description: Indicates whether the invited user was granted manager permissions.
invited_by_account_pk:
type: integer
nullable: true
example: 1042
description: A unique identifier of the user who sent the invitation.
created_at:
type: string
format: date-time
example: '2026-06-08T10:30:00Z'
description: Timestamp indicating when the invitation was created.
expires_at:
type: string
format: date-time
example: '2026-06-15T10:30:00Z'
description: Timestamp indicating when the invitation expires.
securitySchemes:
oauth:
type: oauth2
description: 'OAuth 2.0 support via client credentials flow. See [here](doc:using-api-credentials) for usage information.
'
flows:
clientCredentials:
tokenUrl: https://auth.ocrolus.com/oauth/token
scopes: {}