Create a contact
Example Request & Response
$ curl https://api.intercom.io/contacts \\\n-X POST \\\n-H 'Authorization:Bearer <Your access token>' \\\n-H 'Accept:application/json'\n-H 'Content-Type: application/json' -d\n\n{\n\t\"role\": \"user\",\n\t\"external_id\": \"25\",\n\t\"email\": \"wash@serenity.io\",\n\t\"phone\": \"+1123456789\",\n\t\"name\": \"Hoban Washburn\",\n\t\"avatar\": \"https://example.org/128Wash.jpg\",\n\t\"last_seen_at\": 1571069751,\n\t\"signed_up_at\": 1571069751,\n\t\"owner_id\": 127,\n\t\"unsubscribed_from_emails\": false,\n\t\"custom_attributes\": {\n\t\t\"paid_subscriber\": true,\n\t\t\"monthly_spend\": 155.5,\n\t\t\"team_mates\": 1\n\t}\n}\n
Example Errors
HTTP/1.1 409 CONFLICT\n{\n \"type\": \"error.list\",\n \"request_id\": \"80ec9d92-99ff-4da9-9a0e-c0ab7c42f7e7\",\n \"errors\": [\n {\n \"code\": \"conflict\",\n \"message\": \"A contact matching those details already exists with id=5da6f18e3d7cf967e4582d05\"\n }\n ]\n}
HTTP/1.1 400 BAD REQUEST\n{\n \"type\": \"error.list\",\n \"request_id\": \"00043csj9iva7pl9mmmg\",\n \"errors\": [\n {\n \"code\": \"parameter_invalid\",\n \"message\": \"The owner specified is not a member of the workspace\"\n }\n ]\n}\n
You can create a new contact (ie. user or lead).
Request Body Parameters
| Attribute | Type | Required | Description |
|---|---|---|---|
| role | String | Yes | The role of the contact. Accepted values are user or lead. |
| external_id | String | Yes - if role is user and email is blank | A unique identifier for the contact which is given to Intercom |
| String | Yes - if role is user and external_id is blank | The contacts email | |
| phone | String | No | The contacts phone |
| name | String | No | The contacts name |
| avatar | String | No | An image URL containing the avatar of a contact |
| signed_up_at | Timestamp | No | The time specified for when a contact signed up |
| last_seen_at | Timestamp | No | The time when the contact was last seen (either where the Intercom Messenger was installed or when specified manually) |
| owner_id | Integer | No | The id of an admin that has been assigned account ownership of the contact |
| unsubscribed_from_emails | Boolean | No | Whether the contact is unsubscribed from emails |
| custom_attributes | Object | No | The custom attributes which are set for the contact |
custom_attributes Object for Custom Object Association creation
| Attribute | Type | Required | Description |
|---|---|---|---|
| A custom attribute of type relationship e.g "orders" | Array of Strings | No | With a relationship attribute as the key, an array of Custom Object Instance ids can be passed to create associations between the contact and the Custom Object Instance |
Example
{ "custom_attributes": { "orders": ["123", "234", "345"] } }
🚧 Creating new Custom Data Attributes
You can only write to custom data attributes that already exist on the workspace. If you need to create new attributes to write to, you should Create Data Attributes through the Data Attributes API.
Response
This will return a Contact model of the contact you just created.