openapi: 3.0.3
info:
  version: '1.0'
  title: Company authorization customers API
  description: The Bokio Company API containing all resources for company tenant.
  termsOfService: https://docs.bokio.se/page/terms/
  contact:
    name: Bokio
    url: https://docs.bokio.se
    email: support@bokio.se
servers:
- url: https://api.bokio.se/v1
  description: Bokio API
  x-bokio-api: true
security:
- tokenAuth: []
tags:
- name: customers
  description: Operations for managing customer data
paths:
  /companies/{companyId}/customers:
    parameters:
    - name: companyId
      in: path
      required: true
      description: Unique identifier of the company
      schema:
        type: string
        format: uuid
      example: ea9ee4dd-fae3-4aec-a7db-6fc9cc1f8135
    post:
      tags:
      - customers
      summary: Create a customer
      description: 'Creates a customer for the company.


        **Scope:** `customers:write`

        '
      operationId: post-customer
      requestBody:
        description: Post the necessary fields for the API to create a customer.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/customer'
            examples:
              New customer:
                value:
                  name: customer 1
                  type: company
                  vatNumber: SE1234567890
                  orgNumber: 123456-7890
                  paymentTerms: '30'
                  contactsDetails:
                  - name: John Doe
                    email: john@email.com
                    phone: 0927-5631505
                    isDefault: true
                  address:
                    line1: Älvsborgsvägen 10
                    line2: null
                    city: Göteborg
                    postalCode: 123 45
                    country: SE
                  language: sv
      responses:
        '200':
          description: Customer created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/customer'
              examples:
                customer created:
                  value:
                    name: customer 1
                    type: company
                    vatNumber: SE1234567890
                    orgNumber: 123456-7890
                    paymentTerms: '30'
                    contactsDetails:
                    - id: 240a4af0-edfd-47b1-b4ab-f30450eaac19
                      name: John Doe
                      email: john@email.com
                      phone: 0927-5631505
                      isDefault: true
                    address:
                      line1: Älvsborgsvägen 10
                      line2: null
                      city: Göteborg
                      postalCode: 123 45
                      country: SE
                    language: sv
                    modifiedDateTime: 2024-10-10 00:00:00+00:00
        '400':
          description: Missing required information
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/apiError'
              examples:
                Error:
                  value:
                    code: validation-error
                    message: Validation failed with 3 errors
                    bokioErrorId: 9b408943-7a1e-47ac-85a7-ac52b2c210d3
                    errors:
                    - field: '#/name'
                      message: The name field is required
                    - field: '#/type'
                      message: The type field is required
                    - field: '#/address/country'
                      message: 'Invalid country code: XX'
      security:
      - tokenAuth: []
    get:
      tags:
      - customers
      summary: Get customers
      description: 'Get all customers for the company. Use the query parameters to filter and navigate through the results.

        **Scope:** `customers:read`'
      operationId: get-customer
      parameters:
      - name: page
        in: query
        required: false
        description: Page number
        schema:
          type: integer
          format: int32
          default: 1
      - name: pageSize
        in: query
        required: false
        description: Number of items per page
        schema:
          type: integer
          format: int32
          default: 25
          maximum: 100
      - name: query
        in: query
        required: false
        description: 'Optional query to filter the data set with supported fields listed below and [available operations](filtering).


          | Field                | Type        |

          | -------------------- | ----------- |

          | name                 | string      |

          | type                 | string      |

          | vatNumber            | string      |

          | orgNumber            | string      |

          | modifiedDateTime     | date-time   |

          '
        schema:
          type: string
        example: name==customer 1
      responses:
        '200':
          description: Customers found
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/pagedResponse'
                - type: object
                  properties:
                    items:
                      type: array
                      items:
                        $ref: '#/components/schemas/customer'
      security:
      - tokenAuth: []
  /companies/{companyId}/customers/{customerId}:
    parameters:
    - name: companyId
      in: path
      required: true
      description: Unique identifier of the company
      schema:
        type: string
        format: uuid
      example: ea9ee4dd-fae3-4aec-a7db-6fc9cc1f8135
    - name: customerId
      in: path
      required: true
      schema:
        type: string
        format: uuid
      example: 55c899c5-82b2-47fa-9c51-e35fc9b26443
      description: Unique identifier of the customer
    get:
      tags:
      - customers
      summary: Get a customer
      description: 'Retrieve the information of the customer with the matching customerId.


        **Scope:** `customers:read`

        '
      operationId: get-customers-customerId
      responses:
        '200':
          description: Customer found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/customer'
              examples:
                customer found:
                  value:
                    id: 55c899c5-82b2-47fa-9c51-e35fc9b26443
                    name: customer 1
                    type: company
                    vatNumber: SE1234567890
                    orgNumber: 123456-7890
                    paymentTerms: '30'
                    contactsDetails:
                    - id: 240a4af0-edfd-47b1-b4ab-f30450eaac19
                      name: John Doe
                      email: john@email.com
                      phone: 0927-5631505
                      isDefault: true
                    address:
                      line1: Älvsborgsvägen 10
                      line2: null
                      city: Göteborg
                      postalCode: 123 45
                      country: SE
                    language: sv
                    modifiedDateTime: 2024-10-10 00:00:00+00:00
        '404':
          description: Customer not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/apiError'
              examples:
                Error:
                  value:
                    code: not-found
                    message: Customer not found
                    bokioErrorId: 9b408943-7a1e-47ac-85a7-ac52b2c210d3
      security:
      - tokenAuth: []
    put:
      tags:
      - customers
      summary: Update a customer
      description: 'Update an existing customer for the company.


        **Scope:** `customers:write`

        '
      operationId: put-customer
      requestBody:
        description: Post the necessary fields for the API to update a customer.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/customer'
            examples:
              Update customer:
                value:
                  id: 55c899c5-82b2-47fa-9c51-e35fc9b26443
                  name: customer 1
                  type: company
                  vatNumber: SE1234567890
                  orgNumber: 123456-7890
                  paymentTerms: '30'
                  contactsDetails:
                  - Id: 240a4af0-edfd-47b1-b4ab-f30450eaac19
                    name: John Doe
                    email: john@email.com
                    phone: 0927-5631505
                    isDefault: true
                  address:
                    line1: Älvsborgsvägen 10
                    line2: null
                    city: Göteborg
                    postalCode: 123 45
                    country: SE
                  language: sv
      responses:
        '200':
          description: Customer updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/customer'
              examples:
                Update customer:
                  value:
                    id: 55c899c5-82b2-47fa-9c51-e35fc9b26443
                    name: customer 1
                    type: company
                    vatNumber: SE1234567890
                    orgNumber: 123456-7890
                    paymentTerms: '30'
                    contactsDetails:
                    - id: 240a4af0-edfd-47b1-b4ab-f30450eaac19
                      name: John Doe
                      email: john@email.com
                      phone: 0927-5631505
                      isDefault: true
                    address:
                      line1: Älvsborgsvägen 10
                      line2: null
                      city: Göteborg
                      postalCode: 123 45
                      country: SE
                    language: sv
                    modifiedDateTime: 2024-10-10 00:00:00+00:00
        '400':
          description: Missing required information
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/apiError'
              examples:
                Error:
                  value:
                    code: validation-error
                    message: Validation failed with 3 errors
                    bokioErrorId: 9b408943-7a1e-47ac-85a7-ac52b2c210d3
                    errors:
                    - field: '#/name'
                      message: The name field is required
                    - field: '#/type'
                      message: The type field is required
                    - field: '#/address/country'
                      message: 'Invalid country code: XX'
      security:
      - tokenAuth: []
    delete:
      tags:
      - customers
      summary: Delete a customer
      description: 'Delete an existing customer for the company.


        NOTE: Currently only supports deleting customers that have been added through the API.


        **Scope:** `customers:write`

        '
      operationId: delete-customer
      responses:
        '204':
          description: Customer deleted
      security:
      - tokenAuth: []
