Facebook Lead Ads fixed fields list
Custom fields
Verify consumers data
Sandbox
Test integration within production environment
The first step is to create a token to connect an app or form to a campaign to Bunker DB analytics and use our consumers API. Each token is unique and —for security reasons— is displayed one time only. The token has to be copied and used to connect your app, form, etc., to Bunker DB analytics locating it within your code.
Our latest API version (v4) offers the same integration functionalities as version 3 and only adds the possibility to include custom fields and a new sales endpoint.
Create an API token
Select “Edit campaign.”
You can also access the edition section of your campaign here:
Go to the “API” tab.
Click on “Create API token.” The system may ask you to re-enter your username and password to access the sudo mode.
Add a brief description.
Copy the token and share it with the developer responsible for the integration.
🦸🏽
To access these options in Bunker DB, you must have a Superuser role on the platform.
API connection
Authentication is performed by sending an Authorization header that contains the Bearer token generated in Bunker DB analytics. All API methods require authentication.
All third parties' responsibility is to make a secure connection, check the validity and authenticity of SSL certificates when connecting to Bunker DB analytics.
Example:
"Authorization: Bearer 0420036fa63cbde636703216a7ee235c7ba7ab96"
All Bunker DB analytics installations are under https protocol, so point-to-point traffic is encrypted.
How to use endpoints
The integration must be done server-to-server (server-side) in order to not expose the token, as it is sensitive information.
All API interactions are implemented in JSON format, where the header ContentType: Application/JSON must be present at all times.
Here you have the description of all available methods to test functionalities within the API endpoints integrations:
Preferences
GET/api/v4/preferences
This method returns —in JSON format— the preferences configured in the campaign, which will then be sent through the API when creating consumers. It would be best to create the Bunker DB analytics campaign's same preferences to be assigned to consumers as they are inserted into the database.
Consumers
POST: /api/v4/consumers
With this method, the API allows you to insert a consumer whose custom field and corresponding value can be included directly in the JSON. If the API response is 201, it means the insert was successful.
If nonexistent fields are used, the consumer is stored in Bunker DB analytics without the field information. The API returns a warning —unknown field— when a field is unknown.
Sales
POST: /api/v4/sales
The information required to register each sale is: on the one hand, the match_key data that refers to the search model and assignment to the corresponding pre-existing record.
On the other hand, we have the information about the sale itself:
event_time: (required) - day and time in YYYY-MM-DD HH:MM:SS format.
order_id: (string) - Order number to link with the external sales system.
external_sale_id: (string) - Sale identifier or ID with the external sales system.
value - Sale value.
currency - Currency used in the transaction; if not provided, Bunker DB will use the currency defined for the brand. It follows the international standard ISO 4217.
Sale example:
[
{
"match_key": {
"phone": "4692023332"
},
"event_time": "2019-07-13 12:34:21",
"order_id": "12332223421"
}
]
As shown, the match_key contains the search expression to resolve the possible record.
The available fields are:
id
document
email
phone
cellphone
The assignment is direct and can produce the following results:
created/updated: Sale created or updated correctly for registration.
not found: The record was not found according to the provided id, email, phone, cellphone, document - These fields refer to the attribution model implemented in Bunker DB analytics where they can return the same states as the previous case if the related record could be accurately detected. Or either return:
not unique: In this case, a unique record could not be identified, and the matches are included in the response so that the operator can select the one that best fits (re-registering the sale but in this case using the corresponding id).
Response states
To create, update, not_found, and not_unique, another state is called invalid, which applies only when the event_time date is malformed or could not be recognized.
The response maintains the same order as the input information, adding:
sale_id: Sale identifier only for created/updated states.
status: Refers to one of the previously mentioned states (created, updated, not found, not unique, invalid).
reason: Complementary information to the state, if required.
matches: Only for the "not unique" state, and this is where the list of records corresponding to the mapping by attribution is provided, and for which a single record could not be identified.
userdata_id: The matched record identifier is returned. Only for the states: created/updated.
Example response for not_unique
[
{
"match_key": {
"email": "[email protected](opens in new tab)"
},
"event_time": "2016-08-10 11:14:13",
"value": 2200,
"response": {
"status": "not unique",
"reason": "Can't resolve unique registry by attribution",
"matches": [
{
"BunkerID": "41369",
"CampaignRefID": null,
"First Name": "Mateo",
"Last Name": "Menestrina",
"Email": "[email protected](opens in new tab)",
"Record created at": "2015-12-03 00:00:00",
"Document": null,
"Document Type": null,
"Document Country": null,
"Phone": null,
"Cellphone": null,
"Gender": null,
"Birthday": null,
"Address": null,
"City": null,
"State": null,
"Country": null,
"Postal Code": null,
"Device": null
},
{
"BunkerID": "41370",
"CampaignRefID": null,
"First Name": "Jow",
"Last Name": "Doe",
"Email": "[email protected]",
"Record created at": "",
"Document": null,
"Document Type": null,
"Document Country": null,
"Phone": null,
"Cellphone": null,
"Gender": null,
"Birthday": null,
"Address": null,
"City": null,
"State": null,
"Country": null,
"Postal Code": null,
"Device": null
}
]
}
}
]
Example response for: created and updated.
[
{
"match_key": {
"id": "41367"
},
"event_time": "2019-07-13 12:34:21",
"order_id": "12332223421",
"response": {
"sale_id": 5,
"status": "created",
"userdata_id": "41367"
}
},
{
"match_key": {
"email": "[email protected](opens in new tab)"
},
"event_time": "2016-02-10 11:14:13",
"order_id": "3325-uy",
"response": {
"sale_id": 3,
"status": "updated",
"userdata_id": "41367"
}
}
]
Example response for not_found
[
{
"match_key": {
"id": "4136799999"
},
"event_time": "2019-07-13 12:34:21",
"order_id": "12332223421",
"response": {
"status": "not_found",
"reason": "Userdata not found",
"userdata_id": "4136799999"
}
}
]
Example response for invalid
[
{
"match_key": {
"id": "4136799999"
},
"event_time": "30-02-2020",
"value": 545.5,
"response": {
"status": "invalid",
"reason": "The parsed event_time was invalid",
"userdata_id": "4136799999"
}
}
]
Fields
GET: /api/v4/fields
This method returns all fields —fixed or custom— that can be attributed to consumers.
Fixed fields list
Within the API response, the fixed fields are identified as "false" in the "dynamicfield" field.
Properties marked with (*) must be present in all requests, all other properties are optional and should only be specified when the client has valid and significant values.
The body of the request is an object with the following properties:
platform_id: (string [3-254]). Platform identifier: "facebook_app", "web", "google".
external_id: (string [1-45]) Object external identifier. If it were used in a previous request to add an ActionPersonData object whose campaign_id property had the same value, the previous object would be removed to avoid two objects in the same campaign with the same external identifier.
obtained_time: (datetime) Date and time when the data of this person were obtained. Format must be defined in ISO 8601. The default value is the date and time when the server receives the request.
facebook_uid: (string [1 -50]) Facebook identifier.
email: (string [3 -254]) email.
twitter_uid: (string [1 -50]) Twitter identifier.
linkedin_uid: (string [1-50]) LinkedIn identifier.
google_uid: (string [1 -50]) Google identifier.
cellphone: (string [4 -50]) mobile phone number.
document: (string [5 -20]) Document number.
document_type: (string) Document type. By default, "DNI" will be assigned. It must be one of the following values:
Citizen: Credential.
DFI: Documento de identificación Federal.
DNI: Documento de identificación Nacional.
Driver: Driver’s license.
Militar: Military ID.
Passport: Passport.
Social: Social security number (SSN).
CPF: Cadastro de Pessoas Físicas.
document_country: (string [2]) Document issuing country. Format must be defined in ISO 3166-1 in a two-letter format. The list is shown in ISO 3166-1-alpha-2 format. Default assign will be: "UY".
phone: (string [4-50]) Phone number.
first_name: (string [1-100]) Name.
last_name: (string [1-100]) Last name.
gender: (char [1]) Gender.
"f" = female.
"m" = male.
birthday: (date) Date of birth.
Date format must be YYYY-MM-DD. Example: 1983-02-26.
Maximum range is 130 years.
address_country: (string [2]) Residence country. Format must be defined in ISO 3166-1 in a two-letter format.
address: (string [1-65535]) Physical address. You can use address_line_one and address_line_two instead. Keep in mind that address will have priority.
address_line_one: (string [1-65535]) Address the first line; note that this field will have priority if you use 'address.'
address_line_two: (string [1-65535]) Address the second line; note that this field will have priority if you use 'address.'
address_postal_code: (string [1-50]) Zipcode number.
address_state: (string [1-255]) State/department name.
address_city: (string [1-255]) City name.
allow_newsletters: (Boolean) Defines if a consumer agrees to receive the newsletter.
allow_sms: (boolean) Defines if a consumer agrees to receive SMS.
allow_brand: (boolean) Defines if a consumer agrees to receive the brand’s content.
allow_global: (boolean) Defines if a consumer agrees to receive another brand’s content from the same company.
device: (string [15]) Device type.
"desktop"
"tablet"
"phone"
preferences: Consumer assigned preferences in JSON format. These preferences must be equal to the campaign’s preferences.
utm_medium: (string [0-100]) Used for medium reference. Example: CPC, banner, email newsletter.
utm_source: (string [0-100]) Used for source reference. Example: Facebook.
utm_campaign: (string [0-100]) Used for unique campaign name reference. Example: slogan, promo coding, etc.
utm_term: (string [0-100]) Used for paid keyword reference within Google Search or as the ad set reference.
utm_content: (string [0-100]) Used for the ad reference.
Facebook Lead Ads fixed fields list
form_id: (string [0-255]) Required. Form identifier.
Lead_id: (string [0-255]) Required. Lead identifier.
Ad_id: (string [0-255]) Required. Ad identifier.
Ad_name: (string [0-255]) Ad name.
Adset_id: (string [0-255]) Required. Ad set identifier.
Adset_name: (string [0-255]) Ad set name.
Campaign_id: (string [0-255]) Required. Campaign identifier.
Campaign_name: (string [0-255]) Campaign name.
Created: (datetime) Lead creation date.
Platform: (string [0-255]) Ad placement: "Facebook", "Instagram".
Is_organic: (boolean) Organic leads identifier.
In case the Lead Ads are not connected through the Facebook connection with Bunker DB Analytics, these fields can be sent using the API V4.
Custom fields
The custom fields' purpose —“dynamicField” = true— stores data not covered in the API fixed fields.
A JSON will be displayed with the following attributes:
fieldName
displayName
description
type
size (for text type only)
options
Through this endpoint, the API will return the available custom fields previously created in Bunker DB analytics, and these can be:
Yes / No: they may have a value of type yes/no, or empty. Example: ¿Is red?
Numerical: can have a numerical value. Example: How many children do you have?
Text: can have any text value completed by the participating consumer in the promotion. Example: How do you like to spend your birthday?
Date: can enter a date (datetime format). Example: Registration date.
Multiple options: they will select a value from a list of options defined by the user admin or brand manager at the installation level. Example: What is your hair color?
Verify consumers data
GET/api/v4/consumers
With the same authentication data that was used to create a consumer, the data can be fetched using the "GET" method on URL:
https://sandbox.bunkerdb.com/api/v4/consumers/ConsumerID
This way, the data entered for a consumer can be verified.
Sandbox
Developers should deploy to production only after it has been thoroughly tested using the sandbox endpoint. It is important to note that the information entered in the sandbox is public and for testing purposes —all developers use the same sandbox environment— and it is deleted every 48 hours.
Endpoints
API token format example:
“120d03c9b55600f2cba445ca2d021364dba504d5”
Test integration within the production environment
To test the API integration, you must use the [email protected] address to create a form record. If the registration were completed successfully, it would be seen in the API test section within the "API TEST" tab in the campaign edition for a week.
Tests carried out within the production environment do not alter the database as long as they are carried out with
[email protected] address. In case you need help, please contact [email protected].
Step by step - how to test the API integration
Create an API token to integrate the form within Bunker DB analytics.
Insert a "test user" with the address: [email protected].
All other fields can be random.Only Superuser roles or users with the "API tokens manager" permission can access the "API Tokens" module.
If registration is successful, the testing information should be seen in the campaign edition, under the "API" tab and "Test records" section.
You can also flush all tests manually with the "Flush all" button.
Data created with [email protected] address will be saved in your account for one week only.