Agilis API Documentation

This guide walks through the complete offer creation flow, from fetching categories to managing a live offer. The Agilis Advertising API lets developers create and manage advertiser offers programmatically.

• Base URL: https://ads.agilis.dating
• Authentication: All requests require a valid API key in the x-api-key request header.
• Content-Type: application/json for JSON requests; multipart/form-data for offer creation.

Overview

The offer creation flow involves up to five steps, depending on the payment method chosen:

1. Fetch Categories        GET  /categories
2. Estimate Price          POST /offers/price-estimate       (recommended before creating)
3. Create Offer            POST /offers
   ├─ Payment method E ──► Stripe checkout link returned
   │                        User completes payment externally
   │                        Webhook activates offer → Active or Scheduled
   └─ Payment method B ──► Ad Units deducted from balance immediately
                            Offer becomes Active or Scheduled at once

Once the offer exists you can view it, pause/resume it, retrieve analytics, or delete it.

1 Fetch Categories

Before creating an offer you need a valid category_id. Retrieve the categories assigned to your organisation.

Endpoint: GET /categories

curl -X GET "https://ads.agilis.dating/categories" \
  -H "x-api-key: YOUR_API_KEY_HERE"

Successful response — HTTP 200

{
  "categories": [
    { "category_id": 1, "category_name": "Retail" },
    { "category_id": 2, "category_name": "Food & Beverage" },
    { "category_id": 3, "category_name": "Health & Fitness" }
  ]
}

Use the category_id value in Step 3.

Error responses

HTTP	Body	Meaning
401	{"message": "Unauthorised"}	API key is missing, invalid, or disabled; or the associated user account is disabled
500	{"message": "Internal server error"}	Unexpected server error

2 Estimate Price Recommended

Calculate how many Ad Units the offer will cost before committing. This is especially important if you intend to pay from balance (payment method B) so you can confirm there are sufficient credits.

Endpoint: POST /offers/price-estimate

Price formula: Duration in hours × number of Agilis users within the target radius. The result is a float rounded to 2 decimal places.

curl -X POST "https://ads.agilis.dating/offers/price-estimate" \
  -H "x-api-key: YOUR_API_KEY_HERE" \
  -H "Content-Type: application/json" \
  -d '{
    "start_datetime": "2026-08-01T09:00:00Z",
    "end_datetime":   "2026-08-31T23:59:00Z",
    "location": [51.5074, -0.1278],
    "radius": 10
  }'

Parameters

Field	Type	Required	Notes
start_datetime	string	Yes	ISO 8601, UTC only (e.g. 2026-08-01T09:00:00Z)
end_datetime	string	Yes	ISO 8601, UTC only
location	array	Yes	[latitude, longitude]
radius	integer	Yes	Miles — minimum 5, maximum 30

Successful response — HTTP 200, S1

{
  "return_code": "S1",
  "price_estimate": 45.50
}

Error responses

HTTP	Body	Meaning
400	{"return_code": "E1", ...}	One or more inputs are missing or invalid
400	{"return_code": "E2", ...}	start_datetime or end_datetime is not in valid ISO 8601 format
401	{"message": "Unauthorised"}	Authentication failure

3 Create the Offer

Submit the offer as a multipart/form-data request. The image must be sent as a binary file stream. The API runs automated content moderation on the image before the offer is created. If moderation fails, the offer is not created and no charge is made.

Endpoint: POST /offers

Parameters

Field	Type	Required	Notes
title	string	Yes
description	string	Yes
terms_and_conditions	string	Yes	Maximum 500 characters
category_id	integer	Yes	From Step 1
url	string	Yes	Advertiser's offer URL
image	file (binary)	Yes	JPG, PNG or GIF; maximum 10 MB; sent as binary stream
currency	string	Yes	GBP, USD, CAD or AUD (case-insensitive)
location[]	float	Yes	Two values: latitude then longitude
radius	integer	Yes	Miles — minimum 5
start_datetime	string	Yes	ISO 8601, UTC (e.g. 2026-08-01T09:00:00Z)
expiry_datetime	string	Yes	ISO 8601, UTC; minimum 60 seconds after start_datetime
payment_method	string	Yes	E = Stripe link by email; B = deduct from organisation balance
environment	string	Yes	LIVE or TEST (case-insensitive)

Path A — Payment by Stripe link (payment_method=E)

The offer is created in Awaiting Payment status. A Stripe Checkout link is generated and returned. The organisation admin receives the link and completes payment externally. When Stripe confirms payment via webhook, the offer is automatically activated.

curl -X POST "https://ads.agilis.dating/offers" \
  -H "x-api-key: YOUR_API_KEY_HERE" \
  -H "Idempotency-Key: 3f1a9c7e-1b2d-4f9a-8c0e-2a6b5d4e7f10" \
  -F "title=Summer Sale — 20% Off" \
  -F "description=Discount valid through August on all summer items." \
  -F "terms_and_conditions=Valid for online purchases only. One per customer." \
  -F "category_id=1" \
  -F "url=https://www.example.com/summer-sale" \
  -F "currency=GBP" \
  -F "location[]=51.5074" \
  -F "location[]=-0.1278" \
  -F "radius=10" \
  -F "start_datetime=2026-08-01T09:00:00Z" \
  -F "expiry_datetime=2026-08-31T23:59:00Z" \
  -F "payment_method=E" \
  -F "environment=LIVE" \
  -F "image=@/path/to/offer-image.jpg"

