NAV
cURL C# JavaScript Python

Upsert Lead

The CINC API provides an upsert endpoint for handling the creation and updating of lead objects. This was done to reduce the number of necessary endpoints when updating different fields and avoid handling dedupe calls. The endpoint currently keys of the lead.id field, the lead.username field, or the lead.info.contact.email field. The lead identifier and the email fields cannot be updated and the lead.id is not required if attempting to create the lead. When updating a lead, any of the fields can be used to identify the lead. The lead.username field can be changed, but it will change the lead.info.contact.email field as well. Also, all leads are unique to a given CINC site and no two leads with the same username/email can exist. This means that multiple CINC sites may have the same lead, but the lead.id is guaranteed to be unique across sites.

Create or Update

When sending in a lead, the only required field is the lead.username (or lead.info.contact.email) which becomes the username for the lead. All other fields will be set to some default or to null when created. If the lead already exists, then the fields will be updated with the provided values.

Example code: Create or Update

# Define the lead
lead='{"username": "mylead@email.com"}'

# Send the HTTP request
response=$(curl -s -o /dev/null -w "%{http_code}" -X POST 'https://public.cincapi.com/v2/site/leads' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <access_token>' \
  -d "$lead")

# Parse the response
if [ "$response" = "200" ]; then
  echo "Lead updated successfully."
elif [ "$response" = "201" ]; then
  echo "Lead created successfully."
else
  echo "Lead upsert failed."
fi

var lead = new
{
    username = "mylead@email.com"
};

var json = JsonConvert.SerializeObject(lead);

using (var client = new HttpClient())
{
    client.DefaultRequestHeaders.Add("Content-Type", "application/json");
    client.DefaultRequestHeaders.Add("Authorization", "Bearer <access_token>");

    var response = await client.PostAsync("https://public.cincapi.com/v2/site/leads", new StringContent(json, Encoding.UTF8, "application/json"));

    if (response.IsSuccessStatusCode)
    {
        Console.WriteLine("Lead upserted successfully.");
        var result = JsonConvert.DeserializeObject<dynamic>(await response.Content.ReadAsStringAsync());
        Console.WriteLine(result.id);

        if (response.StatusCode == HttpStatusCode.OK)
        {
            Console.WriteLine("Lead updated successfully.");
        }
        else if (response.StatusCode == HttpStatusCode.Created)
        {
            Console.WriteLine("Lead created successfully.");
        }
    }
    else
    {
        Console.WriteLine("Lead upsert failed.");
    }
}

const lead = {
  username: 'mylead@email.com'
};

const response = await fetch('https://public.cincapi.com/v2/site/leads', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer <access_token>'
  },
  body: JSON.stringify(lead)
}).catch(error => console.error(error));

if (response?.ok) {
  console.log('Lead upserted successfully.');
  const result = await response.json();

  // The lead identifier is returned in the response.
  console.log(result.id);

  // If the code is 200, then the lead was updated.
  if (response.status === 200) {
    console.log('Lead updated successfully.');
  }
  // If the code is 201, then the lead was created.
  else if (response.status === 201) {
    console.log('Lead created successfully.');
  }
} else {
  console.log('Lead upsert failed.');
}

import requests
import json

# Define the lead
lead = {
  'username': 'mylead@email.com'
}

# Send the HTTP request
response = requests.post(
    'https://public.cincapi.com/v2/site/leads',
    headers={
        'Content-Type': 'application/json',
        'Authorization': 'Bearer <access_token>'
    },
    data=json.dumps(lead)
)

# Check the response
if response.ok:
    print('Lead upserted successfully.')
    result = response.json()
    print(result['id'])

    # If the code is 200, then the lead was updated.
    if response.status_code == 200:
        print('Lead updated successfully.')
    # If the code is 201, then the lead was created.
    elif response.status_code == 201:
        print('Lead created successfully.')
else:
    print('Lead upsert failed.')

Changing the Email

