List company consumptions

Find all employee consumptions for a specific company

curl --request GET \
  --url https://pre-partners-api.cobee.io/api/v3/companies/{companyId}/consumptions \
  --header 'Authorization: Bearer <token>'

import requests

url = "https://pre-partners-api.cobee.io/api/v3/companies/{companyId}/consumptions"

headers = {"Authorization": "Bearer <token>"}

response = requests.get(url, headers=headers)

print(response.text)

const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

fetch('https://pre-partners-api.cobee.io/api/v3/companies/{companyId}/consumptions', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://pre-partners-api.cobee.io/api/v3/companies/{companyId}/consumptions",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://pre-partners-api.cobee.io/api/v3/companies/{companyId}/consumptions"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://pre-partners-api.cobee.io/api/v3/companies/{companyId}/consumptions")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'

response = http.request(request)
puts response.read_body

{
  "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": "dd3de3a0-f903-42a0-b729-4cb16f185bc6",
        "internalId": "12345",
        "legalId": "129387655X",
        "consumptions": [
          {
            "behaviour": "allowance",
            "category": "meal-benefit",
            "sumType": "expenses",
            "amountInCents": 1
          }
        ]
      }
    ]
  }
}

{
  "message": "Resource not found"
}

{
  "message": "Internal server error"
}

GET

companies

{companyId}

consumptions

Find all employee consumptions for a specific company

curl --request GET \
  --url https://pre-partners-api.cobee.io/api/v3/companies/{companyId}/consumptions \
  --header 'Authorization: Bearer <token>'

import requests

url = "https://pre-partners-api.cobee.io/api/v3/companies/{companyId}/consumptions"

headers = {"Authorization": "Bearer <token>"}

response = requests.get(url, headers=headers)

print(response.text)

const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

fetch('https://pre-partners-api.cobee.io/api/v3/companies/{companyId}/consumptions', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://pre-partners-api.cobee.io/api/v3/companies/{companyId}/consumptions",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://pre-partners-api.cobee.io/api/v3/companies/{companyId}/consumptions"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://pre-partners-api.cobee.io/api/v3/companies/{companyId}/consumptions")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'

response = http.request(request)
puts response.read_body

{
  "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": "dd3de3a0-f903-42a0-b729-4cb16f185bc6",
        "internalId": "12345",
        "legalId": "129387655X",
        "consumptions": [
          {
            "behaviour": "allowance",
            "category": "meal-benefit",
            "sumType": "expenses",
            "amountInCents": 1
          }
        ]
      }
    ]
  }
}

{
  "message": "Resource not found"
}

{
  "message": "Internal server error"
}

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: In columns format the consumption columns are derived from the data: a column only appears when at least one employee in the report has consumption for it, so a missing column means there was no consumption. As an exception, when groupBy=category and categories are provided, the CSV is guaranteed to contain one column per requested category — in the same order as requested — with 0 when there is no consumption.

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:

Show Examples

application/json

Show default

{
  "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
          }
        ]
      }
    ]
  }
}

Show groupBy=category

{
  "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
          }
        ]
      }
    ]
  }
}

Show groupBy=category,behaviour

{
  "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

Show csvFormat=lines

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

Show csvFormat=lines & groupBy=category

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

Show csvFormat=lines & groupBy=category,behaviour

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

Show csvFormat=columns

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

Show csvFormat=columns & groupBy=category

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

Show csvFormat=columns & groupBy=category & categories=meal-benefit,transport-benefit,nursery-benefit

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,0

Show csvFormat=columns & groupBy=category,behaviour

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

Authorizations

Authorization

string

header

required

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

Headers

enum<string>

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

Available options:

application/json,

text/csv

Path Parameters

companyId

string<uuid>

required

The unique identifier of the company

Query Parameters

payrollCycleId

string<uuid>

The unique identifier of the payroll cycle. If not provided, the open payroll cycle will be used.

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 In columns format the columns are derived from the data, so a missing column means no consumption. When combined with groupBy=category and categories, every requested category is guaranteed to appear as a column.

Available options:

lines,

columns

Response

Company employees consumptions successfully retrieved

company

object

required

Show child attributes

Get Started

Guides

Data Models

Authentication

Corporations

Employees

Limits

Consumption Reports

Payroll Cycles

Overview

application/json

text/csv

Authorizations

Headers

Path Parameters

Query Parameters

Response

​Overview

​application/json

​text/csv

Authorizations

Headers

Path Parameters

Query Parameters

Response

Overview

application/json

text/csv