openapi: 3.0.1
info:
  title: App Marketplace accounting-entries Companies API
  description: API for Pleo App Marketplace
  termsOfService: https://pleo.io/terms/
  contact:
    email: partner-ecosystem-team@pleo.io
  license:
    name: Apache 2.0
    url: http://www.apache.org/licenses/LICENSE-2.0.html
  version: 39.4.0
servers:
- url: https://external.pleo.io
  description: Production server
- url: https://external.staging.pleo.io
  description: Staging server
security:
- bearerAuth: []
- basicAuth: []
tags:
- name: Companies
  description: "The Companies API enables you to search for company records that are managed in Pleo. You can perform the following: \n - Search for multiple companies\n - Search for a specific company record by company ID"
paths:
  /v1/companies:
    get:
      tags:
      - Companies
      summary: Search for Companies
      description: Use this endpoint to search for companies associated with a specific organisation.
      operationId: Search for Companies
      parameters:
      - name: organization_id
        in: query
        description: Enter the organization ID of the companies you are searching for. Ensure that the access token used for authentication has the correct permissions to search for companies in the given organization.
        required: false
        style: form
        explode: true
        schema:
          type: string
          format: uuid
      - name: before
        in: query
        description: Lower bound of the page of data to return (cannot be used together with [after] or [offset]).
        required: false
        style: form
        explode: true
        schema:
          pattern: ^[A-Z2-7=~]+$
          type: string
      - name: after
        in: query
        description: Upper bound of the page of data to return (cannot be used together with [before] or [offset]).
        required: false
        style: form
        explode: true
        schema:
          pattern: ^[A-Z2-7=~]+$
          type: string
      - name: offset
        in: query
        description: Offset of the page of data to return (cannot be used together with [before] or [after]).
        required: false
        style: form
        explode: true
        schema:
          type: integer
          format: int64
      - name: limit
        in: query
        description: The maximum amount of items to return.
        required: false
        style: form
        explode: true
        schema:
          type: integer
          format: int32
      - name: sorting_keys
        in: query
        description: The keys to sort the results by.
        required: false
        style: form
        explode: true
        schema:
          type: array
          items:
            type: string
      - name: sorting_order
        in: query
        description: The order to sort the results by. Must be the same length as [sortingKeys]; one order per key.
        required: false
        style: form
        explode: true
        schema:
          type: array
          items:
            $ref: '#/components/schemas/PageOrder'
      responses:
        '200':
          description: Company search successful
          content:
            application/json;charset=UTF-8:
              schema:
                $ref: '#/components/schemas/CursorPaginatedResponseExternalCompanyResponseModel'
        '403':
          description: User lacks the necessary permissions
  /v1/companies/{companyId}:
    get:
      tags:
      - Companies
      summary: Search for a Specific Company
      description: Search for a specific company by company ID.
      operationId: Get company by ID
      parameters:
      - name: companyId
        in: path
        description: Enter the company ID.
        required: true
        style: simple
        explode: false
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: Company resource found
          content:
            application/json;charset=UTF-8:
              schema:
                $ref: '#/components/schemas/DataResponseExternalCompanyResponseModel'
        '403':
          description: User lacks the necessary permissions.
        '404':
          description: Company with given ID not found
components:
  schemas:
    DataResponseExternalCompanyResponseModel:
      required:
      - data
      type: object
      properties:
        data:
          $ref: '#/components/schemas/ExternalCompanyResponseModel'
    CursorPageInfo:
      required:
      - currentRequestPagination
      - hasNextPage
      - hasPreviousPage
      type: object
      properties:
        currentRequestPagination:
          $ref: '#/components/schemas/CursorPageCurrentRequestInfo'
        endCursor:
          type: string
        hasNextPage:
          type: boolean
        hasPreviousPage:
          type: boolean
        startCursor:
          type: string
        total:
          type: integer
          format: int64
    ExternalCompanyResponseModel:
      required:
      - address
      - id
      - name
      type: object
      properties:
        address:
          $ref: '#/components/schemas/ExternalAddressResponseModel'
        id:
          type: string
          description: ID of the Company
          format: uuid
        name:
          type: string
          description: Name of the Company
        organizationId:
          type: string
          description: Organization ID of the Company
          format: uuid
        registrationNumber:
          type: string
          description: Registration number of the company
    ExternalAddressResponseModel:
      type: object
      properties:
        addressLine1:
          type: string
          description: Line 1 of the company address.
        addressLine2:
          type: string
          description: Line 2 of the company address.
        country:
          type: string
          description: Country of the company.
        locality:
          type: string
          description: Locality of the company address.
        postalCode:
          type: string
          description: Postal code of the company address.
        region:
          type: string
          description: Region of the company.
      description: Address of the company
    CursorPageCurrentRequestInfo:
      required:
      - parameters
      type: object
      properties:
        after:
          type: string
        before:
          type: string
        limit:
          type: integer
          format: int32
        offset:
          type: integer
          format: int64
        parameters:
          type: object
          additionalProperties:
            type: array
            items:
              type: string
        sortingKeys:
          type: array
          items:
            type: string
        sortingOrder:
          type: array
          items:
            $ref: '#/components/schemas/PageOrder'
    PageOrder:
      type: string
      enum:
      - ASC
      - ASC_NULLS_FIRST
      - ASC_NULLS_LAST
      - DESC
      - DESC_NULLS_FIRST
      - DESC_NULLS_LAST
    CursorPaginatedResponseExternalCompanyResponseModel:
      required:
      - data
      - pagination
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/ExternalCompanyResponseModel'
        pagination:
          $ref: '#/components/schemas/CursorPageInfo'
  securitySchemes:
    bearerAuth:
      type: http
      description: 'JWT Bearer token authentication. Include the token in the Authorization header as: `Bearer <token>`'
      scheme: bearer
      bearerFormat: JWT
    basicAuth:
      type: http
      description: Basic HTTP authentication using API key. Use your API key as the username and leave the password empty. The credentials will be Base64 encoded automatically.
      scheme: basic