This endpoint is used both for creating a single lead and for bulk uploads (multiple leads in one request), just like the CSV import in the Tuco app.
Request body
object[]
required
One or more contacts. A single contact is a one-element array. body is accepted as an alias
for this field.
Show lead fields
string
The phone number, in E.164 (e.g. "+12025551234"). This is the identifier that matters —
it is how the lead is deduplicated, and how you text them later. Numbers without a country
code are normalized using defaultCountryCode.
string
First name. Used for message personalization.
string
Last name.
string
Email address. Lowercased before dedup.
string
Company name.
string
Job title.
string
Free-text notes.
string
LinkedIn profile URL.
string
Alternate phone 1. Tried when the primary number is not reachable, and counted for dedup.
string
Alternate phone 2.
string
Alternate phone 3.
string
Alternate email 1.
string
Alternate email 2.
string
Alternate email 3.
object
Free-form key/value data. See custom field keys for the ones already in use.
string
Email of the workspace user who owns this contact. Falls back to the first user in the workspace when omitted or unrecognised.
string
The list these leads belong to, from GET /api/lists.
Omit to use the Quick Sends list. An id that does not exist returns 404.
string
default:"+1"
Used to normalize phone numbers that arrive without a country code, e.g. "+44".
string
Origin label stored on each lead, e.g. "api" or "gohighlevel".
string
GoHighLevel location id, stored on the created leads when syncing from GHL.
string
Applies an owner to every lead in the request. A per-lead contactOwnerEmail wins over this.
savedCount – number of new leads actually inserted.
duplicateCount – leads skipped as duplicates within the same list (email/phone‑based).
totalProcessed – total rows you attempted to upload.
listId – list the leads were added to.
leadIds – array of Tuco lead IDs for newly created leads only, in the same order as inserted. Use these to link created leads back to your system or to fetch/update them later.
leadListIds – array of list IDs the new leads were added to (one list per request; same as listId when adding to a single list).
duplicates – present only when some (but not all) leads were duplicates; each entry describes the submitted input and the existing lead in the list.
All duplicates – status 200 OK (not 409). No new leads are created; the body includes duplicateOnly: true, duplicateCount, totalProcessed, leadId (first existing), existingLeadIds, leadIds, duplicates (each with input and existingLead including _id), and integration IDs (ghlContactId, ghlLocationId, etc.) so you can reconcile with existing records and continue your workflow (e.g. n8n).Other errors: Validation failures return 400 with a readable error. If the requested list does not exist, you get 404. If the workspace is temporarily read‑only (e.g. payment past due), you get 402 with code: "READ_ONLY". See /api-reference/errors for more.
{"docsConfig":{"theme":"mint","$schema":"https://mintlify.com/docs.json","name":"Tuco AI","colors":{"primary":"#FF3515","light":"#FFF5F2","dark":"#111827"},"logo":{"light":"https://mintcdn.com/tucoai/oqQbf84LeXHYKs-3/logo/light.svg?fit=max\u0026auto=format\u0026n=oqQbf84LeXHYKs-3\u0026q=85\u0026s=c601a209f9f05fe52c2cd2e67d63adeb","dark":"https://mintcdn.com/tucoai/oqQbf84LeXHYKs-3/logo/dark.svg?fit=max\u0026auto=format\u0026n=oqQbf84LeXHYKs-3\u0026q=85\u0026s=2d4cbb7e9dea8411a50d67377ca76578"},"favicon":"https://mintcdn.com/tucoai/oqQbf84LeXHYKs-3/images/tuco_v1_round.svg?fit=max\u0026auto=format\u0026n=oqQbf84LeXHYKs-3\u0026q=85\u0026s=0c579fbfd834a8ce1afe94ec9a63c4a6","api":{"openapi":"api-reference/openapi.json","mdx":{"auth":{"method":"bearer"},"server":"https://app.tuco.ai"}},"navbar":{"links":[{"href":"mailto:support@tuco.ai","label":"Support"}],"primary":{"type":"button","label":"Get Started","href":"https://app.tuco.ai"}},"footer":{"socials":{"x":"https://x.com/tucoai","linkedin":"https://linkedin.com/company/tuco-ai"}},"contextual":{"options":["copy","view","chatgpt","claude","perplexity","mcp","cursor","vscode"],"display":"header"},"styling":{"latex":true},"navigation":{"global":{"anchors":[{"anchor":"Dashboard","icon":"browser","href":"https://app.tuco.ai"}]},"pages":[]}},"deployment":{"deploymentMetadataValue":{"subdomain":"tucoai","hasAudioNarration":false,"actualSubdomain":"tucoai","customDomains":["docs.tuco.ai"],"gitSource":{"type":"github","owner":"goforbg","repo":"tuco-docs","deployBranch":"master","contentDirectory":"","isPrivate":true,"mountPath":"","label":""},"entitlements":{},"buildId":"6b00f4f918818903542842d5","clientVersion":"0.0.4270","searchFilterCounts":[{"language":"default","tag":"API Reference","count":102},{"language":"default","tag":"Documentation","count":66},{"language":"default","tag":"Lines \u0026 Leads","count":23},{"language":"default","tag":"Messages","count":16},{"language":"default","tag":"Goal Bots","count":14},{"language":"default","tag":"Webhooks","count":13},{"language":"default","tag":"iMessage Guides","count":13},{"language":"default","tag":"Agency","count":11},{"language":"default","tag":"Core Features","count":9},{"language":"default","tag":"Integrations","count":8}]},"assistantConfig":{"enableStarterQuestions":false},"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":"site-roles","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":"starter-pricing","enabled":true,"variant":{"name":"treatment","enabled":true,"payload":{"type":"string","value":"treatment"},"feature_enabled":true},"impressionData":false},{"name":"llms-txt-v2","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"wildcard-email-auth","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false}],"googleFontsInlined":false},"customCss":[]}
{"page":{"pagePath":"api-reference/endpoint/create","slug":"/api-reference/endpoint/create","pageMetadata":{"title":"Create / Upload Lead Endpoint","api":"POST /api/leads","description":"Create one lead or bulk-upload many leads into a Tuco workspace in a single request, like a CSV import. Optional listId files them into a list.","href":"/api-reference/endpoint/create"},"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 one lead or bulk-upload many leads into a Tuco workspace in a single request, like a CSV import. Optional listId files them into a list.\"\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={a:`a`,code:`code`,hr:`hr`,li:`li`,p:`p`,pre:`pre`,span:`span`,strong:`strong`,ul:`ul`,..._provideComponents(),...props.components},{CodeBlock,Expandable,Heading,ParamField}=_components;if(!CodeBlock)_missingMdxReference(`CodeBlock`,true);if(!Expandable)_missingMdxReference(`Expandable`,true);if(!Heading)_missingMdxReference(`Heading`,true);if(!ParamField)_missingMdxReference(`ParamField`,true);return _jsxs(_Fragment,{children:[_jsx(Heading,{level:`2`,id:`endpoint`,children:`Endpoint`}),`\n`,_jsxs(_components.ul,{children:[`\n`,_jsxs(_components.li,{children:[_jsx(_components.strong,{children:`Method`}),`: `,_jsx(_components.code,{children:`POST`})]}),`\n`,_jsxs(_components.li,{children:[_jsx(_components.strong,{children:`Path`}),`: `,_jsx(_components.code,{children:`/api/leads`})]}),`\n`]}),`\n`,_jsx(_components.p,{children:`This endpoint is used both for creating a single lead and for bulk uploads (multiple leads in one request), just like the CSV import in the Tuco app.`}),`\n`,_jsx(_components.hr,{}),`\n`,_jsx(Heading,{level:`2`,id:`request-body`,children:`Request body`}),`\n`,_jsxs(ParamField,{body:`leads`,type:`object[]`,required:true,id:`param-leads`,children:[_jsxs(_components.p,{children:[`One or more contacts. A single contact is a one-element array. `,_jsx(_components.code,{children:`body`}),` is accepted as an alias\nfor this field.`]}),_jsxs(Expandable,{title:`lead fields`,children:[_jsx(ParamField,{body:`phone`,type:`string`,id:`param-phone`,children:_jsxs(_components.p,{children:[_jsx(_components.strong,{children:`The phone number, in E.164`}),` (e.g. `,_jsx(_components.code,{children:`\"+12025551234\"`}),`). This is the identifier that matters —\nit is how the lead is deduplicated, and how you text them later. Numbers without a country\ncode are normalized using `,_jsx(_components.code,{children:`defaultCountryCode`}),`.`]})}),_jsx(ParamField,{body:`firstName`,type:`string`,id:`param-first-name`,children:`First name. Used for message personalization.`}),_jsx(ParamField,{body:`lastName`,type:`string`,id:`param-last-name`,children:`Last name.`}),_jsx(ParamField,{body:`email`,type:`string`,id:`param-email`,children:`Email address. Lowercased before dedup.`}),_jsx(ParamField,{body:`companyName`,type:`string`,id:`param-company-name`,children:`Company name.`}),_jsx(ParamField,{body:`jobTitle`,type:`string`,id:`param-job-title`,children:`Job title.`}),_jsx(ParamField,{body:`notes`,type:`string`,id:`param-notes`,children:`Free-text notes.`}),_jsx(ParamField,{body:`linkedinUrl`,type:`string`,id:`param-linkedin-url`,children:`LinkedIn profile URL.`}),_jsx(ParamField,{body:`altPhone1`,type:`string`,id:`param-alt-phone1`,children:`Alternate phone 1. Tried when the primary number is not reachable, and counted for dedup.`}),_jsx(ParamField,{body:`altPhone2`,type:`string`,id:`param-alt-phone2`,children:`Alternate phone 2.`}),_jsx(ParamField,{body:`altPhone3`,type:`string`,id:`param-alt-phone3`,children:`Alternate phone 3.`}),_jsx(ParamField,{body:`altEmail1`,type:`string`,id:`param-alt-email1`,children:`Alternate email 1.`}),_jsx(ParamField,{body:`altEmail2`,type:`string`,id:`param-alt-email2`,children:`Alternate email 2.`}),_jsx(ParamField,{body:`altEmail3`,type:`string`,id:`param-alt-email3`,children:`Alternate email 3.`}),_jsxs(ParamField,{body:`customFields`,type:`object`,id:`param-custom-fields`,children:[`Free-form key/value data. See `,_jsx(_components.a,{href:`/api-reference/endpoint/custom-field-keys`,children:`custom field keys`}),` for the ones already in use.`]}),_jsx(ParamField,{body:`contactOwnerEmail`,type:`string`,id:`param-contact-owner-email`,children:`Email of the workspace user who owns this contact. Falls back to the first user in the workspace when omitted or unrecognised.`})]})]}),`\n`,_jsx(ParamField,{body:`listId`,type:`string`,id:`param-list-id`,children:_jsxs(_components.p,{children:[`The list these leads belong to, from `,_jsx(_components.a,{href:`/api-reference/endpoint/list-lists`,children:_jsx(_components.code,{children:`GET /api/lists`})}),`.\nOmit to use the `,_jsx(_components.strong,{children:`Quick Sends`}),` list. An id that does not exist returns `,_jsx(_components.code,{children:`404`}),`.`]})}),`\n`,_jsx(ParamField,{body:`defaultCountryCode`,type:`string`,default:`+1`,id:`param-default-country-code`,children:_jsxs(_components.p,{children:[`Used to normalize phone numbers that arrive without a country code, e.g. `,_jsx(_components.code,{children:`\"+44\"`}),`.`]})}),`\n`,_jsx(ParamField,{body:`source`,type:`string`,id:`param-source`,children:_jsxs(_components.p,{children:[`Origin label stored on each lead, e.g. `,_jsx(_components.code,{children:`\"api\"`}),` or `,_jsx(_components.code,{children:`\"gohighlevel\"`}),`.`]})}),`\n`,_jsx(ParamField,{body:`ghlLocationId`,type:`string`,id:`param-ghl-location-id`,children:_jsx(_components.p,{children:`GoHighLevel location id, stored on the created leads when syncing from GHL.`})}),`\n`,_jsx(ParamField,{body:`contactOwnerEmail`,type:`string`,id:`param-contact-owner-email-1`,children:_jsxs(_components.p,{children:[`Applies an owner to every lead in the request. A per-lead `,_jsx(_components.code,{children:`contactOwnerEmail`}),` wins over this.`]})}),`\n`,_jsx(Heading,{level:`3`,id:`example-body`,children:`Example body`}),`\n`,_jsx(CodeBlock,{filename:``,numberOfLines:`21`,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:`21`,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:` \"leads\"`}),_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`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#116329`,\"--shiki-dark\":`#9CDCFE`},children:` \"firstName\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`: `}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:`\"John\"`}),_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:` \"lastName\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`: `}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:`\"Doe\"`}),_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:` \"email\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`: `}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:`\"john@example.com\"`}),_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:` \"phone\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`: `}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:`\"+12025551234\"`}),_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:` \"companyName\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`: `}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:`\"Acme Corp\"`}),_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:` \"jobTitle\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`: `}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:`\"CEO\"`}),_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:` \"notes\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`: `}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:`\"Warm intro from Sarah\"`}),_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:` \"contactOwnerEmail\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`: `}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:`\"rep@yourcompany.com\"`}),_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:` \"customFields\"`}),_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:` \"industry\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`: `}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:`\"Technology\"`}),_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:` \"segment\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`: `}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:`\"Mid-market\"`})]}),`\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`,_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:` \"listId\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`: `}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:`\"507f1f77bcf86cd799439011\"`}),_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:` \"source\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`: `}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:`\"api\"`}),_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:` \"defaultCountryCode\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`: `}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:`\"+1\"`})]}),`\n`,_jsx(_components.span,{className:`line`,children:_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`}`})}),`\n`]})})}),`\n`,_jsxs(_components.ul,{children:[`\n`,_jsxs(_components.li,{children:[_jsx(_components.code,{children:`leads`}),` – one or more contacts; a single contact is just a one‑element array.`]}),`\n`,_jsxs(_components.li,{children:[_jsx(_components.code,{children:`listId`}),` – `,_jsx(_components.strong,{children:`Optional.`}),` Tuco list that should own these leads. Omit to use the `,_jsx(_components.strong,{children:`Quick Sends`}),` list.`]}),`\n`,_jsxs(_components.li,{children:[_jsx(_components.code,{children:`source`}),` – optional origin label (for example, `,_jsx(_components.code,{children:`\"api\"`}),` or `,_jsx(_components.code,{children:`\"gohighlevel\"`}),`).`]}),`\n`,_jsxs(_components.li,{children:[_jsx(_components.code,{children:`defaultCountryCode`}),` – used to normalize phone numbers when no country code is present.`]}),`\n`,_jsxs(_components.li,{children:[_jsx(_components.code,{children:`ghlLocationId`}),` – optional; used when syncing with GoHighLevel.`]}),`\n`,_jsxs(_components.li,{children:[_jsx(_components.code,{children:`contactOwnerEmail`}),` – Email of the workspace user who owns this contact. If omitted or invalid, defaults to the first user in the workspace.`]}),`\n`,_jsxs(_components.li,{children:[`You may send `,_jsx(_components.code,{children:`body`}),` as an alias for `,_jsx(_components.code,{children:`leads`}),` (same array shape).`]}),`\n`]}),`\n`,_jsx(_components.hr,{}),`\n`,_jsx(Heading,{level:`2`,id:`response`,children:`Response`}),`\n`,_jsxs(_components.p,{children:[_jsx(_components.strong,{children:`Success`}),` – status `,_jsx(_components.code,{children:`201 Created`}),` when at least one lead was created, or `,_jsx(_components.code,{children:`200 OK`}),` when the request succeeded but no new leads were inserted. Example:`]}),`\n`,_jsx(CodeBlock,{filename:``,numberOfLines:`14`,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:`14`,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:` \"message\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`: `}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:`\"Leads saved successfully\"`}),_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:` \"savedCount\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`: `}),_jsx(_components.span,{style:{color:`#0550AE`,\"--shiki-dark\":`#B5CEA8`},children:`1`}),_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:` \"duplicateCount\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`: `}),_jsx(_components.span,{style:{color:`#0550AE`,\"--shiki-dark\":`#B5CEA8`},children:`0`}),_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:` \"totalProcessed\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`: `}),_jsx(_components.span,{style:{color:`#0550AE`,\"--shiki-dark\":`#B5CEA8`},children:`1`}),_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:` \"listId\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`: `}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:`\"507f1f77bcf86cd799439011\"`}),_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:` \"leadId\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`: `}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:`\"674a1b2c3d4e5f678901234a\"`}),_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:` \"leadIds\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`: [`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:`\"674a1b2c3d4e5f678901234a\"`}),_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:` \"leadListIds\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`: [`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:`\"507f1f77bcf86cd799439011\"`}),_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:` \"ghlContactId\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`: `}),_jsx(_components.span,{style:{color:`#0550AE`,\"--shiki-dark\":`#569CD6`},children:`null`}),_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:` \"ghlLocationId\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`: `}),_jsx(_components.span,{style:{color:`#0550AE`,\"--shiki-dark\":`#569CD6`},children:`null`}),_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:` \"hsPortalId\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`: `}),_jsx(_components.span,{style:{color:`#0550AE`,\"--shiki-dark\":`#569CD6`},children:`null`}),_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:` \"hsContactId\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`: `}),_jsx(_components.span,{style:{color:`#0550AE`,\"--shiki-dark\":`#569CD6`},children:`null`})]}),`\n`,_jsx(_components.span,{className:`line`,children:_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`}`})}),`\n`]})})}),`\n`,_jsx(_components.p,{children:`Response fields:`}),`\n`,_jsxs(_components.ul,{children:[`\n`,_jsxs(_components.li,{children:[_jsx(_components.code,{children:`savedCount`}),` – number of new leads actually inserted.`]}),`\n`,_jsxs(_components.li,{children:[_jsx(_components.code,{children:`duplicateCount`}),` – leads skipped as duplicates within the same list (email/phone‑based).`]}),`\n`,_jsxs(_components.li,{children:[_jsx(_components.code,{children:`totalProcessed`}),` – total rows you attempted to upload.`]}),`\n`,_jsxs(_components.li,{children:[_jsx(_components.code,{children:`listId`}),` – list the leads were added to.`]}),`\n`,_jsxs(_components.li,{children:[_jsx(_components.code,{children:`leadIds`}),` – array of Tuco lead IDs for `,_jsx(_components.strong,{children:`newly created`}),` leads only, in the same order as inserted. Use these to link created leads back to your system or to fetch/update them later.`]}),`\n`,_jsxs(_components.li,{children:[_jsx(_components.code,{children:`leadListIds`}),` – array of list IDs the new leads were added to (one list per request; same as `,_jsx(_components.code,{children:`listId`}),` when adding to a single list).`]}),`\n`,_jsxs(_components.li,{children:[_jsx(_components.code,{children:`duplicates`}),` – present only when some (but not all) leads were duplicates; each entry describes the submitted input and the existing lead in the list.`]}),`\n`]}),`\n`,_jsxs(_components.p,{children:[_jsx(_components.strong,{children:`All duplicates`}),` – status `,_jsx(_components.strong,{children:_jsx(_components.code,{children:`200 OK`})}),` (not 409). No new leads are created; the body includes `,_jsx(_components.code,{children:`duplicateOnly: true`}),`, `,_jsx(_components.code,{children:`duplicateCount`}),`, `,_jsx(_components.code,{children:`totalProcessed`}),`, `,_jsx(_components.code,{children:`leadId`}),` (first existing), `,_jsx(_components.code,{children:`existingLeadIds`}),`, `,_jsx(_components.code,{children:`leadIds`}),`, `,_jsx(_components.code,{children:`duplicates`}),` (each with `,_jsx(_components.code,{children:`input`}),` and `,_jsx(_components.code,{children:`existingLead`}),` including `,_jsx(_components.code,{children:`_id`}),`), and integration IDs (`,_jsx(_components.code,{children:`ghlContactId`}),`, `,_jsx(_components.code,{children:`ghlLocationId`}),`, etc.) so you can reconcile with existing records and continue your workflow (e.g. n8n).`]}),`\n`,_jsxs(_components.p,{children:[_jsx(_components.strong,{children:`Other errors:`}),` Validation failures return `,_jsx(_components.code,{children:`400`}),` with a readable error. If the requested list does not exist, you get `,_jsx(_components.code,{children:`404`}),`. If the workspace is temporarily read‑only (e.g. payment past due), you get `,_jsx(_components.code,{children:`402`}),` with `,_jsx(_components.code,{children:`code: \"READ_ONLY\"`}),`. See `,_jsx(_components.code,{children:`/api-reference/errors`}),` for more.`]})]})}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":"Create / Upload Lead Endpoint","api":"POST /api/leads","description":"Create one lead or bulk-upload many leads into a Tuco workspace in a single request, like a CSV import. Optional listId files them into a list.","href":"/api-reference/endpoint/create"}}},"mdxSourceWithNoJs":null},"mdxExtracts":{"tableOfContents":[{"title":"Endpoint","slug":"endpoint","depth":2,"children":[]},{"title":"Request body","slug":"request-body","depth":2,"children":[{"title":"Example body","slug":"example-body","depth":3,"children":[]}]},{"title":"Response","slug":"response","depth":2,"children":[]}],"codeExamples":{},"endpoint":{"title":"Create / Upload Lead Endpoint","path":"/api/leads","servers":[{"url":"https://app.tuco.ai"}],"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":{"leads":[{"type":"array","items":[{"type":"object","properties":{"phone":[{"type":"string","description":"The phone number, in E.164 (e.g. `\"+12025551234\"` ). This is the identifier that matters — it is how the lead is deduplicated, and how you text them later. Numbers without a country code are normalized using `defaultCountryCode` ."}],"firstName":[{"type":"string","description":"First name. Used for message personalization."}],"lastName":[{"type":"string","description":"Last name."}],"email":[{"type":"string","description":"Email address. Lowercased before dedup."}],"companyName":[{"type":"string","description":"Company name."}],"jobTitle":[{"type":"string","description":"Job title."}],"notes":[{"type":"string","description":"Free-text notes."}],"linkedinUrl":[{"type":"string","description":"LinkedIn profile URL."}],"altPhone1":[{"type":"string","description":"Alternate phone 1. Tried when the primary number is not reachable, and counted for dedup."}],"altPhone2":[{"type":"string","description":"Alternate phone 2."}],"altPhone3":[{"type":"string","description":"Alternate phone 3."}],"altEmail1":[{"type":"string","description":"Alternate email 1."}],"altEmail2":[{"type":"string","description":"Alternate email 2."}],"altEmail3":[{"type":"string","description":"Alternate email 3."}],"customFields":[{"type":"object","properties":{},"description":"Free-form key/value data. See custom field keys for the ones already in use."}],"contactOwnerEmail":[{"type":"string","description":"Email of the workspace user who owns this contact. Falls back to the first user in the workspace when omitted or unrecognised."}]}}],"description":"One or more contacts. A single contact is a one-element array. `body` is accepted as an alias for this field.","required":true}],"listId":[{"type":"string","description":"The list these leads belong to, from `GET /api/lists` . Omit to use the Quick Sends list. An id that does not exist returns `404` ."}],"defaultCountryCode":[{"type":"string","description":"Used to normalize phone numbers that arrive without a country code, e.g. `\"+44\"` ."}],"source":[{"type":"string","description":"Origin label stored on each lead, e.g. `\"api\"` or `\"gohighlevel\"` ."}],"ghlLocationId":[{"type":"string","description":"GoHighLevel location id, stored on the created leads when syncing from GHL."}],"contactOwnerEmail":[{"type":"string","description":"Applies an owner to every lead in the request. A per-lead `contactOwnerEmail` wins over this."}]}}],"examples":{"example":{"value":{"leads":[{"phone":"\u003cstring>","firstName":"\u003cstring>","lastName":"\u003cstring>","email":"\u003cstring>","companyName":"\u003cstring>","jobTitle":"\u003cstring>","notes":"\u003cstring>","linkedinUrl":"\u003cstring>","altPhone1":"\u003cstring>","altPhone2":"\u003cstring>","altPhone3":"\u003cstring>","altEmail1":"\u003cstring>","altEmail2":"\u003cstring>","altEmail3":"\u003cstring>","customFields":{},"contactOwnerEmail":"\u003cstring>"}],"listId":"\u003cstring>","defaultCountryCode":"\u003cstring>","source":"\u003cstring>","ghlLocationId":"\u003cstring>","contactOwnerEmail":"\u003cstring>"}}}}}},"response":{},"deprecated":false}},"jsLinks":[],"subdomain":"tucoai","siteName":"Tuco AI","title":"Create / Upload Lead Endpoint - Tuco AI","navMaps":{"firstHrefInVersion":{},"firstHrefInLanguage":{}},"lastModified":"2026-11-12T14:04:13.597Z","originalFileLocation":"api-reference/endpoint/create.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 one lead or bulk-upload many leads into a Tuco workspace in a single request, like a CSV import. Optional listId files them into a list.\">\u003cmeta data-mint-head name=\"application-name\" content=\"Tuco AI\">\u003cmeta data-mint-head name=\"generator\" content=\"Mintlify\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"192x192\" href=\"/mintlify-assets/_mintlify/favicons/tucoai/pPwoyrnQogjfeGN5/_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/tucoai/pPwoyrnQogjfeGN5/_generated/favicon/apple-touch-icon.png\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"16x16\" href=\"/mintlify-assets/_mintlify/favicons/tucoai/pPwoyrnQogjfeGN5/_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/tucoai/pPwoyrnQogjfeGN5/_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/tucoai/pPwoyrnQogjfeGN5/_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/tucoai/pPwoyrnQogjfeGN5/_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/tucoai/pPwoyrnQogjfeGN5/_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/tucoai/pPwoyrnQogjfeGN5/_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/tucoai/pPwoyrnQogjfeGN5/_generated/favicon-dark/favicon.ico\" media=\"(prefers-color-scheme: dark)\">\u003cmeta data-mint-head property=\"og:title\" content=\"Create / Upload Lead Endpoint - Tuco AI\">\u003cmeta data-mint-head property=\"og:description\" content=\"Create one lead or bulk-upload many leads into a Tuco workspace in a single request, like a CSV import. Optional listId files them into a list.\">\u003cmeta data-mint-head property=\"og:site_name\" content=\"Tuco AI\">\u003cmeta data-mint-head property=\"og:url\" content=\"https://docs.tuco.ai/api-reference/endpoint/create\">\u003cmeta data-mint-head property=\"og:type\" content=\"website\">\u003cmeta data-mint-head property=\"og:image\" content=\"https://tucoai.mintlify.site/_mintlify/api/og/v2?division=Lines+%26+Leads\u0026amp;title=Create+%2F+Upload+Lead+Endpoint\u0026amp;description=Create+one+lead+or+bulk-upload+many+leads+into+a+Tuco+workspace+in+a+single+request%2C+like+a+CSV+import.+Optional+listId+files+them+into+a+list.\u0026amp;theme=9d3f09169be245bb34dd9f73\u0026amp;signature=77e235594cd3b3bf7338b0b605879ae3cb09cff8f19847a935d74c7f74f0d4f3\">\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=\"Create / Upload Lead Endpoint - Tuco AI\">\u003cmeta data-mint-head name=\"twitter:description\" content=\"Create one lead or bulk-upload many leads into a Tuco workspace in a single request, like a CSV import. Optional listId files them into a list.\">\u003cmeta data-mint-head name=\"twitter:image\" content=\"https://tucoai.mintlify.site/_mintlify/api/og/v2?division=Lines+%26+Leads\u0026amp;title=Create+%2F+Upload+Lead+Endpoint\u0026amp;description=Create+one+lead+or+bulk-upload+many+leads+into+a+Tuco+workspace+in+a+single+request%2C+like+a+CSV+import.+Optional+listId+files+them+into+a+list.\u0026amp;theme=9d3f09169be245bb34dd9f73\u0026amp;signature=77e235594cd3b3bf7338b0b605879ae3cb09cff8f19847a935d74c7f74f0d4f3\">\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/tucoai/pPwoyrnQogjfeGN5/_generated/favicon/browserconfig.xml\">\u003cmeta data-mint-head name=\"apple-mobile-web-app-title\" content=\"Tuco AI\">\u003cmeta data-mint-head name=\"msapplication-TileColor\" content=\"#FF3515\">\u003clink data-mint-head rel=\"canonical\" href=\"https://docs.tuco.ai/api-reference/endpoint/create\">\u003clink data-mint-head rel=\"alternate\" type=\"application/xml\" href=\"/sitemap.xml\">\u003clink data-mint-head rel=\"alternate\" type=\"text/markdown\" href=\"/api-reference/endpoint/create.md\">\u003cscript data-mint-head type=\"application/ld+json\">{\"@context\":\"https://schema.org\",\"@graph\":[{\"@type\":\"Organization\",\"@id\":\"https://docs.tuco.ai/#organization\",\"name\":\"Tuco AI\",\"url\":\"https://docs.tuco.ai\",\"logo\":{\"@type\":\"ImageObject\",\"url\":\"https://mintcdn.com/tucoai/oqQbf84LeXHYKs-3/logo/light.svg?fit=max\u0026auto=format\u0026n=oqQbf84LeXHYKs-3\u0026q=85\u0026s=c601a209f9f05fe52c2cd2e67d63adeb\"}},{\"@type\":\"WebSite\",\"@id\":\"https://docs.tuco.ai#website\",\"name\":\"Tuco AI\",\"url\":\"https://docs.tuco.ai\",\"publisher\":{\"@id\":\"https://docs.tuco.ai/#organization\"}},{\"@type\":\"WebPage\",\"@id\":\"https://docs.tuco.ai/api-reference/endpoint/create#webpage\",\"url\":\"https://docs.tuco.ai/api-reference/endpoint/create\",\"name\":\"Create / Upload Lead Endpoint\",\"description\":\"Create one lead or bulk-upload many leads into a Tuco workspace in a single request, like a CSV import. Optional listId files them into a list.\",\"dateModified\":\"2026-11-12T14:04:13.597Z\",\"isPartOf\":{\"@id\":\"https://docs.tuco.ai#website\"},\"breadcrumb\":{\"@id\":\"https://docs.tuco.ai/api-reference/endpoint/create#breadcrumb\"}},{\"@type\":\"BreadcrumbList\",\"@id\":\"https://docs.tuco.ai/api-reference/endpoint/create#breadcrumb\",\"itemListElement\":[{\"@type\":\"ListItem\",\"position\":1,\"name\":\"Lines \u0026 Leads\",\"item\":\"https://docs.tuco.ai/api-reference/lines\"},{\"@type\":\"ListItem\",\"position\":2,\"name\":\"Create / Upload Lead Endpoint\",\"item\":\"https://docs.tuco.ai/api-reference/endpoint/create\"}]},{\"@type\":[\"TechArticle\",\"APIReference\"],\"@id\":\"https://docs.tuco.ai/api-reference/endpoint/create#apireference\",\"headline\":\"Create / Upload Lead Endpoint\",\"name\":\"Create / Upload Lead Endpoint\",\"description\":\"Create one lead or bulk-upload many leads into a Tuco workspace in a single request, like a CSV import. Optional listId files them into a list.\",\"url\":\"https://docs.tuco.ai/api-reference/endpoint/create\",\"mainEntityOfPage\":{\"@id\":\"https://docs.tuco.ai/api-reference/endpoint/create#webpage\"},\"dateModified\":\"2026-11-12T14:04:13.597Z\",\"publisher\":{\"@id\":\"https://docs.tuco.ai/#organization\"},\"isPartOf\":{\"@id\":\"https://docs.tuco.ai#website\"}}]}\u003c/script>\u003cscript data-mint-head type=\"application/ld+json\">{\"@context\":\"https://schema.org\",\"@type\":\"WebSite\",\"name\":\"Tuco AI\",\"publisher\":{\"@type\":\"Organization\",\"name\":\"Tuco AI\"},\"provider\":{\"@type\":\"Organization\",\"name\":\"Mintlify\",\"url\":\"https://mintlify.com\"}}\u003c/script>","agentPointerHref":"/api-reference/endpoint/create.md","siteName":"Tuco AI","nav":{"global":{"anchors":[{"anchor":"Dashboard","icon":"browser","href":"https://app.tuco.ai"}]},"tabs":[{"tab":"Documentation","pages":[{"title":"Documentation","href":""}]},{"tab":"API Reference","groups":[{"group":"Overview","pages":[{"title":"API Overview","icon":"code","href":"/api-reference/introduction"},{"title":"Tuco API Keys","icon":"key","href":"/api-reference/api-keys"},{"title":"Agency API Keys","icon":"building","href":"/api-reference/agency-api-keys"}]},{"group":"Webhooks","pages":[{"title":"Webhooks Overview","icon":"webhook","href":"/api-reference/endpoint/webhook"},{"title":"Message Webhooks","icon":"webhook","href":"/api-reference/message-webhooks"},{"title":"List Webhooks","api":"GET /api/webhooks","href":"/api-reference/endpoint/list-webhooks"},{"title":"Create Webhook","api":"POST /api/webhooks","href":"/api-reference/endpoint/create-webhook"},{"title":"Get Webhook","api":"GET /api/webhooks/{id}","href":"/api-reference/endpoint/get-webhook"},{"title":"Update Webhook","api":"PATCH /api/webhooks/{id}","href":"/api-reference/endpoint/update-webhook"},{"title":"Delete Webhook","api":"DELETE /api/webhooks/{id}","href":"/api-reference/endpoint/delete-webhook"},{"title":"Rotate Webhook Secret","api":"POST /api/webhooks/{id}/rotate-secret","href":"/api-reference/endpoint/rotate-webhook-secret"},{"title":"Send Test Webhook","api":"POST /api/webhooks/{id}/test","href":"/api-reference/endpoint/send-test-webhook"},{"title":"Webhook Health Check","api":"POST /api/webhooks/{id}/health-check","href":"/api-reference/endpoint/test-webhook"},{"title":"List Webhook Deliveries","api":"GET /api/webhooks/{id}/deliveries","href":"/api-reference/endpoint/list-webhook-deliveries"},{"title":"Get Webhook Delivery","api":"GET /api/webhooks/{id}/deliveries/{deliveryId}","href":"/api-reference/endpoint/get-webhook-delivery"},{"title":"Replay Webhook Delivery","api":"POST /api/webhooks/{id}/deliveries/{deliveryId}/replay","href":"/api-reference/endpoint/replay-webhook-delivery"}]},{"group":"Errors and status codes","pages":[{"title":"Errors \u0026 Status Codes","icon":"circle-exclamation","href":"/api-reference/errors"}]},{"group":"iMessage Availability","pages":[{"title":"Check iMessage Availability (Single Address)","api":"GET /api/check-availability","href":"/api-reference/endpoint/check-availability"},{"title":"Check iMessage Availability (Round-Robin)","api":"POST /api/check-availability-rr","href":"/api-reference/endpoint/check-availability-rr"},{"title":"Check iMessage Availability (Single Lead)","api":"GET /api/leads/check-availability","href":"/api-reference/endpoint/lead-check-availability"},{"title":"Bulk Availability Check Endpoint","api":"POST /api/leads/check-availability","href":"/api-reference/endpoint/bulk-check-availability"}]},{"group":"Messages","pages":[{"title":"Messages","icon":"paper-plane","href":"/api-reference/messages"},{"title":"Drip (bulk shock-absorber)","icon":"faucet-drip","href":"/api-reference/drip"},{"title":"Send Message","api":"POST /api/messages","href":"/api-reference/endpoint/send-message"},{"title":"Get Message History","api":"GET /api/messages","href":"/api-reference/endpoint/get-messages"},{"title":"Send Drip","api":"POST /api/drip","href":"/api-reference/endpoint/send-drip"},{"title":"Send Reaction","api":"POST /api/messages/react","href":"/api-reference/endpoint/send-reaction"},{"title":"Send to a Group Chat","api":"POST /api/unibox/send-group","href":"/api-reference/endpoint/send-group-message"},{"title":"Create a Group Chat","api":"POST /api/unibox/create-group","href":"/api-reference/endpoint/create-group"},{"title":"Send Typing Indicator","api":"POST /api/messages/typing","href":"/api-reference/endpoint/send-typing-indicator"},{"title":"Send with Attachments","api":"POST /api/messages","href":"/api-reference/endpoint/send-with-attachments"},{"title":"Upload Attachment","openapi":"POST /api/attachments/upload","href":"/api-reference/upload-attachment"},{"title":"Cancel Pending Messages","api":"POST /api/messages/cancel-for-lead","href":"/api-reference/endpoint/cancel-for-lead"},{"title":"Read Fallback SMS Config","api":"GET /api/workspace/fallback-config","href":"/api-reference/endpoint/fallback-config"},{"title":"Update Fallback SMS Config","api":"PATCH /api/workspace/fallback-config","href":"/api-reference/endpoint/update-fallback-config"},{"title":"Atomic Duplicate Guard — POST /api/messages","href":"/imessage-double-send-guard"},{"title":"Message Status","api":"GET /api/messages/{messageId}/journey","href":"/api-reference/endpoint/message-journey"}]},{"group":"Voice / Calling","pages":[{"title":"Place a Call Endpoint","api":"POST /api/voice/calls","tag":"BETA","href":"/api-reference/endpoint/place-call"},{"title":"Get Call Recordings Endpoint","api":"GET /api/voice/recordings","tag":"BETA","href":"/api-reference/endpoint/get-recordings"},{"title":"List Recordings \u0026 Uploads Endpoint","api":"GET /api/attachments/list","tag":"BETA","href":"/api-reference/endpoint/list-recordings"}]},{"group":"Replies","pages":[{"title":"List Conversations","api":"GET /api/unibox/conversations","href":"/api-reference/endpoint/conversations"},{"title":"Check Replies","api":"GET /api/replies","href":"/api-reference/endpoint/get-replies"}]},{"group":"Do Not Contact","pages":[{"title":"List / Check Do-Not-Contact","openapi":"GET /api/dnc","href":"/api-reference/endpoint/list-dnc"},{"title":"Add to Do-Not-Contact","openapi":"POST /api/dnc","href":"/api-reference/endpoint/add-dnc"},{"title":"Bulk Add to Do-Not-Contact","openapi":"PATCH /api/dnc","href":"/api-reference/endpoint/bulk-add-dnc"}]},{"group":"Lines \u0026 Leads","pages":[{"title":"Lines API","icon":"phone","href":"/api-reference/lines"},{"title":"Get All Lines","api":"GET /api/lines/by-user","href":"/api-reference/endpoint/get-lines"},{"title":"Update a Line","api":"PATCH /api/lines/{id}","href":"/api-reference/endpoint/update-line"},{"title":"Line Plan Limits","api":"GET /api/lines/limits","href":"/api-reference/endpoint/line-limits"},{"title":"Calling Add-ons","api":"GET /api/lines/{id}/calling-addons","href":"/api-reference/endpoint/calling-addons"},{"title":"Calling Add-on Slots","api":"GET /api/lines/calling-addon-slots","href":"/api-reference/endpoint/calling-addon-slots"},{"title":"Caller ID Details","api":"GET /api/workspace/caller-id-profile","href":"/api-reference/endpoint/caller-id-profile"},{"title":"Leads API","description":"How Tuco AI treats leads created, updated, and viewed through the API. Part of the Tuco AI iMessage API reference — bearer-token auth, JSON responses, examples.","icon":"users","href":"/api-reference/leads"},{"title":"Create / Upload Lead Endpoint","api":"POST /api/leads","href":"/api-reference/endpoint/create"},{"title":"Get \u0026 Search Leads","api":"GET /api/leads","description":"Retrieve, list, and search leads in a workspace — find a lead by name, email, phone, or company, fetch one by id, or page through them all. Bearer-token auth.","href":"/api-reference/endpoint/get"},{"title":"Delete Lead Endpoint","api":"DELETE /api/leads","href":"/api-reference/endpoint/delete"},{"title":"List Lead Lists","api":"GET /api/lists","href":"/api-reference/endpoint/list-lists"},{"title":"Create Lead List","api":"POST /api/lists","href":"/api-reference/endpoint/create-list"},{"title":"Delete Lead List","api":"DELETE /api/lists","href":"/api-reference/endpoint/delete-list"},{"title":"List Custom Field Keys","api":"GET /api/leads/custom-field-keys","href":"/api-reference/endpoint/custom-field-keys"},{"title":"Create Line Request","api":"POST /api/line-requests","href":"/api-reference/endpoint/create-line-request"},{"title":"Get Line Request","api":"GET /api/line-requests/{id}","href":"/api-reference/endpoint/get-line-request"},{"title":"Manage Line Request","api":"POST /api/line-requests/{id}","href":"/api-reference/endpoint/manage-line-request"},{"title":"Cancel a Line","api":"POST /api/lines/cancel","href":"/api-reference/endpoint/cancel-line"},{"title":"Get Lead","api":"GET /api/leads/{id}","href":"/api-reference/endpoint/get-lead"},{"title":"Update Lead","api":"PATCH /api/leads/{id}","href":"/api-reference/endpoint/update-lead"},{"title":"Add or Remove Lead Tags","api":"POST /api/leads/tags","href":"/api-reference/endpoint/lead-tags"},{"title":"List Lead Tags","api":"GET /api/leads/tags","href":"/api-reference/endpoint/list-lead-tags"}]},{"group":"Analytics","pages":[{"title":"Analytics","icon":"chart-line","href":"/api-reference/analytics"},{"title":"Analytics Insights","api":"GET /api/analytics/insights","href":"/api-reference/endpoint/analytics-insights"},{"title":"Analytics Day Conversations","api":"GET /api/analytics/conversations","href":"/api-reference/endpoint/analytics-conversations"}]},{"group":"Goal Bots","pages":[{"title":"List Goal Bots","api":"GET /api/goal-bots","href":"/api-reference/endpoint/list-goal-bots"},{"title":"Create Goal Bot","api":"POST /api/goal-bots","href":"/api-reference/endpoint/create-goal-bot"},{"title":"Get Goal Bot","api":"GET /api/goal-bots/{id}","href":"/api-reference/endpoint/get-goal-bot"},{"title":"Update Goal Bot","api":"PATCH /api/goal-bots/{id}","href":"/api-reference/endpoint/update-goal-bot"},{"title":"Delete Goal Bot","api":"DELETE /api/goal-bots/{id}","href":"/api-reference/endpoint/archive-goal-bot"},{"title":"Simulate Goal Bot","api":"POST /api/goal-bots/{id}/simulate","href":"/api-reference/endpoint/simulate-goal-bot"},{"title":"Reply Hours","api":"GET|PUT|DELETE /api/goal-bots/{id}/reply-hours","href":"/api-reference/endpoint/reply-hours"},{"title":"List Instruction Bots (retired)","api":"GET /api/instructions","href":"/api-reference/endpoint/list-instruction-bots"},{"title":"List Task Agents","api":"GET /api/tasks","href":"/api-reference/endpoint/list-task-agents"},{"title":"Create Task Agent","api":"POST /api/tasks","href":"/api-reference/endpoint/create-task-agent"},{"title":"Update Task Agent","api":"PATCH /api/tasks/{id}","href":"/api-reference/endpoint/update-task-agent"},{"title":"Delete Task Agent","api":"DELETE /api/tasks/{id}","href":"/api-reference/endpoint/delete-task-agent"},{"title":"Enroll Lead (instruction bots)","api":"POST /api/instructions/{id}/enroll","href":"/api-reference/endpoint/enroll-lead"},{"title":"Unenroll Lead","api":"DELETE /api/goal-bots/{id}/enroll","href":"/api-reference/endpoint/unenroll-lead"}]},{"group":"API Tools","pages":[{"title":"List API Tools","api":"GET /api/campaign-tools","href":"/api-reference/endpoint/list-tools"},{"title":"Create or Update API Tool","api":"POST /api/campaign-tools","href":"/api-reference/endpoint/save-tool"},{"title":"Delete API Tool","api":"DELETE /api/campaign-tools","href":"/api-reference/endpoint/delete-tool"},{"title":"Test API Tool","api":"POST /api/campaign-tools/test","href":"/api-reference/endpoint/test-tool"}]},{"group":"Agency","pages":[{"title":"Agency API Keys","icon":"building","href":"/api-reference/agency-api-keys"},{"title":"List Agency Workspaces","api":"GET /api/agency/subaccounts","href":"/api-reference/endpoint/agency-list-workspaces"},{"title":"Create Agency Workspace","api":"POST /api/agency/subaccounts","href":"/api-reference/endpoint/agency-create-workspace"},{"title":"Re-mint a Client Workspace Key","api":"POST /api/agency/workspace-keys","href":"/api-reference/endpoint/agency-workspace-keys"},{"title":"List Agency Lines","api":"GET /api/agency/lines","href":"/api-reference/endpoint/agency-list-lines"},{"title":"Move a Line Between Workspaces","api":"POST /api/agency/lines","href":"/api-reference/endpoint/agency-move-line"},{"title":"Agency Overview Stats","api":"GET /api/agency/overview","href":"/api-reference/endpoint/agency-overview"},{"title":"Agency Email Preferences","api":"POST /api/agency/email-preferences","href":"/api-reference/endpoint/agency-email-preferences"},{"title":"Agency Webhooks","api":"POST /api/agency/webhooks","href":"/api-reference/endpoint/agency-webhooks"},{"title":"Subscribe a Client to a Plan","api":"POST /api/agency/billing/subscribe","href":"/api-reference/endpoint/agency-subscribe"},{"title":"Monthly Statement","api":"GET /api/agency/statement","href":"/api-reference/endpoint/agency-statement"}]},{"group":"Workspace settings","pages":[{"title":"Workspace Email Preferences","api":"POST /api/email-preferences","href":"/api-reference/endpoint/email-preferences"},{"title":"Invite a Teammate","api":"POST /api/team/invite","href":"/api-reference/endpoint/team-invite"},{"title":"Force a Line Health Check","api":"GET /api/lines/check-availability","href":"/api-reference/endpoint/line-health-check"}]}]}]},"basePath":"","title":"Create / Upload Lead Endpoint - Tuco AI","deploymentId":"dpl_DyXGnKeCjZyA3sUdfMJ7FjkdBefg","buildId":"dpl_DyXGnKeCjZyA3sUdfMJ7FjkdBefg","dynamics":["c2aa737661","2b790eda92","b0f84f53ff"],"chunks":["OpenApiReferenceProvider-CiUHMMOm.js","snippetPresets-BgfXU7Bw.js","utils-DWvOwgy_.js","style-to-object-BY3JEAdk.js","utils-BN7RXSMJ.js","v4-DIgz8zy6.js","addUniqueKeysToSchema-CFw8bq89.js","conditional-requirements-CFM0id0Q.js","cloneDeep-CAwdfOU2.js","_Uint8Array-BJr8e-ZL.js","isObject-FP1Yky1u.js","ApiExamples-XX0UgMZK.js","usePlaygroundInputsStore-DXDFSa1V.js","shallow-CdX5aREi.js","isEqual-CoOaxexF.js","CodeSnippets-Cg2wpzWm.js","CodeSnippet-D_HwgQO_.js","getApiPlaygroundDisplay-CmCoerhe.js","Page-CVJ-f_k1.js","DynamicMarkdown-CQM9Bhbv.js","SectionHeading-DpbrP8nQ.js","icon-BPCgijHy.js","MethodPill-GQ8DuY0c.js","getPastedJson-Cb5mT31m.js","Check2Icon-a7bUI6e8.js","axios-CsQoIw0U.js"]}