API ReferenceAssociated Persons

Create an associated person

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

Authentication

AuthorizationBearer
Authorization header using the Bearer scheme

Path parameters

employee_idstringRequiredformat: "ee_.+"

Headers

X-Platform-IdstringOptional

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

This endpoint expects an object.
first_namestringRequired

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

last_namestringRequired

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

date_of_birthdateRequired

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

sex_at_birthenumRequired
The sex assigned to the associated person at birth
relationship_typeenumRequired
The relationship type between the employee and the associated person
emailstring or nullOptional

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

phone_numberstring or nullOptional

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

Response

OK
idstringformat: "ap_.+"
Unique identifier for the associated person
employee_idstringformat: "ee_.+"
Unique identifier for the employee this person is associated with
first_namestring
First name of the associated person
last_namestring
Last name of the associated person
date_of_birthdate
Date of birth of the associated person
sex_at_birthenum
The sex assigned to the associated person at birth
relationship_typeenum
The relationship type between the employee and the associated person
platform_idstringOptionalformat: "pt_.+"
Unique identifier for the platform
emailstring or nullOptional
Email address of the associated person
phone_numberstring or nullOptional

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

objectstringOptionalRead-only
The object type

Errors

400
Bad Request Error
404
Not Found Error