Audience Targeting API

If you have a specific offering you want to present to the users that would be most interested in it, the Audience Targeting API has you covered!

Specifications

POST /{environment}/targeting/audiences/requests

Description

Request an audience for a promotion.

Parameters

Type Name Description Schema

Path

environment
required

The environment for which a request is made.

string

Body

body
required

Responses

HTTP Code Description Schema

200

Audience targeting request was successful.

400

Audience targeting request is malformed or contains invalid values.

401

Not authorized to make an audience targeting request.

Consumes

  • application/json

Produces

  • application/json

Example HTTP request

Request body
{
  "audience" : {
    "audience_configuration_id" : "some_configuration_id",
    "audience_id" : "dhoghesjwgotuy39",
    "audience_name" : "Don't miss this!",
    "audience_size" : 100,
    "integration_type" : "push_notification_app",
    "limit" : 3,
    "promotion" : [ {
      "id" : "item_1",
      "item_type" : "article"
    }, {
      "id" : "item_2",
      "item_type" : "article"
    } ]
  }
}

Example HTTP response

Response 200
{
  "audience" : {
    "audience_configuration_id" : "some_configuration_id",
    "audience_id" : "dhoghesjwgotuy39",
    "audience_name" : "Don't miss this!",
    "audience_size" : 100,
    "integration_type" : "push_notification_app",
    "limit" : 3,
    "users" : [ {
      "id" : "user_1",
      "user_type" : "login"
    }, {
      "id" : "user_2",
      "user_type" : "login"
    }, {
      "id" : "user_3",
      "user_type" : "login"
    } ]
  }
}

cURL Example

$ curl --location --request POST 'https://{subdomain}.froomle.com/api/{environment}/targeting/audiences/requests' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer X' \
--data-raw '{
  "audience" : {
    "audience_configuration_id" : "some_configuration_id",
    "audience_id" : "dhoghesjwgotuy39",
    "audience_name" : "Don't miss this!",
    "audience_size" : 100,
    "integration_type" : "push_notification_app",
    "limit" : 3,
    "promotion" : [ {
      "id" : "item_1",
      "item_type" : "article"
    }, {
      "id" : "item_2",
      "item_type" : "article"
    } ]
  }
}'

GET /{environment}/targeting/audiences

Description

Returns an audience previously requested through the /targeting/audiences/requests endpoint. Can be used to paginate through large result sets. Note that audiences are only stored for a limited amount of time.

Parameters

Type Name Description Schema

Path

environment
required

The environment for which a request is made.

string

Query

audience_id
required

Unique identifier of the request.

string

Query

limit
required

The number of users to fetch.

integer

Query

offset
required

The rank of the first user to be requested. Starts counting at 1.

integer

Responses

HTTP Code Description Schema

200

Audience was found and returned successfully.

400

Request is malformed or contains invalid values.

401

Not authorized to make an audience targeting request.

Produces

  • application/json

Example HTTP response

Response 200
{
  "audience" : {
    "audience_id" : "dhoghesjwgotuy39",
    "users" : [ {
      "id" : "user_1",
      "user_type" : "login"
    }, {
      "id" : "user_2",
      "user_type" : "login"
    }, {
      "id" : "user_3",
      "user_type" : "login"
    } ]
  }
}

cURL Example

$ curl --location --request GET 'https://{subdomain}.froomle.com/api/{environment}/targeting/audiences?offset=1&limit=10&audience_id={audience_id}' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer X'

Definitions

User

A User object.

Name Description Schema

id
required

Unique identifier of the user.

string

user_type
required

Type of user identifier. Currently one of user_id or device_id.

string


Item

An Item object.

Name Description Schema

id
required

Unique identifier of the item.

string

item_type
required

The type of the item.

string


Promotion

A collection of items we wish to promote to an audience.

Type : < Item > array


ErrorBody

Error message.

Name Description Schema

detail
optional

Detailed description of the error.

string

status
optional

Status-code for the error.

integer

title
optional

Name of the error.

string

type
optional

Type of the exception thrown.

string


AudienceTargetingRequest

Request an audience for a promotion.

Name Description Schema

audience
required

Audience object in request.

audience

Name Description Schema

audience_configuration_id
required

Configuration ID to pose constraints upon audience.

string

audience_id
required

A unique identifier for the audience request which is to be supplied with each logged event.

string

audience_name
required

Name of the audience, to be passed in tracking events later.

string

audience_size
required

Total size of the audience requested. Use limit for pagination.

integer

integration_type
required

Name of the type of integration.

string

limit
optional

Number of Users to be returned

integer

partition_audience_by_item
optional

If true, each user in the response is assigned to a particular item in the promotion.
Default : false

boolean

promotion
required


AudienceTargetingResponse

Response containing an audience for a promotion.

Name Description Schema

audience
required

Audience object in response.

audience

Name Description Schema

audience_id
required

A unique identifier for the audience request which is to be supplied with each logged event.

string

audience_name
required

Name of the audience, to be passed in tracking events later.

string

audience_size
required

Total size of the audience requested. Use limit for pagination.

integer

integration_type
required

Name of the type of integration.

string

limit
required

Number of Users to be returned

integer

users
required

List containing User-objects.

< User > array

AudiencesResponse

Response containing an audience for a promotion.

Name Description Schema

audience
required

Audience object in response.

audience

Name Description Schema

audience_id
required

A unique identifier for the audience request which is to be supplied with each logged event.

string

users
required

List containing User-objects.

< User > array

Security

jwt

Type : apiKey
Name : Authorization
In : HEADER