The email address for a lead is stored in the lead.info.contact.email field. This cannot be changed directly, but it can be changed through the lead.username field. This will require that we utilize the identifier for the lead to ensure we are specifying the correct lead. Otherwise, the system cannot determine what is identifying the lead.

Example code: Changing the Email

# Define the lead
lead_id="<lead_id>"
lead_username="my-new-email@email.com"
lead="{\"id\": \"$lead_id\", \"username\": \"$lead_username\"}"

# Send the HTTP request
response=$(curl -s -X POST 'https://public.cincapi.com/v2/site/leads' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <access_token>' \
  -d "$lead")

# Get the status code and the id from the response
status_code=$(echo "$response" | jq -r '.status')
returned_id=$(echo "$response" | jq -r '.id')

# Check the status code
if [ "$status_code" = "200" ]; then
  echo "Lead updated successfully."
  echo "The lead identifier returned: $returned_id"

  # Check if the returned id is the same as the provided id
  if [ "$returned_id" != "$lead_id" ]; then
    echo "Something went wrong."
  fi
elif [ "$status_code" = "201" ]; then
  echo "We should never be here."
else
  echo "Lead update failed."
fi

var lead = new
{
    id = "<lead_id>",
    username = "my-new-email@email.com"
};

var json = JsonConvert.SerializeObject(lead);

using (var client = new HttpClient())
{
    client.DefaultRequestHeaders.Add("Content-Type", "application/json");
    client.DefaultRequestHeaders.Add("Authorization", "Bearer <access_token>");

    var response = await client.PostAsync("https://public.cincapi.com/v2/site/leads", new StringContent(json, Encoding.UTF8, "application/json"));

    if (response.IsSuccessStatusCode)
    {
        var result = JsonConvert.DeserializeObject<dynamic>(await response.Content.ReadAsStringAsync());
        Console.WriteLine(result.id);

        if (result.id != lead.id)
        {
            Console.WriteLine("Something went wrong.");
        }

        if (response.StatusCode == HttpStatusCode.OK)
        {
            Console.WriteLine("Lead updated successfully.");
        }
        else if (response.StatusCode == HttpStatusCode.Created)
        {
            Console.WriteLine("We should never be here.");
        }
    }
    else
    {
        Console.WriteLine("Lead update failed.");
    }
}

const lead = {
  id: '<lead_id>',
  username: 'my-new-email@email.com'
};

const response = await fetch('https://public.cincapi.com/v2/site/leads', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer <access_token>'
  },
  body: JSON.stringify(lead)
}).catch(error => console.error(error));

if (response?.ok) {
  console.log('Lead updated successfully.');
  const result = await response.json();

  // The lead identifier is returned in the response.
  console.log(result.id);

  // The lead identifier returned will be the one provided.
  if (result.id !== lead.id) {
    console.log('Something went wrong.');
  }

  // If the code is 200, then the lead was updated.
  if (response.status === 200) {
    console.log('Lead updated successfully.');
  }
  // If the lead identifier was provided, then we are specifying a lead and it will not be created.
  else if (response.status === 201) {
    console.log('We should never be here.');
  }
} else {
  console.log('Lead update failed.');
}

import requests
import json

# Define the lead
lead = {
  'id': '<lead_id>',
  'username': 'my-new-email@email.com'
}

# Send the HTTP request
response = requests.post(
    'https://public.cincapi.com/v2/site/leads',
    headers={
        'Content-Type': 'application/json',
        'Authorization': 'Bearer <access_token>'
    },
    data=json.dumps(lead)
)

# Check the response
if response.ok:
    result = response.json()
    print(result['id'])

    if result['id'] != lead['id']:
        print('Something went wrong.')

    if response.status_code == 200:
        print('Lead updated successfully.')
    elif response.status_code == 201:
        print('We should never be here.')
else:
    print('Lead update failed.')

Adding Notes

The endpoint also allows for adding notes to a lead. This is done by specifying the lead.notes field with an array of note objects. To learn more about the note object, see the Lead Notes page. All notes will be added to the lead and it will not attempt to update any notes that already exist.

Example code: Adding Notes

