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

## Overview

Retrieve a list of the corporations associated with the authenticated user. A corporation is a group of related companies.


## OpenAPI

````yaml GET /corporations
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:
    get:
      summary: Get all corporations associated with the authenticated user
      parameters:
        - name: externalId
          in: query
          required: false
          description: >-
            Corporation External ID to filter by. Can be a single ID or multiple
            IDs separated by commas
          schema:
            oneOf:
              - type: string
              - type: array
                items:
                  type: string
          example: 12345,6AA999
        - name: include
          in: query
          required: false
          description: >-
            Whether to include companies for each corporation in the response.
            If true, companies are included; if false, companies are omitted.
          schema:
            type: boolean
          example: true
        - name: page
          in: query
          required: false
          description: Page number to retrieve. Defaults to 1.
          schema:
            type: integer
            minimum: 1
            default: 1
          example: 1
        - name: limit
          in: query
          required: false
          description: >-
            Max number of items per page. Must be greater than 0. Defaults to
            25. Maximum is 25.
          schema:
            type: integer
            minimum: 1
            maximum: 25
            default: 25
          example: 25
      responses:
        '200':
          description: Corporations successfully retrieved
          content:
            application/json:
              schema:
                type: object
                properties:
                  corporations:
                    type: array
                    items:
                      $ref: '#/components/schemas/Corporation'
                  page:
                    type: object
                    properties:
                      size:
                        type: integer
                      totalElements:
                        type: integer
                      totalPages:
                        type: integer
                      number:
                        type: integer
              example:
                corporations:
                  - id: 3fa85f64-5717-4562-b3fc-2c963f66afa6
                    alias: Iberian Foods Group
                    externalId: EXT-0001
                    companies:
                      - id: b2c3d4e5-f6a7-8901-b2c3-d4e5f6789012
                        name: Iberian Foods Madrid
                        legalId: B12345678
                        legalName: Iberian Foods Madrid S.A.
                        state: active
                        contactEmail: john.smith@example.com
                        corporationId: 3fa85f64-5717-4562-b3fc-2c963f66afa6
                        countryISO2Code: ES
                        deliveryAddress:
                          streetName: Calle Gran Vía
                          streetNumber: '10'
                          details: Planta 2
                          street: Calle Gran Vía, 10, Planta 2
                          postalCode: '28013'
                          province: Madrid
                          locality: Madrid
                          district: null
                        legalAddress:
                          streetName: Calle Gran Vía
                          streetNumber: '10'
                          details: Planta 2
                          street: Calle Gran Vía, 10, Planta 2
                          postalCode: '28013'
                          province: Madrid
                          locality: Madrid
                          district: null
                      - id: c3d4e5f6-a7b8-9012-c3d4-e5f678901234
                        name: Iberian Foods Barcelona
                        legalId: B87654321
                        legalName: Iberian Foods Barcelona S.L.
                        state: active
                        contactEmail: jane.doe@example.com
                        corporationId: 3fa85f64-5717-4562-b3fc-2c963f66afa6
                        countryISO2Code: ES
                        deliveryAddress:
                          streetName: Passeig de Gràcia
                          streetNumber: '42'
                          details: null
                          street: Passeig de Gràcia, 42
                          postalCode: '08007'
                          province: Barcelona
                          locality: Barcelona
                          district: null
                        legalAddress:
                          streetName: Passeig de Gràcia
                          streetNumber: '42'
                          details: null
                          street: Passeig de Gràcia, 42
                          postalCode: '08007'
                          province: Barcelona
                          locality: Barcelona
                          district: null
                  - id: 6ba7b811-9dad-11d1-80b4-00c04fd430c8
                    alias: Northern Logistics
                    externalId: EXT-0002
                    companies:
                      - id: d4e5f678-90ab-cdef-0123-456789abcdef
                        name: Northern Logistics Sevilla
                        legalId: A08000143
                        legalName: Northern Logistics Sevilla S.A.U.
                        state: active
                        contactEmail: contact@example.com
                        corporationId: 6ba7b811-9dad-11d1-80b4-00c04fd430c8
                        countryISO2Code: ES
                        deliveryAddress:
                          streetName: Avenida de la Constitución
                          streetNumber: '100'
                          details: Edificio B
                          street: Avenida de la Constitución, 100, Edificio B
                          postalCode: '41001'
                          province: Sevilla
                          locality: Sevilla
                          district: null
                        legalAddress:
                          streetName: Avenida de la Constitución
                          streetNumber: '100'
                          details: Edificio B
                          street: Avenida de la Constitución, 100, Edificio B
                          postalCode: '41001'
                          province: Sevilla
                          locality: Sevilla
                          district: null
                page:
                  size: 25
                  totalElements: 2
                  totalPages: 1
                  number: 1
        '400':
          description: Bad Request - Invalid parameters
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: string
                  message:
                    type: string
                required:
                  - message
              example:
                message: Partner ID is required
        '401':
          description: Unauthorised - Authentication failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                message: Unauthorized
components:
  schemas:
    Corporation:
      type: object
      properties:
        id:
          type: string
          format: uuid
          description: The unique identifier of the corporation
        alias:
          type: string
          description: The alias / name of the corporation
        externalId:
          type: string
          description: The external ID of the corporation
        companies:
          type: array
          description: >-
            List of companies belonging to this corporation. This property is
            included only when the query parameter include=true.
          items:
            $ref: '#/components/schemas/Company'
      required:
        - id
        - alias
        - externalId
    Error:
      required:
        - error
        - message
      type: object
      properties:
        error:
          type: integer
          format: int32
        message:
          type: string
      example:
        message: 'Bad request: Invalid field value'
    Company:
      type: object
      properties:
        id:
          type: string
          format: uuid
          description: The unique identifier of the company
        name:
          type: string
          description: The name of the company
        legalId:
          type: string
          description: The legal identification number of the company
        legalName:
          type: string
          description: The legal name of the company
        state:
          type: string
          enum:
            - active
          description: The state of the company
        contactEmail:
          type: string
          format: email
          description: The contact email of the company
        corporationId:
          type: string
          nullable: true
          description: The corporation ID if applicable, otherwise null
        countryISO2Code:
          type: string
          description: The two-letter ISO code of the company's country
        deliveryAddress:
          $ref: '#/components/schemas/Address'
        legalAddress:
          $ref: '#/components/schemas/Address'
      required:
        - id
        - name
        - legalId
        - legalName
        - state
        - contactEmail
        - countryISO2Code
        - deliveryAddress
        - legalAddress
    Address:
      type: object
      properties:
        streetName:
          type: string
          description: The name of the street
        streetNumber:
          type: string
          description: The number of the building
        details:
          type: string
          nullable: true
          description: Additional address details, if any
        street:
          type: string
          description: Full formatted street address
        postalCode:
          type: string
          description: The postal code of the address
        province:
          type: string
          description: The province or state of the address
        locality:
          type: string
          description: The city or town of the address
        district:
          type: string
          nullable: true
          description: The district of the address, if applicable
      required:
        - streetName
        - streetNumber
        - street
        - postalCode
        - province
        - locality
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer

````