Submit Leads
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.
Lead object
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:
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:
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.
