Every person in an organization is a people record. The person_type filter distinguishes four kinds:
For more details on how to work with custom fields please refer to Working with custom fields guide.
Adding a person takes two requests.
POST /api/v2/people creates the person record. It has no login yet and appears as a Contact in the person_type filter. company_id and role_id are required, and the person needs an email before it can be invited.PATCH /api/v2/people/{id}/invite turns the record into a User. It creates or links the user account for the email, applies company_id, custom_role_id and, for time tracker roles, subsidiary_id, and sends the invitation email.skip_inviteAdd ?skip_invite=true to the invite request to create and link the user account without sending the email. The person is marked virtual: true and invited_at stays empty.
Use it when you are importing people who should exist in planning, reports and time tracking but should not get access yet, or ever. Do not use it for people who need to sign in, since no email is sent and PATCH /api/v2/people/{id}/resend does nothing for virtual people.
Filter by accessible deal ID — returns people who have access to the specified deal.
Filter by accessible doc ID — returns people who have access to the specified document.
Filter by accessible filter ID — returns people who are members of the specified saved view or filter.
Filter by accessible project ID — returns people who have access to the specified project.
The organization (account) ID.
The AI agent account linked to this person, if this person represents an AI agent.
[DESCRIPTION]
Custom instructions the person's AI assistant follows when acting on their behalf. Only returned to the person themselves.
[DESCRIPTION]
The approval policy assignment for this person.
ID of the approval policy assigned to this person for time-off and booking approvals.
Filter by approval workflow ID — returns people who have approvals in the specified workflow.
Timestamp when this person was archived, or null if not archived.
Whether automatic time tracking is enabled for this person.
The person's work availability windows.
URL of the person's avatar thumbnail.
Filter by bookings_after date — used with resourcing filters to find people with bookings ending on or after this date.
Filter by bookings_before date — used with resourcing filters to find people with bookings starting on or before this date.
Whether this person is a champion contact.
[DESCRIPTION]
Color identifier used to visually distinguish this person in the UI.
The company (client) this person belongs to.
Filter by company (client) ID.
The name of the company this person belongs to.
Additional contact data for the person, such as phone numbers and addresses.
Timestamp when this person was created.
File attachments associated with this person via custom fields.
People referenced in custom field values for this person.
Custom field values for this person.
The custom role (permission set) assigned to this person.
ID of the custom role assigned to this person, if any.
Timestamp when this person was deactivated, or null if currently active.
Filter for people eligible to be replacement managers for the specified person ID.
The person's email address.
[DESCRIPTION]
External identifier for syncing this person with an external system.
Whether this person is managed by an external sync integration.
The person's first name.
Full text search filter — matches against name and other indexed fields.
Fuzzy date filter for approximate date matching.
Fuzzy people filter for approximate person name matching.
Granular notification preferences for this person.
ID of the holiday calendar assigned to this person for scheduling and time-off calculations.
HRM type ID: 1 for employee, 2 for contact. Null for placeholders.
1
2
The unique identifier of the person.
The data import that created this person, if they were added through an import rather than manually.
Timestamp when the invitation email was sent to this person.
Whether this person reports, directly or indirectly, to the person making the request. Only included when the request sends the X-Subordinate-Info header and the requester's permissions are limited to their subordinates rather than to everyone.
Whether this person has an associated user account and can log in.
The job role assigned to this person. Job roles describe what a person does, for example a designer or a project manager, and are managed separately from permission roles.
ID of the job role assigned to this person, or null if none is set.
Date when this person joined the organization.
Quick jump search filter — matches against name for navigation shortcuts.
Timestamp of the last recorded activity for this person across the platform.
The person's last name.
Timestamp when this person was last seen active in the application.
The person's manager.
ID of the person who is this person's direct manager.
The person's full name (first and last combined).
The person's nickname or preferred display name.
ID of the offboarding process associated with this person's deactivation.
Current offboarding status: not_initiated, in_progress, or completed.
not_initiated
in_progress
failed
completed
The organization this person belongs to.
URL of the person's original full-size avatar image.
Filter by permission set — returns people with the specified permission slugs.
[DESCRIPTION]
Filter by person type — values: user (can log in), contact (external), placeholder (resource planning), agent.
1
2
3
4
Whether this person is a placeholder used for resource planning, without a real user account.
Filter by project ID — returns people who are members of the specified project.
Filter by project_watching — returns people who are auto-subscribed to the specified project.
Text search filter — matches by full name (exact) or contains partial name.
Filter by built-in role type ID.
Whether this person was created as part of sample/demo data.
Filter for schedulable people — returns employees, contractors, and placeholders who can be booked.
Filter by service ID — returns people who can track time on the specified service.
Filter by service type ID — returns people assigned to the specified service types.
The service types this person delivers.
Whether the person holds a shared seat in the billing group.
Filter by person status: 1 (active) or 2 (deactivated).
1
2
Emoji shown as the person's current status indicator.
Timestamp when the current status emoji and text expire.
Short text message shown as the person's current status.
Filter by subscribable ID — returns subscribers of the specified resource.
Filter by subscribable type — the resource type to match subscribers against.
IDs of people subscribed to follow this person.
The subsidiary (workplace) this person is associated with.
ID of the subsidiary company this person belongs to, if any.
Comma-separated list of tags applied to this person.
Tags applied to this person.
Filter by team ID — returns people who belong to the specified team(s).
The teams this person belongs to.
Whether this person's time-off status is synced from an external calendar.
Whether timesheet submission is disabled for this person.
The time tracking policy assigned to this person.
ID of the time tracking policy applied to this person.
Whether the person's time entries are unlocked for editing outside the normal window.
End date of the time unlock window.
Number of days in the time unlock interval.
The specific date on which the time unlock was applied.
Period identifier for the time unlock.
Start date of the time unlock window.
The person's job title (e.g. CEO, Manager, Developer).
Whether two-factor authentication is enabled for this person's user account.
The ID of the user account linked to this person, if any.
Whether this is a virtual person record.