--- title: "Using the Audience API" slug: "using-the-audience-api" updated: 2024-03-20T10:56:18Z published: 2024-03-20T10:56:18Z canonical: "docs.mapp.com/using-the-audience-api" --- > ## Documentation Index > Fetch the complete documentation index at: https://docs.mapp.com/llms.txt > Use this file to discover all available pages before exploring further. # 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](https://webtrekkaudienceapi.docs.apiary.io/#reference/segments/segments-collection/get-a-segments-list) ### 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](/v1/docs/audience-rest-api-get-started). | | 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](/v1/docs/intelligent-tracking-prevention-itp-21) 2.x). > [!WARNING] > 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](https://webtrekkaudienceapi.docs.apiary.io/#reference/segments/segments-collection/get-a-segments-list) ### 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](/v1/docs/audience-rest-api-get-started). | | 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 ```json {    "user": ,    "segments": {         "" :         "" :    },      "categories": [       {         "id":         "title": ""         "value": ""       },       {          "id":        "title": ""        "value": ""       }   ] } ``` #### Example Response ```json {        "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": ""     }               ] } ``` > [!WARNING] > 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. | 1. Log in Mapp Q3. 2. Go to *"Configuration > System Configuration > Data Collection"*. 3. Your account ID is the one in the field Your **Track ID**.