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

List Leads

List all Leads

List all Leads

$ curl https://api.intercom.io/contacts \
-H 'Authorization:Bearer <Your access token>' \
-H 'Accept: application/json'
HTTP/1.1 200 OK

{
  "type": "contact.list",
  "total_count": 105,
  "contacts": [
    {
      "type": "contact",
      "id": "530370b477ad7120001d",
       ...
     },
     ...
   ],
  "pages": {
    "next": "https://api.intercom.io/contacts?per_page=50&page=2",
    "page": 1,
    "per_page": 50,
    "total_pages": 3
  }
}

# NB: Full Contact objects are returned
intercom.contacts.all.each { ... }
<?php
$leads= $intercom->leads->getLeads([]);
foreach ($leads->contacts as $lead) {
    print_r($lead->id);
    echo "\n";
}
?>
ContactCollection contacts = Contact.list();

// get first page...
List<Contact> items = contacts.getPageItems();

// ...or iterate over all pages
while (contacts.hasNext()) {
    out.println(contacts.next().getID());
}

You can fetch a list of all leads. The lead list is sorted by the created_at field and by default is ordered descending, most recently created first. Apart from sorting, the same parameters for the User list apply here.

List Leads by Email

List by Email

$ curl https://api.intercom.io/[email protected] \
-H 'Authorization:Bearer <Your access token>' \
-H 'Accept:application/json'
HTTP/1.1 200 OK

{
    "type": "contact.list",
    "pages": {
        "type": "pages",
        "next": null,
        "page": 1,
        "per_page": 50,
        "total_pages": 1
    },
    "contacts": [
        {
            "type": "contact",
            "id": "5811f6bbe6b4704ddfa84ac0",
            "user_id": "77177570-cf5d-4f1a-bc75-75202af47d4f",
            "anonymous": true,
            "email": "[email protected]",
            "phone": "00353875551234",
            "name": "O&#39;Brien",
            "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",
                "latitude": 47.913,
                "longitude": -122.3042,
                "postal_code": "98275",
                "region_name": "Washington",
                "timezone": "America/Los_Angeles",
                "country_code": "USA"
            },
            "last_request_at": 1477660267,
            "last_seen_ip": "1.2.3.4",
            "created_at": 1477572283,
            "remote_created_at": null,
            "signed_up_at": null,
            "updated_at": 1480068674,
            "session_count": 0,
            "social_profiles": {
                "type": "social_profile.list",
                "social_profiles": []
            },
            "unsubscribed_from_emails": false,
            "user_agent_data": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10.9",
            "tags": {
                "type": "tag.list",
                "tags": []
            },
            "segments": {
                "type": "segment.list",
                "segments": []
            },
            "custom_attributes": {
                "paid_subscriber": true,
                "monthly_spend": 155.5,
                "team_mates": 9
            }
        }
    ],
    "total_count": 1,
    "limited": false
}
contacts = intercom.contacts.find_all(email: "[email protected]")
ContactCollection contacts = Contact.listByEmail("[email protected]");

// get first page...
List<Contact> items = contacts.getPageItems();

// ...or iterate over all pages
while (contacts.hasNext()) {
    out.println(contacts.next().getID());
}
<?php
$leads= $intercom->leads->getLeads(['email' => '[email protected]']);
foreach ($leads->contacts as $lead) {
    print_r($lead->id);
    echo "\n";
}?>

You can fetch Leads with a given email by querying the leads resource with an email parameter.

List Leads by Phone

List by Phone

$ curl \
https://api.intercom.io/contacts?phone=00353875551234 \
-H 'Authorization:Bearer <Your access token>' \
-H 'Accept:application/json'
HTTP/1.1 200 OK

{
    "type": "contact.list",
    "pages": {
        "type": "pages",
        "next": null,
        "page": 1,
        "per_page": 50,
        "total_pages": 1
    },
    "contacts": [
        {
            "type": "contact",
            "id": "5811f6bbe6b4704ddfa84ac0",
            "user_id": "77177570-cf5d-4f1a-bc75-75202af47d4f",
            "anonymous": true,
            "email": "[email protected]",
            "phone": "00353875551234",
            "name": "O&#39;Brien",
            "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",
                "latitude": 47.913,
                "longitude": -122.3042,
                "postal_code": "98275",
                "region_name": "Washington",
                "timezone": "America/Los_Angeles",
                "country_code": "USA"
            },
            "last_request_at": 1477660267,
            "last_seen_ip": "1.2.3.4",
            "created_at": 1477572283,
            "remote_created_at": null,
            "signed_up_at": null,
            "updated_at": 1480068674,
            "session_count": 0,
            "social_profiles": {
                "type": "social_profile.list",
                "social_profiles": []
            },
            "unsubscribed_from_emails": false,
            "user_agent_data": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10.9",
            "tags": {
                "type": "tag.list",
                "tags": []
            },
            "segments": {
                "type": "segment.list",
                "segments": []
            },
            "custom_attributes": {
                "paid_subscriber": true,
                "monthly_spend": 155.5,
                "team_mates": 9
            }
        }
    ],
    "total_count": 1,
    "limited": false
}

You can fetch Leads with a given phone number by querying the leads resource with a phone parameter.