---
title: "Upload lead records"
method: POST
path: "/v2/leads/upload"
tags: ["Leads"]
---

# Upload lead records

`POST /v2/leads/upload`

## Request

- Base URL: `https://api.carecycle.ai`
- URL: `https://api.carecycle.ai/v2/leads/upload`
- Auth: API key in header `x-api-key`

Add new leads to careCycle. To track which source each lead came from, create the source in careCycle first, then pass sourceId and optional leadCost with each record.

**Response**: For each successfully uploaded record, `results` contains the full customer record (same shape as the `customer.created`/`customer.updated` webhook). Lead upload does not handle policies, so no policies are returned; use `/v2/sync/aca` or `/v2/sync/medicare` for policies.

## Request body

- PostV2LeadsUploadRequestBody
  - `records` object[], required: Array of lead records to upload (1-200)
    - `firstName` string, nullable: Customer first name
    - `lastName` string, nullable: Customer last name
    - `email` string, nullable
    - `postalCode` string, nullable: Customer postal code. Required if timezone is not provided (for TCPA compliance).
    - `timezone` string, nullable: Customer timezone. Required if postalCode is not provided (for TCPA compliance). Accepts IANA format (America/New_York) or abbreviations (EST, CST, MST, PST).
    - `state` string, nullable
    - `city` string, nullable
    - `county` string, nullable
    - `address` string, nullable
    - `address2` string, nullable
    - `dateOfBirth` string, nullable: Customer date of birth. Format: MM-DD-YYYY, MM/DD/YYYY, or YYYY-MM-DD
    - `language` string, nullable
    - `gender` 'Male' | 'Female' | 'Non-Binary' | 'Other' | 'Prefer Not to Say' | 'null', nullable
    - `maritalStatus` 'Single' | 'Married' | 'Divorced' | 'Widowed' | 'Separated' | 'Domestic Partnership' | 'null', nullable
    - `filingStatus` string, nullable
    - `dependentCount` integer, nullable
    - `householdIncome` integer, nullable
    - `isDecisionMaker` boolean, nullable
    - `medicaid` boolean, nullable
    - `medicaidNumber` string, nullable
    - `veteran` boolean, nullable
    - `vaNumber` string, nullable
    - `socialSecurityDisability` boolean, nullable
    - `heightInches` integer, nullable
    - `weightPounds` integer, nullable
    - `smokerStatus` boolean, nullable
    - `carrierAssignedCustomerId` string, nullable: Carrier-assigned customer ID
    - `healthSherpaCustomerId` string, nullable: Health Sherpa customer ID
    - `mbiNumber` string, nullable: Medicare Beneficiary Identifier
    - `doNotCall` boolean, nullable
    - `doNotSMS` boolean, nullable
    - `doNotEmail` boolean, nullable
    - `doNotMail` boolean, nullable
    - `phoneNumber` string, required: Customer phone number (required). Accepts: +1XXXXXXXXXX, XXXXXXXXXX, (XXX) XXX-XXXX
    - `externalId` string, nullable: Your external system identifier for this customer
    - `sourceId` string, nullable: Public source identifier configured in careCycle. The source must exist before leads are uploaded. You may also pass the source UUID.
    - `leadCost` number, nullable: Optional per-lead cost for dynamic CPL source billing. If omitted, the source default lead cost is used.
    - `customFields` object[]: Custom field values (max 50) Your Custom Field keys can be found [here](https://app.carecycle.ai/settings/crm-settings/custom-fields/customer) in your settings
      - `fieldKey` string, required: Custom field key (e.g., 'lead_source', 'utm_campaign')
      - `value` union, required: Value for the custom field
        - string
        - number
        - boolean
        - string[]

## Response `200`

POST /v2/leads/upload Positive response

- PostV2LeadsUploadPositiveResponse
  - `succeeded` number, required: Number of successfully uploaded records
  - `failed` number, required: Number of failed records
  - `results` object[], required: Full customer record for each successfully uploaded record
    - `id` string, required
    - `createdAt` string, date-time, nullable, required: Customer creation time. ISO 8601 timestamp
    - `updatedAt` string, date-time, nullable, required: Customer last update time. ISO 8601 timestamp
    - `deletedAt` string, date-time, nullable, required: Customer deletion time. ISO 8601 timestamp
    - `externalId` string, nullable, required
    - `status` string, nullable, required
    - `firstName` string, nullable, required
    - `middleName` string, nullable, required
    - `lastName` string, nullable, required
    - `salutation` string, nullable, required
    - `suffix` string, nullable, required
    - `preferredName` string, nullable, required
    - `phoneNumber` string, required
    - `isPhonePrimary` boolean, required
    - `lineType` string, nullable, required
    - `email` string, nullable, required
    - `dateOfBirth` string, date, nullable, required: Customer date of birth. Canonical format: YYYY-MM-DD
    - `language` string, nullable, required
    - `ethnicity` string, nullable, required
    - `gender` string, nullable, required
    - `maritalStatus` string, nullable, required
    - `address` string, nullable, required
    - `address2` string, nullable, required
    - `city` string, nullable, required
    - `county` string, nullable, required
    - `state` string, nullable, required
    - `postalCode` string, nullable, required
    - `timezone` string, nullable, required
    - `mbiNumber` string, nullable, required
    - `medicareCard` boolean, nullable, required
    - `medicarePartADate` string, date, nullable, required: Medicare Part A effective date. Canonical format: YYYY-MM-DD
    - `medicarePartBDate` string, date, nullable, required: Medicare Part B effective date. Canonical format: YYYY-MM-DD
    - `hasMedicaid` boolean, nullable, required
    - `medicaidNumber` string, nullable, required
    - `socialSecurityDisability` boolean, nullable, required
    - `heightInches` number, nullable, required
    - `weightPounds` number, nullable, required
    - `smokerStatus` boolean, nullable, required
    - `veteran` boolean, nullable, required
    - `vaNumber` string, nullable, required
    - `householdIncome` number, nullable, required
    - `annualIncome` number, nullable, required
    - `filingStatus` string, nullable, required
    - `dependentCount` number, nullable, required
    - `subsidyEligible` boolean, nullable, required
    - `subsidyAmount` number, nullable, required
    - `carrierAssignedCustomerId` string, nullable, required
    - `agentName` string, nullable, required
    - `agentNpn` number, nullable, required
    - `assignedUser` object, nullable, required
      - `id` string, required
      - `name` string, required
      - `email` string, required
      - `npn` string, nullable, required
      - `role` string, required
      - `licensedStates` string[], nullable, required
    - `doNotCall` boolean, nullable, required
    - `doNotSMS` boolean, nullable, required
    - `doNotEmail` boolean, nullable, required
    - `doNotMail` boolean, nullable, required
    - `testCustomer` boolean, required
  - `errors` object[], required: Errors for failed records (empty if all succeeded)
    - `id` string, uuid, nullable, required
    - `externalId` string, nullable, required
    - `error` string, required: Error message

## Other responses

- `400`: POST /v2/leads/upload Negative response 400
- `401`: POST /v2/leads/upload Negative response 401
- `403`: POST /v2/leads/upload Negative response 403
- `404`: POST /v2/leads/upload Negative response 404
- `409`: POST /v2/leads/upload Negative response 409
- `422`: POST /v2/leads/upload Negative response 422
- `429`: POST /v2/leads/upload Negative response 429
- `500`: POST /v2/leads/upload Negative response 500
- `502`: POST /v2/leads/upload Negative response 502
- `503`: POST /v2/leads/upload Negative response 503

---

[API](https://skmtc.dev/carecycle/apis/carecycle-public-api.md) - [All operations](https://skmtc.dev/carecycle/apis/carecycle-public-api/llms.txt) - [OpenAPI document](https://skmtc.dev/carecycle/apis/carecycle-public-api/revisions/db390c743c36?raw)