Meiro Audience API

The API endpoint is developed to check if a customer entity belongs to a defined segment in Meiro Business Explorer.

API returns 200 responses along with predefined attributes when the customer entity belongs to a defined segment. Attributes of the customer entity are not returned by default.

Customers' attributes to be returned by the successful API call must be defined in the configuration of the WBS container (for safety reasons). Any customer entity attribute might be returned.

Warning: contact the Meiro team/ administrator to set the attributes.

Custom Queries

Meiro Audience API also offers the capability to run custom SQL queries and return their results for both known and unknown customers.

The queries to be run by the successful API call must be defined in the configuration of the WBS container (for safety reasons).

Parameters to these queries are provided via optional URL query parameters - only queries for which all required parameters are provided are executed.

Warning: contact the Meiro team/ administrator to define the custom queries.

Segment IDs

Meiro Audience API allows checking whether a customer belongs to a segment against all available segments, with the possibility to filter the segments by tags.

The number of segments to check against is limited to 10 by default for performance reasons but it might be overridden in the configuration of the WBS container.

Tag names are provided to the segment IDs API endpoint via an optional URL query parameter.

Warning: contact the Meiro team/ administrator to change the number of segments to check against.

1. Authentication

Authentication is not required.

2. Request

GET:https://cdp.{{CLIENT_INSTANCE_NAME}}.meiro.io/wbs?attribute=&value={&segment,parameter_1,parameter_2,...}

2.1 Parameters

Parameter

Data type

Description

attribute (required)

text

ID of the attribute used for profile stitching,

example:

`ps_meiro_user_id`	Meiro user ID
`ps_email_address`	Email address
etc	depends on client's use case

value (required)

text

Value of defined profile stitching attribute, example:

`29f3aec1-1111-4294-b940-019698f4ac25`	Meiro user ID tracked from client website where Meiro SDK is deployed
`john@doe.com`	email address example

segment (optional)

integer

The ID of the segment in Meiro Business Explorer segment builder where the presence of the customer entity should be checked. If the segment parameter is missing, any defined custom queries are executed and their results are returned in the response.

Custom queries’ parameters (optional)

text

Input parameters and their values to be used in the custom queries. Maximum 10 input parameters are allowed with a maximum length of 128 characters for the input parameter value.

3. Valid request example

GET:https://cdp.CLIENT_INSTANCE_NAME.meiro.io/wbs?attribute=ps_meiro_user_id&value=29f3aec1-1111-4294-b940-019698f4ac25&segment=42

3.1 Response examples

200

Customer entity belongs to a defined segment:


json
{
 "status": "ok",
 "client_ip": "178.40.210.109",
 "returned_attributes": {
   "customer_entity_id": "0000000071e3908f5aaaf022aa842b45",
   "modified": "2000-01-01 00:00:00",
   "attribute_first_name": ["John"],
   "attribute_last_name": ["Doe"],
   "attribute_total_order_value": null
 }
}

customer_entity_id (default)

Internal ID of customer entity.

modified (default)

Timestamp of last update of customer entity's attributes.

Returned attributes

attribute_first_name,

attribute_last_name,

attribute_total_order_value must be defined specifically for the client's use case in the configuration of `WBS` container.

404 (Customer not in the segment)

The customer entity defined in the API call is known in the Meiro database but does not belong to the defined segment ID.


json
{
 "status": "error",
 "client_ip": "178.40.210.109",
 "message": "customer not in segment"
}

404 (Customer not found)

There is no customer entity with a defined value of profile stitching attribute in the Meiro database.


json
{
 "status": "error",
 "client_ip": "178.40.210.109",
 "message": "customer not found"
}

50x (Internal server error)

Internal server error. Contact administrator.

customer_entity_id (default)

Internal ID of customer entity.

modified (default)

Timestamp of last update of customer entity's attributes.

Returned attributes

attribute_first_name,

attribute_last_name,

attribute_total_order_value must be defined specifically for the client's use case in the configuration of `WBS` container.

4. Valid request example - Custom Queries

4.1 Valid request example

GET: https://cdp.CLIENT_INSTANCE_NAME.meiro.io/wbs?attribute=ps_meiro_user_id&value=29f3aec1-1111-4294-b940-019698f4ac25&product_id=1234

4.2 Response examples

200

Customer entity was found and custom queries were executed:


json
{
 "status": "ok",
 "client_ip": "178.40.210.109",
 "returned_attributes": {
   "customer_entity_id": "0000000071e3908f5aaaf022aa842b45",
   "modified": "2000-01-01 00:00:00",
   "attribute_first_name": ["John"],
   "attribute_last_name": ["Doe"],
   "attribute_total_order_value": null
 },
"data": {
"found": {
	  "product": [{"sku": "5678"}]
},
  "not_found": null,
  "always": {
	  "next_best_offer": [{"sku": "9012"}]
	}
    }
}

