Using the Audience API

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

View in Apiary

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

View in Apiary

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.

Audience API via the Mapp Server

URI Syntax – Version 2 (recommended)

Using the Ever-ID

Using the Customer-ID

Example: Version 2 with Customer-ID

URI Syntax – Version 1

Using the Ever-ID

Using the Customer-ID

Query Parameters

Audience API with your own Tracking Domain

URI Syntax

URI Syntax – Version 2 (recommended)

Using the Ever-ID

Using the Customer-ID

Example: Version 2 with Customer-ID

URI Syntax – Version 1

Using the Ever-ID

Using the Customer-ID

Query Parameters

GET Segment Information

Using the API via the Mapp server

Using the API with your own tracking domain

Headers

Response Syntax

Example Response

Possible Error Codes

Mapping Table for URM Status

Current Customer Journey Status ("MicroCustomerJourneyStatus")

Customer Journey Status ("MacroCustomerJourneyStatus")

Gender

E-Mail Opt-In

Cookie Notice