Skip to navigation
API ReferenceMembers

Create Dependent

Saves a dependent (spouse or child) for a member. Saving does not enroll the dependent or change the member’s coverage or coverage tier. If the member already has an active dependent matching this person, that relationship is reused and returned with a 200 and created: false; otherwise a new one is created with a 201 and created: true. In both cases the dependent’s address is set to the one supplied; other details of a person Vitable already has on file are not changed. When a new dependent is created at exactly the member’s address, Vitable also adds them to the member’s household where it can; this never fails the request. The returned IDs identify the saved dependent. Social Security numbers are not accepted, and a body with an ssn field returns a 400. The caller must have write access to the target member, and API access tokens cannot save dependents. A member not visible to the caller returns a 404 before the body is validated. Business-rule failures return a 422 with child_over_max_age (a child must be under 26), duplicate_active_spouse (the member already has a different active spouse), same_member, member_creation_failed, or legal_dependent_creation_failed.

Authentication

AuthorizationBearer

API Key or Access Token authentication using Bearer token in Authorization header. API keys use the vit_apk_ prefix, access tokens use the vit_at_ prefix.

Path parameters

member_idstringRequired

Unique member identifier (mbr_*)

Headers

X-Vitable-OrganizationstringOptional

Organization to act as for this request (e.g. org_SGVsbG8gV29ybGQ). Optional when your credentials reach a single organization. Required when they reach several — omitting it then returns 400 organization_required. A malformed value returns 400 invalid_organization_header, and naming an organization you do not have access to returns 403 organization_access_denied.

Request

This endpoint expects an object.
first_namestringRequired<=256 characters
Dependent's legal first name
last_namestringRequired<=256 characters
Dependent's legal last name
date_of_birthdateRequired

Date of birth (YYYY-MM-DD); cannot be in the future

relationshipenumRequired

Relationship of the dependent to the member

  • Spouse - Spouse
  • Child - Child
Allowed values:
addressobjectRequired
Dependent's residential address
suffixenum or nullOptional

Name suffix

  • Sr - Sr
  • Jr - Jr
  • I - I
  • II - II
  • III - III
  • IV - IV
  • V - V
sex_at_birthenum or nullOptional

Sex assigned at birth

  • Male - Male
  • Female - Female
  • Other - Other
  • Unknown - Unknown
Allowed values:
genderenum or nullOptional

Gender identity

  • Male - Male
  • Female - Female
  • Transgender - Transgender
  • Non-binary - Non-binary
  • Prefer not to respond - Prefer not to respond
Allowed values:
emailstring or nullOptional<=256 characters
Dependent's email address. Ignored for dependents under 18, and not changed for a dependent Vitable already has on file.
phonestring or nullOptional<=256 characters

Dependent's 10-digit US phone number; formatting characters and a leading 1 are ignored. Ignored for dependents under 18, and not changed for a dependent Vitable already has on file.

Response headers

X-RateLimit-Limitinteger
Maximum number of requests allowed within the rate limit window
X-RateLimit-Remaininginteger
Number of requests remaining in the current rate limit window
X-RateLimit-Resetinteger

Unix timestamp (seconds) when the rate limit window resets

Response

The member already had this dependent; the existing relationship was returned.

dataobject

Wire serializer for :class:MemberLegalDependentDTO (one legal-dependent row).

Errors

400
Bad Request Error
401
Unauthorized Error
403
Forbidden Error
404
Not Found Error
409
Conflict Error
422
Unprocessable Entity Error
429
Too Many Requests Error
500
Internal Server Error
502
Bad Gateway Error