DocsBuilding AppsInstalling IntercomAPI & Webhook ReferenceCanvas Kit Reference
DocsApp StoreForumBlogYour Apps

Convert a Lead

Example Lead Convert Request

$ curl \
https://api.intercom.io/contacts/convert \
-X POST \
-H 'Authorization:Bearer <Your access token>' \
-H 'Accept:application/json' \
-H 'Content-Type: application/json' -d '
{
  "contact": {
    "user_id": "8a88a590-e1c3-41e2-a502-e0649dbf721c"
  },
  "user": {
    "email": "[email protected]"
  }
}'
HTTP/1.1 200 Ok

{
  "type": "user",
  "email": "[email protected]"
}
# NB: Full User objects are returned
intercom.contacts.convert(contact, user)
<?php
$response = $intercom->leads->convertLead([
    "contact" => [
        "id" => "596f6b60d797879302bd7ac1" 
    ],
    "user" => [
        "user_id" => "470" 
    ]
]);
print_r($response)
?>
User converted = Contact.convert(contact, user);

Leads can be converted to Users. This is done by passing both Lead and User identifiers. If the User exists, then the Lead will be merged into it, the Lead deleted and the User returned. If the User does not exist, the Lead will be converted to a User, with the User identifiers replacing it's Lead identifiers.

Identifiers (id, user_id, email) from Leads are never added onto Users with a merge.

A Lead's email, but not user_id is retained when converting a Lead to a new User.