Create a new lead | Close | Developer API Documentation

curl -X POST https://api.close.com/api/v1/lead/ \
     -H "Content-Type: application/json" \
     -u "<CLOSE_API_KEY>:" \
     -d '{
  "addresses": [
    {
      "address_1": "747 Howard St",
      "address_2": "Room 3",
      "city": "San Francisco",
      "country": "US",
      "label": "business",
      "state": "CA",
      "zipcode": "94103"
    }
  ],
  "contacts": [
    {
      "emails": [
        {
          "email": "gob@example.com",
          "type": "office"
        }
      ],
      "name": "Gob",
      "phones": [
        {
          "phone": "8004445555",
          "type": "office"
        }
      ],
      "title": "Sr. Vice President"
    }
  ],
  "custom.cf_FSYEbxYJFsnY9tN1OTAPIF33j7Sw5Lb7Eawll7JzoNh": "Segway",
  "custom.cf_ORxgoOQ5YH1p7lDQzFJ88b4z0j7PLLTRaG66m8bmcKv": "Website contact form",
  "custom.cf_bA7SU4vqaefQLuK5UjZMVpbfHK4SVujTJ9unKCIlTvI": "Real Estate",
  "custom.cf_nenE344jkwrjyRRezwsf8b4V1MCoXWIDHIStmFavZks": [
    "Choice 1",
    "Choice 2"
  ],
  "description": "Best. Show. Ever.",
  "name": "Bluth Company",
  "status_id": "stat_1ZdiZqcSIkoGVnNOyxiEY58eTGQmFNG3LPlEVQ4V7Nk",
  "url": "http://thebluthcompany.tumblr.com/"
}'

{
  "contact_ids": [
    "cont_qpjDKxbN3WWsuhaJjg2Qr9pkqHqe1yviZ5BS0dEyz05"
  ],
  "created_by": "user_N6KhMpzHRCYQHdn4gRNIFNN5JExnsrprKA6ekxM63XA",
  "date_created": "2013-02-20T05:30:24.854000+00:00",
  "date_updated": "2013-02-20T05:30:24.854000+00:00",
  "description": "Best. Show. Ever.",
  "html_url": "https://app.close.com/lead/lead_70jZ5hiVt5X31MZ3vJ0R0GJMqJEihkoF7TtSVFbN2ty/",
  "id": "lead_70jZ5hiVt5X31MZ3vJ0R0GJMqJEihkoF7TtSVFbN2ty",
  "name": "Bluth Company",
  "organization_id": "orga_RbREgmiiwcr1w2b4cOnCMQaQPSIFxMqAD2Dh243uxcH",
  "status_id": "stat_1ZdiZqcSIkoGVnNOyxiEY58eTGQmFNG3LPlEVQ4V7Nk",
  "updated_by": "user_N6KhMpzHRCYQHdn4gRNIFNN5JExnsrprKA6ekxM63XA",
  "url": "http://thebluthcompany.tumblr.com/",
  "addresses": [
    {
      "address_1": "747 Howard St",
      "address_2": "Room 3",
      "city": "San Francisco",
      "country": "US",
      "label": "business",
      "state": "CA",
      "zipcode": "94103"
    }
  ],
  "display_name": "Bluth Company",
  "status_label": "Potential",
  "tasks": [],
  "contacts": [
    {
      "created_by": "user_N6KhMpzHRCYQHdn4gRNIFNN5JExnsrprKA6ekxM63XA",
      "date_created": "2013-02-20T05:30:24.844000+00:00",
      "date_updated": "2013-02-20T05:30:24.844000+00:00",
      "display_name": "Gob",
      "id": "cont_qpjDKxbN3WWsuhaJjg2Qr9pkqHqe1yviZ5BS0dEyz05",
      "name": "Gob",
      "organization_id": "orga_RbREgmiiwcr1w2b4cOnCMQaQPSIFxMqAD2Dh243uxcH",
      "title": "sr. vice president",
      "updated_by": "user_N6KhMpzHRCYQHdn4gRNIFNN5JExnsrprKA6ekxM63XA",
      "emails": [
        {
          "email": "gob@example.com",
          "is_unsubscribed": false,
          "type": "office"
        }
      ],
      "phones": [
        {
          "phone": "+18004445555",
          "type": "office",
          "phone_formatted": "+1 800-444-5555"
        }
      ]
    }
  ],
  "opportunities": [],
  "custom.cf_FSYEbxYJFsnY9tN1OTAPIF33j7Sw5Lb7Eawll7JzoNh": "Segway",
  "custom.cf_ORxgoOQ5YH1p7lDQzFJ88b4z0j7PLLTRaG66m8bmcKv": "Website contact form",
  "custom.cf_bA7SU4vqaefQLuK5UjZMVpbfHK4SVujTJ9unKCIlTvI": "Real Estate",
  "custom.cf_nenE344jkwrjyRRezwsf8b4V1MCoXWIDHIStmFavZks": [
    "Choice 1",
    "Choice 2"
  ]
}

