Skip to main content
POST
Create / Upload Lead Endpoint

Endpoint

  • Method: POST
  • Path: /api/leads
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

  • leads – one or more contacts; a single contact is just a one‑element array.
  • listIdOptional. 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 body as an alias for leads (same array shape).

Response

Success – status 201 Created when at least one lead was created, or 200 OK when the request succeeded but no new leads were inserted. Example:
Response fields:
  • 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.