> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mazeedplus.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Placements API
> Request personalized content and offers for your users
The Placements API returns personalized content and offers based on user context and behavior. Use this API to display targeted promotions, product recommendations, and custom offers at key moments in your user journey.
## Endpoint
```
POST https://api.mazeedplus.com/select-placement
```
## Authentication
Authenticate your requests by including your API key in the `x-publishable-api-key` header.
```
x-publishable-api-key: pk_live_51H7...
```
## Create a placement
Creates a personalized placement for display to your users.
### Parameters
Unique identifier for the placement (e.g., "home-page", "checkout\_success")
User and transaction data for personalization
Unique customer identifier from your system
Customer mobile phone number with country code (e.g., "+966501234567" for Saudi Arabia, "+971501234567" for UAE, "+201001234567" for Egypt)
Customer first name
Customer last name
Customer age in years
Customer gender ("male" or "female")
Array of customer interests and brand preferences (e.g., \["technology", "fitness", "brand:Nike", "brand:Apple"])
Two-letter country code (ISO 3166-1 alpha-2)
Two-letter language code (ISO 639-1)
Three-letter currency code (ISO 4217)
Order confirmation reference
Payment method used
JSON string of cart contents for cross-sell analysis
Search query to find relevant products
### Returns
The response format depends on the `Accept` header:
#### JSON Response (default)
When `Accept: application/json` or no specific HTML accept header is provided, returns a placement object.
#### HTML Response
When `Accept: text/html` is provided, returns an HTML document directly in the response body with `Content-Type: text/html`.
Unique identifier for this placement
Name of the template used for rendering
Structured data for native rendering
Array of content entities
Groups related products together
Always "collection"
Unique collection identifier
Collection display name
Array of product references
Product ID reference
Individual product for display
Always "product"
Unique product identifier
Product name
Product description (optional)
Pricing information
Price
Three-letter currency code
Original price for discounted items (optional)
Product images and media
Media role ("primary" or "secondary")
Media URL
MIME type (e.g., "image/jpeg")
Product brand (optional)
Product category (optional)
Product purchase/detail page URL
Customer ratings (optional)
Average rating (1-5)
Number of reviews
Promotional incentive or discount
Always "incentive"
Unique incentive identifier
Incentive type ("cart\_credit", "discount\_percentage", "discount\_fixed", "free\_shipping")
Incentive value information
Value amount
Currency code
Incentive display title
Incentive description (optional)
Visual content or messaging
Always "creative"
Unique creative identifier
Creative headline (optional)
Text content or message
Creative media (optional)
Media role ("primary" or "secondary")
Media URL
MIME type (e.g., "image/jpeg")
Creative video URL (optional)
Call-to-action button (optional)
Button text
Button destination URL
ISO timestamp of when the placement was rendered
```bash cURL theme={null}
curl https://api.mazeedplus.com/select-placement \
-H "x-publishable-api-key: pk_live_51H7..." \
-H "Content-Type: application/json" \
-d '{
"identifier": "checkout_success",
"attributes": {
"userId": "user_123456789",
"mobile": "+966501234567",
"currency": "sar",
"country": "sa",
"firstname": "Ahmed",
"lastname": "Ali",
"interests": ["technology", "gaming", "brand:Nike", "brand:Apple"],
"q": "كولومبي قهوه"
}
}'
```
```javascript Node.js theme={null}
const response = await fetch("https://api.mazeedplus.com/select-placement", {
method: "POST",
headers: {
"x-publishable-api-key": "pk_live_51H7...",
"Content-Type": "application/json",
},
body: JSON.stringify({
identifier: "checkout_success",
attributes: {
userId: "user_123456789",
mobile: "+966501234567",
currency: "sar",
country: "sa",
firstname: "Ahmed",
lastname: "Ali",
interests: ["technology", "gaming", "brand:Nike", "brand:Apple"],
q: "كولومبي قهوه",
},
}),
});
const placement = await response.json();
```
```python Python theme={null}
import requests
response = requests.post(
"https://api.mazeedplus.com/select-placement",
headers={
"x-publishable-api-key": "pk_live_51H7...",
"Content-Type": "application/json"
},
json={
"identifier": "checkout_success",
"attributes": {
"userId": "user_123456789",
"mobile": "+966501234567",
"currency": "sar",
"country": "sa",
"firstname": "Ahmed",
"lastname": "Ali",
"interests": ["technology", "gaming", "brand:Nike", "brand:Apple"],
"q": "كولومبي قهوه"
}
}
)
placement = response.json()
```
```php PHP theme={null}
'checkout_success',
'attributes' => [
'userId' => 'user_123456789',
'mobile' => '+966501234567',
'currency' => 'sar',
'country' => 'sa',
'firstname' => 'Ahmed',
'lastname' => 'Ali',
'interests' => ['technology', 'gaming', 'brand:Nike', 'brand:Apple'],
'q' => 'كولومبي قهوه'
]
]));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$response = curl_exec($ch);
$placement = json_decode($response, true);
curl_close($ch);
?>
```
```json Success theme={null}
{
"identifier": "checkout_success",
"templateName": "Product Listing",
"template_data": {
"entities": [
{
"object": "collection",
"id": "col_featured",
"name": "Featured Products",
"items": [
{ "ref": "prod_1234" },
{ "ref": "prod_5678" },
{ "ref": "prod_9012" }
]
},
{
"object": "product",
"id": "prod_1234",
"title": "Wireless Headphones",
"description": "High-quality wireless headphones with active noise cancellation and 30-hour battery life",
"price": {
"amount": 8999,
"currency": "usd"
},
"media": [
{
"role": "primary",
"uri": "https://example.com/headphones.jpg",
"content_type": "image/jpeg"
}
],
"click_url": "https://checkout.mazeedplus.com/p/prod_1234"
},
{
"object": "product",
"id": "prod_5678",
"title": "Smartphone Case",
"description": "Premium protective case with shock-absorbing design",
"price": {
"amount": 2499,
"currency": "usd"
},
"media": [
{
"role": "primary",
"uri": "https://example.com/case.jpg",
"content_type": "image/jpeg"
}
],
"click_url": "https://checkout.mazeedplus.com/p/prod_5678"
},
{
"object": "product",
"id": "prod_9012",
"title": "Charging Cable",
"description": "Fast-charging USB-C cable with braided nylon design",
"price": {
"amount": 1999,
"currency": "usd"
},
"media": [
{
"role": "primary",
"uri": "https://example.com/cable.jpg",
"content_type": "image/jpeg"
}
],
"click_url": "https://checkout.mazeedplus.com/p/prod_9012"
},
{
"object": "incentive",
"id": "inc_abc123",
"kind": "free_shipping",
"value": {
"amount": 0,
"currency": "usd"
},
"title": "Free Shipping",
"description": "Free shipping on orders over $50"
}
]
}
}
```
```json Validation Error - Missing Required Fields theme={null}
{
"error": "Validation failed",
"error_code": "VALIDATION_ERROR",
"message": "Invalid request data",
"details": {
"_errors": [],
"identifier": {
"_errors": [
"Required"
]
}
}
}
```
```json Validation Error - Missing userId theme={null}
{
"error": "Validation failed",
"error_code": "VALIDATION_ERROR",
"message": "Invalid request data",
"details": {
"_errors": [],
"attributes": {
"_errors": [],
"userId": {
"_errors": [
"User ID is required"
]
}
}
}
}
```
```json Validation Error - Invalid Mobile Number theme={null}
{
"error": "Validation failed",
"error_code": "VALIDATION_ERROR",
"message": "Invalid request data",
"details": {
"_errors": [],
"attributes": {
"_errors": [],
"mobile": {
"_errors": [
"Mobile number must include country code with + prefix (e.g., +966501234567)"
]
}
}
}
}
```
```json Placement Not Found Error theme={null}
{
"error": "Placement not found",
"error_code": "PLACEMENT_NOT_FOUND",
"message": "No placement found with identifier: non-existent-placement"
}
```
## Usage
The Placements API can return either structured JSON data or HTML content directly, depending on your Accept header.
### Getting HTML Content Directly
To receive HTML content directly (for iframe or server-side rendering), set the Accept header:
```bash theme={null}
curl https://api.mazeedplus.com/select-placement \
-H "x-publishable-api-key: pk_live_51H7..." \
-H "Content-Type: application/json" \
-H "Accept: text/html" \
-d '{
"identifier": "home",
"attributes": {
"userId": "user_123456789",
"q": "كولومبي قهوه"
}
}'
# Returns HTML document directly:
#
#
#
# ...
#
```
### Getting Structured JSON Data
For native mobile apps or custom rendering, request JSON (default):
```javascript theme={null}
const response = await fetch("https://api.mazeedplus.com/select-placement", {
method: "POST",
headers: {
"x-publishable-api-key": "pk_live_51H7...",
"Content-Type": "application/json",
"Accept": "application/json" // Optional, JSON is default
},
body: JSON.stringify({
identifier: "home",
attributes: {
userId: "user_123456789",
q: "كولومبي قهوه"
}
})
});
const placement = await response.json();
// Use placement.template_data for native rendering
```
### Native mobile integration
Use the structured data for native rendering:
```swift theme={null}
// iOS example
struct Product {
let id: String
let title: String
let price: Price
let imageUrl: String
let url: String
}
// Parse collections and products
let collections = placement.data.entities.filter { $0.object == "collection" }
let products = placement.data.entities.filter { $0.object == "product" }
// Display featured collection
if let featured = collections.first(where: { $0.id == "col_featured" }) {
let featuredProducts = featured.items.compactMap { item in
products.first { $0.id == item.ref }
}
displayProductCollection(featuredProducts)
}
```