Making your first call

This page walks you through a complete API call example, step by step. By the end, you'll have tracked a consent change from the backend using the Add consent endpoint.

Example definition

Goal

Track a consent change by a client from the backend. The client no longer wishes to receive SMS notifications and withdraws the respective consent.

Prerequisites

• You have already defined a consent category for SMS marketing within the Bloomreach Engagement app Consent Management.
• You are using registered as an ID to recognize the client.

Example guide

Overview

Making a call consists of several steps.

• Create a relevant API group and set up permissions.
• Create the method’s URL. Once that is done, you must build the authorization header and the API call body.

1: Create a new API group and set up permissions

To work with consents, you must set up a new group with a private access type. Follow the steps outlined in the Prerequisites section. It is advised that you name the group with your use case in mind, for example, "Consent change". After creating the group, don't forget to save the Secret key at a secure location, as you can only view it once.

Now, configure the permissions needed for working with consents. In the Events tab, tick both Get and Set. These should be all the permissions that you need for this use case. Following the access minimization principle, you should not grant more permissions than needed for the use case for which you are using the API Group.

2: Put together a URL for the API call

To build the URL for the API call, you will need 3 things: the URL of the HTTP method (Add consent in this case), your base URL, and your project token.

First, navigate to our online API Reference and find the particular method. In this example, that would be Add consent, which is just a specific case of the Add event. At the top of the screen, you can find the URL that you need.

As you can see in the screenshot, for the Add event, the URL is:

[base URL]/track/v2/projects/[projectToken]/customers/events

Notice that it has two parameters that you need to fill in: the base URL at the start and the project token in the middle. Find both of these and copy from Project Settings > Access management > API. This is the same place where you have created your API group.

Now you have all the necessary components to build the API call URL. Exchange the parameters in the method’s URL for the respective values (base URL and project token). The final URL for changing the customer’s consent looks like this:

https://myinstance.exponea.com/track/v2/projects/12345678-abcd-1a2b-3c4d-123456789abc/customers/events

3: Create an authorization header

Once you have the call URL, build the call’s header and body. Because you are using the private access type, create a header using the Basic authentication that encodes the API Key ID / API Secret pair that Bloomreach has generated after creating the API group.

Follow the steps outlined in the Authorization header section. The encoding process varies by programming environment. Here's an example in PHP:

$auth_header = "Basic " . base64_encode($keyID . ":" . $secret)

4: Build the body of the API call

Go back to the API reference and review the Add event request parameters and payload example. Use the documentation to construct your request body and fill in the required values. For the event to be recognized as a consent event, include the consent-specific fields described in the Consent management section.

Example of an Add consent body

{
	"customer_ids": { "registered": [customer_identificator] },
	"event_type": "consent",
	"timestamp": [time_of_the_consent_change],
	"properties": {
    	 	"action": "reject",
    	 	"category": "sms_marketing"
	}
}

5: Send the API call

You've configured permissions and prepared the URL, header, and body. Now combine these into the final request and send the call. In production code, handle response codes and errors accordingly.

PHP example

<?php
require_once 'HTTP/Request2.php';
$request = new HTTP_Request2();
$request->setUrl('https://myinstance.exponea.com/track/v2/projects/12345678-abcd-1a2b-3c4d-123456789abc/customers/events');
$request->setMethod(HTTP_Request2::METHOD_POST);
$request->setHeader(array(
  'content-type' => 'application/json',
  'Authorization' => 'Basic MDEyMzQ1Njc4OWFiY2RlZmdoaWprbG1ub3BxcnN0dXZ3eHl6MDEyMzQ1Njc4OWFiY2RlZmdoaWprbG1ub3BxcjphYmNkZWZnaGlqa2xtbm9wcXJzdHV2d3h5ejAxMjM0NTY3ODlhYmNkZWZnaGlqa2xtbm9wcXJzdHV2d3h5ejAx'
));
$request->setBody('{"customer_ids": { "registered": "[email protected]" },	"event_type": "consent", "timestamp": 1620139769, "properties": {"action": "reject", "category": "sms_marketing"}}');
try {
  $response = $request->send();
  // Todo: handle response (success and error)
}
catch(HTTP_Request2_Exception $e) {
  // Todo: handle exception
}