← Back to Dashboard

API Documentation

Salloq Marketing API

Complete API documentation for integrating marketing automation into your Salloq ecommerce and POS platforms.

Introduction

The Salloq Marketing API is a RESTful API that allows you to programmatically manage campaigns, contacts, flows, and track events from your ecommerce and POS platforms. All API requests should be made to: https://marketing.salloq.com/api.php

Base URL: https://marketing.salloq.com/api.php
Format: JSON
Authentication: API Key via Authorization header

Authentication

All API requests require authentication using an API key. Include your API key in the Authorization header and your company ID in the X-Company-ID header.

curl https://marketing.salloq.com/api.php/campaigns \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "X-Company-ID: 1"
⚠️ Keep your API keys secure! Never commit them to version control or expose them in client-side code.

Rate Limiting

API requests are limited to 1000 requests per hour per API key. Rate limit information is included in response headers:

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 999
X-RateLimit-Reset: 1609459200

Error Handling

The API uses standard HTTP status codes:

Status Code Description
200 Success
201 Created
400 Bad Request - Invalid parameters
401 Unauthorized - Invalid API key
404 Not Found
429 Too Many Requests - Rate limit exceeded
500 Internal Server Error

Error Response Format:

{
  "error": "Invalid API key",
  "code": 401,
  "message": "The provided API key is invalid or has been revoked"
}

Flows

GET /flows

Retrieve all flows for your company.

Query Parameters:

Parameter Type Required Description
status string optional Filter by status: draft, active, paused, archived
trigger_type string optional Filter by trigger type

Response:

{
  "flows": [
    {
      "flow_id": 1,
      "name": "Welcome Series",
      "status": "active",
      "trigger_type": "customer_created",
      "created_at": "2024-01-15 10:30:00",
      "steps": [...],
      "connections": [...]
    }
  ]
}
POST /flows

Create a new flow.

Request Body:

Parameter Type Required Description
name string required Flow name
trigger_type string required Event type that triggers the flow
status string optional draft (default) or active
trigger_conditions object optional Conditions for triggering

Example Request:

{
  "name": "Cart Abandonment Flow",
  "trigger_type": "cart_abandoned",
  "status": "draft",
  "trigger_conditions": {
    "operator": "and",
    "rules": [
      {
        "field": "cart_total",
        "comparison": "greater_than",
        "value": 50
      }
    ]
  }
}
PUT /flows/{id}

Update an existing flow.

DELETE /flows/{id}

Delete a flow.

Campaigns

GET /campaigns

Retrieve all campaigns.

Query Parameters:

Parameter Type Description
type string Filter by type: email or sms
status string Filter by status
page integer Page number (default: 1)
per_page integer Results per page (default: 20)
POST /campaigns

Create a new campaign.

Example Request:

{
  "name": "Summer Sale 2024",
  "type": "email",
  "subject": "🌞 50% Off Summer Collection!",
  "preview_text": "Limited time offer on all summer items",
  "content": "<h1>Summer Sale</h1><p>Get 50% off...</p>",
  "list_id": 1,
  "scheduled_at": "2024-06-15 09:00:00"
}
POST /campaigns/send/{id}

Send or schedule a campaign.

{
  "scheduled_at": "2024-06-15 09:00:00"  // Optional - omit to send immediately
}

Contacts

GET /contacts

Retrieve contacts with optional filtering.

Query Parameters:

Parameter Type Description
status string subscribed, unsubscribed, bounced
list_id integer Filter by list membership
search string Search in name and email
page integer Page number
per_page integer Results per page (max: 100)
POST /contacts

Create or update a contact (upsert).

Example Request:

{
  "email": "john@example.com",
  "first_name": "John",
  "last_name": "Doe",
  "phone": "+1-555-0123",
  "external_id": "CUST-12345",
  "source": "ecommerce",
  "tags": ["vip", "newsletter"],
  "properties": {
    "favorite_category": "Electronics",
    "last_purchase_date": "2024-01-15"
  }
}

