MCPCreate or Update Contact
curl --request POST \
--url https://api.birdeye.com/resources/v1/customer-v2/external/saveCustomer \
--header 'Content-Type: application/json' \
--data '
{
"id": 115339282,
"firstName": "Michael",
"lastName": "Scott",
"email": "michael@test.com",
"phone": "(212) xxx-xxxx",
"countryCode": "US",
"emailOptin": true,
"smsOptin": true,
"blocked": false,
"businessIds": [
161458406365307,
161072537475129
],
"tags": [
"Tag One",
"Tag Two"
],
"customFields": [
{
"fieldName": "Company",
"type": "text",
"fieldValue": "Dunder Mifflin"
},
{
"fieldName": "Product",
"type": "text",
"fieldValue": "Paper"
}
],
"externalId": "ABC123"
}
'import requests
url = "https://api.birdeye.com/resources/v1/customer-v2/external/saveCustomer"
payload = {
"id": 115339282,
"firstName": "Michael",
"lastName": "Scott",
"email": "michael@test.com",
"phone": "(212) xxx-xxxx",
"countryCode": "US",
"emailOptin": True,
"smsOptin": True,
"blocked": False,
"businessIds": [161458406365307, 161072537475129],
"tags": ["Tag One", "Tag Two"],
"customFields": [
{
"fieldName": "Company",
"type": "text",
"fieldValue": "Dunder Mifflin"
},
{
"fieldName": "Product",
"type": "text",
"fieldValue": "Paper"
}
],
"externalId": "ABC123"
}
headers = {"Content-Type": "application/json"}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {'Content-Type': 'application/json'},
body: JSON.stringify({
id: 115339282,
firstName: 'Michael',
lastName: 'Scott',
email: 'michael@test.com',
phone: '(212) xxx-xxxx',
countryCode: 'US',
emailOptin: true,
smsOptin: true,
blocked: false,
businessIds: [161458406365307, 161072537475129],
tags: ['Tag One', 'Tag Two'],
customFields: [
{fieldName: 'Company', type: 'text', fieldValue: 'Dunder Mifflin'},
{fieldName: 'Product', type: 'text', fieldValue: 'Paper'}
],
externalId: 'ABC123'
})
};
fetch('https://api.birdeye.com/resources/v1/customer-v2/external/saveCustomer', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.birdeye.com/resources/v1/customer-v2/external/saveCustomer",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'id' => 115339282,
'firstName' => 'Michael',
'lastName' => 'Scott',
'email' => 'michael@test.com',
'phone' => '(212) xxx-xxxx',
'countryCode' => 'US',
'emailOptin' => true,
'smsOptin' => true,
'blocked' => false,
'businessIds' => [
161458406365307,
161072537475129
],
'tags' => [
'Tag One',
'Tag Two'
],
'customFields' => [
[
'fieldName' => 'Company',
'type' => 'text',
'fieldValue' => 'Dunder Mifflin'
],
[
'fieldName' => 'Product',
'type' => 'text',
'fieldValue' => 'Paper'
]
],
'externalId' => 'ABC123'
]),
CURLOPT_HTTPHEADER => [
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.birdeye.com/resources/v1/customer-v2/external/saveCustomer"
payload := strings.NewReader("{\n \"id\": 115339282,\n \"firstName\": \"Michael\",\n \"lastName\": \"Scott\",\n \"email\": \"michael@test.com\",\n \"phone\": \"(212) xxx-xxxx\",\n \"countryCode\": \"US\",\n \"emailOptin\": true,\n \"smsOptin\": true,\n \"blocked\": false,\n \"businessIds\": [\n 161458406365307,\n 161072537475129\n ],\n \"tags\": [\n \"Tag One\",\n \"Tag Two\"\n ],\n \"customFields\": [\n {\n \"fieldName\": \"Company\",\n \"type\": \"text\",\n \"fieldValue\": \"Dunder Mifflin\"\n },\n {\n \"fieldName\": \"Product\",\n \"type\": \"text\",\n \"fieldValue\": \"Paper\"\n }\n ],\n \"externalId\": \"ABC123\"\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.birdeye.com/resources/v1/customer-v2/external/saveCustomer")
.header("Content-Type", "application/json")
.body("{\n \"id\": 115339282,\n \"firstName\": \"Michael\",\n \"lastName\": \"Scott\",\n \"email\": \"michael@test.com\",\n \"phone\": \"(212) xxx-xxxx\",\n \"countryCode\": \"US\",\n \"emailOptin\": true,\n \"smsOptin\": true,\n \"blocked\": false,\n \"businessIds\": [\n 161458406365307,\n 161072537475129\n ],\n \"tags\": [\n \"Tag One\",\n \"Tag Two\"\n ],\n \"customFields\": [\n {\n \"fieldName\": \"Company\",\n \"type\": \"text\",\n \"fieldValue\": \"Dunder Mifflin\"\n },\n {\n \"fieldName\": \"Product\",\n \"type\": \"text\",\n \"fieldValue\": \"Paper\"\n }\n ],\n \"externalId\": \"ABC123\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.birdeye.com/resources/v1/customer-v2/external/saveCustomer")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Content-Type"] = 'application/json'
request.body = "{\n \"id\": 115339282,\n \"firstName\": \"Michael\",\n \"lastName\": \"Scott\",\n \"email\": \"michael@test.com\",\n \"phone\": \"(212) xxx-xxxx\",\n \"countryCode\": \"US\",\n \"emailOptin\": true,\n \"smsOptin\": true,\n \"blocked\": false,\n \"businessIds\": [\n 161458406365307,\n 161072537475129\n ],\n \"tags\": [\n \"Tag One\",\n \"Tag Two\"\n ],\n \"customFields\": [\n {\n \"fieldName\": \"Company\",\n \"type\": \"text\",\n \"fieldValue\": \"Dunder Mifflin\"\n },\n {\n \"fieldName\": \"Product\",\n \"type\": \"text\",\n \"fieldValue\": \"Paper\"\n }\n ],\n \"externalId\": \"ABC123\"\n}"
response = http.request(request)
puts response.read_body{
"id": 115339282
}{
"code": 1167,
"message": "API key is missing"
}{
"code": 1161,
"message": "Invalid API key"
}{
"code": 1532,
"message": "Business id is missing or invalid."
}{
"code": 89,
"message": "Rate limit exceeded"
}Contact
Create or Update Contact
Customers can be created & updated using Create or Update Contact API.
POST
/
v1
/
customer-v2
/
external
/
saveCustomer
Create or Update Contact
curl --request POST \
--url https://api.birdeye.com/resources/v1/customer-v2/external/saveCustomer \
--header 'Content-Type: application/json' \
--data '
{
"id": 115339282,
"firstName": "Michael",
"lastName": "Scott",
"email": "michael@test.com",
"phone": "(212) xxx-xxxx",
"countryCode": "US",
"emailOptin": true,
"smsOptin": true,
"blocked": false,
"businessIds": [
161458406365307,
161072537475129
],
"tags": [
"Tag One",
"Tag Two"
],
"customFields": [
{
"fieldName": "Company",
"type": "text",
"fieldValue": "Dunder Mifflin"
},
{
"fieldName": "Product",
"type": "text",
"fieldValue": "Paper"
}
],
"externalId": "ABC123"
}
'import requests
url = "https://api.birdeye.com/resources/v1/customer-v2/external/saveCustomer"
payload = {
"id": 115339282,
"firstName": "Michael",
"lastName": "Scott",
"email": "michael@test.com",
"phone": "(212) xxx-xxxx",
"countryCode": "US",
"emailOptin": True,
"smsOptin": True,
"blocked": False,
"businessIds": [161458406365307, 161072537475129],
"tags": ["Tag One", "Tag Two"],
"customFields": [
{
"fieldName": "Company",
"type": "text",
"fieldValue": "Dunder Mifflin"
},
{
"fieldName": "Product",
"type": "text",
"fieldValue": "Paper"
}
],
"externalId": "ABC123"
}
headers = {"Content-Type": "application/json"}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {'Content-Type': 'application/json'},
body: JSON.stringify({
id: 115339282,
firstName: 'Michael',
lastName: 'Scott',
email: 'michael@test.com',
phone: '(212) xxx-xxxx',
countryCode: 'US',
emailOptin: true,
smsOptin: true,
blocked: false,
businessIds: [161458406365307, 161072537475129],
tags: ['Tag One', 'Tag Two'],
customFields: [
{fieldName: 'Company', type: 'text', fieldValue: 'Dunder Mifflin'},
{fieldName: 'Product', type: 'text', fieldValue: 'Paper'}
],
externalId: 'ABC123'
})
};
fetch('https://api.birdeye.com/resources/v1/customer-v2/external/saveCustomer', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.birdeye.com/resources/v1/customer-v2/external/saveCustomer",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'id' => 115339282,
'firstName' => 'Michael',
'lastName' => 'Scott',
'email' => 'michael@test.com',
'phone' => '(212) xxx-xxxx',
'countryCode' => 'US',
'emailOptin' => true,
'smsOptin' => true,
'blocked' => false,
'businessIds' => [
161458406365307,
161072537475129
],
'tags' => [
'Tag One',
'Tag Two'
],
'customFields' => [
[
'fieldName' => 'Company',
'type' => 'text',
'fieldValue' => 'Dunder Mifflin'
],
[
'fieldName' => 'Product',
'type' => 'text',
'fieldValue' => 'Paper'
]
],
'externalId' => 'ABC123'
]),
CURLOPT_HTTPHEADER => [
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.birdeye.com/resources/v1/customer-v2/external/saveCustomer"
payload := strings.NewReader("{\n \"id\": 115339282,\n \"firstName\": \"Michael\",\n \"lastName\": \"Scott\",\n \"email\": \"michael@test.com\",\n \"phone\": \"(212) xxx-xxxx\",\n \"countryCode\": \"US\",\n \"emailOptin\": true,\n \"smsOptin\": true,\n \"blocked\": false,\n \"businessIds\": [\n 161458406365307,\n 161072537475129\n ],\n \"tags\": [\n \"Tag One\",\n \"Tag Two\"\n ],\n \"customFields\": [\n {\n \"fieldName\": \"Company\",\n \"type\": \"text\",\n \"fieldValue\": \"Dunder Mifflin\"\n },\n {\n \"fieldName\": \"Product\",\n \"type\": \"text\",\n \"fieldValue\": \"Paper\"\n }\n ],\n \"externalId\": \"ABC123\"\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.birdeye.com/resources/v1/customer-v2/external/saveCustomer")
.header("Content-Type", "application/json")
.body("{\n \"id\": 115339282,\n \"firstName\": \"Michael\",\n \"lastName\": \"Scott\",\n \"email\": \"michael@test.com\",\n \"phone\": \"(212) xxx-xxxx\",\n \"countryCode\": \"US\",\n \"emailOptin\": true,\n \"smsOptin\": true,\n \"blocked\": false,\n \"businessIds\": [\n 161458406365307,\n 161072537475129\n ],\n \"tags\": [\n \"Tag One\",\n \"Tag Two\"\n ],\n \"customFields\": [\n {\n \"fieldName\": \"Company\",\n \"type\": \"text\",\n \"fieldValue\": \"Dunder Mifflin\"\n },\n {\n \"fieldName\": \"Product\",\n \"type\": \"text\",\n \"fieldValue\": \"Paper\"\n }\n ],\n \"externalId\": \"ABC123\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.birdeye.com/resources/v1/customer-v2/external/saveCustomer")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Content-Type"] = 'application/json'
request.body = "{\n \"id\": 115339282,\n \"firstName\": \"Michael\",\n \"lastName\": \"Scott\",\n \"email\": \"michael@test.com\",\n \"phone\": \"(212) xxx-xxxx\",\n \"countryCode\": \"US\",\n \"emailOptin\": true,\n \"smsOptin\": true,\n \"blocked\": false,\n \"businessIds\": [\n 161458406365307,\n 161072537475129\n ],\n \"tags\": [\n \"Tag One\",\n \"Tag Two\"\n ],\n \"customFields\": [\n {\n \"fieldName\": \"Company\",\n \"type\": \"text\",\n \"fieldValue\": \"Dunder Mifflin\"\n },\n {\n \"fieldName\": \"Product\",\n \"type\": \"text\",\n \"fieldValue\": \"Paper\"\n }\n ],\n \"externalId\": \"ABC123\"\n}"
response = http.request(request)
puts response.read_body{
"id": 115339282
}{
"code": 1167,
"message": "API key is missing"
}{
"code": 1161,
"message": "Invalid API key"
}{
"code": 1532,
"message": "Business id is missing or invalid."
}{
"code": 89,
"message": "Rate limit exceeded"
}Headers
e.g. application/json
e.g. [Required] Partner specific API key provided by Birdeye for data exchange.
Media type of the JSON request body.
Query Parameters
Id of the business.
Body
application/json
Id of enterprise customer.
First name of the customer.
Last name of the customer.
Email of customer, optional (if phone is provided).
Phone of customer optional (if email is provided).
Country code of the phone number. Default value=US, Other Possible values=AU,CA,MX,PR,VI
SMS Opt flag.
Email Opt flag.
Contact block flag.
Business Ids under enterprise account. The Business Ids field is mandatory while creating a new contact. While updating, if no business Ids are provided, the same location mappings are retained.
List of tags.
List of Custom fields. We currently support 4 types of customfields - text, number, currency, date (in formats - “MM/dd/yyyy” and "MM-dd-yyyy" only), and yes or no (1:"yes", 0:"no").
Show child attributes
Show child attributes
Unique external identifier of the contact which could be from the CRM or any external system storing your contacts.
Response
OK
Id of enterprise customer.
⌘I