Create person
Creates a new person record with optional group and role assignments
/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
Request Body
first_name
string
First name (required for creation)
last_name
string
Last name (required for creation)
salutation
string
Salutation or title
job_title
string
Job title
email
string
Email address (must be unique within account if provided)
department
string
Department name
enabled
boolean
Whether the person is enabled for access
valid_from
string
Access valid from this date/time
valid_to
string
Access valid until this date/time
image_base64
string
Base64-encoded image data for person's photo
image_remote_url
string
Remote URL to fetch person's photo from (set to empty string to delete image)
telephone
string
Telephone number
mobile
string
Mobile number (E.164 format if passport enabled)
notes
string
Additional notes
barcode
string
Barcode identifier
system_id
string
External system identifier
organisation_id
integer
Organisation ID
custom_1
string
Custom field 1
custom_2
string
Custom field 2
custom_3
string
Custom field 3
custom_4
string
Custom field 4
custom_5
string
Custom field 5
group_ids
array
Array of group IDs to assign this person to
role_ids
array
Array of role IDs to assign to this person (requires permission)
deleted
boolean
Mark person as deleted (used internally)
Example
{
"first_name": "John",
"last_name": "Doe",
"salutation": "string",
"job_title": "string",
"email": "string",
"department": "string",
"enabled": false,
"valid_from": "string",
"valid_to": "string",
"image_base64": "string",
"image_remote_url": "string",
"telephone": "string",
"mobile": "+14155551234",
"notes": "string",
"barcode": "string",
"system_id": "string",
"organisation_id": 0,
"custom_1": "string",
"custom_2": "string",
"custom_3": "string",
"custom_4": "string",
"custom_5": "string",
"group_ids": [
0
],
"role_ids": [
0
],
"deleted": false
}Responses
Person created 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
Unprocessable Entity - Validation failed
Response Fields
error
string
Error message
errors
object
Field-specific validation errors
Show child attributes
value
array
eg. ["value is already in use on your account", "must be between 4 and 7 digits in length"]
Validation errors for the credential value
credential_type_id
array
eg. ["Not found for this account"]
Validation errors for the credential type
limit_reached
string
eg. You have reached your HID Mobile licence limit. Please contact DoorFlow Support.
License limit error message
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:
Employee Onboarding Workflow
Complete code to onboard new employees with card and PIN in 7 minutes
Visitor Management Workflow
Grant temporary access to visitors with time-limited PINs in 7 minutes
Contractor Temporary Access
Grant time-limited access to contractors for weeks or months in 5 minutes
HTTP Status Codes
Understanding API response codes and error formats in 5 minutes
Error Handling & Retries
Handle errors gracefully with complete error code reference and retry strategies