Skip to main content
POST
/
api
/
leads
Create Lead
curl --request POST \
  --url https://app.puffle.ai/api/leads \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "name": {
    "full": "<string>",
    "short": "<string>",
    "aliases": [
      "<string>"
    ],
    "first": "<string>",
    "last": "<string>"
  },
  "title": "<string>",
  "company": {
    "name": "<string>",
    "id": "<string>",
    "domain": "<string>"
  },
  "location": {
    "city": "<string>",
    "state": "<string>",
    "country": "<string>",
    "raw": "<string>"
  },
  "socials": [
    {
      "url": "<string>"
    }
  ],
  "contacts": [
    {
      "value": "<string>"
    }
  ],
  "domain": "<string>",
  "industry": "<string>",
  "size": "<string>",
  "attributes": {},
  "sources": [
    {
      "id": "<string>"
    }
  ],
  "listIds": [
    "<string>"
  ],
  "raw": {}
}
'
{
  "lead": {
    "id": "<string>",
    "type": "person",
    "name": {
      "full": "<string>",
      "short": "<string>",
      "aliases": [
        "<string>"
      ],
      "first": "<string>",
      "last": "<string>"
    },
    "lists": [
      {
        "id": "<string>",
        "name": "<string>"
      }
    ],
    "sources": [
      {
        "id": "<string>"
      }
    ],
    "createdAt": "<string>",
    "updatedAt": "<string>",
    "location": {
      "city": "<string>",
      "state": "<string>",
      "country": "<string>",
      "raw": "<string>"
    },
    "socials": [
      {
        "url": "<string>"
      }
    ],
    "contacts": [
      {
        "value": "<string>"
      }
    ],
    "attributes": {},
    "raw": {},
    "title": "<string>",
    "company": {
      "name": "<string>",
      "id": "<string>",
      "domain": "<string>"
    }
  }
}
CLI: 
puffle lead create --type <type> --name <name>
puffle lead create --type <type> --name <name> --title <title> --company <company> --location <location> --socials <socials> --contacts <contacts> --domain <domain> --industry <industry> --size <size> --attributes <attributes> --source <source> --sources <sources> --list-ids <list-ids> --raw <raw>

​
Overview

Creates a Lead for the authenticated workspace. The endpoint accepts a person or company payload and uses strong identifiers to reuse an existing Lead when it can. Use this endpoint when an integration, import, or agent already has enough structured data to create a durable lead directly. For natural-language discovery, start with Start lead search instead.

​
AI agent notes

Side effect: writes a leads record and may reuse an existing Lead when the identity matches. It does not automatically add the Lead to a List; use a List membership endpoint for that.Identity: person and company Leads dedupe inside the effective user’s workspace. Send stable identifiers such as LinkedIn URL, company domain, email, or provider IDs when available.Response: returns { lead } for later List, enrichment, or campaign calls.

Authorizations

​
Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Body

application/json
​
type
enum<string>
required
Available options:
person,
company
​
name
object
required
​
title
string | null
​
company
object
​
location
object
​
socials
object[]
​
contacts
object[]
​
domain
string | null
​
industry
string | null
​
size
string | null
​
attributes
object
​
source
object
​
sources
object[]
​
listIds
string[]
​
raw
object

Response

Lead created or updated.

​
lead
object
required