> ## Documentation Index
> Fetch the complete documentation index at: https://code.dcycle.io/llms.txt
> Use this file to discover all available pages before exploring further.

# List Workforce Remunerations

> Retrieve the salary records attached to one workforce contract, with amount and currency

[← Own Workforce API](/api-reference/own-workforce/overview)

Return the remuneration records of one contract: how much, in which currency, and over which period. This is the only endpoint that exposes **individual salary amounts**.

<Warning>
  Individual pay is among the most sensitive data in the product. Restrict the API keys that can reach this endpoint, and do not write responses to shared logs or caches.
</Warning>

<Note>
  There is no organization-wide salary list. Reading every salary means walking employees → contracts → remunerations, one request per contract. If you want totals, averages or the **gender pay gap**, do not walk this tree: query the `own_workforce_remuneration` dataset through [Query datasets](/api-reference/datasets/query), which computes them server-side and segments by gender, country, nationality, job category and age.
</Note>

## Request

### Headers

<ParamField header="x-api-key" type="string" required>
  Your API key for authentication

  **Example:** `sk_live_1234567890abcdef`
</ParamField>

<ParamField header="x-organization-id" type="string" required>
  Your organization UUID

  **Example:** `a8315ef3-dd50-43f8-b7ce-d839e68d51fa`
</ParamField>

### Query Parameters

<ParamField query="own_workforce_contract_id" type="string" required>
  Contract UUID, from [List Workforce Contracts](/api-reference/own-workforce/list-contracts)

  **Example:** `own_workforce_contract_id=7c9e6679-7425-40de-944b-e07fc1f90ae7`
</ParamField>

## Response

A bare JSON array of remuneration records.

<ResponseField name="id" type="string">
  Remuneration UUID
</ResponseField>

<ResponseField name="start_date" type="string">
  First day the amount applies, `YYYY-MM-DD`
</ResponseField>

<ResponseField name="end_date" type="string | null">
  Last day it applies. Null means it is still current.
</ResponseField>

<ResponseField name="amount" type="number">
  The remuneration figure, as uploaded. It is an **annual** figure in the reporting model — there is no periodicity field to say otherwise.
</ResponseField>

<ResponseField name="unit" type="string">
  Currency, resolved to its unit name — for example `euros_(eur)`, `us_dollar_(usd)`, `mexican_peso_(mxn)`. Amounts are **not** converted to a common currency, so do not sum across records without converting first.
</ResponseField>

## Example

<CodeGroup>
  ```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}}
  curl -X GET "https://api.dcycle.io/v1/own_workforce_remunerations?own_workforce_contract_id=7c9e6679-7425-40de-944b-e07fc1f90ae7" \
    -H "x-api-key: ${DCYCLE_API_KEY}" \
    -H "x-organization-id: ${DCYCLE_ORG_ID}"
  ```

  ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
  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_workforce_remunerations",
      headers=headers,
      params={"own_workforce_contract_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7"},
  )

  records = response.json()
  # Do not print individual pay. Aggregate, or carry the values straight to their destination.
  print(f"{len(records)} remuneration periods on this contract")
  ```

  ```javascript JavaScript theme={"theme":{"light":"github-light","dark":"github-dark"}}
  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_workforce_remunerations', {
    headers,
    params: { own_workforce_contract_id: '7c9e6679-7425-40de-944b-e07fc1f90ae7' }
  })
  .then(response => {
    // Do not log individual pay. Aggregate, or carry the values straight to their destination.
    console.log(`${response.data.length} remuneration periods on this contract`);
  })
  .catch(error => console.error(error));
  ```
</CodeGroup>

### Successful Response

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
[
  {
    "id": "b1e2d3c4-5f60-4a71-8b92-0c1d2e3f4a5b",
    "start_date": "2023-06-01",
    "end_date": "2024-12-31",
    "amount": 42000.0,
    "unit": "euros_(eur)"
  },
  {
    "id": "c2f3e4d5-6071-4b82-9ca3-1d2e3f4a5b6c",
    "start_date": "2025-01-01",
    "end_date": null,
    "amount": 45500.0,
    "unit": "euros_(eur)"
  }
]
```

## Common Errors

### 401 Unauthorized

**Cause:** the key is invalid, or it does not belong to the organization in `x-organization-id` — the two are looked up as a pair. A request carrying no credentials at all answers `AUTH_REQUIRED` instead.

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "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 in `x-organization-id`.

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "detail": "Logged User is not Member of Organization",
  "code": "LOGGED_USER_NOT_MEMBER"
}
```

### 404 Not Found

**Cause:** no contract with that id inside your perimeter. The contract is resolved through its employee to an organization, so another tenant's salaries are a 404 rather than a readable list.

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "code": "NOT_FOUND",
  "detail": "OwnWorkforceContractModel with id='550e8400-e29b-41d4-a716-446655440000' not found"
}
```

### 422 Unprocessable Entity

**Cause:** `own_workforce_contract_id` missing or not a UUID.

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "detail": [
    {
      "type": "missing",
      "loc": ["query", "own_workforce_contract_id"],
      "msg": "Field required"
    }
  ]
}
```

## Related Endpoints

<CardGroup cols={2}>
  <Card title="List contracts" icon="file-signature" href="/api-reference/own-workforce/list-contracts">
    Where the contract id comes from
  </Card>

  <Card title="Query datasets" icon="chart-simple" href="/api-reference/datasets/query">
    Averages and the gender pay gap, computed server-side
  </Card>
</CardGroup>