Create a new lead
Create a lead. You can include its contacts, addresses and custom fields in the same request. Activities, tasks and opportunities must be created separately.
Returns the created lead.
Custom fields: set a custom field by setting custom.{custom_field_id} to its value, e.g.:
For a custom field with accepts_multiple_values: true, pass the full list of values, e.g. ["A", "B", "C"].
See Custom Fields for more details.
Authentication
Bearer authentication of the form Bearer <token>, where token is your auth token.
Query parameters
Comma-separated list of fields to include in the response.
Request
Free-text description of the lead.
Name of the lead, usually a company name, e.g. Bluth Company.
Label of the lead’s status, e.g. Potential, matched ignoring case. Using status_id instead is recommended, so renaming a status doesn’t break your integration. Pass either status or status_id, not both.
ID of the lead’s status, e.g. stat_1ZdiZqcSIkoGVnNOyxiEY58eTGQmFNG3LPlEVQ4V7Nk. If neither status_id nor status is given, the organization’s first lead status is used. See Lead Statuses.
Website of the lead, e.g. https://www.example.com. https:// is added if the URL has no scheme.
Response
ID of the user who created the lead, e.g. user_N6KhMpzHRCYQHdn4gRNIFNN5JExnsrprKA6ekxM63XA, or null if no user created it
Free-text description of the lead, or null
The lead’s ID, e.g. lead_IIDHIStmFcFQZZP0BRe99V1MCoXWz2PGCm6EDmR9v2O
Name of the lead, usually a company name, or null if unnamed. See display_name.
The owning organization’s ID, e.g. orga_RbREgmiiwcr1w2b4cOnCMQaQPSIFxMqAD2Dh243uxcH
ID of the lead’s status, e.g. stat_1ZdiZqcSIkoGVnNOyxiEY58eTGQmFNG3LPlEVQ4V7Nk
ID of the user who last updated the lead, e.g. user_N6KhMpzHRCYQHdn4gRNIFNN5JExnsrprKA6ekxM63XA, or null if the last update wasn’t made by a user
Website of the lead, e.g. https://close.com, or null if unset
IDs of the lead’s contacts, in the same order as contacts. Only returned when requested in _fields.
Display name of the lead’s first contact, followed by +N when the lead has N more contacts, e.g. Bruce Wayne +2. Empty if the lead has no contacts. Only returned when requested in _fields.
Name to display for the lead: the lead’s name if set, otherwise the name, first email address or first phone number (in international format) of the first contact that has one, then Untitled
Current time in the lead’s timezone, as an ISO 8601 timestamp without a UTC offset. The timezone comes from the lead’s first address, or else from its contacts’ timezones. Null if no timezone is known. Only returned when requested in _fields.
The lead’s first address on one line: the street lines, City, State Zip and the country name, separated by commas. Null if the lead has no address. Only returned when requested in _fields.
Short summary of the lead’s first address: City, State if both are set, otherwise the city, state, country name or postal code. Null if the lead has no address. Only returned when requested in _fields.
First email address of the first contact that has one, or null if no contact has an email address. Only returned when requested in _fields.
First phone number of the first contact that has one, or null if no contact has a phone number. Only returned when requested in _fields.
Label of the lead’s status, e.g. Potential
Incomplete tasks on the lead (_type lead), soonest due first. To list all of a lead’s tasks, including completed ones, use List Tasks with lead_id.
Contacts on the lead. Deprecated: use List Contacts with lead_id instead.
Opportunities on the lead. Deprecated: use List Opportunities with lead_id instead.