leads

Create /leads

Create a lead. Required: company or name (at least one). Optional: company/contact details, address, types, categories, assignees, responsible_role_id (round-robin assign to the next active staff of that role), status, source, and organization. Returns record with the detail projection. If the email, phone or company code already exists, no new lead is created: a repeated-request task is added to the existing lead and the response is 200 with duplicate: true, message and the existing lead as record (or duplicate_of with its type and uuid when the match is not a lead you can read).

POST

/leads

Create /leads

curl --request POST \
  --url https://default.hannacrm.app/api/v4/leads \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "city": "<string>",
  "company": "<string>",
  "company_code": "<string>",
  "country": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "custom_fields": [
    {
      "slug": "<string>",
      "value": "<any>"
    }
  ],
  "description": "<string>",
  "email": "<string>",
  "is_newsletter_subscribe": "<string>",
  "last_contact": "<string>",
  "lead_categories": [
    "<string>"
  ],
  "lead_types": [
    "<string>"
  ],
  "name": "<string>",
  "organization": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "phone": "<string>",
  "responsible": [
    "<string>"
  ],
  "responsible_role_id": "<string>",
  "source": "<string>",
  "state": "<string>",
  "status": "<string>",
  "street": "<string>",
  "title": "<string>",
  "vat_code": "<string>",
  "website": "<string>",
  "zip": "<string>"
}
'

{
  "duplicate": true,
  "duplicate_of": {
    "type": "client",
    "uuid": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
  },
  "message": "<string>",
  "record": {
    "address": {
      "city": "<string>",
      "country": "<string>",
      "state": "<string>",
      "street": "<string>",
      "zip": "<string>"
    },
    "assigned_users": [
      {}
    ],
    "avg_salary": "<string>",
    "city": "<string>",
    "company": "<string>",
    "company_code": "<string>",
    "country": "<string>",
    "created_at": "2023-11-07T05:31:56Z",
    "created_by": {
      "name": "<string>",
      "uuid": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
    },
    "custom_fields": [
      {
        "slug": "<string>",
        "value": "<any>"
      }
    ],
    "dateadded": "2023-11-07T05:31:56Z",
    "description": "<string>",
    "email": "<string>",
    "employees_count": "<string>",
    "is_newsletter_subscribe": "<string>",
    "last_contact": "2023-11-07T05:31:56Z",
    "lead_activities": [
      {}
    ],
    "lead_categories": [
      {}
    ],
    "lead_types": [
      {}
    ],
    "name": "<string>",
    "organization": [
      {}
    ],
    "organization_default": "<string>",
    "phone": "<string>",
    "sale_potential": "<string>",
    "source": {
      "code_name": "<string>",
      "name": "<string>",
      "uuid": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
    },
    "source_name": "<string>",
    "status": {
      "color": "<string>",
      "name": "<string>",
      "uuid": "<string>"
    },
    "title": "<string>",
    "updated_at": "2023-11-07T05:31:56Z",
    "updated_by": {
      "name": "<string>",
      "uuid": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
    },
    "uuid": "<string>",
    "vat_code": "<string>",
    "website": "<string>",
    "yearly_income": "<string>"
  }
}

Authorizations

Authorizationstringheaderrequired

API key (Bearer token) created in Setup → API & MCP.

Body

citystring

City.

companystring

Company name. Required unless name (the contact person) is provided.

company_codestring

Company registration code.

countrystring

Country UUID.

custom_fieldsobject[]

Custom field values by slug.

Show child attributes

descriptionstring

Description/notes.

emailstring

Email address.

Newsletter subscription consent. Accepts 1/0 or true/false. To disable on update send 0 (a JSON false is treated as "not provided").

last_contactstring

Last contact date (Y-m-d or Y-m-d H:i:s). Send today's date to mark the lead as contacted today.

lead_categoriesstring[]

Lead category UUIDs or code_name values.

lead_typesstring[]

Lead type UUIDs or code_name values.

namestring

Contact person name. Required unless company is provided.

organizationstring

Organization UUID.

phonestring

Phone number.

responsiblestring[]

Responsible staff UUIDs.

responsible_role_idstring

Staff role UUID or numeric ID (tblroles.roleid), as listed by GET /roles. On create, assigns the next active staff member of this role in round-robin order. Merged with responsible when both are sent.

sourcestring

Lead source UUID, code_name, or numeric ID.

statestring

State/region.

statusstring

Lead status UUID, code_name, or numeric ID.

streetstring

Street address.

titlestring

Contact title / position.

vat_codestring

VAT code.

websitestring

Website URL.

zipstring

ZIP/postal code.

any

Response

Duplicate: a matching record already exists, nothing was created.

duplicateenum<boolean>required

Available options: true

duplicate_ofobject

Sent instead of record when the match is not a record of this module you can read.

Show child attributes

messagestringrequired

Which value matched (email, phone, company code).

recordobject

Fields enabled for this documentation instance (projection enabled: feature, option, subdomain, closures) plus account-level form field visibility. Role- and user-level field overrides are not applied here, so an API key whose staff user has such overrides may receive fewer fields. A disabled field is omitted from the response object entirely; a present key with a null value means the record simply has no value.

Show child attributes

Still need help? Ask the team