Add Leads

Add one or more people under a company. If you include leadListId, Hermes sets that ID on the company when the company is created or when an existing company is retried for that list. The people are then considered part of the lead list through their company.

lead_lists.id -> companies.lead_list_id
companies.id -> leads.company_id

This company_name + people[] shape is the required shape when an API-key integration needs to attach imported leads to a lead list.

Request

• company_name (string) (required) — Company/account name.

• leadListId (integer) — Lead list ID to attach the company to when the company is new or currently has no list.

• source (string) — Where these leads came from (e.g., "manual", "clawback").

• people (object[]) (required) — People to create as leads under the company.

• people[].firstName (string) (required) — Lead's first name.

• people[].lastName (string) (required) — Lead's last name.

• people[].role (string) — Job title / role.

• people[].email (string) — Email address.

• people[].phone (string) — Phone number.

• people[].linkedin_profile_url (string) — LinkedIn profile URL.

Each person must include at least one contact field: email, phone, or linkedin_profile_url. Hermes does not return success for a lead-list import unless at least one lead row is created or found for the company.

curl -X POST https://api.hermes.camie.ai/v1/leads \
  -H "Authorization: Bearer hermes_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "company_name": "Acme Corp",
    "leadListId": 15,
    "source": "clawback",
    "people": [
      {
        "firstName": "John",
        "lastName": "Smith",
        "role": "Marketing Director",
        "email": "john@company.com",
        "phone": "+1234567890",
        "linkedin_profile_url": "https://www.linkedin.com/in/john-smith"
      }
    ]
  }'

const res = await fetch('https://api.hermes.camie.ai/v1/leads', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer hermes_your_api_key',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    company_name: 'Acme Corp',
    leadListId: 15,
    source: 'clawback',
    people: [
      {
        firstName: 'John',
        lastName: 'Smith',
        role: 'Marketing Director',
        email: 'john@company.com',
        phone: '+1234567890',
        linkedin_profile_url: 'https://www.linkedin.com/in/john-smith'
      }
    ]
  })
});

Response (201 Created)

{
  "success": true,
  "message": "Leads created",
  "data": {
    "company_id": 12,
    "company_name": "Acme Corp",
    "lead_list_id": 15,
    "leads": [
      {
        "id": 3,
        "personFirstName": "John",
        "personLastName": "Smith",
        "personRole": "Marketing Director",
        "personEmail": "john@company.com",
        "personPhone": "+1234567890",
        "linkedinProfileUrl": "https://www.linkedin.com/in/john-smith",
        "status": "pending",
        "leadSource": "clawback",
        "createdAt": "2026-03-14T16:30:00.000Z"
      }
    ]
  }
}

Notes

• leadListId is camel-case on the public gateway route.
• The public route also supports a single-person create shape with personFirstName and personLastName, but that shape does not accept leadListId. Use the company_name + people[] shape for lead-list imports.
• If company_name matches an existing company, this route assigns that company to the provided leadListId before creating or finding the lead rows.
• Direct Subsystem 3 calls to /api/v1/leads use lead_list_id, but external API-key integrations should normally use the public gateway route shown above.
• A lead list count is computed through the company relationship, not a lead_list_id column on each lead row.