The information contained in this document is confidential, privileged, and only for the use of internal Birdeye users. This document may not be used, published or redistributed.
This integration is supported for both SMB & Enterprise businesses.
NOTE: If there is an enterprise business to be set up and there are unique sign-in required for every location, such integration should be set up as an SMB i.e an integration group should be created for every location.
Integrating Birdeye with Square
User Manual - SUPPORT ARTICLE
Square is a credit card payment processing service used mainly by small and mid-sized businesses. Square accepts both credit and debit card payments and also offers chargeback protection, fraud detection, and account takeover protection. Square users are able to manage payments, invoices, sales, etc., with Square. Integrating Birdeye with Square will automate the process of review request solicitation for Birdeye clients using Square.
Important Instructions - The Square integration does not work for merchants only using Square to process a credit card. For example, if they only have a square reader that plugs into their phone, we can't send a review request if there is no email ID or phone number stored in a credit card. The merchant needs to use square POS and store the customer information in their dashboard or customer directory.
Table of Contents
Triggers Supported
Square Location ID
Login
Manage Triggers
Manage Properties
Manage Locations
Integration Requirements
Triggers supported
Birdeye allows you to fetch data from your CRM using some predefined triggers. As part of the integration process, you will need to ask the business for its preference. After the integration is complete, requests will be sent out based on the configured trigger. Here is the supported trigger for Square:
Trigger Display Name | Trigger Name/Value | Trigger Description |
Square Transactions Trigger | Transaction | This trigger is used to fetch customer data based on transactions |
Square Location ID from the business.
In order to support the integration, you would require the Square location ID from the business.
Here are the instructions to fetch the location ID from the CRM:
Step 1: On the login page, enter your Square email address and password, and click on the ‘Sign In’ button.
Step 2: On the home page, click on the ‘Transactions’ tab.
Step 3: On the next screen, click on the ‘Export’ button on the top right corner, and from the options in the drop-down menu, select ‘Transactions CSV.’
Step 4: Now open the downloaded Transactions CSV file. As highlighted below, check for the location name (as applicable). See the URL under the 'Details' column; the last part of this URL is the location ID that is required for integration. (here- C57TGNCMWJ9WA)
Information from Birdeye Dashboard
For single location SMB account - Business Id
Login to your Birdeye account, go to Left Navigation Rail and click on ‘Settings’. Once the new page appears, click on ‘Integrations’ and select ‘API.’
You will find the ‘Business ID’ and ‘API key’ shown in the image.
For multi-location account - Enterprise ID and Business IDs of all locations
Enterprise ID
Business IDs of all locations
Login to your Birdeye account, go to Left Navigation Rail and click on ‘Settings’. Once the new page appears, click on ‘Profile’ and select ‘Business Profiles.’
To view Location ID, hover over the ‘Status’ of location.
Integration Process
Before you can integrate Square with Birdeye, you will need to set up the following configurations on the integration support dashboard:
To set up native integration, we have an integration support dashboard, where we need to set up the integration and then follow these steps to complete the configuration.
Login
After successful login in the integration dashboard, you have to click on ‘BE integration’ and then click on ‘Add Integration’.
Search for the CRM in the search bar and select it. Click on ‘Next’.
Manage Triggers
The trigger is automatically selected as only one trigger is supported.
Note: To fetch information for all the triggers available using curl commands, use this command. To replace triggers, use this curl command.
Manage Properties
Here; you can manage group-level properties, which will be applied to all locations under a CRM.
Customer fetch delay: It is used if businesses want to send review requests with a delay (number of days).
Fetch Refunds: Enter the fetch refunds value as true or false. If the client wants the customers in regards to refund transactions to be checked in and sent to review requests, select the property value as ‘true.’
Note: This step will create a group for our integration. Alternatively, you can do it via curl commands.
For SMB accounts, you can access the curl command.
For Enterprise accounts, you can access the curl command.
Manage Locations
For Single Location/Multi-Location Accounts, select the location from the drop-down menu and click on ‘Add.’
(In the case of Single Location accounts, it will give you only one option).
A drawer will appear on the right-hand side.
The Status, Frequency, and Next Runtime will be set by default. You can make the changes if required.
Status: It shows the status of Integration (Active or Inactive).
Frequency: It is the number of times integration will sync with CRM (Days or Hours).
Next RunTime: It is the next scheduled time when the integrations will run.
Location ID: Enter the Location ID provided by the customer (Click here)
Customer fetch delay: It is used if businesses want to send review requests with a delay (number of days).
Customer Group: Enter the names of customers to whom you want to send review requests.
Override Group Properties: With this, you can override the properties added at the group level, specific to each location.
NOTE:
For SMB: You can use ‘manage the locations’ using this curl command.
For Enterprise: You can use ‘manage the locations’ using this curl command.
Completing the Integration Process
After the initial integration is set up by the Birdeye technical support team, you need to log in to your Birdeye account to complete the rest of the integration process.
To complete the process, click on the ‘Settings’ tab located on the left navigation rail of your Birdeye dashboard. Click on the ‘Business Profile’ under the ‘Profile’ section.
Click on the specific location for which you have set up the integration.
Once you click on the particular location, it will redirect you to that location. Now, scroll down to the ‘CRM Integrations’, and click on the ‘Authorize’ button to authorize the business.
You will be asked to log in using your Square credentials. Enter your email and password and click on the ‘Sign In’ button.
The application will then ask you to grant permission. Click on the ‘Allow’ button to agree and proceed.
Once you are redirected, you will see Square as ‘Authorized’ under the CRM integration header.
Curl Commands
Before you can integrate Square with Birdeye, you will need to set up the following configurations:
A business integration group is a configuration that supports the business hierarchy of individual businesses on the Birdeye platform. The properties that are common for all business integrations are entered at the group level. Setting up a business integration group allows you to associate multiple business locations with the Enterprise account. Below is the list of curl commands that you will need to run to set this up.
Create Integration Group (Curl Command)
Copy this Curl Command
curl-X PUT https://common-services.Birdeye.com/integration/add/businessintegrationgroup -H 'content-type: application/json' -d '{ "parentBusinessNumber": 151909936703799,"integrationSourceId": 30, "integrationGroupProperties": [{"propertyKey": "fetch.refunds","propertyValue": "true"}],"integrationGroupTriggers":[{"triggerId":53, "triggerTypeId":1}]}'151909936703799:Business ID - This is the business ID for the location for both single-location and multi-location accounts.
True: Fetch refunds - If the client wants the customers in regards to refund transactions to be checked in and send to review requests, select property value as ‘true.’
53:Integration Trigger ID - Can be one or more triggers. Ask clients what trigger they would like to integrate with, then run the curl command to fetch all possible triggers for Square. Identify the trigger ID(s) and insert (use commas) in case of multiple trigger IDs.
NOTE: We will get the group ID once we run the first curl (Integration Group) and make a note of the group ID as that will require while we will be doing the integration mapping.
Fetch information for all the triggers available for Square (Curl Command)
Copy this Curl Command
curl -X GET https://common-services.Birdeye.com/integration/trigger/integrationtriggers/sourceid/30 -H 'cache-control: no-cache' -H 'content-type: application/json'
Sample Response: A sample response like this would appear after you run the curl command. The response will have the trigger name, description and ID. This trigger ID will be utilized while creating the integration group. Integration can have one or more triggers. To use more than one trigger, enter comma-separated values while creating the integration group.
[
{
"id": 53,
"integrationSourceId": 30,
"triggerService": "SquareTransactionsTriggerService",
"displayName": "Square Transactions Trigger",
"description": "This trigger is used to fetch customer data based on transactions.",
"active": true,
"integrationSourceName": "Square",
"integrationTriggerType": [
{
"id": 1,
"name": "JOB"
}
],
"actionGroupId": 1
}
]30: Trigger ID
Find business integration group details (Curl Command)
Copy this Curl Command
curl -X GET https://common-services.Birdeye.com/integration/businessintegrationgroup/151909943203488 -H 'Cache-Control: no-cache'
151909943203488: Business ID: Enter the Business ID here to get the integration group details for a business.
Response:
[
{
"groupId": 344,
"integrationSourceType": {
"id": 30,
"integrationSource": "Square",
"sourceCategory": "POS",
"oauthEnabled": true
},
"integrationGroupTriggers": [
{
"triggerId": 53,
"triggerTypeId": 1,
"actionIds": [
1
]
}
]
}
]344:Group ID: A group ID will be returned in the sample response with the details of the existing triggers for a business.
Update Triggers Information (use only if a business wants to change) (Curl Command)
Copy this Curl Command
curl -X POST 'https://common-services.Birdeye.com/integration/update/businessintegrationgroup?replaceTriggers=true' -H 'cache-control: no-cache' -H 'content-type: application/json' -d '{ "groupId": 344,"integrationGroupTriggers":[{"triggerId":53,"triggerTypeId":1}]}'
replaceTriggers=true: To replace existing trigger(s), enter the value for replaceTriggers as true. To add a new trigger(s) to the existing list, the value for replaceTriggers should be false.
344:The Group ID that was returned in the previous step will be entered here
53: Enter the Trigger ID(s) that need to be added or updated
Integration Mapping
This configuration is developed to create the actual business integration mapping. Each business integration mapping corresponds to the individual business location.
Copy this Curl Command
curl -X PUThttps://common-services.Birdeye.com/integration/add/businessintegrationmapping -H 'content-type: application/json' -d '{ "businessNumber": 151909943203488,"integrationGroupId": 344, "active": true, "integrationProperties": [{"propertyKey": "location_id","propertyValue": "2TDY2SGY9E7Z1"}]}'151909943203488:Business ID: Enter the business ID here.
344:Group ID: Enter the Group ID that was returned when the Integration group was created.
2TDY2SGY9E7Z1: Location ID: This is the location ID that was obtained from the business from their Square dashboard
Restriction Reason
Restriction reason is used to identify the contacts who have been opted-out(restricted) from sending a review request. This reason can be fetched from Kibana for contacts that are checked in already.
Possible restriction reasons for Square are:
Fetching refunds data is not configured
Integration is beta
Description
The customer is associated with refund transactions, and this business is not configured to use refund data.
Migration API
curl --location --request PUT 'https://common-services.Birdeye.com/commonservices/square/migrate?businessNumber=151980725935863'
151980725935863: business number - Location Business Number for which migration is needed.