> ## 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 company consumptions ## Overview Retrieves all confirmed transactions of a specific company for a specific payroll cycle. > **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 `payrollCycle.end` will be the current date. Otherwise, `payrollCycle.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" }, "employees": [ { "employeeId": "7f4c9ba8-9c2d-4b82-8b8c-e5f8f8f8f8f8", "internalId": "12345", "legalId": "129387655X", "consumptions": [ { "category": "meal-benefit", "behaviour": "flex", "sumType": "expenses", "amountInCents": 42001 }, { "category": "meal-benefit", "behaviour": "flex", "sumType": "withdrawn", "amountInCents": 2199 }, { "category": "meal-benefit", "behaviour": "flex-not-exempt", "sumType": "expenses", "amountInCents": 1599 }, { "category": "transport-benefit", "behaviour": "flex", "sumType": "expenses", "amountInCents": 13636 }, { "category": "nursery-benefit", "behaviour": "flex", "sumType": "expenses", "amountInCents": 77969 } ] } ] } } ``` ```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" }, "employees": [ { "employeeId": "7f4c9ba8-9c2d-4b82-8b8c-e5f8f8f8f8f8", "internalId": "12345", "legalId": "129387655X", "consumptions": [ { "category": "meal-benefit", "amountInCents": 45799 }, { "category": "transport-benefit", "amountInCents": 13636 }, { "category": "nursery-benefit", "amountInCents": 77969 } ] } ] } } ``` ```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" }, "employees": [ { "employeeId": "7f4c9ba8-9c2d-4b82-8b8c-e5f8f8f8f8f8", "internalId": "12345", "legalId": "129387655X", "consumptions": [ { "category": "meal-benefit", "behaviour": "flex", "amountInCents": 42001 }, { "category": "meal-benefit", "behaviour": "flex-not-exempt", "amountInCents": 1599 }, { "category": "nursery-benefit", "behaviour": "flex", "amountInCents": 77969 }, { "category": "transport-benefit", "behaviour": "flex", "amountInCents": 13636 } ] } ] } } ``` #### 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,amount.amountInCents a1b2c3d4-e5f6-7890-a1b2-c3d4e5f67890,B12345678,EUR,b2c3d4e5-f678-9012-a1b2-c3d4e5f67890,1753939051,1756616806,2025,8,7f4c9ba8-9c2d-4b82-8b8c-e5f8f8f8f8f8,12345,129387655X,meal-benefit,flex,expenses,42001 a1b2c3d4-e5f6-7890-a1b2-c3d4e5f67890,B12345678,EUR,b2c3d4e5-f678-9012-a1b2-c3d4e5f67890,1753939051,1756616806,2025,8,7f4c9ba8-9c2d-4b82-8b8c-e5f8f8f8f8f8,12345,129387655X,meal-benefit,flex,withdrawn,2199 a1b2c3d4-e5f6-7890-a1b2-c3d4e5f67890,B12345678,EUR,b2c3d4e5-f678-9012-a1b2-c3d4e5f67890,1753939051,1756616806,2025,8,7f4c9ba8-9c2d-4b82-8b8c-e5f8f8f8f8f8,12345,129387655X,meal-benefit,flex-not-exempt,expenses,1599 a1b2c3d4-e5f6-7890-a1b2-c3d4e5f67890,B12345678,EUR,b2c3d4e5-f678-9012-a1b2-c3d4e5f67890,1753939051,1756616806,2025,8,7f4c9ba8-9c2d-4b82-8b8c-e5f8f8f8f8f8,12345,129387655X,transport-benefit,flex,expenses,13636 a1b2c3d4-e5f6-7890-a1b2-c3d4e5f67890,B12345678,EUR,b2c3d4e5-f678-9012-a1b2-c3d4e5f67890,1753939051,1756616806,2025,8,7f4c9ba8-9c2d-4b82-8b8c-e5f8f8f8f8f8,12345,129387655X,nursery-benefit,flex,expenses,77969 ``` ```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,amount.amountInCents a1b2c3d4-e5f6-7890-a1b2-c3d4e5f67890,B12345678,EUR,b2c3d4e5-f678-9012-a1b2-c3d4e5f67890,1753939051,1756616806,2025,8,7f4c9ba8-9c2d-4b82-8b8c-e5f8f8f8f8f8,12345,129387655X,meal-benefit,45799 a1b2c3d4-e5f6-7890-a1b2-c3d4e5f67890,B12345678,EUR,b2c3d4e5-f678-9012-a1b2-c3d4e5f67890,1753939051,1756616806,2025,8,7f4c9ba8-9c2d-4b82-8b8c-e5f8f8f8f8f8,12345,129387655X,transport-benefit,13636 a1b2c3d4-e5f6-7890-a1b2-c3d4e5f67890,B12345678,EUR,b2c3d4e5-f678-9012-a1b2-c3d4e5f67890,1753939051,1756616806,2025,8,7f4c9ba8-9c2d-4b82-8b8c-e5f8f8f8f8f8,12345,129387655X,nursery-benefit,77969 ``` ```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,amount.amountInCents a1b2c3d4-e5f6-7890-a1b2-c3d4e5f67890,B12345678,EUR,b2c3d4e5-f678-9012-a1b2-c3d4e5f67890,1753939051,1756616806,2025,8,7f4c9ba8-9c2d-4b82-8b8c-e5f8f8f8f8f8,12345,129387655X,meal-benefit,flex,42001 a1b2c3d4-e5f6-7890-a1b2-c3d4e5f67890,B12345678,EUR,b2c3d4e5-f678-9012-a1b2-c3d4e5f67890,1753939051,1756616806,2025,8,7f4c9ba8-9c2d-4b82-8b8c-e5f8f8f8f8f8,12345,129387655X,meal-benefit,flex-not-exempt,1599 a1b2c3d4-e5f6-7890-a1b2-c3d4e5f67890,B12345678,EUR,b2c3d4e5-f678-9012-a1b2-c3d4e5f67890,1753939051,1756616806,2025,8,7f4c9ba8-9c2d-4b82-8b8c-e5f8f8f8f8f8,12345,129387655X,nursery-benefit,flex,77969 a1b2c3d4-e5f6-7890-a1b2-c3d4e5f67890,B12345678,EUR,b2c3d4e5-f678-9012-a1b2-c3d4e5f67890,1753939051,1756616806,2025,8,7f4c9ba8-9c2d-4b82-8b8c-e5f8f8f8f8f8,12345,129387655X,transport-benefit,flex,13636 ``` ```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,meal-benefit_flex-not-exempt_expenses,meal-benefit_flex-not-exempt_withdrawn,transport-benefit_flex_expenses,nursery-benefit_flex_expenses a1b2c3d4-e5f6-7890-a1b2-c3d4e5f67890,B12345678,EUR,b2c3d4e5-f678-9012-a1b2-c3d4e5f67890,1753939051,1756616806,2025,8,7f4c9ba8-9c2d-4b82-8b8c-e5f8f8f8f8f8,12345,129387655X,42001,2199,1599,0,13636,77969 ``` ```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,8,7f4c9ba8-9c2d-4b82-8b8c-e5f8f8f8f8f8,12345,129387655X,45799,13636,77969 ``` ```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,meal-benefit_flex-not-exempt,transport-benefit_flex,nursery-benefit_flex a1b2c3d4-e5f6-7890-a1b2-c3d4e5f67890,B12345678,EUR,b2c3d4e5-f678-9012-a1b2-c3d4e5f67890,1753939051,1756616806,2025,8,7f4c9ba8-9c2d-4b82-8b8c-e5f8f8f8f8f8,12345,129387655X,42001,1599,13636,77969 ``` ## OpenAPI ````yaml GET /companies/{companyId}/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}/consumptions: get: summary: Find all employee consumptions for a specific company parameters: - 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: companyId in: path required: true description: The unique identifier of the company schema: type: string format: uuid - name: payrollCycleId in: query required: false description: >- The unique identifier of the payroll cycle. If not provided, the open payroll cycle will be used. 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. - `lines`: as many lines as grouping benefits for each employee - `columns`: one line for each employee and as many columns as grouping 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: Company employees consumptions successfully retrieved content: application/json: schema: type: object required: - company properties: company: type: object required: - id - legalId - currency - payrollCycle - 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 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' employees: type: array description: List of employees items: type: object required: - employeeId - internalId - legalId - consumptions 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 example: company: id: a1b2c3d4-e5f6-7890-a1b2-c3d4e5f67890 legalId: B12345678 currency: EUR payrollCycle: id: 7f4c9ba8-9c2d-4b82-8b8c-e5f8f8f8f8f8 start: 1672531200 end: 1675123200 fiscalYear: '2023' payrollMonth: '03' employees: - employeeId: 7f4c9ba8-9c2d-4b82-8b8c-e5f8f8f8f8f8 internalId: '12345' legalId: 129387655X consumptions: - behaviour: allowance category: meal-benefit sumType: expenses amountInCents: 4500000 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 ````