Kota employers API

openapi: 3.1.0
info:
  title: API Reference Associated Persons employers API
  version: 1.0.0
servers:
- url: https://test.api.kota.io
  description: test
- url: https://api.kota.io
  description: production
tags:
- name: employers
paths:
  /employers:
    get:
      operationId: list-employers
      summary: List all employers
      description: Returns a list of your `employers`. The `employers` are returned sorted by creation date, with the most recent `employers` appearing first.
      tags:
      - employers
      parameters:
      - name: filter
        in: query
        description: 'Multiple values can be provided by separating them with a comma. Allowed values are: `pending`, `active`, `offboarding`, `inactive`, `restricted`.'
        required: false
        schema:
          type: string
      - name: page
        in: query
        description: The page of results to return. Defaults to 1 if not provided.
        required: false
        schema:
          type: integer
      - name: page_size
        in: query
        description: The number of results to return per page. Defaults to 10 if not provided. Maximum value is 100.
        required: false
        schema:
          type: integer
      - name: Authorization
        in: header
        description: Authorization header using the Bearer scheme
        required: true
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EmployerResponsePagedList'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HttpValidationProblemDetails'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
    post:
      operationId: create-employer
      summary: Create an employer
      description: Creates an `employer`.
      tags:
      - employers
      parameters:
      - name: Authorization
        in: header
        description: Authorization header using the Bearer scheme
        required: true
        schema:
          type: string
      - name: Idempotency-Key
        in: header
        description: Unique key to ensure idempotent requests. If the same key is used for multiple _identical & successful_ requests, the same response will be returned. [Read more here](/api#idempotent-requests)
        required: false
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EmployerResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HttpValidationProblemDetails'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateEmployerRequest'
  /employers/{employer_id}:
    get:
      operationId: retrieve-employer
      summary: Retrieve an employer
      description: Retrieves an `employer` object.
      tags:
      - employers
      parameters:
      - name: employer_id
        in: path
        required: true
        schema:
          type: string
      - name: Authorization
        in: header
        description: Authorization header using the Bearer scheme
        required: true
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EmployerResponse'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
    put:
      operationId: update-employer
      summary: Update an employer
      description: 'Updates the specified `employer` by setting the values of the parameters passed. Any parameters not provided will be left unchanged. For example, if you pass the `legal_address` parameter only the `legal_address` value will be changed.


        Note that the `legal_address` and `contact` fields are treated as single objects that are updated entirely. If you provide either of these fields, the entire object will be replaced with the new data, not just the individual sub-fields you include in the request.For instance, if you provide a partial `legal_address` object, it will overwrite the entire existing `legal_address`, potentially removing any sub-fields you didn''t include in the request.


        This request accepts mostly the same arguments as the `employer` creation call.'
      tags:
      - employers
      parameters:
      - name: employer_id
        in: path
        required: true
        schema:
          type: string
      - name: Authorization
        in: header
        description: Authorization header using the Bearer scheme
        required: true
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EmployerResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HttpValidationProblemDetails'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateEmployerRequest'
  /employers/{employer_id}/offboard:
    post:
      operationId: offboard-employer
      summary: Offboard an employer
      description: Immediately offboard an `employer`. The `employer`’s scheme will be terminated and all `employees` associated with the `employer` will be offboarded and have their insurance terminated. `Employee` offboarding cannot be cancelled if triggered via this call.
      tags:
      - employers
      parameters:
      - name: employer_id
        in: path
        required: true
        schema:
          type: string
      - name: Authorization
        in: header
        description: Authorization header using the Bearer scheme
        required: true
        schema:
          type: string
      - name: Idempotency-Key
        in: header
        description: Unique key to ensure idempotent requests. If the same key is used for multiple _identical & successful_ requests, the same response will be returned. [Read more here](/api#idempotent-requests)
        required: false
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EmployerResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HttpValidationProblemDetails'
components:
  schemas:
    AddressModelWithoutCountry:
      type: object
      properties:
        line1:
          type: string
          description: 'Must not be empty. NOTE: This field will be normalized according to our internal formatting rules.'
        line2:
          type:
          - string
          - 'null'
          description: 'NOTE: This field will be normalized according to our internal formatting rules.'
        line3:
          type:
          - string
          - 'null'
          description: 'NOTE: This field will be normalized according to our internal formatting rules.'
        city:
          type: string
          description: 'Must not be empty. NOTE: This field will be normalized according to our internal formatting rules.'
        state:
          type:
          - string
          - 'null'
          description: 'Required for United States (State), and Canada (Province). NOTE: This field will be normalized according to our internal formatting rules.'
        postal_code:
          type: string
          description: 'Must not be empty, and a valid postal code for the specified country. NOTE: This field will be normalized according to our internal formatting rules.'
      required:
      - line1
      - city
      - postal_code
      title: AddressModelWithoutCountry
    CountryCode:
      type: string
      enum:
      - af
      - ax
      - al
      - dz
      - as
      - ad
      - ao
      - ai
      - aq
      - ag
      - ar
      - am
      - aw
      - au
      - at
      - az
      - bs
      - bh
      - bd
      - bb
      - by
      - be
      - bz
      - bj
      - bm
      - bt
      - bo
      - bq
      - ba
      - bw
      - bv
      - br
      - io
      - bn
      - bg
      - bf
      - bi
      - cv
      - kh
      - cm
      - ca
      - ky
      - cf
      - td
      - cl
      - cn
      - cx
      - cc
      - co
      - km
      - cg
      - cd
      - ck
      - cr
      - ci
      - hr
      - cu
      - cw
      - cy
      - cz
      - dk
      - dj
      - dm
      - do
      - ec
      - eg
      - sv
      - gq
      - er
      - ee
      - sz
      - et
      - fk
      - fo
      - fj
      - fi
      - fr
      - gf
      - pf
      - tf
      - ga
      - gm
      - ge
      - de
      - gh
      - gi
      - gr
      - gl
      - gd
      - gp
      - gu
      - gt
      - gg
      - gn
      - gw
      - gy
      - ht
      - hm
      - va
      - hn
      - hk
      - hu
      - is
      - in
      - id
      - ir
      - iq
      - ie
      - im
      - il
      - it
      - jm
      - jp
      - je
      - jo
      - kz
      - ke
      - ki
      - kp
      - kr
      - xk
      - kw
      - kg
      - la
      - lv
      - lb
      - ls
      - lr
      - ly
      - li
      - lt
      - lu
      - mo
      - mg
      - mw
      - my
      - mv
      - ml
      - mt
      - mh
      - mq
      - mr
      - mu
      - yt
      - mx
      - fm
      - md
      - mc
      - mn
      - me
      - ms
      - ma
      - mz
      - mm
      - na
      - nr
      - np
      - nl
      - nc
      - nz
      - ni
      - ne
      - ng
      - nu
      - nf
      - mk
      - mp
      - 'no'
      - om
      - pk
      - pw
      - ps
      - pa
      - pg
      - py
      - pe
      - ph
      - pn
      - pl
      - pt
      - pr
      - qa
      - re
      - ro
      - ru
      - rw
      - bl
      - sh
      - kn
      - lc
      - mf
      - pm
      - vc
      - ws
      - sm
      - st
      - sa
      - sn
      - rs
      - sc
      - sl
      - sg
      - sx
      - sk
      - si
      - sb
      - so
      - za
      - gs
      - ss
      - es
      - lk
      - sd
      - sr
      - sj
      - se
      - ch
      - sy
      - tw
      - tj
      - tz
      - th
      - tl
      - tg
      - tk
      - to
      - tt
      - tn
      - tr
      - tm
      - tc
      - tv
      - ug
      - ua
      - ae
      - gb
      - um
      - us
      - uy
      - uz
      - vu
      - ve
      - vn
      - vg
      - vi
      - wf
      - eh
      - ye
      - zm
      - zw
      title: CountryCode
    AddressModel:
      type: object
      properties:
        line1:
          type: string
          description: 'Must not be empty. NOTE: This field will be normalized according to our internal formatting rules.'
        line2:
          type:
          - string
          - 'null'
          description: 'NOTE: This field will be normalized according to our internal formatting rules.'
        line3:
          type:
          - string
          - 'null'
          description: 'NOTE: This field will be normalized according to our internal formatting rules.'
        city:
          type: string
          description: 'Must not be empty. NOTE: This field will be normalized according to our internal formatting rules.'
        state:
          type:
          - string
          - 'null'
          description: 'Required for United States (State), and Canada (Province). NOTE: This field will be normalized according to our internal formatting rules.'
        postal_code:
          type: string
          description: 'Must not be empty, and a valid postal code for the specified country. NOTE: This field will be normalized according to our internal formatting rules.'
        country_code:
          $ref: '#/components/schemas/CountryCode'
      required:
      - line1
      - city
      - postal_code
      - country_code
      title: AddressModel
    EmployerStatus:
      type: string
      enum:
      - pending
      - active
      - offboarding
      - inactive
      - restricted
      title: EmployerStatus
    CreateEmployerRequest:
      type: object
      properties:
        legal_name:
          type: string
          description: 'Legal name of the company. NOTE: This field will be normalized according to our internal formatting rules.'
        registration_number:
          type:
          - string
          - 'null'
          description: 'Company registration number. NOTE: This field will be normalized according to our internal formatting rules.'
        legal_address:
          $ref: '#/components/schemas/AddressModel'
        contact:
          $ref: '#/components/schemas/ContactModel'
        earliest_benefits_start_date:
          type:
          - string
          - 'null'
          format: date
          description: 'The earliest date this employer is permitted to set up any benefits scheme. If this date is in the future, benefit setup will be blocked until then. Used to delay scheme setup access (e.g., for onboarding alignment).


            **Constraints:**


            - Can only be set or updated if no group policy or group quote exists.

            - Must be a valid date in the future.'
        metadata:
          type:
          - object
          - 'null'
          additionalProperties:
            type: string
          description: Set of key-value pairs that you can attach to an object. This can be useful for storing additional information about the object in a structured format. Maximum 25 keys. Individual keys can be up to 40 characters and values up to 500 characters.
      required:
      - legal_name
      - legal_address
      - contact
      title: CreateEmployerRequest
    HttpValidationProblemDetails:
      type: object
      properties:
        type:
          type:
          - string
          - 'null'
        title:
          type:
          - string
          - 'null'
        status:
          type:
          - integer
          - 'null'
        detail:
          type:
          - string
          - 'null'
        instance:
          type:
          - string
          - 'null'
        errors:
          type: object
          additionalProperties:
            type: array
            items:
              type: string
      title: HttpValidationProblemDetails
    UpdateEmployerRequest:
      type: object
      properties:
        legal_name:
          type:
          - string
          - 'null'
        registration_number:
          type:
          - string
          - 'null'
        legal_address:
          $ref: '#/components/schemas/AddressModelWithoutCountry'
          description: Treated as a single object that is updated entirely, `null` sub-fields (e.g. Line 3) will delete the existing values
        contact:
          $ref: '#/components/schemas/ContactModel'
        earliest_benefits_start_date:
          type:
          - string
          - 'null'
          format: date
          description: 'The earliest date this employer is permitted to set up any benefits scheme. If this date is in the future, benefit setup will be blocked until then. Used to delay scheme setup access (e.g., for onboarding alignment).


            **Constraints:**


            - Can only be set or updated if no group policy or group quote exists.

            - Must be a valid date.'
        metadata:
          type:
          - object
          - 'null'
          additionalProperties:
            type: string
          description: Set of key-value pairs that you can attach to an object. This can be useful for storing additional information about the object in a structured format. Maximum 25 keys. Individual keys can be up to 40 characters and values up to 500 characters. Treated as a single object that is updated entirely.
      title: UpdateEmployerRequest
    EmployerResponse:
      type: object
      properties:
        id:
          type: string
        platform_id:
          type: string
        status:
          $ref: '#/components/schemas/EmployerStatus'
        legal_name:
          type: string
        registration_number:
          type:
          - string
          - 'null'
        legal_address:
          $ref: '#/components/schemas/AddressModel'
        contact:
          $ref: '#/components/schemas/ContactModel'
        offboard_on:
          type:
          - string
          - 'null'
          format: date-time
        earliest_benefits_start_date:
          type:
          - string
          - 'null'
          format: date
        metadata:
          type:
          - object
          - 'null'
          additionalProperties:
            type: string
          description: Set of key-value pairs that you can attach to an object. This can be useful for storing additional information about the object in a structured format. Maximum 25 keys. Individual keys can be up to 40 characters and values up to 500 characters.
        object:
          type: string
          description: The object type
      required:
      - id
      - legal_name
      - legal_address
      - contact
      title: EmployerResponse
    EmployerResponsePagedList:
      type: object
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/EmployerResponse'
          description: A paginated array containing the response elements
        page:
          type: integer
          description: The current page of the results
        page_size:
          type: integer
          description: The number of results on this page. This can be different from the requested page size if the total number of results is less than the requested page size
        total_count:
          type: integer
          description: The total number of elements available in the response. This is the total number of elements available across all pages, not just the current page.
        has_next_page:
          type: boolean
          description: Whether there are more pages available after this page
        has_previous_page:
          type: boolean
          description: Whether there are more pages available before this page
      required:
      - items
      - page
      - page_size
      - total_count
      title: EmployerResponsePagedList
    ProblemDetails:
      type: object
      properties:
        type:
          type:
          - string
          - 'null'
        title:
          type:
          - string
          - 'null'
        status:
          type:
          - integer
          - 'null'
        detail:
          type:
          - string
          - 'null'
        instance:
          type:
          - string
          - 'null'
      title: ProblemDetails
    ContactModel:
      type: object
      properties:
        name:
          type: string
          description: 'Contact person name. NOTE: This field will be normalized according to our internal formatting rules.'
        email:
          type: string
          description: 'Contact email address. NOTE: This field will be normalized according to our internal formatting rules.'
      required:
      - name
      - email
      title: ContactModel
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: Authorization header using the Bearer scheme