Upload lead records
Upload lead records. For source attribution, 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.
Authorization
x-api-key API key required for authentication.
Keys begin with 'cc_' prefix. Get your API key from the Developer Dashboard.
In: header
Request Body
application/json
POST /v2/leads/upload Request body
TypeScript Definitions
Use the request body type in TypeScript.
Array of lead records to upload (1-200)
Customer phone number (required). Accepts: +1XXXXXXXXXX, XXXXXXXXXX, (XXX) XXX-XXXX
Customer first name
Customer last name
Customer postal code. Required if timezone is not provided (for TCPA compliance).
Customer timezone. Required if postalCode is not provided (for TCPA compliance). Accepts IANA format (America/New_York) or abbreviations (EST, CST, MST, PST).
Customer date of birth. Format: MM-DD-YYYY or MM/DD/YYYY
Carrier-assigned customer ID
Health Sherpa customer ID
Medicare Beneficiary Identifier
Your external system identifier for this customer
Public source identifier configured in careCycle. The source must exist before leads are uploaded. You may also pass the source UUID.
Optional per-lead cost for dynamic CPL source billing. If omitted, the source default lead cost is used.
Custom field values (max 50) Your Custom Field keys can be found here in your settings
Custom field key (e.g., 'lead_source', 'utm_campaign')
Value for the custom field
Response Body
application/json
application/json
application/json
application/json
application/json
application/json
application/json
application/json
curl -X POST "https://api.carecycle.ai/v2/leads/upload" \ -H "Content-Type: application/json" \ -d '{ "records": [ { "phoneNumber": "string" } ] }'{
"succeeded": 0,
"failed": 0,
"results": [
{
"id": "string",
"createdAt": "string",
"updatedAt": "string",
"externalId": "string",
"status": "string",
"firstName": "string",
"middleName": "string",
"lastName": "string",
"salutation": "string",
"suffix": "string",
"preferredName": "string",
"phoneNumber": "string",
"lineType": "string",
"email": "string",
"dateOfBirth": "string",
"language": "string",
"ethnicity": "string",
"gender": "string",
"maritalStatus": "string",
"address": "string",
"address2": "string",
"city": "string",
"county": "string",
"state": "string",
"postalCode": "string",
"timezone": "string",
"mbiNumber": "string",
"medicareCard": true,
"medicarePartADate": "string",
"medicarePartBDate": "string",
"hasMedicaid": true,
"medicaidNumber": "string",
"socialSecurityDisability": true,
"veteran": true,
"vaNumber": "string",
"householdIncome": 0,
"annualIncome": 0,
"filingStatus": "string",
"dependentCount": 0,
"subsidyEligible": true,
"subsidyAmount": 0,
"carrierAssignedCustomerId": "string",
"agentName": "string",
"agentNpn": 0,
"assignedUser": {
"id": "string",
"name": "string",
"email": "string",
"npn": "string",
"role": "string",
"licensedStates": [
"string"
]
},
"doNotCall": true,
"doNotSMS": true,
"doNotEmail": true,
"doNotMail": true,
"testCustomer": true
}
],
"errors": [
{
"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"externalId": "string",
"error": "string"
}
]
}{
"message": "string",
"code": "string"
}{
"message": "string",
"code": "string"
}{
"message": "string",
"code": "string"
}{
"message": "string",
"code": "string"
}{
"message": "string",
"code": "VALIDATION_ERROR",
"errors": [
{
"path": [
"string"
],
"message": "string",
"expected": "string",
"received": "string",
"code": "string"
}
],
"failedRecords": [
{
"index": 0,
"phoneNumber": "string",
"firstName": "string",
"lastName": "string",
"externalId": "string"
}
]
}{
"message": "string",
"code": "string",
"retryAfter": 0
}{
"message": "string",
"code": "string"
}