KOkota
Employers

Update an employer

Changed on

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.

put/employers/{employer_id}

Request

  • Base URL
    https://test.api.kota.io
  • URL
    https://test.api.kota.io/employers/{employer_id}
  • Auth
    HTTP bearer

Path parameters

employer_idstring required
Example:er_3b1333d87d9d4fd6ad83ba7f6b0e951a

Request body

legal_namestring nullable
registration_numberstring nullable
earliest_benefits_start_datestring date nullable

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.
applicable_collective_agreementstring nullable

Name of the collective agreement that applies to the employer's workforce, if any.

metadataobject nullable

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.

Example request

{
  "earliest_benefits_start_date": "2024-12-01"
}

Response

OK

idstring required
platform_idstring
status'pending' | 'active' | 'offboarding' | 'inactive' | 'restricted'
legal_namestring required
registration_numberstring nullable
offboard_onstring date-time nullable
earliest_benefits_start_datestring date nullable
applicable_collective_agreementstring nullable

Name of the collective agreement that applies to the employer's workforce, if any.

metadataobject nullable

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.

objectstring

The object type

Example response

{
  "id": "er_3b1333d87d9d4fd6ad83ba7f6b0e951a",
  "platform_id": "pt_3b1333d87d9d4fd6ad83ba7f6b0e951a",
  "offboard_on": "2024-12-01T00:00:00Z",
  "earliest_benefits_start_date": "2024-12-01"
}

Changes

  • 998f7cb004abRevision changes
    • warning

      deleted the header request parameter X-Platform-Id

  • db15507aa7bcRevision changes
    • info

      added the new optional request property ////

    • info

      added the optional property to the response with the status