Skip to main content
GET
/
corporations
/
{corporationId}
/
consumptions
Find all employee consumptions for a specific corporation
curl --request GET \
  --url https://pre-partners-api.cobee.io/api/v3/corporations/{corporationId}/consumptions \
  --header 'Authorization: Bearer <token>'
{
  "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": "7f4c9ba8-9c2d-4b82-8b8c-e5f8f8f8f8f8",
          "start": 1672531200,
          "end": 1675123200,
          "fiscalYear": "2023",
          "payrollMonth": "03"
        },
        "employees": [
          {
            "employeeId": "dd3de3a0-f903-42a0-b729-4cb16f185bc6",
            "internalId": "12345",
            "legalId": "129387655X",
            "consumptions": [
              {
                "behaviour": "allowance",
                "category": "meal-benefit",
                "sumType": "expenses",
                "amountInCents": 1
              }
            ]
          }
        ]
      }
    ]
  }
}

​
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:

Authorizations

​
Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Headers

​
Accept
enum<string>

The response file type. It can be application/json or text/csv.

Available options:
application/json,
text/csv

Path Parameters

​
corporationId
string<uuid>
required

The unique identifier of the corporation

Query Parameters

​
payroll
string

The fiscal year and month (YYYY-MM) of the payroll cycle the consumptions belong to (e.g. 2025-03).

Pattern: ^[0-9]{4}-(0[1-9]|1[0-2])$
Example:

"2025-03"

​
csvFormat
enum<string>

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
Available options:
lines,
columns
​
categories
string

List of benefit categories to include in the response, which will return them in the same order as requested.

​
groupBy
string

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.
​
mergeEmployees
enum<string>

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.

Available options:
newest,
oldest

Response

Corporation employee consumptions successfully retrieved

​
corporation
object
required