Skip to navigation

Create a new lead

View as Markdown

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.:

{ "custom.cf_v6S011I6MqcbVvB2FA5Nk8dr5MkL8sWuCiG8cUleO9c": "value", "custom.cf_8wtBWsdRU2Fur7GDnEeXQ7ra2Vu7R4hG1SNYdiEhh0F": "other value" }

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

AuthorizationBasic
Use your API key as the username and leave the password empty.
OR
AuthorizationBearer

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

Query parameters

_fieldsstringOptional

Comma-separated list of fields to include in the response.

Request

This endpoint expects an object.
addresseslist of objects or nullOptional
Addresses of the lead, up to 100.
contactslist of objects or nullOptional
Contacts to create on the lead, up to 300.
descriptionstring or nullOptional

Free-text description of the lead.

namestring or nullOptional

Name of the lead, usually a company name, e.g. Bluth Company.

statusstring or nullOptional

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.

status_idstring or nullOptional

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.

urlstring or nullOptional

Website of the lead, e.g. https://www.example.com. https:// is added if the URL has no scheme.

Response

Successful response
created_bystring or null

ID of the user who created the lead, e.g. user_N6KhMpzHRCYQHdn4gRNIFNN5JExnsrprKA6ekxM63XA, or null if no user created it

date_createddatetime
When the lead was created, as an ISO 8601 timestamp in UTC
date_updateddatetime
When the lead was last updated, as an ISO 8601 timestamp in UTC
descriptionstring or null

Free-text description of the lead, or null

html_urlstring
Link to the lead in the Close app
idstring

The lead’s ID, e.g. lead_IIDHIStmFcFQZZP0BRe99V1MCoXWz2PGCm6EDmR9v2O

namestring or null

Name of the lead, usually a company name, or null if unnamed. See display_name.

organization_idstring

The owning organization’s ID, e.g. orga_RbREgmiiwcr1w2b4cOnCMQaQPSIFxMqAD2Dh243uxcH

status_idstring

ID of the lead’s status, e.g. stat_1ZdiZqcSIkoGVnNOyxiEY58eTGQmFNG3LPlEVQ4V7Nk

updated_bystring or null

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

urlstring or null

Website of the lead, e.g. https://close.com, or null if unset

addresseslist of objectsOptional
Addresses of the lead
contact_idslist of stringsOptional

IDs of the lead’s contacts, in the same order as contacts. Only returned when requested in _fields.

contacts_summarystringOptional

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.

created_by_agent_idstring or nullOptional
ID of the agent that created the lead, or null if no agent created it.
created_by_namestring or nullOptional
Full name of the user who created the lead, or null if no user created it
display_namestringOptional

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

localtimedatetime or nullOptional

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.

primary_address_fullstring or nullOptional

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.

primary_address_summarystring or nullOptional

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.

primary_emailobject or nullOptional

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.

primary_phoneobject or nullOptional

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.

status_labelstringOptional

Label of the lead’s status, e.g. Potential

taskslist of maps from strings to anyOptional

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.

updated_by_agent_idstring or nullOptional
ID of the agent that last updated the lead, or null if the last update wasn't made by an agent.
updated_by_namestring or nullOptional
Full name of the user who last updated the lead, or null if the last update wasn't made by a user
contactslist of objectsOptionalDeprecated

Contacts on the lead. Deprecated: use List Contacts with lead_id instead.

opportunitieslist of objectsOptionalDeprecated

Opportunities on the lead. Deprecated: use List Opportunities with lead_id instead.

Errors

400
Bad Request Error
401
Unauthorized Error
403
Forbidden Error
429
Too Many Requests Error