List people
Returns a paginated list of people accessible to the authenticated user. Supports incremental sync via since or since_utc parameters.
/api/3/people
Authentication
This endpoint requires authentication:
Use an OAuth 2.0 access token in the Authorization header. This is the recommended authentication method for all integrations. OAuth provides automatic token expiration, granular permission scopes, detailed usage tracking, and per-integration revocation. Learn how to obtain an access token.
Header Format:
Authorization: Bearer YOUR_ACCESS_TOKEN
Required Scopes:
account.person.readonly
Parameters
Query Parameters
email
string
Filter by email (case-insensitive partial match)
system_id
string
Filter by organisation system ID
since
string
Return only people updated since this timestamp (local time)
since_utc
string
Return only people updated since this timestamp (UTC)
per_page
integer
Number of results per page
Default: 50
page
integer
Page number for pagination
Default: 1
skip_pagination
boolean
Skip pagination and return all results
Responses
List of people retrieved successfully
Response Fields
id
integer
required
Unique identifier for the person
eg. 12345
first_name
string
required
First name (required)
eg. John
last_name
string
required
Last name (required)
eg. Doe
salutation
string | null
Salutation or title (Mr., Ms., Dr., etc.)
eg. Mr.
job_title
string | null
Job title
eg. Software Engineer
email
string | null
Email address (must be unique within account if provided)
eg. john.doe@example.com
organisation_id
integer | null
Organisation ID
system_id
string | null
External system identifier
eg. EMP-12345
department
string | null
Department name
eg. Engineering
enabled
boolean
required
Whether the person is currently enabled for access
eg. true
valid_from
string | null
Access valid from this date/time
valid_to
string | null
Access valid until this date/time
image_url
string | null
URL to person's full-size photo
image_thumbnail_url
string | null
URL to person's thumbnail photo
telephone
string | null
Telephone number
mobile
string | null
Mobile number (E.164 format required if passport enabled)
eg. +14155551234
notes
string | null
Additional notes
barcode
string | null
Barcode identifier
custom_1
string | null
Custom field 1
custom_2
string | null
Custom field 2
custom_3
string | null
Custom field 3
custom_4
string | null
Custom field 4
custom_5
string | null
Custom field 5
created_at
string
Timestamp of creation
updated_at
string
Timestamp of last update
groups
array<integer>
required
Array of group IDs this person belongs to
eg. [1, 3, 5]
roles
array<integer>
required
Array of role IDs assigned to this person
eg. [2, 4]
Unauthorized - Invalid or missing authentication
Response Fields
error
string
eg. unauthorized
error_description
string
eg. The access token is invalid
Forbidden - User does not have permission
Response Fields
error
string
eg. forbidden
error_description
string
eg. You are not authorized to access this resource
Internal Server Error
Response Fields
error
string
eg. internal_server_error
error_description
string
eg. An unexpected error occurred
Mentioned in Guides
This endpoint is used in the following guides:
Core Resources Reference
Quick reference for People, Credentials, Channels, Groups, and Roles
Employee Onboarding Workflow
Complete code to onboard new employees with card and PIN in 7 minutes
Employee Offboarding Workflow
Revoke access when employees leave while maintaining audit trail in 5 minutes
After-Hours Access Workflow
Grant remote access to specific people for single-use door unlock in 3 minutes
Error Handling & Retries
Handle errors gracefully with complete error code reference and retry strategies