Manage contacts across locations effortlessly with a robust Contact Management System.
Every API here is available over the APIs.io API and to AI agents over MCP.
One button, every client — Claude, Cursor, VS Code and the rest.
https://apis.io/mcp
find_apisBrowse and filter every API in the catalog.get_api_artifactsOne API's artifacts, grouped by type.get_openapiThe primary OpenAPI for this API.find_similar_apisAPIs that look like this one.apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.resolveTurn a domain, URL or GitHub org into the provider it belongs to.find_cohortsEvery scored population of providers in the catalog.curl "https://apis.io/api/v1/apis/birdeye-contact-api"curl "https://apis.io/api/v1/apis?limit=25"Discovery needs no key. Ratings and market analysis are Pro.
openapi: 3.2.0
info:
title: Birdeye Contact API
version: '1.0'
description: 'Operations tagged Contact across 2 of this provider''s published API definitions: birdeye-birdeye-api-openapi.yml, birdeye-openapi-original.yml. Each path carries the servers of the definition it was published in.'
servers:
- url: https://api.birdeye.com
description: Production
- url: https://api.birdeye.com/resources
tags:
- name: Contact
description: Manage contacts across locations effortlessly with a robust Contact Management System.
paths:
/v1/customer-v2/external/saveCustomer:
post:
summary: Create or Update Contact
operationId: create-or-update-contact
tags:
- Contact
parameters:
- name: businessId
in: query
required: true
description: Id of the business.
schema:
type: string
example: '12345678'
responses:
'200':
description: HTTP 200 response
content:
application/json:
schema:
type: object
example:
code: 5043
message: Contact not found for the given request
requestBody:
required: true
content:
application/json:
schema:
$schema: http://json-schema.org/draft-07/schema#
type: object
properties:
id:
type: string
firstName:
type: string
lastName:
type: string
email:
type: string
phone:
type: string
countryCode:
type: string
smsOptin:
type: boolean
emailOptin:
type: boolean
blocked:
type: boolean
businessIds:
type: array
tags:
type: string
customFields:
type: array
externalId:
type: string
security:
- apiKey: []
servers:
- url: https://api.birdeye.com
description: Production
/v1/customer-v2/external/getCustomer:
post:
summary: Get Contact
operationId: get-contact
tags:
- Contact
parameters:
- name: businessId
in: query
required: true
description: Id of the business.
schema:
type: string
example: '12345678'
responses:
'200':
description: HTTP 200 response
content:
application/json:
schema:
type: object
example:
code: 5043
message: Contact not found for the given request
requestBody:
required: true
content:
application/json:
schema:
$schema: http://json-schema.org/draft-07/schema#
type: object
properties:
id:
type: string
cid:
type: string
email:
type: string
phone:
type: string
experienceScore:
type: boolean
security:
- apiKey: []
servers:
- url: https://api.birdeye.com
description: Production
/v1/customer-v2/external/deleteCustomer:
post:
summary: Delete Contact
operationId: delete-contact
tags:
- Contact
parameters:
- name: businessId
in: query
required: true
description: Id of the business.
schema:
type: string
example: '12345678'
responses:
'200':
description: HTTP 200 response
content:
application/json:
schema:
type: object
example:
code: 5043
message: Contact not found for the given request
requestBody:
required: true
content:
application/json:
schema:
$schema: http://json-schema.org/draft-07/schema#
type: object
properties:
id:
type: string
businessIds:
type: array
required:
- id
security:
- apiKey: []
servers:
- url: https://api.birdeye.com
description: Production
/v1/customer/checkin:
post:
summary: Customer Checkin
operationId: customer-checkin
tags:
- Contact
parameters:
- name: bid
in: query
required: true
description: Id of the business.
schema:
type: string
example: '12345678'
responses:
'200':
description: HTTP 200 response
content:
application/json:
schema:
type: object
example:
code: 1175
message: No business found with the given id
requestBody:
required: true
content:
application/json:
schema:
$schema: http://json-schema.org/draft-07/schema#
type: object
properties:
name:
type: string
emailId:
type: string
phone:
type: string
smsEnabled:
type: number
additionalParams:
type: object
employees:
type: array
externalId:
type: string
security:
- apiKey: []
servers:
- url: https://api.birdeye.com
description: Production
/v1/customer/history/{customerId}:
get:
summary: Customer activity log
operationId: customer-activity-log
tags:
- Contact
parameters:
- name: businessId
in: query
required: true
description: Id of the business.
schema:
type: string
example: '12345678'
- name: startDate
in: query
required: false
description: The start date format should be MM/dd/yyyy. if start date is not set, then we will use the date customer was created.
schema:
type: string
example: 12/30/2021
- name: endDate
in: query
required: false
description: The end date format should be MM/dd/yyyy. if end date is not set, then we will use the current date.
schema:
type: string
example: 12/30/2022
- name: customerId
in: path
required: true
description: Id of the customer.
schema:
type: string
example: '12344'
responses:
'200':
description: HTTP 200 response
content:
application/json:
schema:
type: object
example:
code: 1524
message: Date entered is invalid.
security:
- apiKey: []
servers:
- url: https://api.birdeye.com
description: Production
/v1/customer/id/{customerId}:
delete:
summary: Customer Delete
operationId: customer-delete
tags:
- Contact
parameters:
- name: customerId
in: path
required: true
description: Id of enterprise customer.
schema:
type: string
example: '12345678'
responses:
'200':
description: HTTP 200 response
content:
application/json:
schema:
type: object
example:
code: 1089
message: Customer id is invalid.
security:
- apiKey: []
servers:
- url: https://api.birdeye.com
description: Production
/v1/customer-v2/change-permission:
post:
summary: Subscribe/Unsubscribe Customer
operationId: subscribe-unsubscribe-customer
tags:
- Contact
parameters: []
responses:
'200':
description: HTTP 200 response
content:
application/json:
schema:
type: object
example:
code: 1089
message: Customer id is invalid.
requestBody:
required: true
content:
application/json:
schema:
$schema: http://json-schema.org/draft-07/schema#
type: object
properties:
permission:
type: string
email:
type: array
phone:
type: array
accountNumber:
type: number
required:
- accountNumber
security:
- apiKey: []
servers:
- url: https://api.birdeye.com
description: Production
/v2/customer/list:
post:
summary: Contact
operationId: contact
tags:
- Contact
parameters:
- name: businessId
in: query
required: true
description: Id of the Business.
schema:
type: string
example: '12345678'
- name: page
in: query
required: true
description: The page number.
schema:
type: number
example: '0'
- name: size
in: query
required: true
description: Maximum number of contacts return in response.
schema:
type: number
example: '30'
- name: sortby
in: query
required: true
description: The sorting order of the list.
schema:
type: string
example: lastActivityOn
responses:
'200':
description: HTTP 200 response
content:
application/json:
schema:
type: object
example:
code: 1167
message: API key is missing
requestBody:
required: true
content:
application/json:
schema:
$schema: http://json-schema.org/draft-07/schema#
type: object
properties:
startDate:
type: string
endDate:
type: string
security:
- apiKey: []
servers:
- url: https://api.birdeye.com
description: Production
/v1/contact/details:
post:
summary: Customer or Lead list
operationId: customer-or-lead-list
tags:
- Contact
parameters:
- name: tags
in: query
required: false
description: If tag data is required send true, default value is false.
schema:
type: boolean
example: 'true'
- name: customfields
in: query
required: false
description: If custom fields data is required send true, default is false.
schema:
type: boolean
example: 'true'
responses:
'200':
description: HTTP 200 response
content:
application/json:
schema:
type: object
example:
code: 2348
message: Max window size allowed is 60000 for a filter selection
requestBody:
required: true
content:
application/json:
schema:
$schema: http://json-schema.org/draft-07/schema#
type: object
properties:
sources:
type: array
startDateUtc:
type: string
endDateUtc:
type: string
contactType:
type: string
businessId:
type: number
page:
type: string
size:
type: string
required:
- startDateUtc
- endDateUtc
- businessId
- page
- size
security:
- apiKey: []
servers:
- url: https://api.birdeye.com
description: Production
/v1/contactUs/{businessId}:
post:
summary: Contact Us Request
operationId: contact-us-request
tags:
- Contact
parameters:
- name: businessId
in: path
required: true
description: Id of the business.
schema:
type: string
example: '12345678'
responses:
'200':
description: HTTP 200 response
content:
application/json:
schema:
type: object
example:
code: 5046
message: The customer is blocked
requestBody:
required: true
content:
application/json:
schema:
$schema: http://json-schema.org/draft-07/schema#
type: object
properties:
customerComment:
type: string
customer:
type: object
properties:
name:
type: string
emailId:
type: string
phone:
type: string
required:
- name
additionalParams:
type: object
required:
- customer
security:
- apiKey: []
servers:
- url: https://api.birdeye.com
description: Production
/v1/contact/{businessId}/update-feed:
post:
summary: Get opt-out contact data
operationId: get-opt-out-contact-data
tags:
- Contact
parameters:
- name: businessId
in: path
required: true
description: Id of a business (Long).
schema:
type: number
example: '123456'
responses:
'200':
description: HTTP 200 response
content:
application/json:
schema:
type: object
example:
code: 20083
message: End date can't be before start date
requestBody:
required: true
content:
application/json:
schema:
$schema: http://json-schema.org/draft-07/schema#
type: object
properties:
start:
type: number
end:
type: number
subscriptionStatus:
type: array
required:
- start
- end
- subscriptionStatus
security:
- apiKey: []
servers:
- url: https://api.birdeye.com
description: Production
components:
schemas:
21121Model:
type: object
properties:
code:
type: number
message:
type: string
example:
code: 21121
message: Invalid contact source provided in the request.
1167Model:
type: object
properties:
code:
type: number
message:
type: string
example:
code: 1167
message: API key is missing
1523Model:
type: object
properties:
code:
type: number
message:
type: string
example:
code: 1523
message: The correct date format should be mm/dd/yyyy.
21120Model:
type: object
properties:
code:
type: number
message:
type: string
example:
code: 21120
message: Invalid contact type provided in the request. Valid contact types are lead or customer
1011Model:
type: object
properties:
code:
type: number
message:
type: string
example:
code: 1011
message: Business id is invalid
1033Model:
type: object
properties:
code:
type: number
message:
type: string
example:
code: 1033
message: You are not authorized to perform this action
1087Model:
type: object
properties:
code:
type: number
message:
type: string
example:
code: 1087
message: Customer email id is invalid.
1089Model:
type: object
properties:
code:
type: number
message:
type: string
example:
code: 1089
message: Customer id is invalid.
Apiary_getOptOutContactData_Response200:
type: object
properties:
emailOptOut:
type: array
description: All the contacts grouped under this field, which were opted out from email in the given duration
items:
type: object
properties:
id:
type: number
description: id of the enterprise customer.
firstName:
type: string
description: First name of the contact.
lastName:
type: string
description: Last name of the contact.
emailId:
type: string
description: EmailId of the contact, if exists.
phone:
type: string
description: Phone number of the contact, if exists. Format is (xxx) xxx-xxxx.
textOptOut:
type: array
description: All the contacts grouped under this field, which were opted out from text in the given duration
items:
type: object
properties:
id:
type: number
description: id of the enterprise customer.
firstName:
type: string
description: First name of the contact.
lastName:
type: string
description: Last name of the contact.
emailId:
type: string
description: EmailId of the contact, if exists.
phone:
type: string
description: Phone number of the contact, if exists. Format is (xxx) xxx-xxxx.
blocked:
type: array
description: All the contacts grouped under this field, which were blockedl in the given duration.
items:
type: object
properties:
id:
type: number
description: id of the enterprise customer.
firstName:
type: string
description: First name of the contact.
lastName:
type: string
description: Last name of the contact.
emailId:
type: string
description: EmailId of the contact, if exists.
phone:
type: string
description: Phone number of the contact, if exists. Format is (xxx) xxx-xxxx.
Apiary_contact_Response200:
type: object
properties:
page:
type: number
description: The page number.
size:
type: number
description: Maximum number of contacts return in response.
totalPages:
type: number
description: Number of pages to query.
totalCount:
type: number
description: Number of contacts to query.
customers:
type: array
description: Customer list
items:
type: object
properties:
customerId:
type: number
description: Id of enterprise customer.
name:
type: string
description: Name of enterprise customer.
email:
type: string
description: Email Id of enterprise customer.
phone:
type: string
description: Phone number of enterprise customer.
lastActivityWithTime:
type: string
description: Last activity time.
1142Model:
type: object
properties:
code:
type: number
message:
type: string
example:
code: 1142
message: Customer name cannot be blank
1170Model:
type: object
properties:
code:
type: number
message:
type: string
example:
code: 1170
message: SMS Alert flag is invalid. Valid values are 0 or 1.
5043Model:
type: object
properties:
code:
type: number
message:
type: string
example:
code: 5043
message: Contact not found for the given request
1175Model:
type: object
properties:
code:
type: number
message:
type: string
example:
code: 1175
message: No business found with the given id
Apiary_customerOrLeadList_Response200:
type: object
properties:
page:
type: number
description: Page number to request.
size:
type: number
description: Number of records per page.
totalPages:
type: number
description: Total number of pages.
contacts:
type: array
description: Contact details
items:
type: object
properties:
firstName:
type: string
description: First name of the contact.
lastName:
type: string
description: Last name of the contact.
email:
type: string
description: Email Id of the contact.
phone:
type: string
description: Phone number of the contact.
created:
type: string
description: 01-06T22:25:12.000+0000 (string) - Created date of the contact.
contactType:
type: string
description: Contact type.
source:
type: string
description: Source of the customer/lead.
mappings:
type: array
items:
type: object
properties:
businessId:
type: number
description: Business number of the location.
customerId:
type: number
description: Id of the customer.
description: Locations customer/lead is associated with
Apiary_subscribeUnsubscribeCustomer_Request:
type: object
properties:
permission:
type: string
description: Action to be taken. Valid values are both-subscribed, both-unsubscribed, sms-subscribed, and email-subscribed.
email:
type: array
description: Customer email ids.
items: {}
phone:
type: array
description: Customer phone numbers.
items: {}
accountNumber:
type: number
description: Location id.
required:
- accountNumber
- permission
example:
permission: both-unsubscribed
email:
- test1@mail.in
phone:
- '2345654326'
accountNumber: 123456789876543
Apiary_createOrUpdateContact_Request:
type: object
properties:
id:
type: string
description: Id of enterprise customer.
firstName:
type: string
description: First name of the customer.
lastName:
type: string
description: Last name of the customer.
email:
type: string
description: Email of customer, optional (if phone is provided).
phone:
type: string
description: Phone of customer optional (if email is provided).
countryCode:
type: string
description: Country code of the phone number. Default value=US, Other Possible values=AU,CA,MX,PR,VI
smsOptin:
type: boolean
description: SMS Opt flag.
emailOptin:
type: boolean
description: Email Opt flag.
blocked:
type: boolean
description: Contact block flag.
businessIds:
type: array
description: 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.
items: {}
tags:
type: string
description: List of tags.
customFields:
type: array
description: 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").
items:
type: object
properties:
fieldName:
type: string
description: Field name.
type:
type: string
description: Field type.
fieldValue:
type: string
description: Value of field.
externalId:
type: string
description: Unique external identifier of the contact which could be from the CRM or any external system storing your contacts.
example:
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
1161Model:
type: object
properties:
code:
type: number
message:
type: string
example:
code: 1161
message: Invalid API key
1001Model:
type: object
properties:
code:
type: number
message:
type: string
example:
code: 1001
message: Name of the contact is too long.
1532Model:
type: object
properties:
code:
type: number
message:
type: string
example:
code: 1532
message: Business id is missing or invalid.
1021Model:
type: object
properties:
code:
type: number
message:
type: string
example:
code: 1021
message: Invalid Phone Number.
Apiary_getContact_Response200:
type: object
properties:
id:
type: string
description: Id of enterprise customer.
firstName:
type: string
description: First name of the customer.
lastName:
type: string
description: Last name of the customer.
email:
type: string
description: Email of customer, optional (if phone is provided).
phone:
type: string
description: Phone of customer optional (if email is provided).
countryCode:
type: string
description: Country code of the phone number. Default value=US, Other Possible values=AU,CA,MX,PR,VI
smsOptin:
type: boolean
description: SMS Opting flag.
mappings:
type: array
description: List of locations where customer is mapped. If requested by cid, only that location's mapping is returned.
items:
type: object
properties:
cid:
type: number
description: Customer location id.
location:
type: string
description: Name of the location.
bid:
type: number
description: Location id.
businessNumber:
type: number
description: Location Number.
tags:
type: string
description: List of tags.
customFields:
type: array
description: List of Custom fields.
items:
type: object
properties:
fieldName:
type: string
description: Field name.
type:
type: string
description: Field type.
fieldValue:
type: string
description: Value of field.
externalId:
type: string
description: Unique external identifier of the contact which could be from the CRM or any external system storing your contacts.
experienceScore:
type: number
description: Experience score of the customer. Returned only when experienceScore is true in the request.
experienceScoreSource:
type: string
description: Source of the experience score (e.g. review, survey). Returned only when experienceScore is true in the request.
1086Model:
type: object
properties:
code:
type: number
message:
type: string
example:
code: 1086
message: Customer email id cannot be blank.
5008Model:
type: object
properties:
code:
type: number
message:
type: string
example:
code: 5008
message: RequestBody not found
1091Model:
type: object
properties:
code:
type: number
message:
type: string
example:
code: 1091
message: User id not authorized to view this customer.
21122Model:
type: object
properties:
code:
type: number
message:
type: string
example:
code: 21122
message: Reseller business is not supported in this request
20083Model:
type: object
properties:
code:
type: number
message:
type: string
example:
code: 20083
message: End date can't be before start date
Apiary_customerCheckin_Request:
type: object
properties:
name:
type: string
description: Name of the customer.
emailId:
type: string
description: Email ID of the customer (optional If business has enabled for sms, then either email or phone will be required).
phone:
type: string
description: Phone number of the customer (optional If business has enabled for sms, then either email or phone will be required).
smsEnabled:
type: number
description: Whether customer has opted to receive SMS request or not. Valid values are 0(false), 1(true). Default is 1.
additionalParams:
type: object
properties: {}
description: Custom tags can be added as key value pair.
employees:
type: array
items:
type: object
properties:
emailId:
type: string
description: Email Id of assisted Employee.
externalId:
type: string
description: Unique external identifier of the contact which could be from the CRM or any external system storing your contacts.
example:
name: Steve Smith
emailId: steves@abcd.com
phone: 408-xxx-xxxx
smsEnabled: 1
additionalParams:
Tag Group Name 1: Tag Name 1
Tag Group Name 2: Tag Name 2
location: New York
employees:
- emailId: sshikha@abcd.com
externalId: ABC123
89Model:
type
# --- truncated at 32 KB (35 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/birdeye/refs/heads/main/openapi/birdeye-contact-api-openapi.yml