customer_entity_id (default) Internal ID of customer entity.

modified (default)

Timestamp of last update of customer entity's attributes.

returned attributes

attribute_first_name

attribute_last_name

attribute_total_order_value must be defined specifically for the client's use case in the configuration of `WBS` container.

custom queries data

customer_entity_id (default)	Internal ID of customer entity.
modified (default)	Timestamp of last update of customer entity's attributes.
Returned attributes	`attribute_first_name,` `attribute_last_name,` `attribute_total_order_value` must be defined specifically for the client's use case in the configuration of `WBS` container.
Custom queries data	`found` - contains results of queries defined for a known customer `not_found`- contains results of queries defined for an unknown customer `always` - contains results of queries for any customer (known or unknown)

200

Customer entity was found but no custom queries were available to be executed:


json
{
 "status": "ok",
 "client_ip": "178.40.210.109",
 "returned_attributes": {
   "customer_entity_id": "0000000071e3908f5aaaf022aa842b45",
   "modified": "2000-01-01 00:00:00",
   "attribute_first_name": ["John"],
   "attribute_last_name": ["Doe"],
   "attribute_total_order_value": null
 },
"data": {
	"found": {},
  "not_found": null,
  "always": {}
}
}

customer_entity_id (default)	Internal ID of customer entity.
modified (default)	Timestamp of last update of customer entity's attributes.
Returned attributes	`attribute_first_name,` `attribute_last_name,` `attribute_total_order_value` must be defined specifically for the client's use case in the configuration of `WBS` container.
Custom queries data	`found` - contains results of queries defined for a known customer `not_found`- contains results of queries defined for an unknown customer `always`- contains results of queries for any customer (known or unknown)

200

There is no customer entity with a defined value of profile stitching attribute in the Meiro database but custom queries were available to be executed:


json
{
 "status": "ok",
 "client_ip": "178.40.210.109",
 "returned_attributes": {},
 "data": {
"found": null,
  "not_found": {
	  "product": [{"sku": "5678"}]
	},
  "always": {
	  "next_best_offer": [{"sku": "9012"}]
	}
 }
}

Custom queries data

found - contains results of queries defined for a known customer

not_found- contains results of queries defined for an unknown customer

always - contains results of queries for any customer (known or unknown)

404 (custom queries not defined)

There is no customer entity with a defined value of profile stitching attribute in the Meiro database and no custom queries were available to be executed.

json
{
  "status": "error",
  "client_ip": "178.40.210.109",
  "message": "Custom queries not defined"
}

50x (internal server error)

Internal server error. Contact administrator.

5. Request - Customer Segment IDs

GET: https://cdp.{{CLIENT_INSTANCE_NAME}}.meiro.io/wbs/segments?attribute=&value={&tags,tags,...}

5.1. Parameters

Parameter

Data type

Description

attribute (required)

text

ID of the attribute used for profile stitching,

example:

`ps_meiro_user_id`	Meiro user ID
`ps_email_address`	Email address
etc	depends on client's use case

value (required)

text

Value of defined profile stitching attribute,

example:

`29f3aec1-1111-4294-b940-019698f4ac25`	Meiro user ID tracked from client website where Meiro SDK is deployed
`john@doe.com`	email address example

tags (optional)

text

List of tags to be used for filtering segments to check the customer against.

Valid request example - No tags provided

GET: https://cdp.CLIENT_INSTANCE_NAME.meiro.io/wbs/segments?attribute=ps_meiro_user_id&value=29f3aec1-1111-4294-b940-019698f4ac25

Response examples

200

Customer entity belongs to the segments with the following IDs:

json
{
 "status": "ok",
 "client_ip": "178.40.210.109",
 "segment_ids": [15, 12, 14, 13, 11, 10, 6, 5]
}

segment_ids (default)

A list of segment IDs the customer belongs to.

404 (No segments found for the customer)

The customer entity defined in the API call is known in the Meiro database but does not belong to any available segments.

json
{
 "status": "error",
 "client_ip": "178.40.210.109",
 "message": "segments not found"
}

404 (Customer not found)

There is no customer entity with a defined value of profile stitching attribute in the Meiro database.

50x (Internal server error)

Internal server error. Contact administrator.

Valid request example - Tags provided

GET: https://cdp.CLIENT_INSTANCE_NAME.meiro.io/wbs/segments?attribute=ps_meiro_user_id&value=29f3aec1-1111-4294-b940-019698f4ac25&tags=Drama&tags=Sport

Response examples

200

Customer entity belongs to the segments with tags “Drama” or “Sport” with the following IDs:

json
{
 "status": "ok",
 "client_ip": "178.40.210.109",
 "segment_ids": [15, 12, 14, 13, 11, 10]
}

segment_ids (default)

A list of segment IDs with tags Drama or Sport the customer belongs to.