components:
  schemas:
    customer:
      type: object
      title: customer
      required:
      - name
      - type
      properties:
        id:
          type: string
          format: uuid
          readOnly: true
        name:
          type: string
        type:
          type: string
          enum:
          - company
          - private
        vatNumber:
          type: string
        orgNumber:
          type: string
        paymentTerms:
          type: string
          description: 'Payment terms for the invoices. Payment terms can both take free text or days, in digits, until the payment is due.


            On the invoice, if a digit is provided it will be suffixed with "days". For example, "30" will be displayed as "30 days" on the invoice. Note that the suffix will, similar to the rest of the invoice, use the language on the customer.

            '
        contactsDetails:
          type: array
          items:
            type: object
            properties:
              id:
                type: string
                format: uuid
                nullable: true
                description: Should not be set for new items
              name:
                type: string
              email:
                type: string
              phone:
                type: string
              isDefault:
                type: boolean
        address:
          $ref: '#/components/schemas/addressWithCountrySubdivision'
        language:
          type: string
          description: Default 'sv'
          enum:
          - sv
          - en
        modifiedDateTime:
          type: string
          format: date-time
          readOnly: true
          nullable: true
          description: The date and time the customer was last modified. Returns null for customers that were changed before this field was introduced.
      example:
        id: 55c899c5-82b2-47fa-9c51-e35fc9b26443
        name: customer 1
        type: company
        vatNumber: SE1234567890
        orgNumber: 123456-7890
        paymentTerms: '30'
        contactsDetails:
        - name: John Doe
          email: john@email.com
          phone: 0927-5631505
          isDefault: true
        address:
          line1: Älvsborgsvägen 10
          line2: null
          city: Göteborg
          postalCode: 123 45
          country: SE
        language: sv
        modifiedDateTime: 2024-10-10 00:00:00+00:00
    pagedResponse:
      type: object
      title: pagedResponse
      properties:
        totalItems:
          type: integer
          format: int32
          example: 1
        totalPages:
          type: integer
          format: int32
          example: 1
        currentPage:
          type: integer
          format: int32
          example: 1
    addressWithCountrySubdivision:
      type: object
      title: addressWithCountrySubdivision
      required:
      - line1
      - city
      - postalCode
      - country
      properties:
        line1:
          type: string
        line2:
          type: string
          nullable: true
        city:
          type: string
        postalCode:
          type: string
        country:
          description: ISO 3166-1 alpha-2 country code
          type: string
          format: country
        countrySubdivision:
          description: ISO 3166-2 subdivision code (e.g. ENG, SCT, WLS, NIR for GB). Currently required for GB (United kingdom) country.
          type: string
          nullable: true
      example:
        line1: 10 Downing Street
        line2: null
        city: London
        postalCode: SW1A 2AA
        country: GB
        countrySubdivision: ENG
    apiError:
      type: object
      title: apiError
      properties:
        code:
          type: string
        message:
          type: string
        bokioErrorId:
          type: string
          format: uuid
        errors:
          type: array
          items:
            type: object
            properties:
              field:
                type: string
              message:
                type: string
  securitySchemes:
    tokenAuth:
      type: http
      scheme: bearer
    access_token:
      type: oauth2
      flows:
        clientCredentials:
          tokenUrl: /token
          scopes: {}
        authorizationCode:
          authorizationUrl: /authorize
          tokenUrl: /token
          scopes:
            bank-payments:read-limited: Read access to bank payments created by the integration
            bank-payments:write: Write access to bank payments
            chart-of-accounts:read: Read access to chart of accounts
            company-information:read: Read access to company information
            credit-notes:read: Read access to credit notes
            credit-notes:write: Write access to credit notes
            customers:read: Read access to customers
            customers:write: Write access to customers
            fiscal-years:read: Read access to fiscal years
            invoices:read: Read access to invoices
            invoices:write: Write access to invoices
            items:read: Read access to items
            items:write: Write access to items
            journal-entries:read: Read access to journal entries
            journal-entries:write: Write access to journal entries
            sie:read: Read access to SIE files
            supplier-invoices:read: Read access to supplier invoices
            supplier-invoices:write: Write access to supplier invoices
            suppliers:read: Read access to suppliers
            suppliers:write: Write access to suppliers
            tags:read: Read access to tag groups and tags
            tags:write: Write access to tag groups and tags
            uploads:read: Read access to uploads
            uploads:write: Write access to uploads
    client_auth:
      type: http
      scheme: basic
externalDocs:
  url: https://docs.bokio.se
  description: Read the API Documentation
x-readme:
  explorer-enabled: true
  proxy-enabled: false
  samples-languages:
  - shell
  - http
  - node
  - csharp
  - java