> For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://developer.vitablehealth.com/api/members/create-dependent/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://developer.vitablehealth.com/_mcp/server. # Create Dependent POST https://api.vitablehealth.com/v1/members/{member_id}/dependents Content-Type: application/json 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`. Reference: https://developer.vitablehealth.com/api/members/create-dependent ## Authentication - `Authorization` header (bearer token, required) — 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. ## Servers - `https://api.vitablehealth.com` (Production, default) - `https://api.uat.vitablehealth.com` (UAT) ## Request ### Path parameters - `member_id` (string, required) — Unique member identifier (mbr_*) ### Headers - `X-Vitable-Organization` (string, optional) — 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`. ### Body (application/json) This endpoint expects a CreateMemberDependentRequest. - `first_name` (string, required) — Dependent's legal first name - `last_name` (string, required) — Dependent's legal last name - `date_of_birth` (date, required) — Date of birth (YYYY-MM-DD); cannot be in the future - `relationship` (enum, required) — Relationship of the dependent to the member * `Spouse` - Spouse * `Child` - Child - Allowed values: `Spouse`, `Child` - `address` (CreateMemberDependentAddressRequest, required) — Dependent's residential address - `suffix` (enum, optional, nullable) — Name suffix * `Sr` - Sr * `Jr` - Jr * `I` - I * `II` - II * `III` - III * `IV` - IV * `V` - V - Allowed values: `Sr`, `Jr`, `I`, `II`, `III`, `IV`, `V` - `sex_at_birth` (enum, optional, nullable) — Sex assigned at birth * `Male` - Male * `Female` - Female * `Other` - Other * `Unknown` - Unknown - Allowed values: `Male`, `Female`, `Other`, `Unknown` - `gender` (enum, optional, nullable) — Gender identity * `Male` - Male * `Female` - Female * `Transgender` - Transgender * `Non-binary` - Non-binary * `Prefer not to respond` - Prefer not to respond - Allowed values: `Male`, `Female`, `Transgender`, `Non-binary`, `Prefer not to respond` - `email` (string, optional, nullable) — Dependent's email address. Ignored for dependents under 18, and not changed for a dependent Vitable already has on file. - `phone` (string, optional, nullable) — 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 ### 200 The member already had this dependent; the existing relationship was returned. - `data` (SavedMemberDependent, required) — Wire serializer for :class:`MemberLegalDependentDTO` (one legal-dependent row). ### 201 A new dependent relationship was created. - `data` (SavedMemberDependent, required) — Wire serializer for :class:`MemberLegalDependentDTO` (one legal-dependent row). ## Errors ### 400 Bad Request Error Invalid request. - `timestamp` (datetime, required) — ISO 8601 timestamp when the error occurred - `message` (string, required) — Human-readable error message - `error` (string, required) — Error message (same as message, for backwards compatibility) - `trace_id` (string, required) — Unique trace ID for debugging and support requests - `app_error_code` (string, optional, nullable) — Application-specific error code for programmatic handling ### 401 Unauthorized Error Unauthorized - Invalid or missing API key - `timestamp` (datetime, required) — ISO 8601 timestamp when the error occurred - `message` (string, required) — Human-readable error message - `error` (string, required) — Error message (same as message, for backwards compatibility) - `trace_id` (string, required) — Unique trace ID for debugging and support requests - `app_error_code` (string, optional, nullable) — Application-specific error code for programmatic handling ### 403 Forbidden Error The caller is an access token; access tokens cannot save dependents. - `timestamp` (datetime, required) — ISO 8601 timestamp when the error occurred - `message` (string, required) — Human-readable error message - `error` (string, required) — Error message (same as message, for backwards compatibility) - `trace_id` (string, required) — Unique trace ID for debugging and support requests - `app_error_code` (string, optional, nullable) — Application-specific error code for programmatic handling ### 404 Not Found Error Resource not found. - `timestamp` (datetime, required) — ISO 8601 timestamp when the error occurred - `message` (string, required) — Human-readable error message - `error` (string, required) — Error message (same as message, for backwards compatibility) - `trace_id` (string, required) — Unique trace ID for debugging and support requests - `app_error_code` (string, optional, nullable) — Application-specific error code for programmatic handling ### 409 Conflict Error Conflict - Resource already exists or conflicts with current state - `timestamp` (datetime, required) — ISO 8601 timestamp when the error occurred - `message` (string, required) — Human-readable error message - `error` (string, required) — Error message (same as message, for backwards compatibility) - `trace_id` (string, required) — Unique trace ID for debugging and support requests - `app_error_code` (string, optional, nullable) — Application-specific error code for programmatic handling ### 422 Unprocessable Entity Error A business rule was violated: `child_over_max_age`, `duplicate_active_spouse`, `same_member`, `member_creation_failed`, or `legal_dependent_creation_failed`. - `timestamp` (datetime, required) — ISO 8601 timestamp when the error occurred - `message` (string, required) — Human-readable error message - `error` (string, required) — Error message (same as message, for backwards compatibility) - `trace_id` (string, required) — Unique trace ID for debugging and support requests - `app_error_code` (string, optional, nullable) — Application-specific error code for programmatic handling ### 429 Too Many Requests Error Too Many Requests - Rate limit exceeded - `timestamp` (datetime, required) — ISO 8601 timestamp when the error occurred - `message` (string, required) — Human-readable error message - `error` (string, required) — Error message (same as message, for backwards compatibility) - `trace_id` (string, required) — Unique trace ID for debugging and support requests - `app_error_code` (string, optional, nullable) — Application-specific error code for programmatic handling ### 500 Internal Server Error Internal Server Error - An unexpected error occurred - `timestamp` (datetime, required) — ISO 8601 timestamp when the error occurred - `message` (string, required) — Human-readable error message - `error` (string, required) — Error message (same as message, for backwards compatibility) - `trace_id` (string, required) — Unique trace ID for debugging and support requests - `app_error_code` (string, optional, nullable) — Application-specific error code for programmatic handling ### 502 Bad Gateway Error Bad Gateway - External service error - `timestamp` (datetime, required) — ISO 8601 timestamp when the error occurred - `message` (string, required) — Human-readable error message - `error` (string, required) — Error message (same as message, for backwards compatibility) - `trace_id` (string, required) — Unique trace ID for debugging and support requests - `app_error_code` (string, optional, nullable) — Application-specific error code for programmatic handling ## Types ### CreateMemberDependentAddressRequest - `address_line_1` (string, required) — Primary street address - `city` (string, required) — City name - `state` (enum, required) — Two-letter state code * `AL` - AL * `AK` - AK * `AZ` - AZ * `AR` - AR * `CA` - CA * `CO` - CO * `CT` - CT * `DC` - DC * `DE` - DE * `FL` - FL * `GA` - GA * `HI` - HI * `ID` - ID * `IL` - IL * `IN` - IN * `IA` - IA * `KS` - KS * `KY` - KY * `LA` - LA * `ME` - ME * `MD` - MD * `MA` - MA * `MI` - MI * `MN` - MN * `MS` - MS * `MO` - MO * `MT` - MT * `NE` - NE * `NV` - NV * `NH` - NH * `NJ` - NJ * `NM` - NM * `NY` - NY * `NC` - NC * `ND` - ND * `OH` - OH * `OK` - OK * `OR` - OR * `PA` - PA * `RI` - RI * `SC` - SC * `SD` - SD * `TN` - TN * `TX` - TX * `UT` - UT * `VT` - VT * `VA` - VA * `WA` - WA * `WI` - WI * `WV` - WV * `WY` - WY * `PR` - PR * `GU` - GU * `AS` - AS * `VI` - VI * `MP` - MP * `MH` - MH * `PW` - PW * `FM` - FM * `AE` - AE * `AA` - AA * `AP` - AP - Allowed values: `AL`, `AK`, `AZ`, `AR`, `CA`, `CO`, `CT`, `DC`, `DE`, `FL`, `GA`, `HI`, `ID`, `IL`, `IN`, `IA`, `KS`, `KY`, `LA`, `ME`, `MD`, `MA`, `MI`, `MN`, `MS`, `MO`, `MT`, `NE`, `NV`, `NH`, `NJ`, `NM`, `NY`, `NC`, `ND`, `OH`, `OK`, `OR`, `PA`, `RI`, `SC`, `SD`, `TN`, `TX`, `UT`, `VT`, `VA`, `WA`, `WI`, `WV`, `WY`, `PR`, `GU`, `AS`, `VI`, `MP`, `MH`, `PW`, `FM`, `AE`, `AA`, `AP` - `zipcode` (string, required) — ZIP code - `address_line_2` (string, optional, nullable) — Secondary street address ### SavedMemberDependent Wire serializer for :class:`MemberLegalDependentDTO` (one legal-dependent row). - `member_id` (string, required) — The dependent's own member identifier with 'mbr_' prefix - `primary_member_id` (string, required) — The primary member's identifier with 'mbr_' prefix - `first_name` (string, required) — Dependent's first name - `last_name` (string, required) — Dependent's last name - `relationship` (enum, required) — Relationship of the dependent to the member (e.g., Spouse, Child) * `Spouse` - Spouse * `Child` - Child - Allowed values: `Spouse`, `Child` - `date_of_birth` (date, required) — Date of birth (YYYY-MM-DD) - `age` (integer, required) — Dependent's age in years, derived from date of birth - `legal_dependent_id` (string, required) — Identifier of the dependent relationship, with 'ldep_' prefix - `created` (boolean, required) — True when the relationship was created by this request, false when an existing one was reused - `sex_at_birth` (enum, optional, nullable) — Sex assigned at birth, if provided * `Male` - Male * `Female` - Female * `Other` - Other * `Unknown` - Unknown - Allowed values: `Male`, `Female`, `Other`, `Unknown` ## Examples ### Reused Dependent **Response** ```json { "data": { "member_id": "mbr_AAAAAAAAAAAAAAAAAAAAAg", "primary_member_id": "mbr_AAAAAAAAAAAAAAAAAAAAAQ", "first_name": "Sam", "last_name": "Doe", "relationship": "Child", "date_of_birth": "2015-06-01", "age": 11, "legal_dependent_id": "ldep_AAAAAAAAAAAAAAAAAAAAAQ", "created": false, "sex_at_birth": "Male" } } ``` **SDK Code** ```python Reused Dependent import requests url = "https://api.vitablehealth.com/v1/members/mbr_abc123def456/dependents" headers = {"Authorization": "Bearer "} response = requests.post(url, headers=headers) print(response.json()) ``` ```javascript Reused Dependent const url = 'https://api.vitablehealth.com/v1/members/mbr_abc123def456/dependents'; const options = {method: 'POST', headers: {Authorization: 'Bearer '}}; try { const response = await fetch(url, options); const data = await response.json(); console.log(data); } catch (error) { console.error(error); } ``` ```go Reused Dependent package main import ( "fmt" "net/http" "io" ) func main() { url := "https://api.vitablehealth.com/v1/members/mbr_abc123def456/dependents" req, _ := http.NewRequest("POST", url, nil) req.Header.Add("Authorization", "Bearer ") res, _ := http.DefaultClient.Do(req) defer res.Body.Close() body, _ := io.ReadAll(res.Body) fmt.Println(res) fmt.Println(string(body)) } ``` ```ruby Reused Dependent require 'uri' require 'net/http' url = URI("https://api.vitablehealth.com/v1/members/mbr_abc123def456/dependents") http = Net::HTTP.new(url.host, url.port) http.use_ssl = true request = Net::HTTP::Post.new(url) request["Authorization"] = 'Bearer ' response = http.request(request) puts response.read_body ``` ```java Reused Dependent import com.mashape.unirest.http.HttpResponse; import com.mashape.unirest.http.Unirest; HttpResponse response = Unirest.post("https://api.vitablehealth.com/v1/members/mbr_abc123def456/dependents") .header("Authorization", "Bearer ") .asString(); ``` ```php Reused Dependent request('POST', 'https://api.vitablehealth.com/v1/members/mbr_abc123def456/dependents', [ 'headers' => [ 'Authorization' => 'Bearer ', ], ]); echo $response->getBody(); ``` ```csharp Reused Dependent using RestSharp; var client = new RestClient("https://api.vitablehealth.com/v1/members/mbr_abc123def456/dependents"); var request = new RestRequest(Method.POST); request.AddHeader("Authorization", "Bearer "); IRestResponse response = client.Execute(request); ``` ```swift Reused Dependent import Foundation let headers = ["Authorization": "Bearer "] let request = NSMutableURLRequest(url: NSURL(string: "https://api.vitablehealth.com/v1/members/mbr_abc123def456/dependents")! as URL, cachePolicy: .useProtocolCachePolicy, timeoutInterval: 10.0) request.httpMethod = "POST" request.allHTTPHeaderFields = headers let session = URLSession.shared let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in if (error != nil) { print(error as Any) } else { let httpResponse = response as? HTTPURLResponse print(httpResponse) } }) dataTask.resume() ``` ### Created Dependent **Response** ```json { "data": { "member_id": "mbr_AAAAAAAAAAAAAAAAAAAAAg", "primary_member_id": "mbr_AAAAAAAAAAAAAAAAAAAAAQ", "first_name": "Sam", "last_name": "Doe", "relationship": "Child", "date_of_birth": "2015-06-01", "age": 11, "legal_dependent_id": "ldep_AAAAAAAAAAAAAAAAAAAAAQ", "created": true, "sex_at_birth": "Male" } } ``` **SDK Code** ```python Created Dependent import requests url = "https://api.vitablehealth.com/v1/members/mbr_abc123def456/dependents" headers = {"Authorization": "Bearer "} response = requests.post(url, headers=headers) print(response.json()) ``` ```javascript Created Dependent const url = 'https://api.vitablehealth.com/v1/members/mbr_abc123def456/dependents'; const options = {method: 'POST', headers: {Authorization: 'Bearer '}}; try { const response = await fetch(url, options); const data = await response.json(); console.log(data); } catch (error) { console.error(error); } ``` ```go Created Dependent package main import ( "fmt" "net/http" "io" ) func main() { url := "https://api.vitablehealth.com/v1/members/mbr_abc123def456/dependents" req, _ := http.NewRequest("POST", url, nil) req.Header.Add("Authorization", "Bearer ") res, _ := http.DefaultClient.Do(req) defer res.Body.Close() body, _ := io.ReadAll(res.Body) fmt.Println(res) fmt.Println(string(body)) } ``` ```ruby Created Dependent require 'uri' require 'net/http' url = URI("https://api.vitablehealth.com/v1/members/mbr_abc123def456/dependents") http = Net::HTTP.new(url.host, url.port) http.use_ssl = true request = Net::HTTP::Post.new(url) request["Authorization"] = 'Bearer ' response = http.request(request) puts response.read_body ``` ```java Created Dependent import com.mashape.unirest.http.HttpResponse; import com.mashape.unirest.http.Unirest; HttpResponse response = Unirest.post("https://api.vitablehealth.com/v1/members/mbr_abc123def456/dependents") .header("Authorization", "Bearer ") .asString(); ``` ```php Created Dependent request('POST', 'https://api.vitablehealth.com/v1/members/mbr_abc123def456/dependents', [ 'headers' => [ 'Authorization' => 'Bearer ', ], ]); echo $response->getBody(); ``` ```csharp Created Dependent using RestSharp; var client = new RestClient("https://api.vitablehealth.com/v1/members/mbr_abc123def456/dependents"); var request = new RestRequest(Method.POST); request.AddHeader("Authorization", "Bearer "); IRestResponse response = client.Execute(request); ``` ```swift Created Dependent import Foundation let headers = ["Authorization": "Bearer "] let request = NSMutableURLRequest(url: NSURL(string: "https://api.vitablehealth.com/v1/members/mbr_abc123def456/dependents")! as URL, cachePolicy: .useProtocolCachePolicy, timeoutInterval: 10.0) request.httpMethod = "POST" request.allHTTPHeaderFields = headers let session = URLSession.shared let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in if (error != nil) { print(error as Any) } else { let httpResponse = response as? HTTPURLResponse print(httpResponse) } }) dataTask.resume() ``` ### Create Child Dependent **Request** ```json { "first_name": "Sam", "last_name": "Doe", "date_of_birth": "2015-06-01", "relationship": "Child", "address": { "address_line_1": "123 Main St", "city": "Detroit", "state": "MI", "zipcode": "48201", "address_line_2": null }, "sex_at_birth": "Male" } ``` **Response** ```json { "data": { "member_id": "mbr_AAAAAAAAAAAAAAAAAAAAAg", "primary_member_id": "mbr_AAAAAAAAAAAAAAAAAAAAAQ", "first_name": "Sam", "last_name": "Doe", "relationship": "Child", "date_of_birth": "2015-06-01", "age": 11, "legal_dependent_id": "ldep_AAAAAAAAAAAAAAAAAAAAAQ", "created": false, "sex_at_birth": "Male" } } ``` **SDK Code** ```python Create Child Dependent import requests url = "https://api.vitablehealth.com/v1/members/mbr_abc123def456/dependents" payload = { "first_name": "Sam", "last_name": "Doe", "date_of_birth": "2015-06-01", "relationship": "Child", "address": { "address_line_1": "123 Main St", "city": "Detroit", "state": "MI", "zipcode": "48201", "address_line_2": None }, "sex_at_birth": "Male" } headers = { "Authorization": "Bearer ", "Content-Type": "application/json" } response = requests.post(url, json=payload, headers=headers) print(response.json()) ``` ```javascript Create Child Dependent const url = 'https://api.vitablehealth.com/v1/members/mbr_abc123def456/dependents'; const options = { method: 'POST', headers: {Authorization: 'Bearer ', 'Content-Type': 'application/json'}, body: '{"first_name":"Sam","last_name":"Doe","date_of_birth":"2015-06-01","relationship":"Child","address":{"address_line_1":"123 Main St","city":"Detroit","state":"MI","zipcode":"48201","address_line_2":null},"sex_at_birth":"Male"}' }; try { const response = await fetch(url, options); const data = await response.json(); console.log(data); } catch (error) { console.error(error); } ``` ```go Create Child Dependent package main import ( "fmt" "strings" "net/http" "io" ) func main() { url := "https://api.vitablehealth.com/v1/members/mbr_abc123def456/dependents" payload := strings.NewReader("{\n \"first_name\": \"Sam\",\n \"last_name\": \"Doe\",\n \"date_of_birth\": \"2015-06-01\",\n \"relationship\": \"Child\",\n \"address\": {\n \"address_line_1\": \"123 Main St\",\n \"city\": \"Detroit\",\n \"state\": \"MI\",\n \"zipcode\": \"48201\",\n \"address_line_2\": null\n },\n \"sex_at_birth\": \"Male\"\n}") req, _ := http.NewRequest("POST", url, payload) req.Header.Add("Authorization", "Bearer ") req.Header.Add("Content-Type", "application/json") res, _ := http.DefaultClient.Do(req) defer res.Body.Close() body, _ := io.ReadAll(res.Body) fmt.Println(res) fmt.Println(string(body)) } ``` ```ruby Create Child Dependent require 'uri' require 'net/http' url = URI("https://api.vitablehealth.com/v1/members/mbr_abc123def456/dependents") http = Net::HTTP.new(url.host, url.port) http.use_ssl = true request = Net::HTTP::Post.new(url) request["Authorization"] = 'Bearer ' request["Content-Type"] = 'application/json' request.body = "{\n \"first_name\": \"Sam\",\n \"last_name\": \"Doe\",\n \"date_of_birth\": \"2015-06-01\",\n \"relationship\": \"Child\",\n \"address\": {\n \"address_line_1\": \"123 Main St\",\n \"city\": \"Detroit\",\n \"state\": \"MI\",\n \"zipcode\": \"48201\",\n \"address_line_2\": null\n },\n \"sex_at_birth\": \"Male\"\n}" response = http.request(request) puts response.read_body ``` ```java Create Child Dependent import com.mashape.unirest.http.HttpResponse; import com.mashape.unirest.http.Unirest; HttpResponse response = Unirest.post("https://api.vitablehealth.com/v1/members/mbr_abc123def456/dependents") .header("Authorization", "Bearer ") .header("Content-Type", "application/json") .body("{\n \"first_name\": \"Sam\",\n \"last_name\": \"Doe\",\n \"date_of_birth\": \"2015-06-01\",\n \"relationship\": \"Child\",\n \"address\": {\n \"address_line_1\": \"123 Main St\",\n \"city\": \"Detroit\",\n \"state\": \"MI\",\n \"zipcode\": \"48201\",\n \"address_line_2\": null\n },\n \"sex_at_birth\": \"Male\"\n}") .asString(); ``` ```php Create Child Dependent request('POST', 'https://api.vitablehealth.com/v1/members/mbr_abc123def456/dependents', [ 'body' => '{ "first_name": "Sam", "last_name": "Doe", "date_of_birth": "2015-06-01", "relationship": "Child", "address": { "address_line_1": "123 Main St", "city": "Detroit", "state": "MI", "zipcode": "48201", "address_line_2": null }, "sex_at_birth": "Male" }', 'headers' => [ 'Authorization' => 'Bearer ', 'Content-Type' => 'application/json', ], ]); echo $response->getBody(); ``` ```csharp Create Child Dependent using RestSharp; var client = new RestClient("https://api.vitablehealth.com/v1/members/mbr_abc123def456/dependents"); var request = new RestRequest(Method.POST); request.AddHeader("Authorization", "Bearer "); request.AddHeader("Content-Type", "application/json"); request.AddParameter("application/json", "{\n \"first_name\": \"Sam\",\n \"last_name\": \"Doe\",\n \"date_of_birth\": \"2015-06-01\",\n \"relationship\": \"Child\",\n \"address\": {\n \"address_line_1\": \"123 Main St\",\n \"city\": \"Detroit\",\n \"state\": \"MI\",\n \"zipcode\": \"48201\",\n \"address_line_2\": null\n },\n \"sex_at_birth\": \"Male\"\n}", ParameterType.RequestBody); IRestResponse response = client.Execute(request); ``` ```swift Create Child Dependent import Foundation let headers = [ "Authorization": "Bearer ", "Content-Type": "application/json" ] let parameters = [ "first_name": "Sam", "last_name": "Doe", "date_of_birth": "2015-06-01", "relationship": "Child", "address": [ "address_line_1": "123 Main St", "city": "Detroit", "state": "MI", "zipcode": "48201", "address_line_2": ], "sex_at_birth": "Male" ] as [String : Any] let postData = JSONSerialization.data(withJSONObject: parameters, options: []) let request = NSMutableURLRequest(url: NSURL(string: "https://api.vitablehealth.com/v1/members/mbr_abc123def456/dependents")! as URL, cachePolicy: .useProtocolCachePolicy, timeoutInterval: 10.0) request.httpMethod = "POST" request.allHTTPHeaderFields = headers request.httpBody = postData as Data let session = URLSession.shared let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in if (error != nil) { print(error as Any) } else { let httpResponse = response as? HTTPURLResponse print(httpResponse) } }) dataTask.resume() ```