- 4 Minutes to read
- Print
- DarkLight
Using the Audience API
- 4 Minutes to read
- Print
- DarkLight
This chapter describes how to place API calls to get the information you need. There are two ways to do this:
Use the Audience API via the Mapp Server
Use the Audience API with your own tracking domain
Audience API via the Mapp Server
Execute API calls to get all the segments a specified user belongs to. There are 2 versions of the API available. They only differ in the output of possible error messages: Version 2 supports additional information (see Error codes). Thus, it helps to better understand the type of error.
URI Syntax – Version 2 (recommended)
Using the Ever-ID
https://r.mateti.net/segments/v2/{trackId}/{placementId}?everId={everId}
Using the Customer-ID
https://r.mateti.net/segments/v2/{trackId}/{placementId}?customerId={customerId}
Example: Version 2 with Customer-ID
https://r.mateti.net/segments/v2/1234567891234/23232323/?customerId=04ee2ab263eeb5f0ca1139d7110f 93c8
URI Syntax – Version 1
Using the Ever-ID
https://r.mateti.net/segments/v1/{trackId}/{placementId}?everId={everId}
Using the Customer-ID
https://r.mateti.net/segments/v1/{trackId}/{placementId}?customerId={customerId}
Query Parameters
Parameter | Type | Description |
---|---|---|
trackId | String | Mandatory. The trackId of the Marketing Automation account. How to get the account ID |
placementId | Long | Mandatory. How to find the desired placement ID is described here. |
everId | String | Mandatory. This ID is used to identify the user for whom you want to retrieve information. Alternatively, you can use the customer ID. The everId is the Mapp Intelligence device ever ID. Depending on your tracking setup you can get this ID from the first-party or third-party cookie. |
customerId | String | Mandatory. This ID is used to identify the user for whom you want to retrieve information. Alternatively, you can use the ever ID. The customer ID must contain the same value that you use for the customer ID in your tracking. |
Audience API with your own Tracking Domain
You can also use your own tracking domain or third-party cookies (due to ITP 2.x).
In this case a separate activation is required. Please contact your Mapp Intelligence consultant.
There are 2 versions of the API available. They only differ in the output of possible error messages: Version 2 supports additional information (see Error codes). Thus, it helps to better understand the type of error.
URI Syntax
{server}/segments/v1/{accountId}/{placementId}?customerId={customerId}
URI Syntax – Version 2 (recommended)
Using the Ever-ID
{server}/segments/v2/{trackId}/{placementId}?everId={everId}
Using the Customer-ID
{server}/segments/v2/{trackId}/{placementId}?customerId={customerId}
Example: Version 2 with Customer-ID
https://{{OWN_TRACKING_DOMAIN}}/segments/v2/1234567891234/23232323?customerId=04ee2ab263eeb5f0ca1139d7110f 93c8
URI Syntax – Version 1
Using the Ever-ID
{server}/segments/v1/{trackId}/{placementId}?everId={everId}
Using the Customer-ID
{server}/segments/v1/{trackId}/{placementId}?customerId={customerId}
Query Parameters
Parameter | Type | Description |
---|---|---|
trackId | String | Mandatory. The trackId of the Marketing Automation account. How to get the account ID |
placementId | Long | Mandatory. How to find the desired placement ID is described here. |
customerId | String | Mandatory. This ID is used to identify the user for whom you want to retrieve information. Alternatively, you can use the ever ID. The customer ID must contain the same value that you use for the customer ID in your tracking. |
GET Segment Information
Using the API via the Mapp server
GET https://r.mateti.net/segments/v2/1234567891234/23232323?customerId=04ee2ab263eeb5f0ca1139d7110f
Using the API with your own tracking domain
GET https:// {{OWN_TRACKING_DOMAIN}} /segments/v2/1234567891234/23232323?customerId=04ee2ab263eeb5f0ca1139d7110f
Headers
content-type: application/json
Response Syntax
{
"user": <everID>,
"segments": {
"<segment name>" : <true|false>
"<segment name>" : <true|false>
},
"categories": [
{
"id": <urm category id>
"title": "<urm category title>"
"value": "<urm category value>"
},
{
"id": <urm category id>
"title": "<urm category title>"
"value": "<urm category value>"
}
]
}
Example Response
{
"everId": "87235498273549765",
"segments": {
"men" : true,
"high frequency buyer" : false
},
"categories": [
{
"id": 1
"title": "URM Custom Profile Macro Status"
"value": "6"
},
{
"id": 2
"title": "URM RFM Status"
"value": "322"
},
{
"id": 3
"title": "URM Predicted conversion probability %"
"value": ""
}
]
}
Some of the URM values are returned as numerical values. You can find the corresponding meaning of the numbers below.
Possible Error Codes
Error Code | Message | Description |
---|---|---|
200 | OK | The response body includes all found segments and URM categories belonging to the user specified in the request. |
400 | Only Version 1: The placement could not be found. The placement ID could not be found. This means either that the placement ID does not exist or that it is not an Audience API placement. | |
400 | No segment data available yet | Only Version 2: It is a new Visitor or the Inkognito Mode is activated |
400 | No Cookie available | Only Version 2: Cookie Storage is blocked. In this case there is no Cookie data available. |
401 | The account ID could not be found. | |
403 | The Audience REST API is not activated for this account. | |
404 | The user could not be found. |
Mapping Table for URM Status
There are four mapping tables available for the URM status.
Current Customer Journey Status ("MicroCustomerJourneyStatus")
Numeric Value | Type | Description |
---|---|---|
0 | UNKNOWN | Unknown. |
1 | OFFSITE | The user had contact outside the website. |
2 | ONSITE | Default. The user had contact on the website. |
3 | PRODUCT_VIEW | The user had viewed a product. |
4 | ADD_TO_BASKET | The user has placed a product in the shopping cart but has not purchased it. |
5 | BUYER | The user has executed the order. |
Customer Journey Status ("MacroCustomerJourneyStatus")
Numeric Value | Type | Description |
---|---|---|
0 | UNKNOWN | Unknown. |
1 | OFFSITE | The user had contact outside the website. |
2 | ONSITE | Default. The user had contact on the website. |
3 | PRODUCT_VIEW | The user had viewed a product. |
4 | ADD_TO_BASKET | The user has placed a product in the shopping cart but has not purchased it. |
5 | REGISTRATION | The user has logged in. |
6 | BUYER | The user has placed an order (new customer). |
7 | REBUYER | The user has executed more than one order (repeat buyer). |
Gender
Numeric Value | Type | Description |
---|---|---|
0 | UNKNOWN | Default: Unknown. |
1 | MALE | Male. |
2 | FEMALE | Female. |
E-Mail Opt-In
Numeric Value | Type | Description |
---|---|---|
0 | UNKNOWN | Default: Unknown. |
1 | YES | Yes. |
2 | NO | No. |