Skip to content

Deel: Retrieve a single person

Deel people.getPersonById: arguments, response, policy and SDK examples.

← People operations · Get started

Operation deel.people_getpersonbyid

Provider route: GET /people/{hris_profile_id}. Alter supplies the connection’s credentials and routing.

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"]["getPersonById"]>[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.getPersonById(input);
const result = await call.wait();
return result.bodyJson();
} finally {
await app.close();
}
}
import os
from alter_sdk import App
from 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_person_by_id(arguments)
result = await call.wait()
return result.body_json()
FieldTypePresenceDescription and constraints
$objectRootAdditional keys: not allowed
pathobjectRequired within parentAdditional keys: not allowed
path.hris_profile_idstringRequired within parentFormat: uuid
queryobjectOptionalAdditional keys: not allowed
query.include_custom_fieldsbooleanOptional
query.include_worker_relationsbooleanOptional

Response media type: application/json. The table describes the pinned successful response. Referenced models link to their complete fields.

FieldTypePresenceDescription and constraints
$ModelRootExpand Retrieve a single person — 200 response body

Referenced models: Retrieve a single person — 200 response body

19 more schemas are linked from the tables above, on the schema pages.

Retrieve a single person — 200 response body
FieldTypePresenceDescription and constraints
$objectRoot
dataModelRequired within parentExpand Retrieve a single person — 200 response body — data

Referenced models: Retrieve a single person — 200 response body — data