Response immediately after creation — HTTP 200, S1

The offer is created but not yet active. Store the offer_id and present the payment_url to the user.

{
  "return_code": "S1",
  "offer_id": 45,
  "status": "Awaiting Payment",
  "payment_url": "https://checkout.stripe.com/c/pay/cs_live_..."
}

Direct your user to this Stripe Checkout page. The quantity on the Stripe invoice equals the number of Ad Units calculated in Step 2. Your user enters their card details and completes payment on Stripe's hosted page.

After payment, Stripe sends a checkout.session.completed webhook to Agilis, which activates the offer automatically. The status becomes Active if start_datetime is now or in the past, or Scheduled if it is in the future.

Path B — Payment from organisation balance (payment_method=B)

Before calling this path, confirm that the organisation's Ad Unit balance is at least equal to the price estimate returned in Step 2. If the balance is insufficient, the API returns E3 and no offer is created. Payment is deducted immediately when the offer is created; no Stripe link is involved.

curl -X POST "https://ads.agilis.dating/offers" \
  -H "x-api-key: YOUR_API_KEY_HERE" \
  -H "Idempotency-Key: 3f1a9c7e-1b2d-4f9a-8c0e-2a6b5d4e7f10" \
  -F "title=Summer Sale — 20% Off" \
  -F "description=Discount valid through August on all summer items." \
  -F "terms_and_conditions=Valid for online purchases only. One per customer." \
  -F "category_id=1" \
  -F "url=https://www.example.com/summer-sale" \
  -F "currency=GBP" \
  -F "location[]=51.5074" \
  -F "location[]=-0.1278" \
  -F "radius=10" \
  -F "start_datetime=2026-08-01T09:00:00Z" \
  -F "expiry_datetime=2026-08-31T23:59:00Z" \
  -F "payment_method=B" \
  -F "environment=LIVE" \
  -F "image=@/path/to/offer-image.jpg"

Response when start date is in the future — HTTP 200, S1

{
  "return_code": "S1",
  "offer_id": 46,
  "status": "Scheduled",
  "payment_url": null
}

Response when start date has already passed — HTTP 200, S1

{
  "return_code": "S1",
  "offer_id": 47,
  "status": "Active",
  "payment_url": null
}

Ad Units are deducted from the organisation balance and Org Admins are notified by email in both cases.

Create Offer error responses (both payment paths)

HTTP	Body	Meaning
400	E1	One or more inputs are missing or invalid (unsupported currency, invalid datetime, duration under 60 seconds, radius under 5 miles, oversized image, or wrong MIME type)
200	E2	Image failed automated content moderation — offer not created; choose a different image
200	E3	Organisation's Ad Unit balance is insufficient — top up and retry (payment_method=B only)
400	E1	Idempotency-Key request header was missing (message: "Idempotency-Key header is required.")
409	—	Idempotency-Key reused while the first request is still being processed — retry shortly
422	—	Idempotency-Key reused with a different payload
401	Unauthorised	Authentication failure
500	Internal server error	Unexpected server error

4 Verify the Offer Was Created

Confirm creation and check the current status by calling View Offers.

curl -X GET "https://ads.agilis.dating/offers?environment=live" \
  -H "x-api-key: YOUR_API_KEY_HERE"

offer_status values

Value	Meaning
Awaiting Payment	Created via method E; payment not yet received
Active	Live and visible to Agilis users
Scheduled	Paid for but start date is in the future
Paused	Temporarily paused by the advertiser
Ended	Expiry datetime has passed

The environment query parameter is mandatory; use test or live (case-insensitive).

Managing an Offer After Creation

Use the pause, resume, analytics, and delete endpoints to manage an offer once it exists. Valid analytics interval values are 24h, 7d, 30d, 60d, 90d, and all (mandatory). Deleting an offer in Awaiting Payment status automatically disables its Stripe payment link first. Full request and response details for each are documented in the Pause and Resume, Analytics, and Delete Offer sections below.

Authentication Notes

• API keys are created in the Agilis Ad Portal under Manage API Keys (Developer role).
• Keys can be scoped to TEST or LIVE environments using the portal's test/live mode toggle.
• A disabled key or disabled user account returns HTTP 401 {"message": "Unauthorised"} on any endpoint.
• Keys have an optional expiry date; expired keys also return 401.

Environment Testing

Set environment: TEST in the Create Offer request to create offers in a sandbox. Test offers are only returned when calling GET /offers?environment=test, do not appear to real Agilis users in the app, and follow the same creation, payment, and management flow as live offers. Switch between environments using the test/live mode toggle in the Ad Portal.