> ## 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.

# [DRAFT] Enable limits

> Enables the limits for a list of employees. If the `employees` array is omitted or empty, the limits will be enabled for the entire company. Takes an optional payroll parameter to schedule the enablement for a future cycle. Past payroll cycles are not allowed.

## Overview

This endpoint allows you to enable benefit limits for a list of employees.

* **Current payroll**: If no `payroll` parameter is provided, the limits are enabled immediately for the current payroll cycle.
* **Future payroll**: If a `payroll` parameter is provided (e.g., `payroll=2026-05`), the limits will be enabled starting from that payroll cycle.
* **Past payroll**: Querying or sending past payroll cycles is **not allowed** and will return a `400 Bad Request`.

You must explicitly specify which `categories` to enable in the request body (e.g., `["meal", "transport"]`). The `categories` array is **mandatory** and must contain at least one item. If `categories` is omitted or empty, the API will return a `400 Bad Request`. There is no default behavior to enable "all" categories.

The `employees` array is **optional**. If you omit the `employees` array or send an empty array, the limits will be enabled globally for **all employees** in the company. If you do provide a list of IDs, it will only apply to those specific employees.

### Synchronous Response

The operation is performed synchronously. The response includes a summary of success and failure counts, and a detailed list of errors for any employees that failed to process.


## OpenAPI

````yaml POST /companies/{companyId}/limits/enable
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}/limits/enable:
    post:
      summary: Enable limits
      description: >-
        Enables the limits for a list of employees. If the `employees` array is
        omitted or empty, the limits will be enabled for the entire company.
        Takes an optional payroll parameter to schedule the enablement for a
        future cycle. Past payroll cycles are not allowed.
      parameters:
        - name: companyId
          in: path
          required: true
          schema:
            type: string
            format: uuid
          description: The company identifier
        - name: payroll
          in: query
          required: false
          description: >-
            The payroll cycle identifier (format YYYY-MM). If not provided, it
            defaults to the current payroll cycle. Past cycles will return a 400
            Bad Request.
          schema:
            type: string
            pattern: ^[0-9]{4}-(0[1-9]|1[0-2])$
            example: 2026-05
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/LimitStatusRequest'
            example:
              employees:
                - e3babcde-0123-4567-89ab-cdef01234567
                - f4cdef01-2345-6789-abcd-ef0123456789
              categories:
                - meal
                - transport
      responses:
        '200':
          description: Limits enabled successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LimitStatusResponse'
              example:
                totalRequested: 500
                succeeded: 499
                failed: 1
                errors:
                  - employeeId: i7f01234-5678-9012-def0-123456789012
                    error:
                      message: Employee not found
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  schemas:
    LimitStatusRequest:
      type: object
      required:
        - categories
      properties:
        employees:
          type: array
          items:
            type: string
            format: uuid
          description: >-
            List of employee IDs to apply the action to. If omitted or empty,
            the action applies to all employees in the company.
        categories:
          type: array
          minItems: 1
          items:
            type: string
            enum:
              - meal
              - transport
              - nursery
          description: >-
            List of benefit categories to apply the action to. This field is
            strictly mandatory.
    LimitStatusResponse:
      type: object
      properties:
        totalRequested:
          type: integer
          description: Total number of employees in the request
        succeeded:
          type: integer
          description: Number of employees successfully updated
        failed:
          type: integer
          description: Number of employees that failed to update
        errors:
          type: array
          items:
            type: object
            properties:
              employeeId:
                type: string
                format: uuid
                description: Employee identifier
              error:
                type: object
                properties:
                  message:
                    type: string
                    description: Human-readable error message
                description: Error details
          description: >-
            List of errors for employees that failed to update. Empty if all
            succeeded.
    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

````