> ## 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.
# List employee consumptions
## Overview
Retrieves all confirmed transactions of a specific employee for the current payroll cycle.
**Deprecated parameters**
The parameter `payrollCycleId` is deprecated. Please use the property `payroll` instead.
> **Important**: By default, consumptions are returned for the current (open) payroll cycle. To retrieve a previous cycle, provide it through payroll property.
> **Important**: The payload can be transformed depending on `categories` and `groupBy`. Choose the options that better suit your integration.
> **Important**: For `text/csv` we can select two formats through `csvFormat` options.
> When `lines` is selected, each row corresponds to a single consumption record.
> When `columns` is selected, each row corresponds to the total consumptions of an employee, and each consumption type is represented as a separate column.
> **Important**: if the requested payroll cycle is not closed yet, then the property `end` will be the current date. Otherwise, `end` will correspond to the last day of the cycle.
Example responses based on `csvFormat` and `categories`:
#### application/json
```json theme={null}
{
"company": {
"id": "a1b2c3d4-e5f6-7890-a1b2-c3d4e5f67890",
"legalId": "B12345678",
"currency": "EUR",
"payrollCycle": {
"id": "b2c3d4e5-f678-9012-a1b2-c3d4e5f67890",
"start": 1753939051,
"end": 1756616806,
"fiscalYear": "2025",
"payrollMonth": "08"
},
"employee": {
"employeeId": "c3d4e5f6-7890-1234-b2c3-d4e5f6789012",
"internalId": "1234",
"legalId": "51626739L",
"consumptions": [
{
"category": "meal-benefit",
"behaviour": "flex",
"sumType": "expenses",
"amountInCents": 22000
},
{
"category": "meal-benefit",
"behaviour": "flex",
"sumType": "withdrawn",
"amountInCents": 2199
},
{
"category": "transport-benefit",
"behaviour": "flex",
"sumType": "expenses",
"amountInCents": 13636
},
{
"category": "nursery-benefit",
"behaviour": "flex",
"sumType": "expenses",
"amountInCents": 24569
}
]
}
}
}
```
```json theme={null}
{
"company": {
"id": "a1b2c3d4-e5f6-7890-a1b2-c3d4e5f67890",
"legalId": "B12345678",
"currency": "EUR",
"payrollCycle": {
"id": "b2c3d4e5-f678-9012-a1b2-c3d4e5f67890",
"start": 1753939051,
"end": 1756616806,
"fiscalYear": "2025",
"payrollMonth": "08"
},
"employee": {
"employeeId": "c3d4e5f6-7890-1234-b2c3-d4e5f6789012",
"internalId": "1234",
"legalId": "51626739L",
"consumptions": [
{
"category": "meal-benefit",
"amountInCents": 19801
},
{
"category": "transport-benefit",
"amountInCents": 13636
},
{
"category": "nursery-benefit",
"amountInCents": 24569
}
]
}
}
}
```
```json theme={null}
{
"company": {
"id": "a1b2c3d4-e5f6-7890-a1b2-c3d4e5f67890",
"legalId": "B12345678",
"currency": "EUR",
"payrollCycle": {
"id": "b2c3d4e5-f678-9012-a1b2-c3d4e5f67890",
"start": 1753939051,
"end": 1756616806,
"fiscalYear": "2025",
"payrollMonth": "08"
},
"employee": {
"employeeId": "c3d4e5f6-7890-1234-b2c3-d4e5f6789012",
"internalId": "1234",
"legalId": "51626739L",
"consumptions": [
{
"category": "meal-benefit",
"behaviour": "flex",
"amountInCents": 19801
},
{
"category": "transport-benefit",
"behaviour": "flex",
"amountInCents": 13636
},
{
"category": "nursery-benefit",
"behaviour": "flex",
"amountInCents": 24569
}
]
}
}
}
```
#### text/csv
```csv theme={null}
company.id,company.legalId,company.currency,payrollCycle.id,payrollCycle.start,payrollCycle.end,payrollCycle.fiscalYear,payrollCycle.payrollMonth,employee.employeeId,employee.internalId,employee.legalId,category,behaviour,sumType,amountInCents
a1b2c3d4-e5f6-7890-a1b2-c3d4e5f67890,B12345678,EUR,b2c3d4e5-f678-9012-a1b2-c3d4e5f67890,1753939051,1756616806,2025,08,c3d4e5f6-7890-1234-b2c3-d4e5f6789012,1234,51626739L,meal-benefit,flex,expenses,22000
a1b2c3d4-e5f6-7890-a1b2-c3d4e5f67890,B12345678,EUR,b2c3d4e5-f678-9012-a1b2-c3d4e5f67890,1753939051,1756616806,2025,08,c3d4e5f6-7890-1234-b2c3-d4e5f6789012,1234,51626739L,meal-benefit,flex,withdrawn,2199
a1b2c3d4-e5f6-7890-a1b2-c3d4e5f67890,B12345678,EUR,b2c3d4e5-f678-9012-a1b2-c3d4e5f67890,1753939051,1756616806,2025,08,c3d4e5f6-7890-1234-b2c3-d4e5f6789012,1234,51626739L,transport-benefit,flex,expenses,13636
a1b2c3d4-e5f6-7890-a1b2-c3d4e5f67890,B12345678,EUR,b2c3d4e5-f678-9012-a1b2-c3d4e5f67890,1753939051,1756616806,2025,08,c3d4e5f6-7890-1234-b2c3-d4e5f6789012,1234,51626739L,nursery-benefit,flex,expenses,24569
```
```csv theme={null}
company.id,company.legalId,company.currency,payrollCycle.id,payrollCycle.start,payrollCycle.end,payrollCycle.fiscalYear,payrollCycle.payrollMonth,employee.employeeId,employee.internalId,employee.legalId,category,amountInCents
a1b2c3d4-e5f6-7890-a1b2-c3d4e5f67890,B12345678,EUR,b2c3d4e5-f678-9012-a1b2-c3d4e5f67890,1753939051,1756616806,2025,08,c3d4e5f6-7890-1234-b2c3-d4e5f6789012,1234,51626739L,meal-benefit,19801
a1b2c3d4-e5f6-7890-a1b2-c3d4e5f67890,B12345678,EUR,b2c3d4e5-f678-9012-a1b2-c3d4e5f67890,1753939051,1756616806,2025,08,c3d4e5f6-7890-1234-b2c3-d4e5f6789012,1234,51626739L,transport-benefit,13636
a1b2c3d4-e5f6-7890-a1b2-c3d4e5f67890,B12345678,EUR,b2c3d4e5-f678-9012-a1b2-c3d4e5f67890,1753939051,1756616806,2025,08,c3d4e5f6-7890-1234-b2c3-d4e5f6789012,1234,51626739L,nursery-benefit,24569
```
```csv theme={null}
company.id,company.legalId,company.currency,payrollCycle.id,payrollCycle.start,payrollCycle.end,payrollCycle.fiscalYear,payrollCycle.payrollMonth,employee.employeeId,employee.internalId,employee.legalId,category,behaviour,amountInCents
a1b2c3d4-e5f6-7890-a1b2-c3d4e5f67890,B12345678,EUR,b2c3d4e5-f678-9012-a1b2-c3d4e5f67890,1753939051,1756616806,2025,08,c3d4e5f6-7890-1234-b2c3-d4e5f6789012,1234,51626739L,meal-benefit,flex,19801
a1b2c3d4-e5f6-7890-a1b2-c3d4e5f67890,B12345678,EUR,b2c3d4e5-f678-9012-a1b2-c3d4e5f67890,1753939051,1756616806,2025,08,c3d4e5f6-7890-1234-b2c3-d4e5f6789012,1234,51626739L,transport-benefit,flex,13636
a1b2c3d4-e5f6-7890-a1b2-c3d4e5f67890,B12345678,EUR,b2c3d4e5-f678-9012-a1b2-c3d4e5f67890,1753939051,1756616806,2025,08,c3d4e5f6-7890-1234-b2c3-d4e5f6789012,1234,51626739L,nursery-benefit,flex,24569
```
```csv theme={null}
company.id,company.legalId,company.currency,payrollCycle.id,payrollCycle.start,payrollCycle.end,payrollCycle.fiscalYear,payrollCycle.payrollMonth,employee.employeeId,employee.internalId,employee.legalId,meal-benefit_flex_expenses,meal-benefit_flex_withdrawn,transport-benefit_flex_expenses,nursery-benefit_flex_expenses
a1b2c3d4-e5f6-7890-a1b2-c3d4e5f67890,B12345678,EUR,b2c3d4e5-f678-9012-a1b2-c3d4e5f67890,1753939051,1756616806,2025,08,c3d4e5f6-7890-1234-b2c3-d4e5f6789012,1234,51626739L,22000,2199,13636,24569
```
```csv theme={null}
company.id,company.legalId,company.currency,payrollCycle.id,payrollCycle.start,payrollCycle.end,payrollCycle.fiscalYear,payrollCycle.payrollMonth,employee.employeeId,employee.internalId,employee.legalId,meal-benefit,transport-benefit,nursery-benefit
a1b2c3d4-e5f6-7890-a1b2-c3d4e5f67890,B12345678,EUR,b2c3d4e5-f678-9012-a1b2-c3d4e5f67890,1753939051,1756616806,2025,08,c3d4e5f6-7890-1234-b2c3-d4e5f6789012,1234,51626739L,19801,13636,24569
```
```csv theme={null}
company.id,company.legalId,company.currency,payrollCycle.id,payrollCycle.start,payrollCycle.end,payrollCycle.fiscalYear,payrollCycle.payrollMonth,employee.employeeId,employee.internalId,employee.legalId,meal-benefit_flex,transport-benefit_flex,nursery-benefit_flex
a1b2c3d4-e5f6-7890-a1b2-c3d4e5f67890,B12345678,EUR,b2c3d4e5-f678-9012-a1b2-c3d4e5f67890,1753939051,1756616806,2025,08,c3d4e5f6-7890-1234-b2c3-d4e5f6789012,1234,51626739L,19801,13636,24569
```
## OpenAPI
````yaml GET /companies/{companyId}/employees/{employeeId}/consumptions
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:
/companies/{companyId}/employees/{employeeId}/consumptions:
get:
summary: Find employee consumptions
parameters:
- name: companyId
in: path
required: true
description: The unique identifier of the company
schema:
type: string
format: uuid
example: a1b2c3d4-e5f6-7890-a1b2-c3d4e5f67890
- name: employeeId
in: path
required: true
description: The unique identifier of the employee
schema:
type: string
- name: Accept
in: header
required: false
description: The response file type. It can be `application/json` or `text/csv`.
schema:
type: string
enum:
- application/json
- text/csv
- name: payrollCycleId
in: query
required: false
description: >-
The unique identifier of the payroll cycle. If not provided, the
open payroll cycle will be used. This parameter is deprecated, use
`payroll` instead.
deprecated: true
schema:
type: string
format: uuid
- name: payroll
in: query
required: false
description: >-
The fiscal year and month (YYYY-MM) of the payroll cycle the
consumptions belong to (e.g. `2025-03`).
schema:
type: string
pattern: ^[0-9]{4}-(0[1-9]|1[0-2])$
example: 2025-03
- name: csvFormat
in: query
required: false
description: >-
The format of the resulting consumptions request. Lines: as many
lines as benefits for each employee, Columns: one line for each
employee and as many columns as benefits
schema:
type: string
enum:
- lines
- columns
- name: categories
in: query
required: false
description: >-
List of benefit categories to include in the response, which will
return them in the same order as requested.
schema:
type: string
- name: groupBy
in: query
required: false
description: >-
Consumptions can be grouped to return data that is more similar to
how your system works. The consumptions can be grouped by:
- `category`: it will calculate the sum of expenses minus withdrawals for all the consumptions in a category,
- `category,behaviour`: sum of all expenses minus withdrawals for all the consumptions in category and behaviour.
schema:
type: string
responses:
'200':
description: Employee consumptions successfully retrieved
content:
application/json:
schema:
type: object
required:
- company
properties:
company:
type: object
required:
- id
- legalId
- currency
- payrollCycle
- employee
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
payrollCycle:
type: object
required:
- id
- start
- end
- fiscalYear
- payrollMonth
properties:
id:
type: string
description: The unique identifier of the payroll cycle.
format: uuid
example: 7f4c9ba8-9c2d-4b82-8b8c-e5f8f8f8f8f8
start:
type: integer
description: >-
The start date for the payroll cycle, in timestamp
format.
format: timestamp
example: 1672531200
end:
type: integer
nullable: true
description: >-
The end date for the payroll cycle, in timestamp
format. A Null value is returned if the cycle is
currently open.
example: 1675123200
fiscalYear:
type: string
description: The fiscal year of the payroll cycle.
example: '2023'
payrollMonth:
type: string
description: >-
The month of the payroll cycle in MM format (e.g.,
'03' for March).
pattern: ^[0-9]{2}$
example: '03'
employee:
type: object
description: Employee
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
consumptions:
type: array
description: List of employee consumptions
items:
type: object
required:
- behaviour
- category
- sumType
- amountInCents
properties:
behaviour:
type: string
description: The behaviour type of the consumption
enum:
- allowance
- allowance-not-exempt
- flex
- flex-not-exempt
example: allowance
category:
type: string
description: The category of the consumption
enum:
- any
- capitalization-benefit
- claps-benefit
- education-benefit
- gym-benefit
- health-insurance-benefit
- home-office-benefit
- individual-capitalization-benefit
- it-product-benefit
- life-insurance-benefit
- meal-benefit
- nursery-benefit
- pension-plan-benefit
- renting-benefit
- retirement-insurance-benefit
- transport-benefit
- unknown
- wellness-benefit
example: meal-benefit
sumType:
type: string
description: The sum type of the consumption
enum:
- expenses
- withdrawn
example: expenses
amountInCents:
type: integer
description: >-
The monetary amount in cents (e.g., 4500000
for 45,000)
minimum: 0
text/csv:
schema:
type: string
format: binary
'404':
description: Not Found - The employee, company, or payroll cycle 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
````