Upsert Contact
Please find the list of acceptable values for the country field here
The Upsert API will adhere to the configuration defined under the “Allow Duplicate Contact” setting at the Location level. If the setting is configured to check both Email and Phone, the API will attempt to identify an existing contact based on the priority sequence specified in the setting, and will create or update the contact accordingly.
If two separate contacts already exist—one with the same email and another with the same phone—and an upsert request includes both the email and phone, the API will update the contact that matches the first field in the configured sequence, and ignore the second field to prevent duplication.
curl --request POST \
--url https://services.leadconnectorhq.com/contacts/upsert \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--header 'Version: <version>' \
--data '
{
"locationId": "ve9EPM428h8vShlRW1KT",
"firstName": "Rosan",
"lastName": "Deo",
"name": "Rosan Deo",
"email": "rosan@deos.com",
"gender": "male",
"phone": "+1 888-888-8888",
"address1": "3535 1st St N",
"city": "Dolomite",
"state": "AL",
"postalCode": "35061",
"website": "https://www.tesla.com",
"timezone": "America/Chihuahua",
"dnd": true,
"dndSettings": {},
"inboundDndSettings": {},
"tags": [
"nisi sint commodo amet",
"consequat"
],
"customFields": [
{
"id": "6dvNaf7VhkQ9snc5vnjJ",
"key": "my_custom_field",
"field_value": "My Text"
}
],
"source": "public api",
"dateOfBirth": "1990-09-25",
"country": "US",
"companyName": "DGS VolMAX",
"assignedTo": "y0BeYjuRIlDwsDcOHOJo",
"createNewIfDuplicateAllowed": false
}
'const options = {
method: 'POST',
headers: {
Version: '<version>',
Authorization: 'Bearer <token>',
'Content-Type': 'application/json'
},
body: JSON.stringify({
locationId: 've9EPM428h8vShlRW1KT',
firstName: 'Rosan',
lastName: 'Deo',
name: 'Rosan Deo',
email: 'rosan@deos.com',
gender: 'male',
phone: '+1 888-888-8888',
address1: '3535 1st St N',
city: 'Dolomite',
state: 'AL',
postalCode: '35061',
website: 'https://www.tesla.com',
timezone: 'America/Chihuahua',
dnd: true,
dndSettings: {},
inboundDndSettings: {},
tags: ['nisi sint commodo amet', 'consequat'],
customFields: [{id: '6dvNaf7VhkQ9snc5vnjJ', key: 'my_custom_field', field_value: 'My Text'}],
source: 'public api',
dateOfBirth: '1990-09-25',
country: 'US',
companyName: 'DGS VolMAX',
assignedTo: 'y0BeYjuRIlDwsDcOHOJo',
createNewIfDuplicateAllowed: false
})
};
fetch('https://services.leadconnectorhq.com/contacts/upsert', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));import requests
url = "https://services.leadconnectorhq.com/contacts/upsert"
payload = {
"locationId": "ve9EPM428h8vShlRW1KT",
"firstName": "Rosan",
"lastName": "Deo",
"name": "Rosan Deo",
"email": "rosan@deos.com",
"gender": "male",
"phone": "+1 888-888-8888",
"address1": "3535 1st St N",
"city": "Dolomite",
"state": "AL",
"postalCode": "35061",
"website": "https://www.tesla.com",
"timezone": "America/Chihuahua",
"dnd": True,
"dndSettings": {},
"inboundDndSettings": {},
"tags": ["nisi sint commodo amet", "consequat"],
"customFields": [
{
"id": "6dvNaf7VhkQ9snc5vnjJ",
"key": "my_custom_field",
"field_value": "My Text"
}
],
"source": "public api",
"dateOfBirth": "1990-09-25",
"country": "US",
"companyName": "DGS VolMAX",
"assignedTo": "y0BeYjuRIlDwsDcOHOJo",
"createNewIfDuplicateAllowed": False
}
headers = {
"Version": "<version>",
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text){
"new": true,
"contact": {
"id": "seD4PfOuKoVMLkEZqohJ",
"name": "rubika deo",
"locationId": "ve9EPM428h8vShlRW1KT",
"firstName": "rubika",
"lastName": "Deo",
"email": "rubika@deos.com",
"emailLowerCase": "rubika@deos.com",
"timezone": "Asia/Calcutta",
"companyName": "DGS VolMAX",
"phone": "+18832327657",
"dnd": true,
"dndSettings": {
"Call": {
"status": "active",
"message": "<string>",
"code": "<string>"
},
"Email": {
"status": "active",
"message": "<string>",
"code": "<string>"
},
"SMS": {
"status": "active",
"message": "<string>",
"code": "<string>"
},
"WhatsApp": {
"status": "active",
"message": "<string>",
"code": "<string>"
},
"GMB": {
"status": "active",
"message": "<string>",
"code": "<string>"
},
"FB": {
"status": "active",
"message": "<string>",
"code": "<string>"
}
},
"type": "read",
"source": "public api",
"assignedTo": "ve9EPM428h8vShlRW1KT",
"address1": "3535 1st St N",
"city": "ruDolomitebika",
"state": "AL",
"country": "US",
"postalCode": "35061",
"website": "https://www.tesla.com",
"tags": [
"nisi sint commodo amet",
"consequat"
],
"dateOfBirth": "Date format YYYY-MM-DD",
"dateAdded": "2021-07-02T05:18:26.704Z",
"dateUpdated": "2021-07-02T05:18:26.704Z",
"attachments": "<string>",
"ssn": "<string>",
"keyword": "test",
"firstNameLowerCase": "rubika",
"fullNameLowerCase": "rubika deo",
"lastNameLowerCase": "deo",
"lastActivity": "2021-07-16T11:39:30.564Z",
"customFields": [
{
"id": "MgobCB14YMVKuE4Ka8p1",
"value": "name"
}
],
"businessId": "641c094001436dbc2081e642",
"attributionSource": {
"url": "Trigger Link",
"campaign": "<string>",
"utmSource": "<string>",
"utmMedium": "<string>",
"utmContent": "<string>",
"referrer": "https: //www.google.com",
"campaignId": "<string>",
"fbclid": "<string>",
"gclid": "CjOKCQjwnNyUBhCZARISAI9AYIFtNnIcWcYGIOQINz_ZoFI5SSLRRugSoPZoiEu27IZBY£1-MAIWmEaAo2VEALW_WCB",
"msclikid": "<string>",
"dclid": "<string>",
"fbc": "<string>",
"fbp": "fb. 1.1674748390986.1171287961",
"fbEventId": "Mozilla/5.0",
"userAgent": "Mozilla/5.0",
"ip": "58.111.106.198",
"medium": "survey",
"mediumId": "FglfHAn30PRwsZVyQlKp"
},
"lastAttributionSource": {
"url": "Trigger Link",
"campaign": "<string>",
"utmSource": "<string>",
"utmMedium": "<string>",
"utmContent": "<string>",
"referrer": "https: //www.google.com",
"campaignId": "<string>",
"fbclid": "<string>",
"gclid": "CjOKCQjwnNyUBhCZARISAI9AYIFtNnIcWcYGIOQINz_ZoFI5SSLRRugSoPZoiEu27IZBY£1-MAIWmEaAo2VEALW_WCB",
"msclikid": "<string>",
"dclid": "<string>",
"fbc": "<string>",
"fbp": "fb. 1.1674748390986.1171287961",
"fbEventId": "Mozilla/5.0",
"userAgent": "Mozilla/5.0",
"ip": "58.111.106.198",
"medium": "survey",
"mediumId": "FglfHAn30PRwsZVyQlKp"
},
"visitorId": "ve9EPM428h8vShlRW1KT"
},
"traceId": "<string>"
}{
"statusCode": 400,
"message": "Bad Request"
}{
"statusCode": 401,
"message": "Invalid token: access token is invalid",
"error": "Unauthorized"
}{
"statusCode": 422,
"message": [
"Unprocessable Entity"
],
"error": "Unprocessable Entity"
}Authorizations
Body
Controls whether to create a new contact or update an existing duplicate. Scenario 1: If this value is true and the location allows duplicate contacts, a new contact will be created immediately without checking for duplicates. Scenario 2: If this value is true but the location does not allow duplicate contacts, this field is ignored and the normal upsert behavior applies: the API will search for an existing duplicate contact, update it if found, or create a new contact if not found. Scenario 3: If this value is false or not provided, the normal upsert behavior applies regardless of the location's duplicate contact setting.
false
Was this page helpful?
curl --request POST \
--url https://services.leadconnectorhq.com/contacts/upsert \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--header 'Version: <version>' \
--data '
{
"locationId": "ve9EPM428h8vShlRW1KT",
"firstName": "Rosan",
"lastName": "Deo",
"name": "Rosan Deo",
"email": "rosan@deos.com",
"gender": "male",
"phone": "+1 888-888-8888",
"address1": "3535 1st St N",
"city": "Dolomite",
"state": "AL",
"postalCode": "35061",
"website": "https://www.tesla.com",
"timezone": "America/Chihuahua",
"dnd": true,
"dndSettings": {},
"inboundDndSettings": {},
"tags": [
"nisi sint commodo amet",
"consequat"
],
"customFields": [
{
"id": "6dvNaf7VhkQ9snc5vnjJ",
"key": "my_custom_field",
"field_value": "My Text"
}
],
"source": "public api",
"dateOfBirth": "1990-09-25",
"country": "US",
"companyName": "DGS VolMAX",
"assignedTo": "y0BeYjuRIlDwsDcOHOJo",
"createNewIfDuplicateAllowed": false
}
'const options = {
method: 'POST',
headers: {
Version: '<version>',
Authorization: 'Bearer <token>',
'Content-Type': 'application/json'
},
body: JSON.stringify({
locationId: 've9EPM428h8vShlRW1KT',
firstName: 'Rosan',
lastName: 'Deo',
name: 'Rosan Deo',
email: 'rosan@deos.com',
gender: 'male',
phone: '+1 888-888-8888',
address1: '3535 1st St N',
city: 'Dolomite',
state: 'AL',
postalCode: '35061',
website: 'https://www.tesla.com',
timezone: 'America/Chihuahua',
dnd: true,
dndSettings: {},
inboundDndSettings: {},
tags: ['nisi sint commodo amet', 'consequat'],
customFields: [{id: '6dvNaf7VhkQ9snc5vnjJ', key: 'my_custom_field', field_value: 'My Text'}],
source: 'public api',
dateOfBirth: '1990-09-25',
country: 'US',
companyName: 'DGS VolMAX',
assignedTo: 'y0BeYjuRIlDwsDcOHOJo',
createNewIfDuplicateAllowed: false
})
};
fetch('https://services.leadconnectorhq.com/contacts/upsert', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));import requests
url = "https://services.leadconnectorhq.com/contacts/upsert"
payload = {
"locationId": "ve9EPM428h8vShlRW1KT",
"firstName": "Rosan",
"lastName": "Deo",
"name": "Rosan Deo",
"email": "rosan@deos.com",
"gender": "male",
"phone": "+1 888-888-8888",
"address1": "3535 1st St N",
"city": "Dolomite",
"state": "AL",
"postalCode": "35061",
"website": "https://www.tesla.com",
"timezone": "America/Chihuahua",
"dnd": True,
"dndSettings": {},
"inboundDndSettings": {},
"tags": ["nisi sint commodo amet", "consequat"],
"customFields": [
{
"id": "6dvNaf7VhkQ9snc5vnjJ",
"key": "my_custom_field",
"field_value": "My Text"
}
],
"source": "public api",
"dateOfBirth": "1990-09-25",
"country": "US",
"companyName": "DGS VolMAX",
"assignedTo": "y0BeYjuRIlDwsDcOHOJo",
"createNewIfDuplicateAllowed": False
}
headers = {
"Version": "<version>",
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text){
"new": true,
"contact": {
"id": "seD4PfOuKoVMLkEZqohJ",
"name": "rubika deo",
"locationId": "ve9EPM428h8vShlRW1KT",
"firstName": "rubika",
"lastName": "Deo",
"email": "rubika@deos.com",
"emailLowerCase": "rubika@deos.com",
"timezone": "Asia/Calcutta",
"companyName": "DGS VolMAX",
"phone": "+18832327657",
"dnd": true,
"dndSettings": {
"Call": {
"status": "active",
"message": "<string>",
"code": "<string>"
},
"Email": {
"status": "active",
"message": "<string>",
"code": "<string>"
},
"SMS": {
"status": "active",
"message": "<string>",
"code": "<string>"
},
"WhatsApp": {
"status": "active",
"message": "<string>",
"code": "<string>"
},
"GMB": {
"status": "active",
"message": "<string>",
"code": "<string>"
},
"FB": {
"status": "active",
"message": "<string>",
"code": "<string>"
}
},
"type": "read",
"source": "public api",
"assignedTo": "ve9EPM428h8vShlRW1KT",
"address1": "3535 1st St N",
"city": "ruDolomitebika",
"state": "AL",
"country": "US",
"postalCode": "35061",
"website": "https://www.tesla.com",
"tags": [
"nisi sint commodo amet",
"consequat"
],
"dateOfBirth": "Date format YYYY-MM-DD",
"dateAdded": "2021-07-02T05:18:26.704Z",
"dateUpdated": "2021-07-02T05:18:26.704Z",
"attachments": "<string>",
"ssn": "<string>",
"keyword": "test",
"firstNameLowerCase": "rubika",
"fullNameLowerCase": "rubika deo",
"lastNameLowerCase": "deo",
"lastActivity": "2021-07-16T11:39:30.564Z",
"customFields": [
{
"id": "MgobCB14YMVKuE4Ka8p1",
"value": "name"
}
],
"businessId": "641c094001436dbc2081e642",
"attributionSource": {
"url": "Trigger Link",
"campaign": "<string>",
"utmSource": "<string>",
"utmMedium": "<string>",
"utmContent": "<string>",
"referrer": "https: //www.google.com",
"campaignId": "<string>",
"fbclid": "<string>",
"gclid": "CjOKCQjwnNyUBhCZARISAI9AYIFtNnIcWcYGIOQINz_ZoFI5SSLRRugSoPZoiEu27IZBY£1-MAIWmEaAo2VEALW_WCB",
"msclikid": "<string>",
"dclid": "<string>",
"fbc": "<string>",
"fbp": "fb. 1.1674748390986.1171287961",
"fbEventId": "Mozilla/5.0",
"userAgent": "Mozilla/5.0",
"ip": "58.111.106.198",
"medium": "survey",
"mediumId": "FglfHAn30PRwsZVyQlKp"
},
"lastAttributionSource": {
"url": "Trigger Link",
"campaign": "<string>",
"utmSource": "<string>",
"utmMedium": "<string>",
"utmContent": "<string>",
"referrer": "https: //www.google.com",
"campaignId": "<string>",
"fbclid": "<string>",
"gclid": "CjOKCQjwnNyUBhCZARISAI9AYIFtNnIcWcYGIOQINz_ZoFI5SSLRRugSoPZoiEu27IZBY£1-MAIWmEaAo2VEALW_WCB",
"msclikid": "<string>",
"dclid": "<string>",
"fbc": "<string>",
"fbp": "fb. 1.1674748390986.1171287961",
"fbEventId": "Mozilla/5.0",
"userAgent": "Mozilla/5.0",
"ip": "58.111.106.198",
"medium": "survey",
"mediumId": "FglfHAn30PRwsZVyQlKp"
},
"visitorId": "ve9EPM428h8vShlRW1KT"
},
"traceId": "<string>"
}{
"statusCode": 400,
"message": "Bad Request"
}{
"statusCode": 401,
"message": "Invalid token: access token is invalid",
"error": "Unauthorized"
}{
"statusCode": 422,
"message": [
"Unprocessable Entity"
],
"error": "Unprocessable Entity"
}