Sign in

v2

latestOpenAPI 3.1.12026-08-0785394779.1 KB
Employers

Create an employer

Creates an employer.

post/employers

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

X-Platform-Idstring

The target platform id. Required only when calling with a dashboard (WorkOS AuthKit) access token instead of a platform API key — the token carries no platform claim, so the caller must say which platform it means. Ignored for platform API key / embed session token callers.

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.
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
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"
}