Statlas Ads API

This guide is for design partners integrating with Statlas Ads to receive batch requests, check statuses, and deliver completed ad assets.

Base URL

https://api.statlas.io/v1

Authentication

All API requests require a Bearer token in the Authorization header.

Authorization: Bearer YOUR_PARTNER_API_KEY

Your API key is tied to your partner_id and can be obtained from your Statlas partner dashboard.

Webhooks & Notifications

Statlas can notify your team when events occur. Configure your notification preferences in the partner dashboard.

Supported Channels

Channel	Description
Email	Notifications sent to configured email addresses
Slack	Messages posted to a Slack channel via incoming webhook
Webhook	HTTP POST to your custom endpoint

Webhook Events

Event	Description
`batch.created`	A new batch request has been submitted
`batch.updated`	Batch details have been modified
`revision.requested`	Client has requested changes on one or more ads

Webhook Payload Example

{
  "event": "batch.created",
  "timestamp": "2025-01-15T14:30:00Z",
  "data": {
    "batch_id": "BAT001",
    "batch_code": "BAMBU-XMAS-001",
    "shop": "bambu-earth",
    "partner_id": "PTN00123",
    "total_ads": 5,
    "video_count": 3,
    "static_count": 2,
    "marketing_event": "XMAS",
    "event_type": "Campaign",
    "go_live_date": "2025-01-20",
    "product_name": "MUD MASK",
    "brief_notes": "Focus on holiday gifting angle",
    "attachments": [
      {
        "name": "brand_guidelines.pdf",
        "url": "https://storage.statlas.io/attachments/..."
      }
    ]
  }
}

Revision Notification Payload

{
  "event": "revision.requested",
  "timestamp": "2025-01-16T10:44:00Z",
  "data": {
    "batch_id": "BAT001",
    "batch_code": "BAMBU-XMAS-001",
    "shop": "bambu-earth",
    "ad_no": 3,
    "revision_url": "https://app.statlas.io/revisions/BAT001/3",
    "feedback_summary": "I don't like this color"
  }
}

Revisions

There is no API for managing revisions. When you receive a revision.requested notification, use the revision_url to view feedback and communicate directly with the client through the Statlas interface.

Endpoints

Get Batch Details

Retrieve details for a specific batch request.

GET /batches/{batch_id}

Path Parameters

Parameter	Type	Description
`batch_id`	string	The batch identifier (e.g., `BAT001`)

Query Parameters

Parameter	Type	Required	Description
`shop`	string	Yes	The shop identifier

Response

{
  "id": "BAT001",
  "batch_code": "BAMBU-XMAS-001",
  "shop": "bambu-earth",
  "partner_id": "PTN00123",
  "total_ads": 5,
  "video_count": 3,
  "static_count": 2,
  "marketing_event": "XMAS",
  "event_type": "Campaign",
  "go_live_date": "2025-01-20",
  "product_id": "prod_mudmask",
  "product_name": "MUD MASK",
  "is_collection": false,
  "status": "in_production",
  "submitted_at": "2025-01-15T14:30:00Z",
  "completed_at": null,
  "brief_notes": "Focus on holiday gifting angle",
  "attachments": [],
  "market_code": "US",
  "funnel_type": "awareness",
  "audience": "Women 25-45",
  "angle": "Holiday gifting",
  "ads": [
    {
      "ad_no": 1,
      "ad_code": "BAMBU-XMAS-001-01",
      "ad_type": "video",
      "status": "pending",
      "has_revision": false
    },
    {
      "ad_no": 2,
      "ad_code": "BAMBU-XMAS-001-02",
      "ad_type": "static",
      "status": "revision_requested",
      "has_revision": true
    }
  ]
}

List Open Batches

Retrieve all batches assigned to your partner account that are awaiting delivery.

GET /batches

Query Parameters

