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

Update an employer

PUT
/employers/:employer_id
PUT
/employers/:employer_id
$curl -X PUT https://test.api.kota.io/employers/er_3b1333d87d9d4fd6ad83ba7f6b0e951a \
>     -H "Authorization: Bearer <apiKey>" \
>     -H "Content-Type: application/json" \
>     -d '{}'
1{
2  "id": "er_3b1333d87d9d4fd6ad83ba7f6b0e951a",
3  "legal_name": "Acme Corporation Ltd",
4  "legal_address": {
5    "line1": "123 Industrial Way",
6    "city": "Springfield",
7    "postal_code": "12345",
8    "country_code": "us"
9  },
10  "contact": {
11    "name": "Jane Doe",
12    "email": "jane.doe@acmecorp.com"
13  },
14  "platform_id": "pt_3b1333d87d9d4fd6ad83ba7f6b0e951a",
15  "status": "pending",
16  "registration_number": "12345678",
17  "offboard_on": "2024-12-01T00:00:00Z",
18  "earliest_benefits_start_date": "2024-12-01",
19  "metadata": {},
20  "object": "employer"
21}
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.
Previous

Retrieve an employer

Next

Offboard an employer

Built with

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.

Authentication

AuthorizationBearer
Authorization header using the Bearer scheme

Path parameters

employer_idstringRequiredformat: "er_.+"

Request

This endpoint expects an object.
legal_namestring or nullOptional
registration_numberstring or nullOptional
legal_addressobjectOptional

Treated as a single object that is updated entirely, null sub-fields (e.g. Line 3) will delete the existing values

contactobjectOptional
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.
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. Treated as a single object that is updated entirely.

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
404
Not Found Error