Retrieve a single person — 200 response body — data
FieldTypePresenceDescription and constraints
$objectRoot
active_worker_termination_statusJSONOptionalThe status of the active worker termination.
active_worker_termination_status (anyOf 1)stringAlternativeThe status of the active worker termination.
Known values: PENDING, CONTRACT_TERMINATION_DATA_COLLECTED, IN_PROGRESS, COMPLETED, FAILED, CANCELED
active_worker_termination_status (anyOf 2)nullAlternative
additional_detailsJSONOptional
additional_details (anyOf 1)arrayAlternativeCountry-scoped additional employment data points (national IDs, tax IDs, etc.) sourced from hris_employment_eligibility.eligibility_data. Returned only when the caller's organization has the feature flag enabled and the request is not redacting PII.
additional_details (anyOf 1)[]ModelEach itemExpand Retrieve a single person — 200 response body — data additional details null item
additional_details (anyOf 2)nullAlternativeCountry-scoped additional employment data points (national IDs, tax IDs, etc.) sourced from hris_employment_eligibility.eligibility_data. Returned only when the caller's organization has the feature flag enabled and the request is not redacting PII.
additional_details (anyOf 2)[]ModelEach itemExpand Retrieve a single person — 200 response body — data additional details null item
addressesarrayOptionalAn array of address objects containing the employee's physical addresses.
addresses[]ModelEach itemExpand Retrieve a single person — 200 response body — data addresses item
birth_dateJSONOptional
birth_date (anyOf 1)stringAlternativeThe birth date of the employee.
birth_date (anyOf 2)nullAlternativeThe birth date of the employee.
client_legal_entityModelOptionalExpand Retrieve a single person — 200 response body — data client legal entity
The primary client legal entity associated with the employee.
completion_dateJSONOptional
completion_date (anyOf 1)stringAlternativeThe completion date of the task or project.
completion_date (anyOf 2)nullAlternativeThe completion date of the task or project.
countryJSONOptional
country (anyOf 1)stringAlternativeThe country of the employee.
country (anyOf 2)nullAlternativeThe country of the employee.
created_atstringOptionalThe creation timestamp of the employee record.
Format: date-time
custom_fieldsarrayOptionalAn array of custom field objects containing additional attributes associated with the employee (e.g., Job title, Project code, etc.).
custom_fields[]ModelEach itemExpand Retrieve a single person — 200 response body — data custom fields item
departmentModelOptionalExpand Retrieve a single person — 200 response body — data department
The department of the employee.
direct_employee_termination_last_daystringOptionalThe last day of work mentioned on the primary contract termination.
Format: date
direct_managerJSONOptionalThe direct manager of the employee.
direct_manager (anyOf 1)ModelAlternativeExpand Retrieve a single person — 200 response body — data direct manager The direct manager of the employee
direct_manager (anyOf 2)nullAlternative
direct_reportsJSONOptional
direct_reports (anyOf 1)arrayAlternativeThe direct reports to the employee.
direct_reports (anyOf 1)[]ModelEach itemExpand Retrieve a single person — 200 response body — data direct reports The direct reports to the employee item
direct_reports (anyOf 2)nullAlternativeThe direct reports to the employee.
direct_reports (anyOf 2)[]ModelEach itemExpand Retrieve a single person — 200 response body — data direct reports The direct reports to the employee item
direct_reports_countJSONOptional
direct_reports_count (anyOf 1)integerAlternativeThe count of direct reports to the employee.
direct_reports_count (anyOf 2)stringAlternativePattern: ^-?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$
emailsarrayOptionalAn array of the employee's email addresses.
emails[]ModelEach itemExpand Retrieve a single person — 200 response body — data emails item
employmentsarrayOptionalAn array of employment records associated with the employee, including contract details, team information, payment details, and employment status.
employments[]ModelEach itemExpand Retrieve a single person — 200 response body — data employments item
external_idJSONOptional
external_id (anyOf 1)stringAlternativeThe external ID of the employee.
external_id (anyOf 2)nullAlternativeThe external ID of the employee.
first_namestringOptionalThe first name of the employee.
full_namestringOptionalThe full name of the employee.
hiring_statusstringOptionalThe current hiring status of the employee.
hiring_typestringOptionalThe type of hiring of the employee.
idstringOptionalUnique identifier for the employee.
Format: uuid
job_titleJSONOptional
job_title (anyOf 1)stringAlternativeThe job title of the employee.
job_title (anyOf 2)nullAlternativeThe job title of the employee.
last_namestringOptionalThe last name of the employee.
nationalitiesarrayOptionalThe nationality of the employee.
nationalities[]stringEach item
new_hiring_statusstringOptionalThe new hiring status of the employee.
preferred_first_nameJSONOptional
preferred_first_name (anyOf 1)stringAlternativeThe preferred first name of the employee.
preferred_first_name (anyOf 2)nullAlternativeThe preferred first name of the employee.
preferred_last_nameJSONOptional
preferred_last_name (anyOf 1)stringAlternativeThe preferred last name of the employee.
preferred_last_name (anyOf 2)nullAlternativeThe preferred last name of the employee.
profile_organizational_structuresarrayOptionalAn array of organizational structures associated with the employee profile.
profile_organizational_structures[]ModelEach itemExpand Retrieve a single person — 200 response body — data profile organizational structures item
seniorityJSONOptional
seniority (anyOf 1)stringAlternativeThe seniority level of the employee.
seniority (anyOf 2)nullAlternativeThe seniority level of the employee.
start_dateJSONOptional
start_date (anyOf 1)stringAlternativeThe date the employee started working.
Format: date
start_date (anyOf 2)nullAlternativeThe date the employee started working.
Format: date
stateJSONOptional
state (anyOf 1)stringAlternativeThe state of the employee.
state (anyOf 2)nullAlternativeThe state of the employee.
timezoneJSONOptional
timezone (anyOf 1)stringAlternativeThe timezone of the employee.
timezone (anyOf 2)nullAlternativeThe timezone of the employee.
updated_atJSONOptional
updated_at (anyOf 1)stringAlternativeLong date-time format following ISO-8601
Format: date-time
updated_at (anyOf 2)nullAlternativeLong date-time format following ISO-8601
Format: date-time
work_locationJSONOptional
work_location (anyOf 1)stringAlternativeThe work location of the employee.
work_location (anyOf 2)nullAlternativeThe work location of the employee.
worker_idstringOptionalThe worker ID of the employee.

Referenced models: Retrieve a single person — 200 response body — data additional details null item, Retrieve a single person — 200 response body — data client legal entity, Retrieve a single person — 200 response body — data addresses item, Retrieve a single person — 200 response body — data custom fields item, Retrieve a single person — 200 response body — data department, Retrieve a single person — 200 response body — data direct manager The direct manager of the employee, Retrieve a single person — 200 response body — data direct reports The direct reports to the employee item, Retrieve a single person — 200 response body — data emails item, Retrieve a single person — 200 response body — data employments item, Retrieve a single person — 200 response body — data profile organizational structures item

SDK function policy ID: deel.people_getpersonbyid. Catalog operation: people_getpersonbyid. 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"}

Official provider source

Report an issue with this page

Necessary

Required for sign-in, security, authorization, and remembering your choices.

Always active

Analytics

Helps us understand which product and documentation features are useful.

Performance diagnostics

Uses performance tracing and privacy-masked session replay to diagnose problems.

You can change these choices at any time from Cookie settings.