Employers

Create an employer

Changed on

Creates an employer.

post/employers

Request

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

Headers

Idempotency-Keystring

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 body

legal_namestring required

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

registration_numberstring nullable

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

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 in the future.
applicable_collective_agreementstring nullable

Name of the collective agreement that applies to the employer's workforce, if any. NOTE: This field will be normalized according to our internal formatting rules.

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.

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