List Workforce Employees With Contracts
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/with-contracts-and-remunerations', 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/with-contracts-and-remunerations"
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/with-contracts-and-remunerations \
--header 'x-api-key: <x-api-key>' \
--header 'x-organization-id: <x-organization-id>'{
"items": {
"external_employee_id": "<string>",
"organization_id": "<string>",
"gender": "<string>",
"disabled_employee": "<string>",
"birth_date": "<string>",
"contracts": {
"start_date": "<string>",
"end_date": {},
"remunerations": {
"start_date": "<string>",
"end_date": {}
}
}
}
}List Workforce Employees With Contracts
Retrieve every employee with their contracts and remuneration periods nested in one response
GET
/
v1
/
own_workforces
/
with-contracts-and-remunerations
List Workforce Employees With Contracts
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/with-contracts-and-remunerations', 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/with-contracts-and-remunerations"
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/with-contracts-and-remunerations \
--header 'x-api-key: <x-api-key>' \
--header 'x-organization-id: <x-organization-id>'{
"items": {
"external_employee_id": "<string>",
"organization_id": "<string>",
"gender": "<string>",
"disabled_employee": "<string>",
"birth_date": "<string>",
"contracts": {
"start_date": "<string>",
"end_date": {},
"remunerations": {
"start_date": "<string>",
"end_date": {}
}
}
}
}← Own Workforce API
Return every employee of the organization tree with their contracts nested inside, and each contract’s remuneration periods nested inside that. One call instead of walking employee → contracts → remunerations.
Note that the employee objects here carry no
This endpoint does not paginate and takes no filters. It walks the header organization and its descendants and returns every employee, every contract and every remuneration period in a single response. For an organization with thousands of employees that payload is large and the request is slow. Use List Workforce Employees when you can page, and this one only when you genuinely need the whole nested tree.
Remuneration amounts are not included here. The nested remuneration objects carry only
start_date and end_date, so this endpoint tells you when someone was paid on a given band, not how much. For amounts and currency, call List Workforce Remunerations per contract, or read the aggregates from Query datasets.Request
Headers
string
required
Your API key for authenticationExample:
sk_live_1234567890abcdefstring
required
Your organization UUIDExample:
a8315ef3-dd50-43f8-b7ce-d839e68d51faResponse
array[object]
Show employee
Show employee
string
The identifier from your HR system
string
Owning organization — always present here, so you can tell subsidiaries apart
string
M, F, O or NSstring
no_disability, with_disability, disability_33 or disability_65string
YYYY-MM-DDid: they are keyed by external_employee_id within their organization. To address an employee on the other endpoints, resolve the UUID through List Workforce Employees.
Example
curl -X GET "https://api.dcycle.io/v1/own_workforces/with-contracts-and-remunerations" \
-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"),
}
response = requests.get(
"https://api.dcycle.io/v1/own_workforces/with-contracts-and-remunerations",
headers=headers,
timeout=120,
)
for employee in response.json()["items"]:
spans = sum(len(contract["remunerations"]) for contract in employee["contracts"])
print(f"{employee['external_employee_id']}: {len(employee['contracts'])} contracts, {spans} pay periods")
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/with-contracts-and-remunerations', {
headers,
timeout: 120000
})
.then(response => {
response.data.items.forEach(employee => {
const spans = employee.contracts.reduce((n, c) => n + c.remunerations.length, 0);
console.log(`${employee.external_employee_id}: ${employee.contracts.length} contracts, ${spans} pay periods`);
});
})
.catch(error => console.error(error));
Successful Response
{
"items": [
{
"external_employee_id": "EMP-2024-001",
"organization_id": "a8315ef3-dd50-43f8-b7ce-d839e68d51fa",
"gender": "F",
"disabled_employee": "no_disability",
"birth_date": "1990-01-01",
"contracts": [
{
"start_date": "2023-06-01",
"end_date": null,
"remunerations": [
{ "start_date": "2023-06-01", "end_date": "2024-12-31" },
{ "start_date": "2025-01-01", "end_date": null }
]
}
]
}
]
}
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"
}
Related Endpoints
List employees
The paginated, filterable alternative
List remunerations
Amounts and currency, per contract
Was this page helpful?