Contacts, addresses, and custom fields can all be nested in the lead. Activities, tasks, and opportunities must be posted separately.

status / status_id (optional): Post either status or status_id (but not both). If neither is provided, the organization’s default (first) status will be used. Using status_id is recommended so that users can rename statuses in the UI without breaking your implementation.

custom.FIELD_ID (optional): Set custom fields by setting custom.FIELD_ID to the field value, where FIELD_ID is the ID of the custom field, e.g.:

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

If a custom field has accepts_multiple_values: true, the entire value will be replaced. For example, given a Lead has a Custom Choice Field with value ["A", "B"], adding choice "C" would mean setting the value to ["A", "B", "C"].

Note that using the custom field dict or the custom.FIELD_NAME syntax (instead of custom field IDs) is deprecated and will be removed from the API. See Custom Fields for more details.

Contacts, addresses, and custom fields can all be nested in the lead. Activities, tasks, and opportunities must be posted separately. **status / status_id** (optional): Post either `status` or `status_id` (but not both). If neither is provided, the organization's default (first) status will be used. Using `status_id` is recommended so that users can rename statuses in the UI without breaking your implementation. **custom.FIELD_ID** (optional): Set custom fields by setting `custom.FIELD_ID` to the field value, where FIELD_ID is the ID of the custom field, e.g.: ```json { "custom.cf_v6S011I6MqcbVvB2FA5Nk8dr5MkL8sWuCiG8cUleO9c": "value", "custom.cf_8wtBWsdRU2Fur7GDnEeXQ7ra2Vu7R4hG1SNYdiEhh0F": "other value" } ``` If a custom field has `accepts_multiple_values: true`, the entire value will be replaced. For example, given a Lead has a Custom Choice Field with value `["A", "B"]`, adding choice `"C"` would mean setting the value to `["A", "B", "C"]`. Note that using the `custom` field dict or the `custom.FIELD_NAME` syntax (instead of custom field IDs) is deprecated and will be removed from the API. See [Custom Fields](/resources/custom-fields/) for more details.

Authentication

AuthorizationBasic

Basic authentication of the form Basic <base64(username:)>.

AuthorizationBearer

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

Request

This endpoint expects any.

Response

Successful response

contact_idslist of strings

created_bystring or null

date_createddatetime

date_updateddatetime

descriptionstring or null

html_urlstring

idstring

namestring or null

organization_idstring

status_idstring

updated_bystring or null

urlstring or null

addresseslist of objects

contacts_summarystring

created_by_namestring or null

display_namestring

integration_linkslist of objects

localtimedatetime or null

primary_address_summarystring or null

primary_emailobject or null

primary_phoneobject or null

recent_callslist of maps from strings to any

sourcestring or null

status_labelstring

summarieslist of maps from strings to any

taskslist of maps from strings to any

updated_by_namestring or null

contactslist of objectsDeprecated

opportunitieslist of objectsDeprecated

Errors

400

Bad Request Error

401

Unauthorized Error

404

Not Found Error

Contacts, addresses, and custom fields can all be nested in the lead. Activities, tasks, and opportunities must be posted separately.

custom.FIELD_ID (optional): Set custom fields by setting custom.FIELD_ID to the field value, where FIELD_ID is the ID of the custom field, e.g.:

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

Note that using the custom field dict or the custom.FIELD_NAME syntax (instead of custom field IDs) is deprecated and will be removed from the API. See Custom Fields for more details.