Events

POST /events

Track an event from your ecommerce or POS platform.

Request Body:

Parameter Type Required Description
event_type string required Type of event (see Event Types)
event_data object required Event data including customer info

Example - Order Placed:

{
  "event_type": "order_placed",
  "event_data": {
    "order_id": "ORD-12345",
    "customer_id": "CUST-67890",
    "email": "customer@example.com",
    "first_name": "Jane",
    "last_name": "Smith",
    "total": 149.99,
    "items": [
      {
        "product_id": "PROD-001",
        "name": "Wireless Headphones",
        "price": 149.99,
        "quantity": 1
      }
    ]
  }
}

Webhooks

POST /webhook

Webhook endpoint for receiving events from Salloq platforms. Configure this URL in your Salloq ecommerce/POS webhook settings.

Webhook URL: https://marketing.salloq.com/api/webhook

Headers:

Header Description
X-Webhook-Signature HMAC signature for verification
X-Company-ID Your company ID

Event Types

Supported event types for triggering flows and tracking customer behavior:

Event Type Description Required Data
customer_created New customer account created email, first_name, last_name
order_placed Order completed order_id, email, total
order_completed Order fulfilled order_id, email
cart_abandoned Cart left without checkout email, cart_total, items
product_viewed Product page viewed email, product_id, product_name
subscription_created Subscription started email, subscription_id, plan
subscription_cancelled Subscription ended email, subscription_id

Code Examples

PHP Example - Track Order Event

<?php
$apiKey = 'YOUR_API_KEY';
$companyId = 1;

$data = [
    'event_type' => 'order_placed',
    'event_data' => [
        'order_id' => 'ORD-12345',
        'email' => 'customer@example.com',
        'first_name' => 'John',
        'last_name' => 'Doe',
        'total' => 99.99,
        'items' => [
            [
                'product_id' => 'PROD-001',
                'name' => 'Product Name',
                'price' => 99.99,
                'quantity' => 1
            ]
        ]
    ]
];

$ch = curl_init('https://marketing.salloq.com/api/events');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($data));
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Content-Type: application/json',
    'Authorization: Bearer ' . $apiKey,
    'X-Company-ID: ' . $companyId
]);

$response = curl_exec($ch);
curl_close($ch);

echo $response;
?>

JavaScript Example - Create Contact

const apiKey = 'YOUR_API_KEY';
const companyId = 1;

const contactData = {
  email: 'john@example.com',
  first_name: 'John',
  last_name: 'Doe',
  tags: ['newsletter', 'customer'],
  properties: {
    signup_source: 'website',
    interests: 'electronics'
  }
};

fetch('https://marketing.salloq.com/api/contacts', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': `Bearer ${apiKey}`,
    'X-Company-ID': companyId
  },
  body: JSON.stringify(contactData)
})
.then(response => response.json())
.then(data => console.log('Contact created:', data))
.catch(error => console.error('Error:', error));

Python Example - Send Campaign

import requests
import json

api_key = 'YOUR_API_KEY'
company_id = 1

campaign_data = {
    'name': 'Summer Sale',
    'type': 'email',
    'subject': '50% Off Everything!',
    'content': '<h1>Summer Sale</h1><p>Limited time offer...</p>',
    'list_id': 1
}

headers = {
    'Content-Type': 'application/json',
    'Authorization': f'Bearer {api_key}',
    'X-Company-ID': str(company_id)
}

# Create campaign
response = requests.post(
    'https://marketing.salloq.com/api/campaigns',
    headers=headers,
    data=json.dumps(campaign_data)
)

campaign = response.json()
campaign_id = campaign['campaign_id']

# Send campaign
send_response = requests.post(
    f'https://marketing.salloq.com/api/campaigns/send/{campaign_id}',
    headers=headers
)

print('Campaign sent:', send_response.json())
Need Help? Contact our support team at support@salloq.com or visit the Integrations page to configure your webhooks.