API ReferenceBuilding AppsInstalling IntercomAPI & Webhook ReferenceCanvas Kit Reference
DocsApp StoreForumBlogYour Apps

Create Lead

Example Request

$ curl https://api.intercom.io/contacts \
-H 'Authorization:Bearer <Your access token>' \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' -d '
  "phone": "123987456",
  "email": "[email protected]",
  "name": "Winston Smith"
HTTP/1.1 200 OK

# lead response

    "type": "contact",
    "id": "5811f6bbe6b4704ddfa84ac0",
    "user_id": "77177570-cf5d-4f1a-bc75-75202af47d4f",
    "anonymous": true,
    "email": "[email protected]",
    "phone": "00353875551234",
    "name": "Winston Smith",
    "pseudonym": "Lime Camel from Dublin",
    "avatar": {
        "type": "avatar",
        "image_url": null
    "app_id": "ja43hiec",
    "companies": {
        "type": "company.list",
        "companies": []
    "location_data": {
        "type": "location_data",
        "city_name": "Mukilteo",
        "continent_code": "NA",
        "country_name": "United States",
        "postal_code": "98275",
        "region_name": "Washington",
        "timezone": "America/Los_Angeles",
        "country_code": "USA"
    "last_request_at": 1477660267,
    "created_at": 1477572283,
    "remote_created_at": null,
    "signed_up_at": null,
    "updated_at": 1480067287,
    "session_count": 0,
    "social_profiles": {
        "type": "social_profile.list",
        "social_profiles": []
    "unsubscribed_from_emails": false,
    "tags": {
        "type": "tag.list",
        "tags": []
    "utm_campaign": null,
    "utm_content": null,
    "utm_medium": null,
    "utm_source": null,
    "utm_term": null,
    "segments": {
        "type": "segment.list",
        "segments": []
    "custom_attributes": {
        "paid_subscriber": true,
        "monthly_spend": 155.5,
        "team_mates": 9
intercom.contacts.create(:email => "[email protected]")
import static io.intercom.api.CustomAttribute.*;

Contact contact = new Contact()
    .setEmail("[email protected]");
contact = Contact.create(contact);
$intercom->leads->create(["email" => "[email protected]"]);

Leads can be created via a POST method to https://api.intercom.io/contacts, which accepts a JSON object describing the lead.

No identifying information is required to create a Lead, Intercom assigns a user_id to each new Lead. Indeed, it is not possible to assign these through the API - to work with self-assigned user_ids, use the Users resource.

Contrary to Users, signed_up_at and sessions are not available for Leads. Otherwise, attributes to update on a Lead are the same as for a User.

Note that as with Users, user agent data is submitted as last_seen_user_agent.