v2

latestOpenAPI 3.1.12026-08-0785394779.1 KB

Associated Persons

Create an associated person

Creates an associated person (dependent or beneficiary) linked to an employee.

post/employees/{employee_id}/associated_persons

Path parameters

employee_idstring required

Example:ee_3b1333d87d9d4fd6ad83ba7f6b0e951a

Headers

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

first_namestring required

Must not be empty. NOTE: This field will be normalized according to our internal formatting rules.

last_namestring required

Must not be empty. NOTE: This field will be normalized according to our internal formatting rules.

date_of_birthstring date required

Must be in the past, but after 1900-01-01

sex_at_birth'male' | 'female' required

relationship_type'spouse' | 'partner' | 'child' | 'other' required

emailstring nullable

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

phone_numberstring nullable

Phone number in E.164 international format (e.g. +447700900999). NOTE: This field will be normalized according to our internal formatting rules.

Example request

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

Response

idstring required

Unique identifier for the associated person

platform_idstring

Unique identifier for the platform

employee_idstring required

Unique identifier for the employee this person is associated with

first_namestring required

First name of the associated person

last_namestring required

Last name of the associated person

date_of_birthstring date required

Date of birth of the associated person

sex_at_birth'male' | 'female' required

relationship_type'spouse' | 'partner' | 'child' | 'other' required

emailstring nullable

Email address of the associated person

phone_numberstring nullable

Phone number in E.164 international format (e.g. +447700900999)

objectstring

The object type

Example response

{
  "id": "ap_3b1333d87d9d4fd6ad83ba7f6b0e951a",
  "platform_id": "pt_3b1333d87d9d4fd6ad83ba7f6b0e951a",
  "employee_id": "ee_3b1333d87d9d4fd6ad83ba7f6b0e951a",
  "date_of_birth": "2024-12-01"
}