Request Rate: ~100 requests per 5 seconds per project
Duplicate Detection: More than 5 duplicate submissions in 60 seconds will block the API key for 60 minutes
Body Parameters
string
Existing lead ID to validate (required if lead not provided)
object
New lead object (required if leadId not provided)
Show Lead Object Properties
string
required
MongoDB ObjectId of the project
string
required
MongoDB ObjectId of the process
string
Optional ID to group leads for analytics
string
Phone number (required if email not provided)
string
Email address (required if phone not provided)
string
Full name (required if firstName not provided)
string
First name (required if name not provided)
string
Last name
string
External reference ID for tracking
object
Additional metadata
boolean
default:"true"
Whether to initialize the lead for calling
Response
boolean
Indicates if the request was successful
string
MongoDB ObjectId of the lead
string
Lead’s name
string
Phone number
string
Email address
string
Project ID
string
Process ID
string
External reference ID
string
Current state of the lead
object
Lead metadata
string
ISO 8601 timestamp of creation
string
ISO 8601 timestamp of last update
Error Responses
400 Bad Request
Missing body
Returned when neither leadId nor lead is provided.
Example: { "error": "Either leadId or lead object is required" }
Missing projectId
Returned when creating a new lead without lead.projectId.
Example: { "error": "projectId is required in lead object" }
Validation errors / bad leads
Returned when the lead fails validation during creation or duplicate checks.
Typical messages include:
"A call attempt has already been made to this phone number for this project"
"Phone number contains repeating digits pattern"
"already exists for this project and process"
These indicate a bad/invalid lead. Do not retry these leads via this API.
Recommended behavior:
Mark the lead as invalid in your system.
Fix the underlying data (phone number, process, etc.) before attempting again as a new lead.
403 Forbidden
Returned when lead.projectId does not match the authenticated project for the API key.
Example: { "error": "projectId does not match authenticated project" }
429 Too Many Requests
Returned when duplicate protection blocks the API key due to too many duplicate submissions.
Example response: { "success": false, "error": "...temporarily blocked..." }
Do not retry the same bad/duplicate leads.
Recommended behavior:
Stop sending further requests from the offending source.
Investigate and fix the duplication issue before resuming traffic.
500 Internal Server Error
Unexpected server-side error.
Safe to retry with exponential backoff only for 5xx responses (not for 4xx).
Retry Guidance
Do not retry bad leads
Any 400 response with validation/duplicate messages (as above) should be treated as a permanent failure for that payload.
Re-sending the same bad lead can:
Trigger duplicate-protection rate limits.
Lead to 429 blocks for your API key.
When to retry
It is acceptable to implement retries (with backoff) for:
Network errors.
5xx responses (500 and other server errors).
Do not automatically retry on 4xx responses; fix the request or underlying data instead.
{"docsConfig":{"theme":"mint","$schema":"https://mintlify.com/docs.json","name":"Uservox Docs","colors":{"primary":"#16A34A","light":"#07C983","dark":"#15803D"},"logo":{"light":"https://uservox.ai/home/images/logo/logo_dark_lg.png","dark":"https://uservox.ai/home/images/logo/logo_dark_lg.png"},"favicon":"https://mintcdn.com/uservox/LCcwBNBHTHdM9mfQ/favicon.svg?fit=max\u0026auto=format\u0026n=LCcwBNBHTHdM9mfQ\u0026q=85\u0026s=25ae4d037a876e965deed25f94edb9bb","api":{"mdx":{"auth":{"method":"bearer"},"server":"https://crm.uservox.ai/api/v1"}},"navbar":{"links":[{"href":"mailto:hi@mintlify.com","label":"Support"}],"primary":{"type":"button","label":"Dashboard","href":"https://app.uservox.ai"}},"footer":{"socials":{"x":"https://x.com/mintlify","github":"https://github.com/mintlify","linkedin":"https://linkedin.com/company/mintlify"}},"styling":{"latex":false},"navigation":{"global":{"anchors":[{"anchor":"Uservox","icon":"globe","href":"https://uservox.ai"},{"anchor":"Dashboard","icon":"rectangle-terminal","href":"https://app.uservox.ai"}]},"pages":[]}},"deployment":{"deploymentMetadataValue":{"subdomain":"uservox","hasAudioNarration":false,"actualSubdomain":"uservox","customDomains":["docs.uservox.ai"],"gitSource":{"type":"github","owner":"girnarai","repo":"docs","deployBranch":"main","contentDirectory":"","isPrivate":false,"mountPath":"","label":""},"entitlements":{},"buildId":"6aeace110e439ad241858ad5","clientVersion":"0.0.4143","searchFilterCounts":[{"language":"default","tag":"Guides","count":56},{"language":"default","tag":"API Reference","count":12},{"language":"default","tag":"Process","count":12},{"language":"default","tag":"Leads","count":11},{"language":"default","tag":"Agent","count":10},{"language":"default","tag":"API Integration","count":8},{"language":"default","tag":"Settings","count":7},{"language":"default","tag":"WhatsApp","count":5},{"language":"default","tag":"Essentials","count":4},{"language":"default","tag":"Activities","count":3}]},"assistantConfig":{},"basePath":"","hasChatPermissions":false,"hasWebMcpPermissions":false,"toggles":[{"name":"kill-isr","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"custom-rbac-roles","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"agent-mintlify-slack","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"agent-integrations-settings","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"rbac-expansion","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"automations-pr-grouping","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"custom-prefix","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"analytics-v7","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"user-flows-analytics","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"no-publish-flow","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"workos-onboarding","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"snapshot-serving-live","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"stripTemperatureMiddleware","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"support-platform-pylon-zendesk","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"snapshot-serving","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"instant-rollback","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"granular-notifications-server","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"granular-notifications","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"automations-fable","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"fixed-ai-action-pricing","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"automation-resolve-merge-conflict","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"scoped-publishing","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"mintql","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"page-level-analytics","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"editor-version-history-v2","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"billing-page-v2","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"full-page-search","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"workspace-projects","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"assistant-v5","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"fork-pr-previews","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"revalidation-jwt","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"workos-sso-scim","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"hobby-abuse-scan","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"dashboard-inbox","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"workos-signup","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"turbopuffer-dual-write","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"workos-enabled","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"approve-review-flow","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"editor-metadata","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"sso-setup-deadline-banner","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"turbopuffer-serve","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"live-agents","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"llms-txt-v2","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false}],"googleFontsInlined":false},"customCss":[{"filePath":"style.css","content":"select option{background-color:var(--background-primary)!important;color:var(--text-primary)!important}.dark select option{background-color:#1a1a1a!important;color:#ffffff!important}#api-playground-input select option{background-color:var(--background-primary)!important;color:var(--text-primary)!important}select{color-scheme:dark}.dark select{background-color:#2d2d2d;color:#ffffff}.dark select option{background-color:#2d2d2d;color:#ffffff}"}],"page":{"pagePath":"api-reference/initiate-lead","slug":"/api-reference/initiate-lead","pageMetadata":{"title":"Initiate Lead","api":"POST /leads/initiate","description":"Create or validate a lead and optionally start initialization for calling","href":"/api-reference/initiate-lead"},"description":{"compiledSource":"\"use strict\";\nconst {jsx: _jsx} = arguments[0];\nconst {useMDXComponents: _provideComponents} = arguments[0];\nfunction _createMdxContent(props) {\n const _components = {\n p: \"p\",\n ..._provideComponents(),\n ...props.components\n };\n return _jsx(_components.p, {\n children: \"Create or validate a lead and optionally start initialization for calling\"\n });\n}\nfunction MDXContent(props = {}) {\n const {wrapper: MDXLayout} = {\n ..._provideComponents(),\n ...props.components\n };\n return MDXLayout ? _jsx(MDXLayout, {\n ...props,\n children: _jsx(_createMdxContent, {\n ...props\n })\n }) : _createMdxContent(props);\n}\nreturn {\n default: MDXContent\n};\n","frontmatter":{},"scope":{}},"pageType":"default","mdx":{"mdxSource":{"compiledSource":"\"use strict\";const{Fragment:_Fragment,jsx:_jsx,jsxs:_jsxs}=arguments[0];const{useMDXComponents:_provideComponents}=arguments[0];function _createMdxContent(props){const _components={code:`code`,li:`li`,p:`p`,strong:`strong`,ul:`ul`,..._provideComponents(),...props.components},{Expandable,Heading,ParamField,ResponseField,Warning}=_components;if(!Expandable)_missingMdxReference(`Expandable`,true);if(!Heading)_missingMdxReference(`Heading`,true);if(!ParamField)_missingMdxReference(`ParamField`,true);if(!ResponseField)_missingMdxReference(`ResponseField`,true);if(!Warning)_missingMdxReference(`Warning`,true);return _jsxs(_Fragment,{children:[_jsxs(Warning,{children:[_jsx(_components.p,{children:_jsx(_components.strong,{children:`Rate Limits:`})}),_jsxs(_components.ul,{children:[`\n`,_jsx(_components.li,{children:`Request Rate: ~100 requests per 5 seconds per project`}),`\n`,_jsx(_components.li,{children:`Duplicate Detection: More than 5 duplicate submissions in 60 seconds will block the API key for 60 minutes`}),`\n`]})]}),`\n`,_jsx(Heading,{level:`2`,id:`body-parameters`,children:`Body Parameters`}),`\n`,_jsx(ParamField,{body:`leadId`,type:`string`,id:`param-lead-id`,children:_jsxs(_components.p,{children:[`Existing lead ID to validate (required if `,_jsx(_components.code,{children:`lead`}),` not provided)`]})}),`\n`,_jsxs(ParamField,{body:`lead`,type:`object`,id:`param-lead`,children:[_jsxs(_components.p,{children:[`New lead object (required if `,_jsx(_components.code,{children:`leadId`}),` not provided)`]}),_jsxs(Expandable,{title:`Lead Object Properties`,children:[_jsx(ParamField,{body:`projectId`,type:`string`,required:true,id:`param-project-id`,children:_jsx(_components.p,{children:`MongoDB ObjectId of the project`})}),_jsx(ParamField,{body:`processId`,type:`string`,required:true,id:`param-process-id`,children:_jsx(_components.p,{children:`MongoDB ObjectId of the process`})}),_jsx(ParamField,{body:`groupId`,type:`string`,id:`param-group-id`,children:_jsx(_components.p,{children:`Optional ID to group leads for analytics`})}),_jsx(ParamField,{body:`phone`,type:`string`,id:`param-phone`,children:_jsx(_components.p,{children:`Phone number (required if email not provided)`})}),_jsx(ParamField,{body:`email`,type:`string`,id:`param-email`,children:_jsx(_components.p,{children:`Email address (required if phone not provided)`})}),_jsx(ParamField,{body:`name`,type:`string`,id:`param-name`,children:_jsx(_components.p,{children:`Full name (required if firstName not provided)`})}),_jsx(ParamField,{body:`firstName`,type:`string`,id:`param-first-name`,children:_jsx(_components.p,{children:`First name (required if name not provided)`})}),_jsx(ParamField,{body:`lastName`,type:`string`,id:`param-last-name`,children:_jsx(_components.p,{children:`Last name`})}),_jsx(ParamField,{body:`referenceId`,type:`string`,id:`param-reference-id`,children:_jsx(_components.p,{children:`External reference ID for tracking`})}),_jsx(ParamField,{body:`metadata`,type:`object`,id:`param-metadata`,children:_jsx(_components.p,{children:`Additional metadata`})})]})]}),`\n`,_jsx(ParamField,{body:`init`,type:`boolean`,default:`true`,id:`param-init`,children:_jsx(_components.p,{children:`Whether to initialize the lead for calling`})}),`\n`,_jsx(Heading,{level:`2`,id:`response`,children:`Response`}),`\n`,_jsx(ResponseField,{name:`success`,type:`boolean`,id:`param-success`,children:_jsx(_components.p,{children:`Indicates if the request was successful`})}),`\n`,_jsx(ResponseField,{name:`_id`,type:`string`,id:`param-id`,children:_jsx(_components.p,{children:`MongoDB ObjectId of the lead`})}),`\n`,_jsx(ResponseField,{name:`name`,type:`string`,id:`param-name-1`,children:_jsx(_components.p,{children:`Lead’s name`})}),`\n`,_jsx(ResponseField,{name:`phone`,type:`string`,id:`param-phone-1`,children:_jsx(_components.p,{children:`Phone number`})}),`\n`,_jsx(ResponseField,{name:`email`,type:`string`,id:`param-email-1`,children:_jsx(_components.p,{children:`Email address`})}),`\n`,_jsx(ResponseField,{name:`projectId`,type:`string`,id:`param-project-id-1`,children:_jsx(_components.p,{children:`Project ID`})}),`\n`,_jsx(ResponseField,{name:`processId`,type:`string`,id:`param-process-id-1`,children:_jsx(_components.p,{children:`Process ID`})}),`\n`,_jsx(ResponseField,{name:`referenceId`,type:`string`,id:`param-reference-id-1`,children:_jsx(_components.p,{children:`External reference ID`})}),`\n`,_jsx(ResponseField,{name:`currentState`,type:`string`,id:`param-current-state`,children:_jsx(_components.p,{children:`Current state of the lead`})}),`\n`,_jsx(ResponseField,{name:`metadata`,type:`object`,id:`param-metadata-1`,children:_jsx(_components.p,{children:`Lead metadata`})}),`\n`,_jsx(ResponseField,{name:`createdAt`,type:`string`,id:`param-created-at`,children:_jsx(_components.p,{children:`ISO 8601 timestamp of creation`})}),`\n`,_jsx(ResponseField,{name:`updatedAt`,type:`string`,id:`param-updated-at`,children:_jsx(_components.p,{children:`ISO 8601 timestamp of last update`})}),`\n`,_jsx(Heading,{level:`2`,id:`error-responses`,children:`Error Responses`}),`\n`,_jsxs(_components.ul,{children:[`\n`,_jsxs(_components.li,{children:[`\n`,_jsx(_components.p,{children:_jsx(_components.strong,{children:`400 Bad Request`})}),`\n`,_jsxs(_components.ul,{children:[`\n`,_jsxs(_components.li,{children:[_jsx(_components.strong,{children:`Missing body`}),`\n`,_jsxs(_components.ul,{children:[`\n`,_jsxs(_components.li,{children:[`Returned when neither `,_jsx(_components.code,{children:`leadId`}),` nor `,_jsx(_components.code,{children:`lead`}),` is provided.`]}),`\n`,_jsxs(_components.li,{children:[`Example: `,_jsx(_components.code,{children:`{ \"error\": \"Either leadId or lead object is required\" }`})]}),`\n`]}),`\n`]}),`\n`,_jsxs(_components.li,{children:[_jsx(_components.strong,{children:`Missing projectId`}),`\n`,_jsxs(_components.ul,{children:[`\n`,_jsxs(_components.li,{children:[`Returned when creating a new lead without `,_jsx(_components.code,{children:`lead.projectId`}),`.`]}),`\n`,_jsxs(_components.li,{children:[`Example: `,_jsx(_components.code,{children:`{ \"error\": \"projectId is required in lead object\" }`})]}),`\n`]}),`\n`]}),`\n`,_jsxs(_components.li,{children:[_jsx(_components.strong,{children:`Validation errors / bad leads`}),`\n`,_jsxs(_components.ul,{children:[`\n`,_jsx(_components.li,{children:`Returned when the lead fails validation during creation or duplicate checks.`}),`\n`,_jsxs(_components.li,{children:[`Typical messages include:`,`\n`,_jsxs(_components.ul,{children:[`\n`,_jsx(_components.li,{children:_jsx(_components.code,{children:`\"A call attempt has already been made to this phone number for this project\"`})}),`\n`,_jsx(_components.li,{children:_jsx(_components.code,{children:`\"Phone number contains repeating digits pattern\"`})}),`\n`,_jsx(_components.li,{children:_jsx(_components.code,{children:`\"already exists for this project and process\"`})}),`\n`]}),`\n`]}),`\n`,_jsx(_components.li,{children:_jsx(_components.strong,{children:`These indicate a bad/invalid lead. Do not retry these leads via this API.`})}),`\n`,_jsxs(_components.li,{children:[`Recommended behavior:`,`\n`,_jsxs(_components.ul,{children:[`\n`,_jsx(_components.li,{children:`Mark the lead as invalid in your system.`}),`\n`,_jsx(_components.li,{children:`Fix the underlying data (phone number, process, etc.) before attempting again as a new lead.`}),`\n`]}),`\n`]}),`\n`]}),`\n`]}),`\n`]}),`\n`]}),`\n`,_jsxs(_components.li,{children:[`\n`,_jsx(_components.p,{children:_jsx(_components.strong,{children:`403 Forbidden`})}),`\n`,_jsxs(_components.ul,{children:[`\n`,_jsxs(_components.li,{children:[`Returned when `,_jsx(_components.code,{children:`lead.projectId`}),` does not match the authenticated project for the API key.`]}),`\n`,_jsxs(_components.li,{children:[`Example: `,_jsx(_components.code,{children:`{ \"error\": \"projectId does not match authenticated project\" }`})]}),`\n`]}),`\n`]}),`\n`,_jsxs(_components.li,{children:[`\n`,_jsx(_components.p,{children:_jsx(_components.strong,{children:`429 Too Many Requests`})}),`\n`,_jsxs(_components.ul,{children:[`\n`,_jsx(_components.li,{children:`Returned when duplicate protection blocks the API key due to too many duplicate submissions.`}),`\n`,_jsxs(_components.li,{children:[`Example response: `,_jsx(_components.code,{children:`{ \"success\": false, \"error\": \"...temporarily blocked...\" }`})]}),`\n`,_jsx(_components.li,{children:_jsx(_components.strong,{children:`Do not retry the same bad/duplicate leads.`})}),`\n`,_jsxs(_components.li,{children:[`Recommended behavior:`,`\n`,_jsxs(_components.ul,{children:[`\n`,_jsx(_components.li,{children:`Stop sending further requests from the offending source.`}),`\n`,_jsx(_components.li,{children:`Investigate and fix the duplication issue before resuming traffic.`}),`\n`]}),`\n`]}),`\n`]}),`\n`]}),`\n`,_jsxs(_components.li,{children:[`\n`,_jsx(_components.p,{children:_jsx(_components.strong,{children:`500 Internal Server Error`})}),`\n`,_jsxs(_components.ul,{children:[`\n`,_jsx(_components.li,{children:`Unexpected server-side error.`}),`\n`,_jsxs(_components.li,{children:[`Safe to retry with exponential backoff `,_jsx(_components.strong,{children:`only`}),` for 5xx responses (not for 4xx).`]}),`\n`]}),`\n`]}),`\n`]}),`\n`,_jsx(Heading,{level:`2`,id:`retry-guidance`,children:`Retry Guidance`}),`\n`,_jsxs(_components.ul,{children:[`\n`,_jsxs(_components.li,{children:[_jsx(_components.strong,{children:`Do not retry bad leads`}),`\n`,_jsxs(_components.ul,{children:[`\n`,_jsx(_components.li,{children:`Any 400 response with validation/duplicate messages (as above) should be treated as a permanent failure for that payload.`}),`\n`,_jsxs(_components.li,{children:[`Re-sending the same bad lead can:`,`\n`,_jsxs(_components.ul,{children:[`\n`,_jsx(_components.li,{children:`Trigger duplicate-protection rate limits.`}),`\n`,_jsxs(_components.li,{children:[`Lead to `,_jsx(_components.code,{children:`429`}),` blocks for your API key.`]}),`\n`]}),`\n`]}),`\n`]}),`\n`]}),`\n`,_jsxs(_components.li,{children:[_jsx(_components.strong,{children:`When to retry`}),`\n`,_jsxs(_components.ul,{children:[`\n`,_jsxs(_components.li,{children:[`It is acceptable to implement retries (with backoff) for:`,`\n`,_jsxs(_components.ul,{children:[`\n`,_jsx(_components.li,{children:`Network errors.`}),`\n`,_jsxs(_components.li,{children:[`5xx responses (`,_jsx(_components.code,{children:`500`}),` and other server errors).`]}),`\n`]}),`\n`]}),`\n`,_jsxs(_components.li,{children:[`Do `,_jsx(_components.strong,{children:`not`}),` automatically retry on 4xx responses; fix the request or underlying data instead.`]}),`\n`]}),`\n`]}),`\n`]})]})}function MDXContent(props={}){const{wrapper:MDXLayout}={..._provideComponents(),...props.components};return MDXLayout?_jsx(MDXLayout,{...props,children:_jsx(_createMdxContent,{...props})}):_createMdxContent(props)}return{default:MDXContent};function _missingMdxReference(id,component){throw new Error(`Expected `+(component?`component`:`object`)+\" `\"+id+\"` to be defined: you likely forgot to import, pass, or provide it.\")}","frontmatter":{},"scope":{"config":{},"pageMetadata":{"title":"Initiate Lead","api":"POST /leads/initiate","description":"Create or validate a lead and optionally start initialization for calling","href":"/api-reference/initiate-lead"}}},"mdxSourceWithNoJs":null},"mdxExtracts":{"tableOfContents":[{"title":"Body Parameters","slug":"body-parameters","depth":2,"children":[]},{"title":"Response","slug":"response","depth":2,"children":[]},{"title":"Error Responses","slug":"error-responses","depth":2,"children":[]},{"title":"Retry Guidance","slug":"retry-guidance","depth":2,"children":[]}],"codeExamples":{},"endpoint":{"title":"Initiate Lead","path":"/leads/initiate","servers":[{"url":"https://crm.uservox.ai/api/v1"}],"method":"post","request":{"security":[{"title":"Bearer Auth","parameters":{"header":{"Authorization":{"type":"http","scheme":"bearer","description":"Bearer authentication header of the form `Bearer \u003ctoken>`, where `\u003ctoken>` is your auth token."}},"query":{},"cookie":{}}}],"parameters":{"query":{},"header":{},"cookie":{},"path":{}},"body":{"application/json":{"schemaArray":[{"type":"object","properties":{"leadId":[{"type":"string","description":"Existing lead ID to validate (required if `lead` not provided)"}],"lead":[{"type":"object","properties":{"projectId":[{"type":"string","description":"MongoDB ObjectId of the project","required":true}],"processId":[{"type":"string","description":"MongoDB ObjectId of the process","required":true}],"groupId":[{"type":"string","description":"Optional ID to group leads for analytics"}],"phone":[{"type":"string","description":"Phone number (required if email not provided)"}],"email":[{"type":"string","description":"Email address (required if phone not provided)"}],"name":[{"type":"string","description":"Full name (required if firstName not provided)"}],"firstName":[{"type":"string","description":"First name (required if name not provided)"}],"lastName":[{"type":"string","description":"Last name"}],"referenceId":[{"type":"string","description":"External reference ID for tracking"}],"metadata":[{"type":"object","properties":{},"description":"Additional metadata"}]},"description":"New lead object (required if `leadId` not provided)"}],"init":[{"type":"boolean","description":"Whether to initialize the lead for calling"}]}}],"examples":{"example":{"value":{"leadId":"\u003cstring>","lead":{"projectId":"\u003cstring>","processId":"\u003cstring>","groupId":"\u003cstring>","phone":"\u003cstring>","email":"\u003cstring>","name":"\u003cstring>","firstName":"\u003cstring>","lastName":"\u003cstring>","referenceId":"\u003cstring>","metadata":{}},"init":true}}}}}},"response":{"200":{"application/json":{"schemaArray":[{"type":"object","properties":{"success":[{"type":"boolean","description":"Indicates if the request was successful"}],"_id":[{"type":"string","description":"MongoDB ObjectId of the lead"}],"name":[{"type":"string","description":"Lead’s name"}],"phone":[{"type":"string","description":"Phone number"}],"email":[{"type":"string","description":"Email address"}],"projectId":[{"type":"string","description":"Project ID"}],"processId":[{"type":"string","description":"Process ID"}],"referenceId":[{"type":"string","description":"External reference ID"}],"currentState":[{"type":"string","description":"Current state of the lead"}],"metadata":[{"type":"object","properties":{},"description":"Lead metadata"}],"createdAt":[{"type":"string","description":"ISO 8601 timestamp of creation"}],"updatedAt":[{"type":"string","description":"ISO 8601 timestamp of last update"}]}}],"examples":{"example":{"value":{"success":true,"_id":"\u003cstring>","name":"\u003cstring>","phone":"\u003cstring>","email":"\u003cstring>","projectId":"\u003cstring>","processId":"\u003cstring>","referenceId":"\u003cstring>","currentState":"\u003cstring>","metadata":{},"createdAt":"\u003cstring>","updatedAt":"\u003cstring>"}}}}}},"deprecated":false}},"jsLinks":[],"subdomain":"uservox","siteName":"Uservox Docs","title":"Initiate Lead - Uservox Docs","navMaps":{"firstHrefInVersion":{},"firstHrefInLanguage":{}},"lastModified":"2026-01-28T08:56:52.195Z","originalFileLocation":"api-reference/initiate-lead.mdx"},"headHtml":"\u003cscript data-mint-head>(function(){var d=document.documentElement,p=null;if(!p){try{p=localStorage.getItem(\"isDarkMode\")}catch(e){}if(p==='true')p='dark';else if(p==='false')p='light';if(p!=='light'\u0026\u0026p!=='dark'\u0026\u0026p!=='system')p=\"system\"}var r=p==='system'?(matchMedia(\"(prefers-color-scheme: dark)\").matches?'dark':'light'):p;d.classList.remove(r==='dark'?'light':'dark');d.classList.add(r);d.setAttribute(\"data-theme-preference\",p)})();\u003c/script>\u003cmeta data-mint-head name=\"description\" content=\"Create or validate a lead and optionally start initialization for calling\">\u003cmeta data-mint-head name=\"application-name\" content=\"Uservox Docs\">\u003cmeta data-mint-head name=\"generator\" content=\"Mintlify\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"192x192\" href=\"/mintlify-assets/_mintlify/favicons/uservox/6JfG41JkCT6k9_XZ/_generated/favicon/android-chrome-192x192.png\" media=\"(prefers-color-scheme: light)\">\u003clink data-mint-head rel=\"apple-touch-icon\" type=\"image/png\" sizes=\"180x180\" href=\"/mintlify-assets/_mintlify/favicons/uservox/6JfG41JkCT6k9_XZ/_generated/favicon/apple-touch-icon.png\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"16x16\" href=\"/mintlify-assets/_mintlify/favicons/uservox/6JfG41JkCT6k9_XZ/_generated/favicon/favicon-16x16.png\" media=\"(prefers-color-scheme: light)\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"32x32\" href=\"/mintlify-assets/_mintlify/favicons/uservox/6JfG41JkCT6k9_XZ/_generated/favicon/favicon-32x32.png\" media=\"(prefers-color-scheme: light)\">\u003clink data-mint-head rel=\"shortcut icon\" type=\"image/x-icon\" href=\"/mintlify-assets/_mintlify/favicons/uservox/6JfG41JkCT6k9_XZ/_generated/favicon/favicon.ico\" media=\"(prefers-color-scheme: light)\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"192x192\" href=\"/mintlify-assets/_mintlify/favicons/uservox/6JfG41JkCT6k9_XZ/_generated/favicon-dark/android-chrome-192x192.png\" media=\"(prefers-color-scheme: dark)\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"16x16\" href=\"/mintlify-assets/_mintlify/favicons/uservox/6JfG41JkCT6k9_XZ/_generated/favicon-dark/favicon-16x16.png\" media=\"(prefers-color-scheme: dark)\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"32x32\" href=\"/mintlify-assets/_mintlify/favicons/uservox/6JfG41JkCT6k9_XZ/_generated/favicon-dark/favicon-32x32.png\" media=\"(prefers-color-scheme: dark)\">\u003clink data-mint-head rel=\"shortcut icon\" type=\"image/x-icon\" href=\"/mintlify-assets/_mintlify/favicons/uservox/6JfG41JkCT6k9_XZ/_generated/favicon-dark/favicon.ico\" media=\"(prefers-color-scheme: dark)\">\u003cmeta data-mint-head property=\"og:title\" content=\"Initiate Lead - Uservox Docs\">\u003cmeta data-mint-head property=\"og:description\" content=\"Create or validate a lead and optionally start initialization for calling\">\u003cmeta data-mint-head property=\"og:site_name\" content=\"Uservox Docs\">\u003cmeta data-mint-head property=\"og:url\" content=\"https://docs.uservox.ai/api-reference/initiate-lead\">\u003cmeta data-mint-head property=\"og:type\" content=\"website\">\u003cmeta data-mint-head property=\"og:image\" content=\"https://uservox.mintlify.site/_mintlify/api/og/v2?division=Leads\u0026amp;title=Initiate+Lead\u0026amp;description=Create+or+validate+a+lead+and+optionally+start+initialization+for+calling\u0026amp;theme=c07a5ba392f34eb82f82ef23\u0026amp;signature=bfdb6b2dca240124ca5b9ad7853a51f19b522a7578b94a9a41350491ec9b612a\">\u003cmeta data-mint-head property=\"og:image:width\" content=\"1200\">\u003cmeta data-mint-head property=\"og:image:height\" content=\"630\">\u003cmeta data-mint-head name=\"twitter:card\" content=\"summary_large_image\">\u003cmeta data-mint-head name=\"twitter:title\" content=\"Initiate Lead - Uservox Docs\">\u003cmeta data-mint-head name=\"twitter:description\" content=\"Create or validate a lead and optionally start initialization for calling\">\u003cmeta data-mint-head name=\"twitter:image\" content=\"https://uservox.mintlify.site/_mintlify/api/og/v2?division=Leads\u0026amp;title=Initiate+Lead\u0026amp;description=Create+or+validate+a+lead+and+optionally+start+initialization+for+calling\u0026amp;theme=c07a5ba392f34eb82f82ef23\u0026amp;signature=bfdb6b2dca240124ca5b9ad7853a51f19b522a7578b94a9a41350491ec9b612a\">\u003cmeta data-mint-head name=\"twitter:image:width\" content=\"1200\">\u003cmeta data-mint-head name=\"twitter:image:height\" content=\"630\">\u003cmeta data-mint-head name=\"msapplication-config\" content=\"/mintlify-assets/_mintlify/favicons/uservox/6JfG41JkCT6k9_XZ/_generated/favicon/browserconfig.xml\">\u003cmeta data-mint-head name=\"apple-mobile-web-app-title\" content=\"Uservox Docs\">\u003cmeta data-mint-head name=\"msapplication-TileColor\" content=\"#16A34A\">\u003clink data-mint-head rel=\"canonical\" href=\"https://docs.uservox.ai/api-reference/initiate-lead\">\u003clink data-mint-head rel=\"alternate\" type=\"application/xml\" href=\"/sitemap.xml\">\u003clink data-mint-head rel=\"alternate\" type=\"text/markdown\" href=\"/api-reference/initiate-lead.md\">\u003cscript data-mint-head type=\"application/ld+json\">{\"@context\":\"https://schema.org\",\"@graph\":[{\"@type\":\"Organization\",\"@id\":\"https://docs.uservox.ai/#organization\",\"name\":\"Uservox Docs\",\"url\":\"https://docs.uservox.ai\",\"logo\":{\"@type\":\"ImageObject\",\"url\":\"https://uservox.ai/home/images/logo/logo_dark_lg.png\"}},{\"@type\":\"WebSite\",\"@id\":\"https://docs.uservox.ai#website\",\"name\":\"Uservox Docs\",\"url\":\"https://docs.uservox.ai\",\"publisher\":{\"@id\":\"https://docs.uservox.ai/#organization\"}},{\"@type\":\"WebPage\",\"@id\":\"https://docs.uservox.ai/api-reference/initiate-lead#webpage\",\"url\":\"https://docs.uservox.ai/api-reference/initiate-lead\",\"name\":\"Initiate Lead\",\"description\":\"Create or validate a lead and optionally start initialization for calling\",\"dateModified\":\"2026-01-28T08:56:52.195Z\",\"isPartOf\":{\"@id\":\"https://docs.uservox.ai#website\"},\"breadcrumb\":{\"@id\":\"https://docs.uservox.ai/api-reference/initiate-lead#breadcrumb\"}},{\"@type\":\"BreadcrumbList\",\"@id\":\"https://docs.uservox.ai/api-reference/initiate-lead#breadcrumb\",\"itemListElement\":[{\"@type\":\"ListItem\",\"position\":1,\"name\":\"Uservox Docs\",\"item\":\"https://docs.uservox.ai\"},{\"@type\":\"ListItem\",\"position\":2,\"name\":\"Initiate Lead\",\"item\":\"https://docs.uservox.ai/api-reference/initiate-lead\"}]},{\"@type\":[\"TechArticle\",\"APIReference\"],\"@id\":\"https://docs.uservox.ai/api-reference/initiate-lead#apireference\",\"headline\":\"Initiate Lead\",\"name\":\"Initiate Lead\",\"description\":\"Create or validate a lead and optionally start initialization for calling\",\"url\":\"https://docs.uservox.ai/api-reference/initiate-lead\",\"mainEntityOfPage\":{\"@id\":\"https://docs.uservox.ai/api-reference/initiate-lead#webpage\"},\"dateModified\":\"2026-01-28T08:56:52.195Z\",\"publisher\":{\"@id\":\"https://docs.uservox.ai/#organization\"},\"isPartOf\":{\"@id\":\"https://docs.uservox.ai#website\"}}]}\u003c/script>\u003cscript data-mint-head type=\"application/ld+json\">{\"@context\":\"https://schema.org\",\"@type\":\"WebSite\",\"name\":\"Uservox Docs\",\"publisher\":{\"@type\":\"Organization\",\"name\":\"Uservox Docs\"},\"provider\":{\"@type\":\"Organization\",\"name\":\"Mintlify\",\"url\":\"https://mintlify.com\"}}\u003c/script>","agentPointerHref":"/api-reference/initiate-lead.md","siteName":"Uservox Docs","nav":{"global":{"anchors":[{"anchor":"Uservox","icon":"globe","href":"https://uservox.ai"},{"anchor":"Dashboard","icon":"rectangle-terminal","href":"https://app.uservox.ai"}]},"tabs":[{"tab":"Guides","pages":[{"title":"Guides","href":""}]},{"tab":"API Reference","groups":[{"group":"API Documentation","pages":[{"title":"API Reference","description":"Uservox CRM API reference: create, update and query leads, track call activity, and receive webhooks. Base URL, authentication and rate limits.","href":"/api-reference/introduction"}]},{"group":"Leads","pages":[{"title":"Initiate Lead","api":"POST /leads/initiate","href":"/api-reference/initiate-lead"},{"title":"Bulk Initiate Leads","api":"POST /leads/bulk/initiate","description":"Create or validate multiple leads in a single request and optionally start initialization","href":"/api-reference/bulk-initiate-leads"},{"title":"Update Lead","api":"POST /leads/update","href":"/api-reference/update-lead"},{"title":"Get Lead","api":"GET /leads/get","href":"/api-reference/get-lead"},{"title":"Query Leads","api":"GET /leads/query","href":"/api-reference/query-leads"}]},{"group":"Activities","pages":[{"title":"Activity Payloads","href":"/api-reference/activity-payloads"},{"title":"Callback Payloads","href":"/api-reference/lead-update-callback-payloads"},{"title":"Get Activity by ID","api":"GET /leads/activity/get","href":"/api-reference/get-activity"}]},{"group":"Conversations","pages":[{"title":"Get Conversation Stats","api":"POST /conversations/search/dsl/stats","href":"/api-reference/get-conversation-stats"}]},{"group":"Analytics","pages":[{"title":"Get Activity Stats","api":"POST https://api.uservox.ai/api/v1/analytics/customer/stats","href":"/api-reference/get-activity-stats"}]},{"group":"Processes","pages":[{"title":"List Processes","api":"GET /processes/list/{projectId}","href":"/api-reference/list-processes"}]}]}]},"basePath":"","title":"Initiate Lead - Uservox Docs","buildId":"dpl_Fyv1NbzwP68g2bEH2Roy98uY1zmE","deploymentId":"dpl_Fyv1NbzwP68g2bEH2Roy98uY1zmE","dynamics":["c2aa737661","2b790eda92","b0f84f53ff"],"chunks":["OpenApiReferenceProvider-DdEMm2kG.js","utils-BMo572L7.js","cloneDeep-izs3Hzxb.js","_Uint8Array-BVIqJ90l.js","isObjectLike-C8vmzPEN.js","isArray-Dcu1dQ5t.js","utils-C-4m9KAx.js","toString-BX-iyh8G.js","isSymbol-CSH9U2Gm.js","addUniqueKeysToSchema-DPLK2Oq9.js","snippetPresets-BKjfJMC9.js","style-to-object-BY3JEAdk.js","v4-DIgz8zy6.js","conditional-requirements-CFM0id0Q.js","ApiExamples-DTsgtCEj.js","isEqual-BfaiBbcl.js","usePlaygroundInputsStore-C8vmhyQM.js","shallow-r9w8LQGS.js","getApiPlaygroundDisplay-DjPI64HQ.js","CodeSnippet-C8Bvhl16.js","CodeSnippets-BtWUwcMy.js","Page-BIYvYBgk.js","getPastedJson-Dcm_3Pgl.js","icon-BXwrTpjc.js","MethodPill-CcjfVmmy.js","DuplicateIcon-BuKIbXAQ.js","createIcon-DaL9yXsO.js","DynamicMarkdown-Co5nikxh.js","SectionHeading-P4UNTsMZ.js","axios-vUo_bRtp.js"]}