Create / Upload Lead Endpoint
Lines & Leads
Create / Upload Lead Endpoint
Create a single lead or upload multiple leads into a Tuco workspace
POST
Create / Upload Lead Endpoint
Endpoint
- Method:
POST - Path:
/api/leads
Request Body
leads– one or more contacts; a single contact is just a one‑element array.listId– Optional. Tuco list that should own these leads. Omit to use the Quick Sends list.source– optional origin label (for example,"api"or"gohighlevel").defaultCountryCode– used to normalize phone numbers when no country code is present.ghlLocationId– optional; used when syncing with GoHighLevel.contactOwnerEmail– Email of the workspace user who owns this contact. If omitted or invalid, defaults to the first user in the workspace.- You may send
bodyas an alias forleads(same array shape).
Response
Success – status201 Created when at least one lead was created, or 200 OK when the request succeeded but no new leads were inserted. Example:
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 aslistIdwhen 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.
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.