Consumers API v4

Article author
Bunker DB Support
  • Updated

 

The first step to connect an app or form to a campaign to Bunker DB analytics and use our consumers' API is to create a token. 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 "Campaign" tab.
  2. Select a campaign and then click on "Edit campaign."



  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.



  6. Enter a description for the token created.



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.





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.



It is all third-parties responsibility to make a secure connection, checking 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



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.

 

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. The 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. The maximum range is 130 years.
  • address_country: (string [2]) Residence country. The 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 the address will have priority.
  • address_line_one: (string [1-65535]) If you use address, this field will have priority.
  • address_line_two: (string [1-65535]) If you use address, this field will have priority.
  • 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.

 

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?

 

POST: /api/v4/consumers

With this method, the API allows you to insert a consumer in which its custom field and its 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.

 

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

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

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

 

API token format example:

"120d03c9b55600f2cba445ca2d021364dba504d5"

 


 

 

Test integration on 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 on 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.

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

  2. On the integrated form, insert a "test user" with the address: testapi@bunkerdb.com.
    All other fields can be random.
  3. If registration is successful, the testing information should be seen in the campaign edition, under the "API" tab and "Test records" section.



  • Data created with testapi@bunkerdb.com address will be saved within the installation for one week only.
  1. To delete all tests manually, use the "Flush all" button.

 

 

 

Was this article helpful?

Have more questions? Submit a request