API consumers v4 — with sales

Article author
Bunker DB Support
  • Updated

Contents

 

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.

 

 

Step by step – how to create an API token

  1. Click on the "CAMPAIGNS" tab.
  2. Select a campaign and then click on "Edit campaign."

    image-1.png

  3. Select the "API" tab.
  4. Click on "CREATE API TOKEN."

    Only Superuser roles or users with the "API tokens manager" permission can access the "API Tokens" module.



  5. The platform will request you to insert your Bunker DB analytics account password to access Sudo mode.

    image-2.png

    image-3.jpeg
  6. Enter a description for the token created.

    image-4.png

Once your token has been created, you will see it only once on the right side of the platform. Make sure to copy it and paste it so it can be safe for you to use it.

 

Safe and correct usage of tokens is the user´s full responsibility. Bunker DB analytics won't assume any responsibility whatsoever for any damages caused by incorrect usage or handling of access credentials or tokens.

image-5.jpeg

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

image-6.png

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.

image-7.png

 

Consumers

 

POST: /api/v4/consumers

image-8.png

This method receives the same JSON as versions 2 and 3 of the API, excepting the campaign id, which is no longer necessary thanks to the token.

image-9.png

 

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:

  • BunkerID
  • 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": "example@bunkerdb.com(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": "example@bunkerdb.com(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": "Mateo",

                        "Last Name": "Menestrina",

                        "Email": "example@bunkerdb.com(opens in new tab)",

                        "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": "example@bunkerdb.com(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

image-10.png

This method returns all fields —fixed or custom— that can be attributed to consumers.

image-11.png

 

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:

image-12.png

  • 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?

 

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.

image-13.png

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.

image-14.png

 

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

image-15.png

This way, the data entered for a consumer can be verified.

image-16.png

 

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

https://sandbox.bunkerdb.com/api/v4/preferences

https://sandbox.bunkerdb.com/api/v4/consumers

https://sandbox.bunkerdb.com/api/v4/sales

 

API token format example:

“120d03c9b55600f2cba445ca2d021364dba504d5”

 


 

 

Test integration within the production environment

To test the API integration, you must use the testapi@bunkerdb.com 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

testapi@bunkerdb.com address. In case you need help, please contact support@bunkerdb.com.

 

 

Step by step - how to test the API integration

  1. Create an API token to integrate the form within Bunker DB analytics.
  2. Insert a "test user" with the address: testapi@bunkerdb.com.
    All other fields can be random.

    Only Superuser roles or users with the "API tokens manager" permission can access the "API Tokens" module.

  3. If registration is successful, the testing information should be seen in the campaign edition, under the "API" tab and "Test records" section.

    image-17.jpeg

  • Data created with testapi@bunkerdb.com address will be saved within the installation for one week only.
  1. You can also flush all tests manually with the "Flush all" button.

    image-18.jpeg

 

 

 

Was this article helpful?

Have more questions? Submit a request