Kota employers API
The employers API from Kota — 3 operation(s) for employers.
Work with this as data
Every API here is available over the APIs.io API and to AI agents over MCP.
MCP server
One button, every client — Claude, Cursor, VS Code and the rest.
https://apis.io/mcp
Tools for apis
7 MCP tools reach this
find_apisBrowse and filter every API in the catalog.get_api_artifactsOne API's artifacts, grouped by type.get_openapiThe primary OpenAPI for this API.find_similar_apisAPIs that look like this one.apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.resolveTurn a domain, URL or GitHub org into the provider it belongs to.find_cohortsEvery scored population of providers in the catalog.
Call it yourself
curl for this page
This API
curl "https://apis.io/api/v1/apis/kota-employers-api"
All apis
curl "https://apis.io/api/v1/apis?limit=25"Discovery needs no key. Ratings and market analysis are Pro.
OpenAPI Specification
openapi: 3.2.0
info:
title: Kota Employers API
version: '1.0'
description: 'Operations tagged employers across 2 of this provider''s published API definitions: kota-api-reference-openapi.json, kota-openapi-original.json. Each path carries the servers of the definition it was published in.'
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'
servers:
- url: https://test.api.kota.io
description: test
- url: https://api.kota.io
description: production
/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'
servers:
- url: https://test.api.kota.io
description: test
- url: https://api.kota.io
description: production
/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'
servers:
- url: https://test.api.kota.io
description: test
- url: https://api.kota.io
description: production
components:
schemas:
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
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
EmployerStatus:
type: string
enum:
- pending
- active
- offboarding
- inactive
- restricted
title: EmployerStatus
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
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
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
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
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
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
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
ContactModel_2:
required:
- email
- name
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.'
additionalProperties: false
EmployerResponse_2:
required:
- contact
- id
- legal_address
- legal_name
type: object
properties:
id:
pattern: er_.+
type: string
example: er_3b1333d87d9d4fd6ad83ba7f6b0e951a
platform_id:
pattern: pt_.+
type: string
example: pt_3b1333d87d9d4fd6ad83ba7f6b0e951a
status:
allOf:
- $ref: '#/components/schemas/EmployerStatus_2'
legal_name:
type: string
registration_number:
type:
- 'null'
- string
legal_address:
allOf:
- $ref: '#/components/schemas/AddressModel_2'
contact:
allOf:
- $ref: '#/components/schemas/ContactModel_2'
offboard_on:
type:
- 'null'
- string
format: date-time
example: '2024-12-01T00:00:00Z'
earliest_benefits_start_date:
type:
- 'null'
- string
format: date
example: '2024-12-01'
metadata:
type:
- 'null'
- object
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
readOnly: true
additionalProperties: false
EmployerStatus_2:
enum:
- pending
- active
- offboarding
- inactive
- restricted
type: string
AddressModel_2:
required:
- city
- country_code
- line1
- postal_code
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:
- 'null'
- string
description: 'NOTE: This field will be normalized according to our internal formatting rules.'
line3:
type:
- 'null'
- string
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:
- 'null'
- string
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:
allOf:
- $ref: '#/components/schemas/CountryCode_2'
additionalProperties: false
CreateEmployerRequest_2:
required:
- contact
- legal_address
- legal_name
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:
- 'null'
- string
description: 'Company registration number. NOTE: This field will be normalized according to our internal formatting rules.'
legal_address:
allOf:
- $ref: '#/components/schemas/AddressModel_2'
contact:
allOf:
- $ref: '#/components/schemas/ContactModel_2'
earliest_benefits_start_date:
type:
- 'null'
- string
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.'
format: date
example: '2024-12-01'
metadata:
type:
- 'null'
- object
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.
additionalProperties: false
ProblemDetails_2:
type: object
properties:
type:
type:
- 'null'
- string
title:
type:
- 'null'
- string
status:
type:
- 'null'
- integer
format: int32
detail:
type:
- 'null'
- string
instance:
type:
- 'null'
- string
additionalProperties: {}
EmployerResponsePagedList_2:
required:
- items
- page
- page_size
- total_count
type: object
properties:
items:
type: array
items:
$ref: '#/components/schemas/EmployerResponse_2'
description: A paginated array containing the response elements
page:
type: integer
description: The current page of the results
format: int32
example: 123
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
format: int32
example: 123
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.
format: int32
example: 123
has_next_page:
type: boolean
description: Whether there are more pages available after this page
readOnly: true
example: true
has_previous_page:
type: boolean
description: Whether there are more pages available before this page
readOnly: true
example: true
additionalProperties: false
UpdateEmployerRequest_2:
type: object
properties:
legal_name:
type:
- 'null'
- string
registration_number:
type:
- 'null'
- string
legal_address:
type: 'null'
allOf:
- $ref: '#/components/schemas/AddressModelWithoutCountry_2'
description: Treated as a single object that is updated entirely, `null` sub-fields (e.g. Line 3) will delete the existing values
contact:
type: 'null'
allOf:
- $ref: '#/components/schemas/ContactModel_2'
earliest_benefits_start_date:
type:
- 'null'
- string
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.'
format: date
example: '2024-12-01'
metadata:
type:
- 'null'
- object
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.
additionalProperties: false
HttpValidationProblemDetails_2:
type: object
properties:
type:
type:
- 'null'
- string
title:
type:
- 'null'
- string
status:
type:
- 'null'
- integer
format: int32
detail:
type:
- 'null'
- string
instance:
type:
- 'null'
- string
errors:
type: object
additionalProperties:
type: array
items:
type: string
additionalProperties: {}
AddressModelWithoutCountry_2:
required:
- city
- line1
- postal_code
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:
- 'null'
- string
description: 'NOTE: This field will be normalized according to our internal formatting rules.'
line3:
type:
- 'null'
- string
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:
- 'null'
- string
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.'
additionalProperties: false
CountryCode_2:
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
# --- truncated at 32 KB (33 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/kota/refs/heads/main/openapi/kota-employers-api-openapi.yml