# Define the lead
lead='{
  "username": "mylead@email.com",
  "notes": [
    {
      "content": "This is a note.",
      "category": "general"
    },
    {
      "content": "The default is a general note."
    },
    {
      "content": "Can also pin the note to the top of the notes section for that lead.",
      "is_pinned": true
    }
  ]
}'

# Send the HTTP request
response=$(curl -s -X POST 'https://public.cincapi.com/v2/site/leads' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <access_token>' \
  -d "$lead")

# Get the status code and the id from the response
status_code=$(echo "$response" | jq -r '.status')
returned_id=$(echo "$response" | jq -r '.id')

# Check the status code
if [ "$status_code" = "200" ]; then
  echo "Lead updated successfully."
  echo "The lead identifier returned: $returned_id"
elif [ "$status_code" = "201" ]; then
  echo "Lead created successfully."
  echo "The lead identifier returned: $returned_id"
else
  echo "Lead upsert failed."
fi

var lead = new
{
    username = "mylead@email.com",
    notes = new[]
    {
        new { content = "This is a note.", category = "general" },
        new { content = "The default is a general note." },
        new { content = "Can also pin the note to the top of the notes section for that lead.", is_pinned = true }
    }
};

var json = JsonConvert.SerializeObject(lead);

using (var client = new HttpClient())
{
    client.DefaultRequestHeaders.Add("Content-Type", "application/json");
    client.DefaultRequestHeaders.Add("Authorization", "Bearer <access_token>");

    var response = await client.PostAsync("https://public.cincapi.com/v2/site/leads", new StringContent(json, Encoding.UTF8, "application/json"));

    if (response.IsSuccessStatusCode)
    {
        Console.WriteLine("Lead upserted successfully.");
        var result = JsonConvert.DeserializeObject<dynamic>(await response.Content.ReadAsStringAsync());
        Console.WriteLine(result.id);

        if (response.StatusCode == HttpStatusCode.OK)
        {
            Console.WriteLine("Lead updated successfully.");
        }
        else if (response.StatusCode == HttpStatusCode.Created)
        {
            Console.WriteLine("Lead created successfully.");
        }
    }
    else
    {
        Console.WriteLine("Lead upsert failed.");
    }
}

const lead = {
  username: 'mylead@email.com',
  notes: [
    {
      content: 'This is a note.',
      category: 'general'
    },
    {
      content: 'The default is a general note.'
    },
    {
      content: 'Can also pin the note to the top of the notes section for that lead.',
      is_pinned: true
    }
  ]
};

const response = await fetch('https://public.cincapi.com/v2/site/leads', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer <access_token>'
  },
  body: JSON.stringify(lead)
}).catch(error => console.error(error));

if (response?.ok) {
  console.log('Lead upserted successfully.');
  const result = await response.json();

  // The lead identifier is returned in the response.
  console.log(result.id);

  // If the code is 200, then the lead was updated.
  if (response.status === 200) {
    console.log('Lead updated successfully.');
  }
  // If the code is 201, then the lead was created.
  else if (response.status === 201) {
    console.log('Lead created successfully.');
  }
} else {
  console.log('Lead upsert failed.');
}

import requests
import json

# Define the lead
lead = {
  'username': 'mylead@email.com',
  'notes': [
    {
      'content': 'This is a note.',
      'category': 'general'
    },
    {
      'content': 'The default is a general note.'
    },
    {
      'content': 'Can also pin the note to the top of the notes section for that lead.',
      'is_pinned': True
    }
  ]
}

# Send the HTTP request
response = requests.post(
    'https://public.cincapi.com/v2/site/leads',
    headers={
        'Content-Type': 'application/json',
        'Authorization': 'Bearer <access_token>'
    },
    data=json.dumps(lead)
)

# Check the response
if response.ok:
    print('Lead upserted successfully.')
    result = response.json()
    print(result['id'])

    if response.status_code == 200:
        print('Lead updated successfully.')
    elif response.status_code == 201:
        print('Lead created successfully.')
else:
    print('Lead upsert failed.')

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

cURL C# JavaScript Python