Deel: List of People
Deel people.getPeople: arguments, response, policy and SDK examples.
← People operations · Get started
Operation deel.people_getpeople
Provider route: GET /people. Alter supplies the connection’s credentials and routing.
Call through Alter
Section titled “Call through Alter”Install @alter-ai/sdk @alter-ai/deel with npm, or alter-sdk-deel with pip. Supply your connected customer’s grant ID and the arguments described below.
import { App } from "@alter-ai/sdk";import { DeelIntegration } from "@alter-ai/deel";
async function execute(input: Parameters<DeelIntegration["people"]["getPeople"]>[0]) { const app = new App({ apiKey: process.env.ALTER_API_KEY! }); try { const provider = new DeelIntegration(app, { grantId: process.env.PROVIDER_GRANT_ID! }); const call = await provider.people.getPeople(input); const result = await call.wait(); return result.bodyJson(); } finally { await app.close(); }}import osfrom alter_sdk import Appfrom alter_sdk_deel import DeelIntegration
async def execute(arguments): async with App(api_key=os.environ["ALTER_API_KEY"]) as app: provider = DeelIntegration(app, {"grant_id": os.environ["PROVIDER_GRANT_ID"]}) call = await provider.people.get_people(arguments) result = await call.wait() return result.body_json()| Field | Type | Presence | Description and constraints |
|---|---|---|---|
$ | object | Root | Additional keys: not allowed |
query | object | Optional | Additional keys: not allowed |
query.offset | integer | Optional | Default: 0 Maximum: 999999999 Minimum: 0 |
query.limit | integer | Optional | Maximum: 200 Minimum: 1 |
query.search | string | Optional | |
query.teams | array | Optional | |
query.teams[] | string | Each item | Format: uuid |
query.fields | array | Optional | |
query.fields[] | Model | Each item | Expand List of People — request body — query fields item |
query.sort_by | string | Optional | One of: id, first_name, last_name, full_name, email, country, birth_date, hiring_type, start_date, team, job_title, hiring_status, completion_date, direct_manager, direct_reports_count, band_placement, comparative_ratio |
query.sort_order | string | Optional | One of: asc, desc |
query.hiring_statuses | array | Optional | |
query.hiring_statuses[] | string | Each item | One of: pending_invite, draft, invited, onboarding, onboarding_at_risk, onboarding_overdue, onboarded, offboarding, active, inactive, in_review, quote_requires_changes |
query.band_placements | array | Optional | |
query.band_placements[] | string | Each item | One of: ABOVE, WITHIN, BELOW |
query.comparative_ratios_from | string | Optional | |
query.comparative_ratios_to | string | Optional | |
query.hiring_types | array | Optional | |
query.hiring_types[] | string | Each item | One of: contractor, eor, peo, hris_direct_employee, hris_direct_contractor, direct_employee, contractor_outside_deel, person_without_contract |
query.person_statuses | array | Optional | |
query.person_statuses[] | string | Each item | One of: ACTIVE, NOT_STARTED, INACTIVE |
Referenced models: List of People — request body — query fields item
Response
Section titled “Response”Response media type: application/json. The table describes the pinned successful response. Referenced models link to their complete fields.
| Field | Type | Presence | Description and constraints |
|---|---|---|---|
$ | Model | Root | Expand List of People — 200 response body |
Referenced models: List of People — 200 response body
Schemas
Section titled “Schemas”5 more schemas are linked from the tables above, on the schema pages.
List of People — 200 response body
| Field | Type | Presence | Description and constraints |
|---|---|---|---|
$ | object | Root | |
data | array | Required within parent | |
data[] | Model | Each item | Expand List of People — 200 response body — data item |
page | Model | Optional | Expand List of People — 200 response body — page |
Referenced models: List of People — 200 response body — data item, List of People — 200 response body — page
List of People — request body — query fields item
| Field | Type | Presence | Description and constraints |
|---|---|---|---|
$ | string | Root | One of: id, created_at, first_name, last_name, full_name, preferred_first_name, preferred_last_name, worker_id, external_id, hris_organization_user_id, termination_last_day, worker_relations, custom_field_values, emails, birth_date, start_date, nationalities, client_legal_entity, state, seniority, completion_date, direct_manager, direct_reports, direct_reports_count, employments, employments[0].id, employments[0].name, employments[0].team, employments[0].custom_field_values, employments[0].email, employments[0].state, employments[0].country, employments[0].payment, employments[0].is_ended, employments[0].termination_last_day, employments[0].timezone, employments[0].job_title, employments[0].seniority, employments[0].start_date, employments[0].work_email, employments[0].hiring_type, employments[0].hiring_status, employments[0].completion_date, employments[0].contract_status, employments[0].voluntarily_left, employments[0].contract_coverage, employments[0].new_hiring_status, employments[0].client_legal_entity, employments[0].has_eor_termination, employments[0].contract_is_archived, employments[0].contract_has_contractor, employments[0].is_user_contract_deleted, employments[0].hris_direct_employee_invitation, employments[0].employee_number, hiring_status, new_hiring_status, is_pwac, hiring_type, job_title, country, timezone, department, work_location, updated_at, addresses, additional_details, profile_organizational_structures, worker_termination_last_date_of_work, active_worker_termination_status, last_day_of_work_local_date, person_status |
List of People — 200 response body — page
| Field | Type | Presence | Description and constraints |
|---|---|---|---|
$ | object | Root | |
items_per_page | JSON | Required within parent | |
items_per_page (anyOf 1) | number | Alternative | Format: double Maximum: 200 Minimum: 1 |
items_per_page (anyOf 2) | string | Alternative | Pattern: ^-?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$ |
offset | JSON | Required within parent | |
offset (anyOf 1) | integer | Alternative | Maximum: 999999999 Minimum: 0 |
offset (anyOf 2) | string | Alternative | Pattern: ^-?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$ |
total_rows | JSON | Required within parent | |
total_rows (anyOf 1) | number | Alternative | Format: double |
total_rows (anyOf 2) | string | Alternative | Pattern: ^-?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$ |
Retrieve a single person — 200 response body — data additional details null item
| Field | Type | Presence | Description and constraints |
|---|---|---|---|
$ | object | Root | |
country | string | Optional | ISO-2 country code that scopes this entry. Maximum length: 2 Minimum length: 2 Pattern: ^[A-Z]{2}$ |
type | string | Optional | Field name (the JSONB key from hris_employment_eligibility.eligibility_data, e.g. socialSecurity, idNumber, taxIdentificationNumber). |
value | Model | Optional | Expand Retrieve a single person — 200 response body — data additional details null item value Raw value associated with the field. May be a string, number, boolean, or null. |
Referenced models: Retrieve a single person — 200 response body — data additional details null item value
List of People — 200 response body — data item addresses null item
| Field | Type | Presence | Description and constraints |
|---|---|---|---|
$ | object | Root | |
country | JSON | Optional | |
country (anyOf 1) | string | Alternative | Country code. Maximum length: 2 Minimum length: 2 Pattern: ^[A-Z]{2}$ |
country (anyOf 2) | null | Alternative | Country code. Maximum length: 2 Minimum length: 2 Pattern: ^[A-Z]{2}$ |
lineTwo | string | Optional | Second address line. |
locality | string | Optional | Locality name. |
postalCode | string | Optional | Postal code. |
region | string | Optional | Region code. |
streetAddress | string | Optional | Street and number. |
Retrieve a single person — 200 response body — data client legal entity
| Field | Type | Presence | Description and constraints |
|---|---|---|---|
$ | object | Root | The primary client legal entity associated with the employee. |
id | JSON | Optional | |
id (anyOf 1) | string | Alternative | Unique identifier of this resource. Format: uuid |
id (anyOf 2) | null | Alternative | Unique identifier of this resource. Format: uuid |
name | JSON | Optional | |
name (anyOf 1) | string | Alternative | The name of the client legal entity. |
name (anyOf 2) | null | Alternative | The name of the client legal entity. |
List of People — 200 response body — data item department
| Field | Type | Presence | Description and constraints |
|---|---|---|---|
$ | object | Root | The department of the employee. |
id | string | Optional | Unique identifier of this resource. Format: uuid |
name | string | Optional | The name of the department. |
parent | string | Optional | The parent department name. |
List of People — 200 response body — data item direct manager The direct manager of the employee
| Field | Type | Presence | Description and constraints |
|---|---|---|---|
$ | object | Root | The direct manager of the employee. |
first_name | string | Optional | The first name of the manager. |
id | string | Optional | Unique identifier for the manager. |
last_name | string | Optional | The last name of the manager. |
work_email | JSON | Optional | |
work_email (anyOf 1) | string | Alternative | The work email of the manager. |
work_email (anyOf 2) | null | Alternative | The work email of the manager. |
worker_id | JSON | Optional | |
worker_id (anyOf 1) | number | Alternative | The worker ID of the manager. Format: double |
worker_id (anyOf 2) | string | Alternative | Pattern: ^-?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$ |
List of People — 200 response body — data item direct reports The direct reports to the employee item
| Field | Type | Presence | Description and constraints |
|---|---|---|---|
$ | object | Root | |
first_name | string | Optional | The first name of the direct report. |
id | string | Optional | Unique identifier for the direct report. |
last_name | string | Optional | The last name of the direct report. |
work_email | JSON | Optional | |
work_email (anyOf 1) | string | Alternative | The work email of the direct report. |
work_email (anyOf 2) | null | Alternative | The work email of the direct report. |
List of People — 200 response body — data item emails An array of the employee's email addresses item
| Field | Type | Presence | Description and constraints |
|---|---|---|---|
$ | object | Root | |
type | JSON | Optional | |
type (anyOf 1) | string | Alternative | The type of email. |
type (anyOf 2) | null | Alternative | The type of email. |
value | JSON | Optional | |
value (anyOf 1) | string | Alternative | The email address. |
value (anyOf 2) | null | Alternative | The email address. |
Retrieve a single person — 200 response body — data additional details null item value
| Field | Type | Presence | Description and constraints |
|---|---|---|---|
$ | JSON | Root | Raw value associated with the field. May be a string, number, boolean, or null. |
$ (anyOf 1) | string | Alternative | |
$ (anyOf 2) | JSON | Alternative | |
$ (anyOf 2) (anyOf 1) | number | Alternative | Format: double |
$ (anyOf 2) (anyOf 2) | string | Alternative | Pattern: ^-?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$ |
$ (anyOf 3) | boolean | Alternative | |
$ (anyOf 4) | object | Alternative | Additional keys: see wildcard field |
$ (anyOf 4).* | JSON | Additional keys | Any type |
Retrieve a single person — 200 response body — data employments item client legal entity id, name
| Field | Type | Presence | Description and constraints |
|---|---|---|---|
$ | object | Root | The client legal entity associated with this employment contract. |
id | JSON | Optional | |
id (anyOf 1) | string | Alternative | Unique identifier of this resource. Format: uuid |
id (anyOf 2) | null | Alternative | Unique identifier of this resource. Format: uuid |
name | JSON | Optional | |
name (anyOf 1) | string | Alternative | The name of the client legal entity. |
name (anyOf 2) | null | Alternative | The name of the client legal entity. |
Policy, approvals and errors
Section titled “Policy, approvals and errors”SDK function policy ID: deel.people_getpeople. Catalog operation: people_getpeople. Rules can name either ID; function rules distinguish managed calls and conservatively cover raw calls sharing the route. Existing grant permissions and policy rules apply. wait() returns an immediate result or waits for a required approval; it never approves the request itself. Persist the approval ID to resume after a restart.
Provider errors retain their response; JSON decoding raises ProviderAPIError for provider failures. ManagedOperationError identifies contract/input/retention errors. See error handling and provider-specific behavior. Sensitive input may be refused before approval storage. A decoding error never resubmits a write.
Required provider scopes: ["people:read"]
Pinned headers: {"X-Version": "2026-01-01"}