Request Rate: ~100 requests per 5 seconds per project
Maximum Leads: 1000 leads per request
Body Parameters
string[]
Array of existing lead IDs (required if leads not provided)
object[]
Array of new lead objects (required if leadIds 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
object
Additional metadata
boolean
default:"true"
Whether to initialize leads for calling
Query Parameters
string
API version. Use "1.2" for simplified response format
Response
array
Array of successfully created/validated leads
array
Array of errors for leads that failed validation
Show Error Object Properties
object
The lead data that failed (default format)
string
Reference ID of failed lead (v1.2 format)
string
Error message
Error Responses
400 Bad Request
Missing body / wrong type
Returned when neither leadIds nor leads is provided, or when the value is not an array.
Examples:
{ "error": "Either leadIds or leads array is required" }
{ "error": "Input must be an array" }
Too many leads
Returned when the number of items exceeds the maximum per request.
Example: { "error": "Maximum of 1000 leads allowed per request" } (limit may be overridden by config).
Per-lead validation errors / bad leads
Individual leads that fail validation (duplicate, bad phone, etc.) are reported in the errors array.
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 bad/invalid leads. Do not retry these specific leads via this API.
Recommended behavior:
Mark those leads as invalid in your system.
Fix the underlying data (phone number, process, etc.) before attempting again as new leads.
403 Forbidden
Returned when some leads have missing or invalid projectId relative to the authenticated project.
Example:
{ "error": "Some leads have missing or invalid projectId", "invalidLeads": [ { "data": { ... }, "error": "missing projectId" }, { "data": { ... }, "error": "projectId does not match authenticated project" } ]}
Also returned when the target project is inactive or not found.
404 Not Found
Returned when a processId in the leads array does not exist.
Example: { "error": "Process not found for lead with processId: <id>" }
429 Too Many Requests
Bulk initiate uses the same project-level rate limiting and duplicate protection as the single-lead initiate API.
If you continuously send duplicate or bad data, your API key may be temporarily blocked.
Do not keep retrying the same bad leads, as this can cause more 429s and longer blocks.
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 per-lead validation/duplicate errors returned in the errors array should be treated as permanent failures for those payloads.
Re-sending the same bad lead can:
Trigger duplicate-protection 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/bulk-initiate-leads","slug":"/api-reference/bulk-initiate-leads","pageMetadata":{"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"},"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 multiple leads in a single request and optionally start initialization\"\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`,pre:`pre`,span:`span`,strong:`strong`,ul:`ul`,..._provideComponents(),...props.components},{CodeBlock,Expandable,Heading,ParamField,ResponseField,Warning}=_components;if(!CodeBlock)_missingMdxReference(`CodeBlock`,true);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:`Maximum Leads: 1000 leads per request`}),`\n`]})]}),`\n`,_jsx(Heading,{level:`2`,id:`body-parameters`,children:`Body Parameters`}),`\n`,_jsx(ParamField,{body:`leadIds`,type:`string[]`,id:`param-lead-ids`,children:_jsxs(_components.p,{children:[`Array of existing lead IDs (required if `,_jsx(_components.code,{children:`leads`}),` not provided)`]})}),`\n`,_jsxs(ParamField,{body:`leads`,type:`object[]`,id:`param-leads`,children:[_jsxs(_components.p,{children:[`Array of new lead objects (required if `,_jsx(_components.code,{children:`leadIds`}),` 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`})}),_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 leads for calling`})}),`\n`,_jsx(Heading,{level:`2`,id:`query-parameters`,children:`Query Parameters`}),`\n`,_jsx(ParamField,{query:`v`,type:`string`,id:`param-v`,children:_jsxs(_components.p,{children:[`API version. Use `,_jsx(_components.code,{children:`\"1.2\"`}),` for simplified response format`]})}),`\n`,_jsx(Heading,{level:`2`,id:`response`,children:`Response`}),`\n`,_jsx(ResponseField,{name:`success`,type:`array`,id:`param-success`,children:_jsx(_components.p,{children:`Array of successfully created/validated leads`})}),`\n`,_jsxs(ResponseField,{name:`errors`,type:`array`,id:`param-errors`,children:[_jsx(_components.p,{children:`Array of errors for leads that failed validation`}),_jsxs(Expandable,{title:`Error Object Properties`,children:[_jsx(ResponseField,{name:`data`,type:`object`,id:`param-data`,children:_jsx(_components.p,{children:`The lead data that failed (default format)`})}),_jsx(ResponseField,{name:`referenceId`,type:`string`,id:`param-reference-id-1`,children:_jsx(_components.p,{children:`Reference ID of failed lead (v1.2 format)`})}),_jsx(ResponseField,{name:`error`,type:`string`,id:`param-error`,children:_jsx(_components.p,{children:`Error message`})})]})]}),`\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 / wrong type`}),`\n`,_jsxs(_components.ul,{children:[`\n`,_jsxs(_components.li,{children:[`Returned when neither `,_jsx(_components.code,{children:`leadIds`}),` nor `,_jsx(_components.code,{children:`leads`}),` is provided, or when the value is not an array.`]}),`\n`,_jsxs(_components.li,{children:[`Examples:`,`\n`,_jsxs(_components.ul,{children:[`\n`,_jsx(_components.li,{children:_jsx(_components.code,{children:`{ \"error\": \"Either leadIds or leads array is required\" }`})}),`\n`,_jsx(_components.li,{children:_jsx(_components.code,{children:`{ \"error\": \"Input must be an array\" }`})}),`\n`]}),`\n`]}),`\n`]}),`\n`]}),`\n`,_jsxs(_components.li,{children:[_jsx(_components.strong,{children:`Too many leads`}),`\n`,_jsxs(_components.ul,{children:[`\n`,_jsx(_components.li,{children:`Returned when the number of items exceeds the maximum per request.`}),`\n`,_jsxs(_components.li,{children:[`Example: `,_jsx(_components.code,{children:`{ \"error\": \"Maximum of 1000 leads allowed per request\" }`}),` (limit may be overridden by config).`]}),`\n`]}),`\n`]}),`\n`,_jsxs(_components.li,{children:[_jsx(_components.strong,{children:`Per-lead validation errors / bad leads`}),`\n`,_jsxs(_components.ul,{children:[`\n`,_jsxs(_components.li,{children:[`Individual leads that fail validation (duplicate, bad phone, etc.) are reported in the `,_jsx(_components.code,{children:`errors`}),` array.`]}),`\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 bad/invalid leads. Do not retry these specific leads via this API.`})}),`\n`,_jsxs(_components.li,{children:[`Recommended behavior:`,`\n`,_jsxs(_components.ul,{children:[`\n`,_jsx(_components.li,{children:`Mark those leads as invalid in your system.`}),`\n`,_jsx(_components.li,{children:`Fix the underlying data (phone number, process, etc.) before attempting again as new leads.`}),`\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 some leads have missing or invalid `,_jsx(_components.code,{children:`projectId`}),` relative to the authenticated project.`]}),`\n`,_jsxs(_components.li,{children:[`Example:`,`\n`,_jsx(CodeBlock,{filename:``,numberOfLines:`7`,language:`json`,children:_jsx(_components.pre,{className:`shiki shiki-themes github-light-default dark-plus`,style:{backgroundColor:`#ffffff`,\"--shiki-dark-bg\":`#0B0C0E`,color:`#1f2328`,\"--shiki-dark\":`#D4D4D4`},language:`json`,children:_jsxs(_components.code,{language:`json`,numberOfLines:`7`,children:[_jsx(_components.span,{className:`line`,children:_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`{`})}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#116329`,\"--shiki-dark\":`#9CDCFE`},children:` \"error\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`: `}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:`\"Some leads have missing or invalid projectId\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`,`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#116329`,\"--shiki-dark\":`#9CDCFE`},children:` \"invalidLeads\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`: [`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:` { `}),_jsx(_components.span,{style:{color:`#116329`,\"--shiki-dark\":`#9CDCFE`},children:`\"data\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`: { `}),_jsx(_components.span,{style:{color:`#82071E`,\"--shiki-light-font-style\":`italic`,\"--shiki-dark\":`#F44747`,\"--shiki-dark-font-style\":`inherit`},children:`...`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:` }, `}),_jsx(_components.span,{style:{color:`#116329`,\"--shiki-dark\":`#9CDCFE`},children:`\"error\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`: `}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:`\"missing projectId\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:` },`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:` { `}),_jsx(_components.span,{style:{color:`#116329`,\"--shiki-dark\":`#9CDCFE`},children:`\"data\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`: { `}),_jsx(_components.span,{style:{color:`#82071E`,\"--shiki-light-font-style\":`italic`,\"--shiki-dark\":`#F44747`,\"--shiki-dark-font-style\":`inherit`},children:`...`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:` }, `}),_jsx(_components.span,{style:{color:`#116329`,\"--shiki-dark\":`#9CDCFE`},children:`\"error\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`: `}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:`\"projectId does not match authenticated project\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:` }`})]}),`\n`,_jsx(_components.span,{className:`line`,children:_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:` ]`})}),`\n`,_jsx(_components.span,{className:`line`,children:_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`}`})}),`\n`]})})}),`\n`]}),`\n`,_jsx(_components.li,{children:`Also returned when the target project is inactive or not found.`}),`\n`]}),`\n`]}),`\n`,_jsxs(_components.li,{children:[`\n`,_jsx(_components.p,{children:_jsx(_components.strong,{children:`404 Not Found`})}),`\n`,_jsxs(_components.ul,{children:[`\n`,_jsxs(_components.li,{children:[`Returned when a `,_jsx(_components.code,{children:`processId`}),` in the `,_jsx(_components.code,{children:`leads`}),` array does not exist.`]}),`\n`,_jsxs(_components.li,{children:[`Example: `,_jsx(_components.code,{children:`{ \"error\": \"Process not found for lead with processId: \u003cid>\" }`})]}),`\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:`Bulk initiate uses the same project-level rate limiting and duplicate protection as the single-lead initiate API.`}),`\n`,_jsx(_components.li,{children:`If you continuously send duplicate or bad data, your API key may be temporarily blocked.`}),`\n`,_jsxs(_components.li,{children:[_jsx(_components.strong,{children:`Do not keep retrying the same bad leads`}),`, as this can cause more 429s and longer blocks.`]}),`\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`,_jsxs(_components.li,{children:[`Any per-lead validation/duplicate errors returned in the `,_jsx(_components.code,{children:`errors`}),` array should be treated as permanent failures for those payloads.`]}),`\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 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":"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"}}},"mdxSourceWithNoJs":null},"mdxExtracts":{"tableOfContents":[{"title":"Body Parameters","slug":"body-parameters","depth":2,"children":[]},{"title":"Query Parameters","slug":"query-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":"Bulk Initiate Leads","path":"/leads/bulk/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":{"v":{"schema":[{"type":"string","description":"API version. Use `\"1.2\"` for simplified response format"}]}},"header":{},"cookie":{},"path":{}},"body":{"application/json":{"schemaArray":[{"type":"object","properties":{"leadIds":[{"type":"array","items":[{"type":"string"}],"description":"Array of existing lead IDs (required if `leads` not provided)"}],"leads":[{"type":"array","items":[{"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"}],"metadata":[{"type":"object","properties":{},"description":"Additional metadata"}]}}],"description":"Array of new lead objects (required if `leadIds` not provided)"}],"init":[{"type":"boolean","description":"Whether to initialize leads for calling"}]}}],"examples":{"example":{"value":{"leadIds":["\u003cstring>"],"leads":[{"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":"array","items":[{"type":"object","properties":{}}],"description":"Array of successfully created/validated leads"}],"errors":[{"type":"array","items":[{"type":"object","properties":{"data":[{"type":"object","properties":{},"description":"The lead data that failed (default format)"}],"referenceId":[{"type":"string","description":"Reference ID of failed lead (v1.2 format)"}],"error":[{"type":"string","description":"Error message"}]}}],"description":"Array of errors for leads that failed validation"}]}}],"examples":{"example":{"value":{"success":[{}],"errors":[{"data":{},"referenceId":"\u003cstring>","error":"\u003cstring>"}]}}}}}},"deprecated":false}},"jsLinks":[],"subdomain":"uservox","siteName":"Uservox Docs","title":"Bulk Initiate Leads - Uservox Docs","navMaps":{"firstHrefInVersion":{},"firstHrefInLanguage":{}},"lastModified":"2026-01-28T08:56:52.166Z","originalFileLocation":"api-reference/bulk-initiate-leads.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 multiple leads in a single request and optionally start initialization\">\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=\"Bulk Initiate Leads - Uservox Docs\">\u003cmeta data-mint-head property=\"og:description\" content=\"Create or validate multiple leads in a single request and optionally start initialization\">\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/bulk-initiate-leads\">\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=Bulk+Initiate+Leads\u0026amp;description=Create+or+validate+multiple+leads+in+a+single+request+and+optionally+start+initialization\u0026amp;theme=c07a5ba392f34eb82f82ef23\u0026amp;signature=8600d771ea3a5e6c362b88cf11baabe2a62ba0a37d21171c0663f51039f22fcf\">\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=\"Bulk Initiate Leads - Uservox Docs\">\u003cmeta data-mint-head name=\"twitter:description\" content=\"Create or validate multiple leads in a single request and optionally start initialization\">\u003cmeta data-mint-head name=\"twitter:image\" content=\"https://uservox.mintlify.site/_mintlify/api/og/v2?division=Leads\u0026amp;title=Bulk+Initiate+Leads\u0026amp;description=Create+or+validate+multiple+leads+in+a+single+request+and+optionally+start+initialization\u0026amp;theme=c07a5ba392f34eb82f82ef23\u0026amp;signature=8600d771ea3a5e6c362b88cf11baabe2a62ba0a37d21171c0663f51039f22fcf\">\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/bulk-initiate-leads\">\u003clink data-mint-head rel=\"alternate\" type=\"application/xml\" href=\"/sitemap.xml\">\u003clink data-mint-head rel=\"alternate\" type=\"text/markdown\" href=\"/api-reference/bulk-initiate-leads.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/bulk-initiate-leads#webpage\",\"url\":\"https://docs.uservox.ai/api-reference/bulk-initiate-leads\",\"name\":\"Bulk Initiate Leads\",\"description\":\"Create or validate multiple leads in a single request and optionally start initialization\",\"dateModified\":\"2026-01-28T08:56:52.166Z\",\"isPartOf\":{\"@id\":\"https://docs.uservox.ai#website\"},\"breadcrumb\":{\"@id\":\"https://docs.uservox.ai/api-reference/bulk-initiate-leads#breadcrumb\"}},{\"@type\":\"BreadcrumbList\",\"@id\":\"https://docs.uservox.ai/api-reference/bulk-initiate-leads#breadcrumb\",\"itemListElement\":[{\"@type\":\"ListItem\",\"position\":1,\"name\":\"Leads\",\"item\":\"https://docs.uservox.ai/api-reference/initiate-lead\"},{\"@type\":\"ListItem\",\"position\":2,\"name\":\"Bulk Initiate Leads\",\"item\":\"https://docs.uservox.ai/api-reference/bulk-initiate-leads\"}]},{\"@type\":[\"TechArticle\",\"APIReference\"],\"@id\":\"https://docs.uservox.ai/api-reference/bulk-initiate-leads#apireference\",\"headline\":\"Bulk Initiate Leads\",\"name\":\"Bulk Initiate Leads\",\"description\":\"Create or validate multiple leads in a single request and optionally start initialization\",\"url\":\"https://docs.uservox.ai/api-reference/bulk-initiate-leads\",\"mainEntityOfPage\":{\"@id\":\"https://docs.uservox.ai/api-reference/bulk-initiate-leads#webpage\"},\"dateModified\":\"2026-01-28T08:56:52.166Z\",\"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/bulk-initiate-leads.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","href":"/api-reference/introduction"}]},{"group":"Leads","pages":[{"title":"Initiate Lead","api":"POST /leads/initiate","description":"Create or validate a lead and optionally start initialization for calling","href":"/api-reference/initiate-lead"},{"title":"Bulk Initiate Leads","api":"POST /leads/bulk/initiate","href":"/api-reference/bulk-initiate-leads"},{"title":"Update Lead","api":"POST /leads/update","description":"Update a lead's metadata through the Uservox API and optionally move it to a new state. The update is queued and its result sent by webhook.","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":"Bulk Initiate Leads - 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"]}