Parameter	Type	Required	Description
`status`	string	No	Filter by status: `submitted`, `in_production`, `in_review`, `completed`
`shop`	string	No	Filter by shop identifier
`limit`	integer	No	Max results (default: 50, max: 100)
`offset`	integer	No	Pagination offset

Response

{
  "data": [
    {
      "id": "BAT001",
      "batch_code": "BAMBU-XMAS-001",
      "shop": "bambu-earth",
      "total_ads": 5,
      "video_count": 3,
      "static_count": 2,
      "marketing_event": "XMAS",
      "go_live_date": "2025-01-20",
      "product_name": "MUD MASK",
      "status": "in_production",
      "submitted_at": "2025-01-15T14:30:00Z"
    }
  ],
  "pagination": {
    "total": 12,
    "limit": 50,
    "offset": 0
  }
}

Submit Completed Ads (Batch Upload)

Upload completed ad assets for an entire batch. This is the primary method for delivering finished work.

POST /batches/{batch_id}/deliver

Path Parameters

Parameter	Type	Description
`batch_id`	string	The batch identifier

Request Body

Each ad in the batch should have a Google Drive folder URL containing the assets. Each folder represents one ad and may contain multiple images or a video file.

{
  "shop": "bambu-earth",
  "ads": [
    {
      "ad_no": 1,
      "ad_type": "video",
      "headline": "Unwrap Beautiful Skin",
      "description": "The perfect holiday gift",
      "body": "Give the gift of radiant skin this holiday season with our best-selling MUD MASK.",
      "folder_url": "https://drive.google.com/drive/folders/abc123",
      "assets": [
        {
          "name": "mudmask_holiday_15s.mp4",
          "url": "https://drive.google.com/file/d/xyz789",
          "width": 1080,
          "height": 1920,
          "file_size_bytes": 15234567
        }
      ]
    },
    {
      "ad_no": 2,
      "ad_type": "static",
      "headline": "Holiday Glow",
      "description": "Limited time offer",
      "folder_url": "https://drive.google.com/drive/folders/def456",
      "assets": [
        {
          "name": "mudmask_static_1080x1920.png",
          "url": "https://drive.google.com/file/d/aaa111",
          "width": 1080,
          "height": 1920,
          "file_size_bytes": 2345678
        },
        {
          "name": "mudmask_static_1200x628.png",
          "url": "https://drive.google.com/file/d/bbb222",
          "width": 1200,
          "height": 628,
          "file_size_bytes": 1876543
        }
      ]
    }
  ]
}

Asset Requirements

Field	Type	Required	Description
`name`	string	Yes	Filename including extension
`url`	string	Yes	Direct URL to the asset (Google Drive file link)
`width`	integer	No	Width in pixels
`height`	integer	No	Height in pixels
`file_size_bytes`	integer	No	File size in bytes

Google Drive Permissions

Ensure your Google Drive folders are shared with statlas-assets@statlas.iam.gserviceaccount.com with Viewer access. We cannot retrieve assets from folders we don't have access to.

Response

{
  "success": true,
  "batch_id": "BAT001",
  "status": "in_review",
  "ads_delivered": 5,
  "message": "Batch delivery successful. Client has been notified."
}

Upload Asset Directly

If you prefer to upload assets directly to Statlas storage instead of providing Google Drive links, use this endpoint.

POST /batches/{batch_id}/ads/{ad_no}/assets

Path Parameters

Parameter	Type	Description
`batch_id`	string	The batch identifier
`ad_no`	integer	The ad number within the batch

Request

Send as multipart/form-data:

Field	Type	Required	Description
`file`	file	Yes	The asset file (image or video)
`shop`	string	Yes	The shop identifier
`name`	string	No	Custom filename (defaults to uploaded filename)

Response

{
  "success": true,
  "asset": {
    "id": "ast_8x7k2m9p",
    "batch_id": "BAT001",
    "ad_no": 1,
    "name": "mudmask_holiday_15s.mp4",
    "url": "https://storage.statlas.io/assets/ast_8x7k2m9p/mudmask_holiday_15s.mp4",
    "width": 1080,
    "height": 1920,
    "file_size_bytes": 15234567,
    "revision_no": 1
  }
}

