> ## Documentation Index > Fetch the complete documentation index at: https://docs.partners.api.cobee.io/llms.txt > Use this file to discover all available pages before exploring further. # [DRAFT] Find committed expenses > Retrieves the committed expenses of an employee or of a whole company, grouped by fiscal year and benefit. Provide exactly one of `employee` or `company`. **Coming soon**: this endpoint is still under review and may change before release. ## Overview Retrieves the committed expenses — amounts an employee has committed to spend over several payroll cycles (for example, nursery) — either for a single employee (`?employee={id}`) or for a whole company (`?company={id}`). Provide exactly one of the two. Results are grouped **by fiscal year and benefit** (for example, "300 € committed in nursery for 2026"). You can optionally narrow the results to a single `fiscalYear`. > **Important**: use this endpoint to know how much an employee has committed so you can adjust their limits. Committed expenses count against the employee's flexible-benefit limit from the moment they are committed. Nursery has an annual limit, so its committed expenses are reported per fiscal year. > **Important**: each individual monthly charge of a committed expense is charged at the start of its payroll cycle and is reported as a regular consumption by the consumptions endpoints and by the `employee.consumption.registered` webhook event. This endpoint reports the **committed expense itself**: the total committed and how much is still pending. > **Important**: the `employee.committed-expense.*` and `employee.committed-expense.payment.*` [webhook events](/en/api-reference/webhooks/events) notify you when a committed expense is **requested**, **finished**, or **cancelled** (as a whole or one payment at a time). Like every other webhook, they only identify what changed — call this endpoint after receiving one to get the current `committedAmountInCents` / `pendingAmountInCents` and compute the employee's remaining limit. > **Important**: `recipient` identifies the person the committed expense applies to when that person is different from the employee. It is omitted when the committed expense applies directly to the employee, so the employee's identifier is not duplicated. When present, `recipient.id` contains the dependent's identifier. ## OpenAPI ````yaml GET /committed-expenses openapi: 3.0.1 info: title: Partners API description: >- Partners API definition where you can check the documentation for the different available operations to integrate with the platform. license: name: MIT version: 1.0.0 servers: - url: https://pre-partners-api.cobee.io/api/v3 - url: https://partners-api.cobee.io/api/v3 security: - bearerAuth: [] paths: /committed-expenses: get: summary: List committed expenses description: >- Retrieves the committed expenses of an employee or of a whole company, grouped by fiscal year and benefit. Provide exactly one of `employee` or `company`. parameters: - name: employeeId in: query required: false description: >- The unique identifier of the employee. Provide either `employee` or `company`, not both. schema: type: string format: uuid example: dd3de3a0-f903-42a0-b729-4cb16f185bc6 - name: companyId in: query required: false description: >- The unique identifier of the company. Provide either `employee` or `company`, not both. schema: type: string format: uuid example: a1b2c3d4-e5f6-7890-a1b2-c3d4e5f67890 - name: fiscalYear in: query required: false description: >- Restrict the results to a single fiscal year (e.g. `2026`). If not provided, all fiscal years with committed expenses are returned. schema: type: string pattern: ^[0-9]{4}$ example: '2026' responses: '200': description: >- Committed expenses successfully retrieved. The response is scoped to an employee or to a company depending on the filter used. content: application/json: schema: type: object required: - company properties: company: type: object required: - id - legalId - currency - employees properties: id: type: string description: The unique identifier of the company. format: uuid example: a1b2c3d4-e5f6-7890-a1b2-c3d4e5f67890 legalId: type: string description: The company's legal id example: B12345678 currency: type: string description: The currency code (e.g., EUR) example: EUR employees: type: array description: Employees with committed expenses in this company items: type: object required: - employeeId - internalId - legalId - committedExpenses properties: employeeId: type: string format: uuid description: The unique identifier of the employee example: dd3de3a0-f903-42a0-b729-4cb16f185bc6 internalId: type: string description: >- The unique identifier of the employee in the client's system example: '12345' legalId: type: string description: The employee's legal id example: 129387655X committedExpenses: type: array description: >- Committed expenses grouped by fiscal year and benefit category. items: type: object required: - id - fiscalYear - category - committedAmountInCents - paidAmountInCents - numberOfPayments properties: id: type: string format: uuid description: >- The unique identifier of the committed expense. example: dd3de3a0-f903-42a0-b729-4cb16f185bc6 fiscalYear: type: string description: >- The fiscal year the committed expense belongs to. example: '2026' category: type: string description: >- The benefit category of the committed expense. enum: - nursery-benefit example: nursery-benefit recipient: type: object description: >- The person the committed expense applies to when different from the employee. Omitted when the committed expense applies directly to the employee, so the employee's identifier is not duplicated. required: - id properties: id: type: string format: uuid description: The unique identifier of the dependent. example: 8a1b2c3d-4e5f-6789-a0b1-c2d3e4f56789 committedAmountInCents: type: integer description: >- Total amount committed for this benefit and fiscal year, in cents (e.g., 30000 for 300.00). minimum: 0 example: 30000 paidAmountInCents: type: integer description: >- Amount already paid/charged for this committed expense, in cents. minimum: 0 example: 10000 numberOfPayments: type: integer description: >- Total number of monthly payments the committed expense is split into. minimum: 1 example: 3 pendingPayments: type: integer description: >- Number of monthly payments not yet charged. Cancelled committed expenses will never charge these. minimum: 0 example: 2 '400': description: >- Bad Request - Neither or both of `employee` and `company` were provided content: application/json: schema: $ref: '#/components/schemas/Error' example: message: Provide exactly one of employee or company '404': description: Not Found - The employee or company was not found content: application/json: schema: $ref: '#/components/schemas/Error' example: message: Resource not found '500': description: Internal Server Error - Something went wrong on our end content: application/json: schema: $ref: '#/components/schemas/Error' example: message: Internal server error components: schemas: Error: required: - error - message type: object properties: error: type: integer format: int32 message: type: string example: message: 'Bad request: Invalid field value' securitySchemes: bearerAuth: type: http scheme: bearer ````