Skip to navigation

Submit Leads

View as Markdown

Submit leads with POST /api/lead-receive-service/agent/receiveLead/{agentId}.

Request body

The example below includes dynamicVariables, which is optional. Its appointment_date key must first be registered in the portal as a date variable; leave dynamicVariables out if you do not use dynamic variables.

{
"leads": [
{
"phoneNumber": "+15551234567",
"firstName": "Jane",
"lastName": "Doe",
"salesforceId": "003xx000004TmiQAAS",
"campaignType": "demo_followup",
"customData": {
"leadId": "LEAD-001"
},
"dynamicVariables": {
"appointment_date": "2026-12-03"
}
}
],
"options": {
"priority": "normal",
"enableAMD": false,
"webhookUrl": "https://example.com/simz/lead-results"
}
}

Lead object

FieldTypeDescription
phoneNumberstringRequired. Lead phone number. E.164 is recommended.
firstNamestringOptional.
lastNamestringOptional.
emailstringOptional.
salesforceIdstringOptional CRM record ID.
campaignTypestringOptional campaign identifier.
customDataobjectOptional. Your own metadata. It must be a JSON object. See Custom Data.
dynamicVariablesobjectOptional. Values for the variables your company registered, as key: value pairs. See Dynamic Variables.

customData must be a JSON object. A lead whose customData is a string (including a string that holds JSON), an array, a number, or a boolean is rejected with the reason customData must be a JSON object.

Every key in dynamicVariables must be registered in the portal under Agents > Variables, and every value must fit the type of its variable. A lead that fails this check is rejected. See Rejected leads.

Credit preflight check

After validating the request and verifying the agent, SimZ checks the company’s available credit balance before creating or queueing a lead batch. If the balance is zero or below, the batch is not created and no leads are queued — the request returns 402 with code: "INSUFFICIENT_CREDITS". Add credits to the account before resubmitting. See Errors and Rate Limits for the full response shape.

Response and batchId

When SimZ accepts one or more leads, the response includes a batchId:

{
"success": true,
"message": "Leads received and queued successfully",
"data": {
"batchId": "batch_123",
"agentId": "agent_123",
"agentName": "Spring Outreach",
"totalLeads": 25,
"acceptedLeads": 25,
"rejectedLeads": 0,
"estimatedStartTime": "2026-07-06T18:30:00Z",
"rejectedLeadDetails": []
}
}

Persist the batchId with your CRM record or campaign run. You need it to:

  • check batch status with GET /api/lead-receive-service/agent/batches/{batchId}
  • pause, resume, or cancel remaining accepted backlog

See Batch Management for the full control flow.

Partial success

If some leads are valid and others are rejected, SimZ can return 207 with accepted and rejected counts. When any leads are accepted, a batchId is still returned for the accepted portion.

Rejected leads

Each rejected lead is listed in data.rejectedLeadDetails with a reason and, when the lead had one, its phoneNumber. A lead rejected by the dynamic variables check also carries a code and the keys that caused the rejection:

{
"success": true,
"message": "Some leads were rejected",
"data": {
"batchId": "batch_123",
"agentId": "agent_123",
"agentName": "Spring Outreach",
"totalLeads": 3,
"acceptedLeads": 1,
"rejectedLeads": 2,
"estimatedStartTime": "2026-07-06T18:30:00Z",
"rejectedLeadDetails": [
{
"phoneNumber": "+15557654321",
"code": "DYNAMIC_VARIABLES_INVALID",
"reason": "Lead rejected: unknown variables: promo_cod; missing required: appointment_date. Create variables in the portal under Agents > Variables.",
"unknownVariables": ["promo_cod"],
"missingVariables": ["appointment_date"],
"invalidVariables": []
},
{
"phoneNumber": "+15559876543",
"reason": "customData must be a JSON object"
}
]
}
}
FieldMeaning
codeDYNAMIC_VARIABLES_INVALID when the lead was rejected by the dynamic variables check.
unknownVariablesKeys in dynamicVariables that are not registered for your company.
missingVariablesMust variables that the outbound prompt refers to and that the lead did not send.
invalidVariablesKeys whose value was not accepted, each with a key and a reason code such as too_long or not_a_date.

The response never contains a value you sent in dynamicVariables, only key names and reason codes. Each lead rejected by this check is also listed in the portal under Blocked Calls.

When no lead in the request is accepted, the response is 400. When at least one lead reached the dynamic variables check, it lists the rejected leads in data.rejectedLeadDetails. Its code is DYNAMIC_VARIABLES_INVALID when at least one lead was rejected by the dynamic variables check, and INVALID_REQUEST otherwise. If SimZ cannot run the check, the response is 503 with code: "DYNAMIC_VARIABLES_CHECK_FAILED" and no leads are queued; retry later.

See Dynamic Variables for the reason codes and full examples.