List Workforce Employees
const options = {
method: 'GET',
headers: {'x-api-key': '<x-api-key>', 'x-organization-id': '<x-organization-id>'}
};
fetch('https://api.dcycle.io/v1/own_workforces', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));import requests
url = "https://api.dcycle.io/v1/own_workforces"
headers = {
"x-api-key": "<x-api-key>",
"x-organization-id": "<x-organization-id>"
}
response = requests.get(url, headers=headers)
print(response.text)curl --request GET \
--url https://api.dcycle.io/v1/own_workforces \
--header 'x-api-key: <x-api-key>' \
--header 'x-organization-id: <x-organization-id>'{
"items": {
"id": "<string>",
"external_employee_id": "<string>",
"employment_category": "<string>",
"location_code": "<string>",
"nationality": {},
"contract_start_date": "<string>",
"contract_end_date": {},
"created_at": {},
"file_id": {},
"file_name": {},
"processing_job_id": {},
"status": {},
"organization_id": {},
"organization_name": {},
"organization_logo_url": {}
},
"total": 123,
"page": 123,
"size": 123,
"filter_hash": {}
}List Workforce Employees
Retrieve a paginated list of own workforce employees with their current contract summary
GET
/
v1
/
own_workforces
List Workforce Employees
const options = {
method: 'GET',
headers: {'x-api-key': '<x-api-key>', 'x-organization-id': '<x-organization-id>'}
};
fetch('https://api.dcycle.io/v1/own_workforces', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));import requests
url = "https://api.dcycle.io/v1/own_workforces"
headers = {
"x-api-key": "<x-api-key>",
"x-organization-id": "<x-organization-id>"
}
response = requests.get(url, headers=headers)
print(response.text)curl --request GET \
--url https://api.dcycle.io/v1/own_workforces \
--header 'x-api-key: <x-api-key>' \
--header 'x-organization-id: <x-organization-id>'{
"items": {
"id": "<string>",
"external_employee_id": "<string>",
"employment_category": "<string>",
"location_code": "<string>",
"nationality": {},
"contract_start_date": "<string>",
"contract_end_date": {},
"created_at": {},
"file_id": {},
"file_name": {},
"processing_job_id": {},
"status": {},
"organization_id": {},
"organization_name": {},
"organization_logo_url": {}
},
"total": 123,
"page": 123,
"size": 123,
"filter_hash": {}
}← Own Workforce API
Retrieve a paginated list of employee records. Each item is one person, flattened with the dates and category of the contract that represents them in the listing.
Request
Headers
string
required
Your API key for authenticationExample:
sk_live_1234567890abcdefstring
required
Your organization UUIDExample:
a8315ef3-dd50-43f8-b7ce-d839e68d51faQuery Parameters
integer
default:"1"
Page number, starting at 1
integer
default:"50"
Page size, between 1 and 100
string
Search by the employee identifier your own HR system usesExample:
external_employee_id=EMP-2024-001array[string]
Filter by the source upload file. Repeat the parameter for several files.Pass the nil UUID
00000000-0000-0000-0000-000000000000 to match rows that came from no file — that is, rows with a null file_id.Example: file_id[]=9f1c7f2a-64a1-4b2c-9d3e-70a5b8c1d2e3datetime
Only rows created at or after this instantFormat: ISO 8601 —
2026-01-01T00:00:00datetime
Only rows created at or before this instantFormat: ISO 8601 —
2026-12-31T23:59:59boolean
default:"false"
Group view.
false returns the header organization only. true widens the list to the header organization’s accepted business family — itself plus its accepted, enabled descendants.array[string]
Restrict a group-view list to these organizations, intersected with the family resolved above. Only meaningful together with
consolidate_group=true.Example: organization_id[]=a8315ef3-dd50-43f8-b7ce-d839e68d51fastring
Scope the list to a project’s reporting perimeter. Only applied together with
scope_to_project_organizations=true.boolean
default:"false"
When
true, narrow the perimeter to the organizations attached to project_id instead of the whole group tree.Response
array[object]
Show employee
Show employee
string
Employee UUID
string
The identifier from your HR system. Unique per organization, so the same value can exist in two organizations of the same group.
string
Free-text job category as uploaded, e.g.
Engineerstring
Name of the contract’s work location. On this endpoint it is the location name; the contract detail endpoint returns the country name in the field of the same name.
string | null
Employee nationality, null when it was not provided
string
Contract start,
YYYY-MM-DDstring | null
Contract end,
YYYY-MM-DD. Null means open-ended.string | null
When the row was ingested
string | null
Source upload file, null for rows not created from a file
string | null
Name of that file
string | null
Ingestion job that produced the row
string | null
Ingestion status of the row
string | null
Owning organization. Populated on group-view responses.
string | null
Owning organization name. Group view only.
string | null
Owning organization logo. Group view only.
integer
Number of rows matching the filters, across all pages
integer
Current page
integer
Current page size
string | null
Fingerprint of the filters that produced this page. Pass it to Bulk Delete Workforce Employees by Filters to prove you are deleting exactly what you listed — if the filters changed in between, that call fails instead of deleting a wider set.
Every date field in this response is typed as a string, not a date, including
contract_start_date and created_at. Parse accordingly.Example
curl -X GET "https://api.dcycle.io/v1/own_workforces?page=1&size=50&created_at_from=2026-01-01T00:00:00" \
-H "x-api-key: ${DCYCLE_API_KEY}" \
-H "x-organization-id: ${DCYCLE_ORG_ID}"
import os
import requests
headers = {
"x-api-key": os.getenv("DCYCLE_API_KEY"),
"x-organization-id": os.getenv("DCYCLE_ORG_ID"),
}
params = {"page": 1, "size": 50, "created_at_from": "2026-01-01T00:00:00"}
response = requests.get(
"https://api.dcycle.io/v1/own_workforces",
headers=headers,
params=params,
)
result = response.json()
print(f"{result['total']} employees")
for employee in result["items"]:
print(f"{employee['external_employee_id']}: {employee['employment_category']} ({employee['location_code']})")
const axios = require('axios');
const headers = {
'x-api-key': process.env.DCYCLE_API_KEY,
'x-organization-id': process.env.DCYCLE_ORG_ID
};
axios.get('https://api.dcycle.io/v1/own_workforces', {
headers,
params: { page: 1, size: 50, created_at_from: '2026-01-01T00:00:00' }
})
.then(response => {
console.log(`${response.data.total} employees`);
response.data.items.forEach(employee => {
console.log(`${employee.external_employee_id}: ${employee.employment_category} (${employee.location_code})`);
});
})
.catch(error => console.error(error));
Successful Response
{
"items": [
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"external_employee_id": "EMP-2024-001",
"employment_category": "Engineer",
"location_code": "Spain",
"nationality": "Spain",
"contract_start_date": "2023-06-01",
"contract_end_date": null,
"created_at": "2026-02-15T09:30:00",
"file_id": "9f1c7f2a-64a1-4b2c-9d3e-70a5b8c1d2e3",
"processing_job_id": "c2a7b81e-3f55-4c0b-9a6d-1e2f3a4b5c6d",
"file_name": "workforce_2026.csv",
"status": "active",
"organization_id": null,
"organization_name": null,
"organization_logo_url": null
}
],
"total": 145,
"page": 1,
"size": 50,
"filter_hash": "b6d1f0c47a9e2d38"
}
Common Errors
401 Unauthorized
Cause: the key is invalid, or it does not belong to the organization inx-organization-id — the two are looked up as a pair. A request carrying no credentials at all answers AUTH_REQUIRED instead.
{
"detail": "Invalid API key for organization",
"code": "INVALID_API_KEY"
}
403 Forbidden
Cause: the key’s owner is not an enabled member of the organization inx-organization-id.
{
"detail": "Logged User is not Member of Organization",
"code": "LOGGED_USER_NOT_MEMBER"
}
400 Bad Request
Cause:x-organization-id absent while authenticating with an API key. It is the first error a new integration hits, and it is a 400 rather than a 422 because the header is read inside the auth dependency.
{
"detail": "x-organization-id header required when using API key authentication",
"code": "ORGANIZATION_ID_REQUIRED"
}
422 Unprocessable Entity
Cause: a malformed query parameter. Authentication is resolved first — the router-level dependency runs before the endpoint’s own parameters are validated — so a request that is both unauthenticated and malformed answers 401, not 422.{
"detail": [
{
"type": "uuid_parsing",
"loc": ["query", "file_id[]", 0],
"msg": "Input should be a valid UUID"
}
]
}
Related Endpoints
Get employee
A single employee by id
Unique values
Build the file filter for this list
Employees with contracts
Employees, contracts and remuneration periods in one call
Bulk delete by filters
Delete exactly what this list returned
Was this page helpful?