Creating a Contact

POST https://driftapi.com/contacts

When creating a contact, the only required attribute is email. Drift will check if this email already exists and respond with an error if another contact record has the same email.

Including the externalId attribute however, will override the duplicate email check and instead prevent the duplication of a contact record with the same externalId. It is possible to create contact records with the same email address if their externalId values are different.

A successful contact creation will return a JSON object with details of the new contact.

{
    "data": {
        "id": 15811408544,
        "createdAt": 1664572604326,
        "attributes": {
            "_END_USER_VERSION": 4,
            "_end_user_version": 4,
            "_calculated_version": 4,
            "socialProfiles": {},
            "externalId": "your_unique_id",
            "external_id": "your_unique_id",
            "email": "[email protected]",
            "events": {},
            "start_date": 1664572604326
        }
    }
}

🚧
Warning! Do not use guessable values (like email or sequential numbers) for externalId's when creating contacts as this could allow the client-side drift.identify method to be misused. However, if guessable values must be used, be sure to set signed identities to required under your widget's security settings. For added security, do both: unguessable externalId's and require signed identities.

📘
Important: Drift will not create an externalId when using this endpoint unless a value for externalId is explicitly passed. Contacts created via this endpoint where no externalId was set will contain externalId: null on their record and cannot leverage the client side drift.identify() method. If any Drift activity will involve logged-in users, always include an externalId when creating a contact.

Example Creation

The following example shows how to create a contact.

var axios = require('axios');
var data = JSON.stringify({
  "attributes": {
    "email": "[email protected]",
    "externalId": "your_unique_id"
  }
});

var config = {
  method: 'post',
  url: 'https://driftapi.com/contacts',
  headers: { 
    'Authorization': 'Bearer BNUmgzu###########E4IUQuf7BXsd', 
    'Content-Type': 'application/json'
  },
  data : data
};

axios(config)
.then(function (response) {
  console.log(JSON.stringify(response.data));
})
.catch(function (error) {
  console.log(error);
});

curl --location --request POST 'https://driftapi.com/contacts' \
--header 'Authorization: Bearer BNUmgzu###########E4IUQuf7BXsd' \
--header 'Content-Type: application/json' \
--data-raw '{
    "attributes": {
        "email": "[email protected]",
        "externalId": "your_unique_id"
    }
}'

POST /contacts HTTP/1.1
Host: driftapi.com
Authorization: Bearer BNUmgzu###########E4IUQuf7BXsd
Content-Type: application/json
Content-Length: 104

{
    "attributes": {
        "email": "[email protected]",
        "externalId": "your_unique_id"
    }
}

OkHttpClient client = new OkHttpClient().newBuilder()
  .build();
MediaType mediaType = MediaType.parse("application/json");
RequestBody body = RequestBody.create(mediaType, "{\n    \"attributes\": {\n        \"email\": \"[email protected]\",\n        \"externalId\": \"your_unique_id\"\n    }\n}");
Request request = new Request.Builder()
  .url("https://driftapi.com/contacts")
  .method("POST", body)
  .addHeader("Authorization", "Bearer BNUmgzu###########E4IUQuf7BXsd")
  .addHeader("Content-Type", "application/json")
  .build();
Response response = client.newCall(request).execute();

import requests
import json

url = "https://driftapi.com/contacts"

payload = json.dumps({
  "attributes": {
    "email": "[email protected]",
    "externalId": "your_unique_id"
  }
})
headers = {
  'Authorization': 'Bearer BNUmgzu###########E4IUQuf7BXsd',
  'Content-Type': 'application/json'
}

response = requests.request("POST", url, headers=headers, data=payload)

print(response.text)

require "uri"
require "json"
require "net/http"

url = URI("https://driftapi.com/contacts")

https = Net::HTTP.new(url.host, url.port)
https.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = "Bearer BNUmgzu###########E4IUQuf7BXsd"
request["Content-Type"] = "application/json"
request.body = JSON.dump({
  "attributes": {
    "email": "[email protected]",
    "externalId": "your_unique_id"
  }
})

response = https.request(request)
puts response.read_body

Validate the contact creation by checking the UI! The contact record can quickly be accessed via the following URL: https://app.drift.com/contacts/details/<contact_id> where contact_id is the numerical value returned in the JSON object at data.id.