For AI agents: a documentation index is available at the root level at /llms.txt and /llms-full.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.
Get access
Getting Started Key Concepts Integration Types Core Components Embed Hosted API API Reference
  • API Reference
      • GETList all employers
      • POSTCreate an employer
      • GETRetrieve an employer
      • PUTUpdate an employer
      • POSTOffboard an employer
    • Contribution Reports
    • Events and Webhooks
    • API Errors
Get access
LogoLogo
API ReferenceEmployers

Create an employer

POST
/employers
POST
/employers
$curl -X POST https://test.api.kota.io/employers \
>     -H "Authorization: Bearer <apiKey>" \
>     -H "Content-Type: application/json" \
>     -d '{
>  "legal_name": "GreenTech Innovations LLC",
>  "legal_address": {
>    "line1": "1234 Elm Street",
>    "city": "Kabul",
>    "postal_code": "1001",
>    "country_code": "af"
>  },
>  "contact": {
>    "name": "Amina Rahimi",
>    "email": "amina.rahimi@greentech.af"
>  }
>}'
1{
2  "id": "er_3b1333d87d9d4fd6ad83ba7f6b0e951a",
3  "legal_name": "GreenTech Innovations LLC",
4  "legal_address": {
5    "line1": "1234 Elm Street",
6    "city": "Kabul",
7    "postal_code": "1001",
8    "country_code": "af"
9  },
10  "contact": {
11    "name": "Amina Rahimi",
12    "email": "amina.rahimi@greentech.af"
13  },
14  "platform_id": "pt_3b1333d87d9d4fd6ad83ba7f6b0e951a",
15  "status": "pending",
16  "registration_number": "AF123456789",
17  "offboard_on": "2024-12-01T00:00:00Z",
18  "earliest_benefits_start_date": "2024-12-01",
19  "metadata": {},
20  "object": "employer"
21}

Creates an employer.

Previous

List all employers

Next

Retrieve an employer

Built with

Authentication

AuthorizationBearer
Authorization header using the Bearer scheme

Headers

Idempotency-KeystringOptional

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

Request

This endpoint expects an object.
legal_namestringRequired

Legal name of the company. NOTE: This field will be normalized according to our internal formatting rules.

legal_addressobjectRequired
contactobjectRequired
registration_numberstring or nullOptional

Company registration number. NOTE: This field will be normalized according to our internal formatting rules.

earliest_benefits_start_datedate or nullOptional

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.
metadatamap from strings to strings or nullOptional

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.

Response

OK
idstringformat: "er_.+"
legal_namestring
legal_addressobject
contactobject
platform_idstringformat: "pt_.+"
statusenum
Allowed values:
registration_numberstring or null
offboard_ondatetime or null
earliest_benefits_start_datedate or null
metadatamap from strings to strings or null

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.

objectstringRead-only
The object type

Errors

400
Bad Request Error