> ## 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 corporation consumptions ## Overview Retrieves all confirmed transactions of a specific corporation for a specific year and month. > **Important**: The payload can be transformed depending on `format`, `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 `payroll` (i.e. `2025-08`) query param belongs to a cycle that 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. > **Important**: when an employee has migrated between companies of the same corporation, they may appear more than once in the response (once per company) under the same `legalId`. Use `mergeEmployees` to consolidate those duplicates into a single employee with the summed consumptions: > > * `mergeEmployees=newest` keeps the employee with the **largest** `createdAt` (most recently created employee record). > * `mergeEmployees=oldest` keeps the employee with the **smallest** `createdAt` (earliest created employee record). > > If not provided, duplicates are preserved as-is. Only applies to employees within the same corporation sharing the same `legalId`. Example responses based on `csvFormat` and `categories`: #### application/json ```json theme={null} { "corporation": { "id": "4a0425b0-e420-4fe4-9d05-783be0360993", "alias": "Corp Inc.", "externalId": "12345", "companies": [{ "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": "dd3de3a0-f903-42a0-b729-4cb16f185bc6", "internalId": "12345", "legalId": "129387655X", "consumptions": [ { "behaviour": "flex", "category": "meal-benefit", "sumType": "expenses", "amountInCents": 42001 }, { "behaviour": "flex", "category": "meal-benefit", "sumType": "withdrawn", "amountInCents": 2199 }, { "behaviour": "flex-not-exempt", "category": "meal-benefit", "sumType": "expenses", "amountInCents": 1599 }, { "behaviour": "flex", "category": "transport-benefit", "sumType": "expenses", "amountInCents": 13636 }, { "behaviour": "flex", "category": "nursery-benefit", "sumType": "expenses", "amountInCents": 77969 } ] } ] }] } } ``` ```json theme={null} { "corporation": { "id": "4a0425b0-e420-4fe4-9d05-783be0360993", "alias": "Corp Inc.", "externalId": "12345", "companies": [{ "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": "dd3de3a0-f903-42a0-b729-4cb16f185bc6", "internalId": "12345", "legalId": "129387655X", "consumptions": [ { "category": "meal-benefit", "amountInCents": 45799 }, { "category": "transport-benefit", "amountInCents": 13636 }, { "category": "nursery-benefit", "amountInCents": 77969 } ] } ] }] } } ``` ```json theme={null} { "corporation": { "id": "4a0425b0-e420-4fe4-9d05-783be0360993", "alias": "Corp Inc.", "externalId": "12345", "companies": [{ "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": "dd3de3a0-f903-42a0-b729-4cb16f185bc6", "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} corporation.id,corporation.alias,corporation.externalId,company.id,company.legalId,company.currency,payrollCycle.id,payrollCycle.start,payrollCycle.end,payrollCycle.fiscalYear,payrollCycle.payrollMonth,employees.employeeId,employees.internalId,employees.legalId,category,behaviour,sumType,amount.amountInCents 4a0425b0-e420-4fe4-9d05-783be0360993,Corp Inc.,12345,a1b2c3d4-e5f6-7890-a1b2-c3d4e5f67890,B12345678,EUR,b2c3d4e5-f678-9012-a1b2-c3d4e5f67890,1753939051,1756616806,2025,8,dd3de3a0-f903-42a0-b729-4cb16f185bc6,12345,129387655X,meal-benefit,flex,expenses,42001 4a0425b0-e420-4fe4-9d05-783be0360993,Corp Inc.,12345,a1b2c3d4-e5f6-7890-a1b2-c3d4e5f67890,B12345678,EUR,b2c3d4e5-f678-9012-a1b2-c3d4e5f67890,1753939051,1756616806,2025,8,dd3de3a0-f903-42a0-b729-4cb16f185bc6,12345,129387655X,meal-benefit,flex,withdrawn,2199 4a0425b0-e420-4fe4-9d05-783be0360993,Corp Inc.,12345,a1b2c3d4-e5f6-7890-a1b2-c3d4e5f67890,B12345678,EUR,b2c3d4e5-f678-9012-a1b2-c3d4e5f67890,1753939051,1756616806,2025,8,dd3de3a0-f903-42a0-b729-4cb16f185bc6,12345,129387655X,meal-benefit,flex-not-exempt,expenses,1599 4a0425b0-e420-4fe4-9d05-783be0360993,Corp Inc.,12345,a1b2c3d4-e5f6-7890-a1b2-c3d4e5f67890,B12345678,EUR,b2c3d4e5-f678-9012-a1b2-c3d4e5f67890,1753939051,1756616806,2025,8,dd3de3a0-f903-42a0-b729-4cb16f185bc6,12345,129387655X,transport-benefit,flex,expenses,13636 4a0425b0-e420-4fe4-9d05-783be0360993,Corp Inc.,12345,a1b2c3d4-e5f6-7890-a1b2-c3d4e5f67890,B12345678,EUR,b2c3d4e5-f678-9012-a1b2-c3d4e5f67890,1753939051,1756616806,2025,8,dd3de3a0-f903-42a0-b729-4cb16f185bc6,12345,129387655X,nursery-benefit,flex,expenses,77969 ``` ```csv theme={null} corporation.id,corporation.alias,corporation.externalId,company.id,company.legalId,company.currency,payrollCycle.id,payrollCycle.start,payrollCycle.end,payrollCycle.fiscalYear,payrollCycle.payrollMonth,employees.employeeId,employees.internalId,employees.legalId,category,amount.amountInCents 4a0425b0-e420-4fe4-9d05-783be0360993,Corp Inc.,12345,a1b2c3d4-e5f6-7890-a1b2-c3d4e5f67890,B12345678,EUR,b2c3d4e5-f678-9012-a1b2-c3d4e5f67890,1753939051,1756616806,2025,8,dd3de3a0-f903-42a0-b729-4cb16f185bc6,12345,129387655X,meal-benefit,45799 4a0425b0-e420-4fe4-9d05-783be0360993,Corp Inc.,12345,a1b2c3d4-e5f6-7890-a1b2-c3d4e5f67890,B12345678,EUR,b2c3d4e5-f678-9012-a1b2-c3d4e5f67890,1753939051,1756616806,2025,8,dd3de3a0-f903-42a0-b729-4cb16f185bc6,12345,129387655X,transport-benefit,13636 4a0425b0-e420-4fe4-9d05-783be0360993,Corp Inc.,12345,a1b2c3d4-e5f6-7890-a1b2-c3d4e5f67890,B12345678,EUR,b2c3d4e5-f678-9012-a1b2-c3d4e5f67890,1753939051,1756616806,2025,8,dd3de3a0-f903-42a0-b729-4cb16f185bc6,12345,129387655X,nursery-benefit,77969 ``` ```csv theme={null} corporation.id,corporation.alias,corporation.externalId,company.id,company.legalId,company.currency,payrollCycle.id,payrollCycle.start,payrollCycle.end,payrollCycle.fiscalYear,payrollCycle.payrollMonth,employees.employeeId,employees.internalId,employees.legalId,category,behaviour,amount.amountInCents 4a0425b0-e420-4fe4-9d05-783be0360993,Corp Inc.,12345,a1b2c3d4-e5f6-7890-a1b2-c3d4e5f67890,B12345678,EUR,b2c3d4e5-f678-9012-a1b2-c3d4e5f67890,1753939051,1756616806,2025,8,dd3de3a0-f903-42a0-b729-4cb16f185bc6,12345,129387655X,meal-benefit,flex,42001 4a0425b0-e420-4fe4-9d05-783be0360993,Corp Inc.,12345,a1b2c3d4-e5f6-7890-a1b2-c3d4e5f67890,B12345678,EUR,b2c3d4e5-f678-9012-a1b2-c3d4e5f67890,1753939051,1756616806,2025,8,dd3de3a0-f903-42a0-b729-4cb16f185bc6,12345,129387655X,meal-benefit,flex-not-exempt,1599 4a0425b0-e420-4fe4-9d05-783be0360993,Corp Inc.,12345,a1b2c3d4-e5f6-7890-a1b2-c3d4e5f67890,B12345678,EUR,b2c3d4e5-f678-9012-a1b2-c3d4e5f67890,1753939051,1756616806,2025,8,dd3de3a0-f903-42a0-b729-4cb16f185bc6,12345,129387655X,nursery-benefit,flex,77969 4a0425b0-e420-4fe4-9d05-783be0360993,Corp Inc.,12345,a1b2c3d4-e5f6-7890-a1b2-c3d4e5f67890,B12345678,EUR,b2c3d4e5-f678-9012-a1b2-c3d4e5f67890,1753939051,1756616806,2025,8,dd3de3a0-f903-42a0-b729-4cb16f185bc6,12345,129387655X,transport-benefit,flex,13636 ``` ```csv theme={null} corporation.id,corporation.alias,corporation.externalId,company.id,company.legalId,company.currency,payrollCycle.id,payrollCycle.start,payrollCycle.end,payrollCycle.fiscalYear,payrollCycle.payrollMonth,employees.employeeId,employees.internalId,employees.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 4a0425b0-e420-4fe4-9d05-783be0360993,Corp Inc.,12345,a1b2c3d4-e5f6-7890-a1b2-c3d4e5f67890,B12345678,EUR,b2c3d4e5-f678-9012-a1b2-c3d4e5f67890,1753939051,1756616806,2025,8,dd3de3a0-f903-42a0-b729-4cb16f185bc6,12345,129387655X,42001,2199,1599,0,13636,77969 ``` ```csv theme={null} corporation.id,corporation.alias,corporation.externalId,company.id,company.legalId,company.currency,payrollCycle.id,payrollCycle.start,payrollCycle.end,payrollCycle.fiscalYear,payrollCycle.payrollMonth,employees.employeeId,employees.internalId,employees.legalId,meal-benefit,transport-benefit,nursery-benefit 4a0425b0-e420-4fe4-9d05-783be0360993,Corp Inc.,12345,a1b2c3d4-e5f6-7890-a1b2-c3d4e5f67890,B12345678,EUR,b2c3d4e5-f678-9012-a1b2-c3d4e5f67890,1753939051,1756616806,2025,8,dd3de3a0-f903-42a0-b729-4cb16f185bc6,12345,129387655X,45799,13636,77969 ``` ```csv theme={null} corporation.id,corporation.alias,corporation.externalId,company.id,company.legalId,company.currency,payrollCycle.id,payrollCycle.start,payrollCycle.end,payrollCycle.fiscalYear,payrollCycle.payrollMonth,employees.employeeId,employees.internalId,employees.legalId,meal-benefit_flex,meal-benefit_flex-not-exempt,transport-benefit_flex,nursery-benefit_flex 4a0425b0-e420-4fe4-9d05-783be0360993,Corp Inc.,12345,a1b2c3d4-e5f6-7890-a1b2-c3d4e5f67890,B12345678,EUR,b2c3d4e5-f678-9012-a1b2-c3d4e5f67890,1753939051,1756616806,2025,8,dd3de3a0-f903-42a0-b729-4cb16f185bc6,12345,129387655X,42001,1599,13636,77969 ``` ## OpenAPI ````yaml GET /corporations/{corporationId}/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: /corporations/{corporationId}/consumptions: get: summary: Find all employee consumptions for a specific corporation 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: corporationId in: path required: true description: The unique identifier of the corporation 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 - name: mergeEmployees in: query required: false description: >- Merges consumptions of employees that appear in multiple companies of the corporation under the same `legalId` (e.g. after a migration between companies). Consumptions from duplicate employees are summed and assigned to a single "winner" employee; losing duplicates are dropped from the response. - `newest`: keep the employee with the largest `createdAt` (most recently created employee record). - `oldest`: keep the employee with the smallest `createdAt` (earliest created employee record). When not provided, no merging is performed and duplicate employees are preserved as-is. schema: type: string enum: - newest - oldest responses: '200': description: Corporation employee consumptions successfully retrieved content: application/json: schema: type: object required: - corporation properties: corporation: type: object required: - id - alias - externalId properties: id: type: string description: The unique identifier of the company. format: uuid example: 4a0425b0-e420-4fe4-9d05-783be0360993 alias: type: string description: The corporation's alias example: Corp. Inc. externalId: type: string description: The corporation's external ID example: '12345' companies: type: array items: 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 text/csv: schema: type: string format: binary '401': description: Unauthorized - Authentication failed content: application/json: schema: $ref: '#/components/schemas/Error' example: message: Unauthorized '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 ````