Skip to main content
GET
/
corporations
/
{corporationId}
/
limits
Get corporation limits
curl --request GET \
  --url https://pre-partners-api.cobee.io/api/v3/corporations/{corporationId}/limits \
  --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",
        "employees": [
          {
            "employeeId": "dd3de3a0-f903-42a0-b729-4cb16f185bc6",
            "internalId": "12345",
            "legalId": "129387655X",
            "limits": {
              "meal": {
                "amount": {
                  "amountInCents": 123,
                  "currency": "EUR"
                },
                "appliesTo": "employee",
                "period": "payroll",
                "type": "recurrent",
                "disabled": false
              },
              "transport": {
                "amount": {
                  "amountInCents": 123,
                  "currency": "EUR"
                },
                "appliesTo": "employee",
                "period": "payroll",
                "type": "recurrent",
                "disabled": false
              },
              "nursery": {
                "amount": {
                  "amountInCents": 123,
                  "currency": "EUR"
                },
                "appliesTo": "employee",
                "period": "payroll",
                "type": "recurrent",
                "disabled": false
              }
            }
          }
        ],
        "currency": "EUR",
        "payrollCycle": {
          "id": "7f4c9ba8-9c2d-4b82-8b8c-e5f8f8f8f8f8",
          "start": 1672531200,
          "end": 1675123200,
          "fiscalYear": "2023",
          "payrollMonth": "03"
        }
      }
    ]
  }
}

​
Overview

This endpoint allows you to retrieve the limits for all employees within a specific corporation. You can optionally filter by a specific payroll cycle using the payroll query parameter (format YYYY-MM).If not provided, the limits for the current payroll cycle are returned. Past payroll cycles are not allowed.
  • Current payroll cycle: If the parameter matches the current cycle (or is omitted), the response includes the current payroll cycle details.
  • Future payroll cycles: If the parameter is for a future month, the payrollCycle object will have id/start/end: null, as the cycle has not yet opened.
  • Past payroll cycles: Querying for past payroll cycles is not allowed and will return a 400 Bad Request.
You can also filter the response by specific benefit categories using the categories query parameter. The response will include only the requested categories in the order they were provided. The response follows a structure similar to the corporation consumptions endpoint, grouping employees by company and providing their respective limits for benefits like meals, transport, and nurseries. You can also filter the response by specific benefit categories using the categories query parameter. The response will include only the requested categories in the order they were provided.

​
CSV Format

You can also request the response in CSV format by setting the Accept header to text/csv. We support two CSV formats through the csvFormat query parameter:
  • lines (default): Each row corresponds to a single limit record.
  • columns: Each row corresponds to a single employee, and each limit type is represented as separate columns. The columns for each benefit are named {category} (amount) and {category}-appliesTo (beneficiary).

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 limits belong to (e.g. 2025-03). If not provided, the current payroll cycle limits are returned. Past payroll cycles are not allowed.

Example:

"2025-03"

​
categories
string

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

​
csvFormat
enum<string>
default:lines

The format of the resulting limits. Only applicable when Accept is text/csv.

  • lines: One row per limit (default).
  • columns: One row per employee, with columns for each benefit category (amount and appliesTo).
Available options:
lines,
columns

Response

Corporation limits successfully retrieved

​
corporation
object
required