Update Ad Details

Update copy or metadata for a specific ad.

PATCH /batches/{batch_id}/ads/{ad_no}

Request Body

{
  "shop": "bambu-earth",
  "headline": "Updated Headline",
  "description": "Updated description text",
  "body": "Updated body copy for the ad."
}

Response

{
  "success": true,
  "ad": {
    "batch_id": "BAT001",
    "ad_no": 1,
    "ad_code": "BAMBU-XMAS-001-01",
    "ad_type": "video",
    "headline": "Updated Headline",
    "description": "Updated description text",
    "body": "Updated body copy for the ad.",
    "status": "pending",
    "update_at": 20250116
  }
}

Mark Batch as Complete

Notify Statlas that all ads in a batch have been delivered and are ready for client review.

POST /batches/{batch_id}/complete

Request Body

{
  "shop": "bambu-earth"
}

Response

{
  "success": true,
  "batch_id": "BAT001",
  "status": "in_review",
  "completed_at": "2025-01-18T09:00:00Z",
  "message": "Batch marked complete. Client has been notified to review."
}

Batch Status Values

Status	Description
`draft`	Request created but not yet submitted
`submitted`	Client has submitted the request
`in_production`	Partner is actively working on the batch
`in_review`	Assets delivered, awaiting client review
`completed`	All ads approved and deployed

Ad Status Values

Status	Description
`pending`	Awaiting client review
`approved`	Client approved the ad
`rejected`	Client rejected the ad
`revision_requested`	Client requested changes

Error Handling

Error Response Format

{
  "error": {
    "code": "BATCH_NOT_FOUND",
    "message": "No batch found with ID 'BAT999' for shop 'bambu-earth'",
    "status": 404
  }
}

Common Error Codes

Code	Status	Description
`UNAUTHORIZED`	401	Invalid or missing API key
`FORBIDDEN`	403	Partner does not have access to this batch
`BATCH_NOT_FOUND`	404	Batch ID does not exist
`VALIDATION_ERROR`	400	Invalid request body or parameters
`ASSET_ACCESS_DENIED`	400	Cannot access Google Drive folder
`RATE_LIMITED`	429	Too many requests

Rate Limits

Endpoint	Limit
GET requests	100 requests/minute
POST/PATCH requests	30 requests/minute
File uploads	10 requests/minute

Workflow Summary

Support

For API support or integration assistance, contact api-support@statlas.io or reach out to your partner success manager.

Base URL​

Authentication​

Webhooks & Notifications​

Supported Channels​

Webhook Events​

Webhook Payload Example​

Revision Notification Payload​

Endpoints​

Get Batch Details​

Path Parameters​

Query Parameters​

Response​

List Open Batches​

Query Parameters​

Response​

Submit Completed Ads (Batch Upload)​

Path Parameters​

Request Body​

Asset Requirements​

Response​

Upload Asset Directly​

Path Parameters​

Request​

Response​

Update Ad Details​

Request Body​

Response​

Mark Batch as Complete​

Request Body​

Response​

Batch Status Values​

Ad Status Values​

Error Handling​

Error Response Format​

Common Error Codes​

Rate Limits​

Workflow Summary​

Support​

Base URL

Authentication

Webhooks & Notifications

Supported Channels

Webhook Events

Webhook Payload Example

Revision Notification Payload

Endpoints

Get Batch Details

Path Parameters

Query Parameters

Response

List Open Batches

Query Parameters

Response

Submit Completed Ads (Batch Upload)

Path Parameters

Request Body

Asset Requirements

Response

Upload Asset Directly

Path Parameters

Request

Response

Update Ad Details

Request Body

Response

Mark Batch as Complete

Request Body

Response

Batch Status Values

Ad Status Values

Error Handling

Error Response Format

Common Error Codes

Rate Limits

Workflow Summary

Support