Skip to main content
POST
/
api
/
leads
Create / Upload Lead Endpoint
curl --request POST \
  --url https://api.example.com/api/leads

​
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": [
    {
      "firstName": "John",
      "lastName": "Doe",
      "email": "[email protected]",
      "phone": "+12025551234",
      "companyName": "Acme Corp",
      "jobTitle": "CEO",
      "notes": "Warm intro from Sarah",
      "customFields": {
        "industry": "Technology",
        "segment": "Mid-market"
      }
    }
  ],
  "listId": "507f1f77bcf86cd799439011",
  "source": "api",
  "defaultCountryCode": "+1"
}
  • leads – one or more contacts; a single contact is just a one‑element array.
  • listId – Tuco list that should own these leads.
  • source – optional origin label (for example, "api" or "hubspot").
  • defaultCountryCode – used to normalize phone numbers when no country code is present.

​
Response

{
  "message": "Leads saved successfully",
  "savedCount": 1,
  "duplicateCount": 0,
  "totalProcessed": 1,
  "listId": "507f1f77bcf86cd799439011"
}
  • 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.
If validation fails you will receive a 400 with a readable error; if the workspace is temporarily read‑only you will receive a 402 READ_ONLY error (see /api-reference/errors).