List all employees
Scope: team:employees.read https://api.alladdin.com/api/v2/employees
Returns a paginated list of employees.
Results are paginated with limit and cursor parameters. Default page size is 50, configurable up to 200.
When resolving an employee the user named, match against BOTH first name and surname, accent- and case-insensitively, and gather ALL matches — never stop at the first result. If more than one employee matches, present the complete list of matches (name plus email or employee code) and let the user choose; never pick one on your own.
Parameters
Query parameters
search string optional
Server-side free-text filter over name, surname, email and code, ignoring case and accents (e.g. "pablo diaz" matches "Pablo Díaz"). ALWAYS use this parameter to resolve an employee the user named — pass the user's exact text. Do NOT filter by name yourself client-side (jmespath/contains): that only sees the current page and cannot fold accents, so it misses matches and picks the wrong person. This search scans ALL employees and returns every match; if more than one comes back, present them and let the user choose.
cursor string optional
Pagination cursor returned by the previous response. Omit to start from the first page.
limit integer optional = 50
Maximum number of items to return
Request
import requests
url = "https://api.alladdin.com/api/v2/employees?search=value&cursor=value&limit=50"
headers = {
"Authorization": "Bearer YOUR_API_KEY",
"Accept": "application/json",
}
response = requests.get(url, headers=headers)
print(response.json())Responses
Response
{
"items": [
{
"id": "507f1f77bcf86cd799439011",
"alladdin_user_id": "string",
"name": "string",
"last_name": "string",
"full_name": "string",
"date_of_birth": "string",
"nationality": "string",
"social_security_number": "string",
"academic_level": "string",
"languages": [
"string"
],
"main_language": "string",
"code": "string",
"gender": "string",
"email": "string",
"secondary_email": "string",
"phone": "string",
"mobile": "string",
"address": {
"address": "string",
"city": "string",
"postal_code": "string",
"province": "string",
"country": "string"
},
"team_ids": [
"string"
],
"workplace_id": "string",
"iban": "string",
"notes": "string",
"current_contract": {
"id": "string",
"type": "string",
"start_date": "2024-01-15",
"end_date": "2024-01-15",
"job_title": "string",
"schedule_hours": 0,
"schedule_mode": "string",
"working_days": [
"..."
],
"salary": "30000.00",
"salary_interval": "string",
"salary_payments": 0,
"salary_extra": [
"..."
]
},
"reporting_to": "string",
"time_off_supervisors": [
"string"
],
"time_off_policy_id": "string",
"terminated": 0,
"terminated_type": "string",
"terminated_reason": "string",
"fiscal_residence": false,
"fiscal_address": {
"id_number": "string",
"address": "string",
"city": "string",
"postal_code": "string",
"province": "string",
"country": "string",
"deadline": "string",
"city_of_birth": "string",
"country_of_birth": "string"
},
"job_title": "string",
"tags": [
"string"
],
"company_phone": "string",
"custom_fields": [
{}
],
"payroll_accounts": {
"es_nomina": {
"salary": "507f1f77bcf86cd799439012",
"tax": null,
"companytax": null,
"retention": null,
"result": "507f1f77bcf86cd799439013"
}
}
}
],
"has_more": false,
"cursor": "string"
}Success responses
200 List of employees application/json object items[] object[] required id string required
Unique identifier
alladdin_user_id string | null required
Linked Alladdin user ID
name string required
First name
last_name string required
Last name
full_name string required
Full name (first name + last name). Use this field to search or filter employees by name.
date_of_birth string | null required
Date of birth
nationality string required
Nationality code
social_security_number string required
Social security number
academic_level string required
Academic level
languages[] string[] required
Languages spoken
main_language string required
Main language code
code string required
Employee code
gender string required
Gender
email string required
Primary email
secondary_email string required
Secondary email
phone string | null required
Phone number
mobile string | null required
Mobile number
address object required
Employee address
team_ids[] string[] required
Team IDs
workplace_id string required
Workplace ID
iban string required
IBAN
notes string required
Notes
current_contract object | null required
Current employment contract
reporting_to string | null required
Reporting-to employee ID
time_off_supervisors[] string[] required
Time-off supervisor IDs
time_off_policy_id string | null required
Time-off policy ID
terminated integer | null required
Termination timestamp
terminated_type string | null required
Termination type
terminated_reason string | null required
Termination reason
fiscal_residence boolean | null required
Fiscal residence flag
fiscal_address object required
Fiscal address for tax purposes
job_title string required
Job title
tags[] string[] required
Tags
company_phone string required
Company phone
custom_fields[] object[] required
Custom fields
payroll_accounts object required
Per-scheme payroll accounting account IDs, empty when none are configured. Keys are scheme identifiers; each maps line types (salary, tax, companytax, retention, result) to accounting account IDs. The result account is the top-level accounting_account_id for a salary record. When populated, takes precedence over the salary-record form data defaults.
has_more boolean required
Whether there are more items on the next page
cursor string | null optional
Opaque cursor to pass as ?cursor= to fetch the next page. Null on the last page.
Error responses
401 Invalid or missing API key application/json 403 Insufficient permissions application/json 429 Rate limit exceeded application/json