> For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://developer.vitablehealth.com/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://developer.vitablehealth.com/_mcp/server. # Submit Census Sync POST https://api.vitablehealth.com/v1/employers/{employer_id}/census-sync Content-Type: application/json Submits a census sync payload for the specified employer. The employees in the payload will be queued for processing. Returns an accepted response with the timestamp of acceptance. Reference: https://developer.vitablehealth.com/api/employers/submit-census-sync ## 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 - `employer_id` (string, required) — Unique employer identifier (empr_*) ### Body (application/json) This endpoint expects a CensusSyncRequest. - `employees` (list of CensusSyncEmployeeRequest, required) ## Response ### 202 - `data` (CensusSyncResponse, required) — The census sync request, including its current processing status. ## Errors ### 400 Bad Request Error Bad Request - Invalid input or validation 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 ### 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 Forbidden - Insufficient permissions for this resource - `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 Not Found - The requested resource does not exist - `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 ### 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 ### CensusSyncEmployeeRequest - `first_name` (string, required) — Employee's legal first name. - `last_name` (string, required) — Employee's legal last name. - `date_of_birth` (date, required) — Employee's date of birth as `YYYY-MM-DD`. Used to match existing members. - `email` (string, required) — Employee's work email address. Vitable sends enrollment invitations here. - `reference_id` (string, optional, nullable) — Your own identifier for this employee. Vitable echoes it back on sync results so you can match failures to your records. - `phone` (string, optional, nullable) — Phone number - `address` (CensusSyncEmployeeAddressRequest, optional, nullable) — Employee's home address, used to determine plan availability. - `start_date` (date, optional, nullable) — Employment start date as `YYYY-MM-DD`. Drives benefit eligibility dates. - `employee_class` (enum, optional, nullable) — Employee class used to match the employer's eligibility policy rules. - Allowed values: `Full Time`, `Part Time`, `Temporary`, `Intern`, `Seasonal`, `Individual Contractor` - `compensation_type` (enum, optional, nullable) — Whether the employee is salaried or hourly. - Allowed values: `Salary`, `Hourly` ### CensusSyncResponse - `employer_id` (string, required) — Employer the census sync was submitted for (`empr_*`). - `accepted_at` (datetime, required) — When Vitable accepted the census sync for processing (RFC 3339). ### CensusSyncEmployeeAddressRequest - `address_line_1` (string, required) — Street address, including house or building number. - `city` (string, required) — City or town name. - `state` (enum, required) — US state or territory for the address. - 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) — US postal code, either five digits or ZIP+4. - `address_line_2` (string, optional, nullable) — Apartment, suite, unit, or floor. Omit if not applicable. ## Examples **Request** ```json { "employees": [ { "first_name": "Jane", "last_name": "Doe", "date_of_birth": "1990-05-15", "email": "jane.doe@acme.com", "reference_id": "EMP-001", "phone": "4155550100", "address": { "address_line_1": "123 Main Street", "city": "San Francisco", "state": "CA", "zipcode": "94102", "address_line_2": "Apt 4B" }, "start_date": "2024-01-15", "employee_class": "Full Time", "compensation_type": "Salary" }, { "first_name": "John", "last_name": "Smith", "date_of_birth": "1985-11-20", "email": "john.smith@acme.com", "phone": "4155550101", "start_date": "2024-03-01", "employee_class": "Part Time", "compensation_type": "Hourly" } ] } ``` **Response** ```json { "data": { "employer_id": "string", "accepted_at": "2024-01-15T09:30:00Z" } } ``` **SDK Code** ```python Census Sync Request import requests url = "https://api.vitablehealth.com/v1/employers/empr_abc123def456/census-sync" payload = { "employees": [ { "first_name": "Jane", "last_name": "Doe", "date_of_birth": "1990-05-15", "email": "jane.doe@acme.com", "reference_id": "EMP-001", "phone": "4155550100", "address": { "address_line_1": "123 Main Street", "city": "San Francisco", "state": "CA", "zipcode": "94102", "address_line_2": "Apt 4B" }, "start_date": "2024-01-15", "employee_class": "Full Time", "compensation_type": "Salary" }, { "first_name": "John", "last_name": "Smith", "date_of_birth": "1985-11-20", "email": "john.smith@acme.com", "phone": "4155550101", "start_date": "2024-03-01", "employee_class": "Part Time", "compensation_type": "Hourly" } ] } headers = { "Authorization": "Bearer ", "Content-Type": "application/json" } response = requests.post(url, json=payload, headers=headers) print(response.json()) ``` ```javascript Census Sync Request const url = 'https://api.vitablehealth.com/v1/employers/empr_abc123def456/census-sync'; const options = { method: 'POST', headers: {Authorization: 'Bearer ', 'Content-Type': 'application/json'}, body: '{"employees":[{"first_name":"Jane","last_name":"Doe","date_of_birth":"1990-05-15","email":"jane.doe@acme.com","reference_id":"EMP-001","phone":"4155550100","address":{"address_line_1":"123 Main Street","city":"San Francisco","state":"CA","zipcode":"94102","address_line_2":"Apt 4B"},"start_date":"2024-01-15","employee_class":"Full Time","compensation_type":"Salary"},{"first_name":"John","last_name":"Smith","date_of_birth":"1985-11-20","email":"john.smith@acme.com","phone":"4155550101","start_date":"2024-03-01","employee_class":"Part Time","compensation_type":"Hourly"}]}' }; try { const response = await fetch(url, options); const data = await response.json(); console.log(data); } catch (error) { console.error(error); } ``` ```go Census Sync Request package main import ( "fmt" "strings" "net/http" "io" ) func main() { url := "https://api.vitablehealth.com/v1/employers/empr_abc123def456/census-sync" payload := strings.NewReader("{\n \"employees\": [\n {\n \"first_name\": \"Jane\",\n \"last_name\": \"Doe\",\n \"date_of_birth\": \"1990-05-15\",\n \"email\": \"jane.doe@acme.com\",\n \"reference_id\": \"EMP-001\",\n \"phone\": \"4155550100\",\n \"address\": {\n \"address_line_1\": \"123 Main Street\",\n \"city\": \"San Francisco\",\n \"state\": \"CA\",\n \"zipcode\": \"94102\",\n \"address_line_2\": \"Apt 4B\"\n },\n \"start_date\": \"2024-01-15\",\n \"employee_class\": \"Full Time\",\n \"compensation_type\": \"Salary\"\n },\n {\n \"first_name\": \"John\",\n \"last_name\": \"Smith\",\n \"date_of_birth\": \"1985-11-20\",\n \"email\": \"john.smith@acme.com\",\n \"phone\": \"4155550101\",\n \"start_date\": \"2024-03-01\",\n \"employee_class\": \"Part Time\",\n \"compensation_type\": \"Hourly\"\n }\n ]\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 Census Sync Request require 'uri' require 'net/http' url = URI("https://api.vitablehealth.com/v1/employers/empr_abc123def456/census-sync") 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 \"employees\": [\n {\n \"first_name\": \"Jane\",\n \"last_name\": \"Doe\",\n \"date_of_birth\": \"1990-05-15\",\n \"email\": \"jane.doe@acme.com\",\n \"reference_id\": \"EMP-001\",\n \"phone\": \"4155550100\",\n \"address\": {\n \"address_line_1\": \"123 Main Street\",\n \"city\": \"San Francisco\",\n \"state\": \"CA\",\n \"zipcode\": \"94102\",\n \"address_line_2\": \"Apt 4B\"\n },\n \"start_date\": \"2024-01-15\",\n \"employee_class\": \"Full Time\",\n \"compensation_type\": \"Salary\"\n },\n {\n \"first_name\": \"John\",\n \"last_name\": \"Smith\",\n \"date_of_birth\": \"1985-11-20\",\n \"email\": \"john.smith@acme.com\",\n \"phone\": \"4155550101\",\n \"start_date\": \"2024-03-01\",\n \"employee_class\": \"Part Time\",\n \"compensation_type\": \"Hourly\"\n }\n ]\n}" response = http.request(request) puts response.read_body ``` ```java Census Sync Request import com.mashape.unirest.http.HttpResponse; import com.mashape.unirest.http.Unirest; HttpResponse response = Unirest.post("https://api.vitablehealth.com/v1/employers/empr_abc123def456/census-sync") .header("Authorization", "Bearer ") .header("Content-Type", "application/json") .body("{\n \"employees\": [\n {\n \"first_name\": \"Jane\",\n \"last_name\": \"Doe\",\n \"date_of_birth\": \"1990-05-15\",\n \"email\": \"jane.doe@acme.com\",\n \"reference_id\": \"EMP-001\",\n \"phone\": \"4155550100\",\n \"address\": {\n \"address_line_1\": \"123 Main Street\",\n \"city\": \"San Francisco\",\n \"state\": \"CA\",\n \"zipcode\": \"94102\",\n \"address_line_2\": \"Apt 4B\"\n },\n \"start_date\": \"2024-01-15\",\n \"employee_class\": \"Full Time\",\n \"compensation_type\": \"Salary\"\n },\n {\n \"first_name\": \"John\",\n \"last_name\": \"Smith\",\n \"date_of_birth\": \"1985-11-20\",\n \"email\": \"john.smith@acme.com\",\n \"phone\": \"4155550101\",\n \"start_date\": \"2024-03-01\",\n \"employee_class\": \"Part Time\",\n \"compensation_type\": \"Hourly\"\n }\n ]\n}") .asString(); ``` ```php Census Sync Request request('POST', 'https://api.vitablehealth.com/v1/employers/empr_abc123def456/census-sync', [ 'body' => '{ "employees": [ { "first_name": "Jane", "last_name": "Doe", "date_of_birth": "1990-05-15", "email": "jane.doe@acme.com", "reference_id": "EMP-001", "phone": "4155550100", "address": { "address_line_1": "123 Main Street", "city": "San Francisco", "state": "CA", "zipcode": "94102", "address_line_2": "Apt 4B" }, "start_date": "2024-01-15", "employee_class": "Full Time", "compensation_type": "Salary" }, { "first_name": "John", "last_name": "Smith", "date_of_birth": "1985-11-20", "email": "john.smith@acme.com", "phone": "4155550101", "start_date": "2024-03-01", "employee_class": "Part Time", "compensation_type": "Hourly" } ] }', 'headers' => [ 'Authorization' => 'Bearer ', 'Content-Type' => 'application/json', ], ]); echo $response->getBody(); ``` ```csharp Census Sync Request using RestSharp; var client = new RestClient("https://api.vitablehealth.com/v1/employers/empr_abc123def456/census-sync"); var request = new RestRequest(Method.POST); request.AddHeader("Authorization", "Bearer "); request.AddHeader("Content-Type", "application/json"); request.AddParameter("application/json", "{\n \"employees\": [\n {\n \"first_name\": \"Jane\",\n \"last_name\": \"Doe\",\n \"date_of_birth\": \"1990-05-15\",\n \"email\": \"jane.doe@acme.com\",\n \"reference_id\": \"EMP-001\",\n \"phone\": \"4155550100\",\n \"address\": {\n \"address_line_1\": \"123 Main Street\",\n \"city\": \"San Francisco\",\n \"state\": \"CA\",\n \"zipcode\": \"94102\",\n \"address_line_2\": \"Apt 4B\"\n },\n \"start_date\": \"2024-01-15\",\n \"employee_class\": \"Full Time\",\n \"compensation_type\": \"Salary\"\n },\n {\n \"first_name\": \"John\",\n \"last_name\": \"Smith\",\n \"date_of_birth\": \"1985-11-20\",\n \"email\": \"john.smith@acme.com\",\n \"phone\": \"4155550101\",\n \"start_date\": \"2024-03-01\",\n \"employee_class\": \"Part Time\",\n \"compensation_type\": \"Hourly\"\n }\n ]\n}", ParameterType.RequestBody); IRestResponse response = client.Execute(request); ``` ```swift Census Sync Request import Foundation let headers = [ "Authorization": "Bearer ", "Content-Type": "application/json" ] let parameters = ["employees": [ [ "first_name": "Jane", "last_name": "Doe", "date_of_birth": "1990-05-15", "email": "jane.doe@acme.com", "reference_id": "EMP-001", "phone": "4155550100", "address": [ "address_line_1": "123 Main Street", "city": "San Francisco", "state": "CA", "zipcode": "94102", "address_line_2": "Apt 4B" ], "start_date": "2024-01-15", "employee_class": "Full Time", "compensation_type": "Salary" ], [ "first_name": "John", "last_name": "Smith", "date_of_birth": "1985-11-20", "email": "john.smith@acme.com", "phone": "4155550101", "start_date": "2024-03-01", "employee_class": "Part Time", "compensation_type": "Hourly" ] ]] as [String : Any] let postData = JSONSerialization.data(withJSONObject: parameters, options: []) let request = NSMutableURLRequest(url: NSURL(string: "https://api.vitablehealth.com/v1/employers/empr_abc123def456/census-sync")! 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() ```