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
   Fetch Interests         GET  /interests                   (only if targeting by interest)
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

1b Fetch Interests Optional

Offers can optionally be targeted at users who have selected particular interests. Retrieve the available interests to obtain their ids. Skip this step if you do not intend to target by interest.

Endpoint: GET /interests

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

Successful response — HTTP 200

{
  "interests": [
    { "interest_id": 3, "interest_name": "Cooking" },
    { "interest_id": 7, "interest_name": "Fitness" },
    { "interest_id": 12, "interest_name": "Live music" }
  ]
}

Use the interest_id values in the optional interests array in Step 3.

Error responses

2 Estimate Price Recommended

Find out what the offer will cost before committing: how many Ad Units it uses, and what those units cost in money. This is especially important if you intend to pay from balance (payment method B), so you can confirm the balance is sufficient.

Endpoint: POST /offers/price-estimate

Price formula: Ad Units = duration in hours × number of matching Agilis users, rounded to 2 decimal places. Cost = Ad Units × the Ad Unit price, rounded to 2 decimal places.

The Ad Unit price is set in pounds sterling: £0.001. In any other currency it is £0.001 × that day's European Central Bank reference rate for the currency, rounded to 8 decimal places. For example, at 1.3412 US dollars to the pound one Ad Unit costs US$0.001341. Rates are refreshed each working day.

Your billing currency. Every organisation is billed in one currency, chosen when it registers. Your balance, every payment, every refund of Unused Time and every invoice are in it, and every price the API quotes or charges is in it. There is no currency parameter: you cannot choose a different currency per offer, and the billing currency cannot be changed through the API: once your organisation is approved, only Agilis support can change it.

Ad Units and money are different things. price_estimate is a number of Ad Units. Your balance, and the amount an offer deducts from it, is money in your billing currency. Compare your balance with estimated_cost, never with price_estimate: for an account in pounds the two differ by a factor of 100.

A user matches when they are within the target radius and satisfy any gender and interests targeting you supply. Only active, non-banned accounts are counted. Because targeting narrows the audience, it also lowers the price — pass the same gender and interests values you intend to use in Step 3, or the estimate will be higher than the amount actually charged.

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": "2027-08-01T09:00:00Z",
    "end_datetime":   "2027-08-31T23:59:00Z",
    "location": [51.5074, -0.1278],
    "radius": 10,
    "gender": ["Male", "Female"],
    "interests": [3, 7]
  }'

Parameters

Successful response — HTTP 200, S1

{
  "return_code": "S1",
  "price_estimate": 1337669.67,
  "matching_users": 1820,
  "ad_units": 1337669.67,
  "ad_unit_price": 0.001,
  "estimated_cost": 1337.67,
  "currency": "GBP",
  "exchange_rate_per_gbp": 1,
  "exchange_rate_date": null
}

The same offer for an organisation billed in US dollars, on a day when the rate was 1.3412:

{
  "return_code": "S1",
  "price_estimate": 1337669.67,
  "matching_users": 1820,
  "ad_units": 1337669.67,
  "ad_unit_price": 0.001341,
  "estimated_cost": 1794.08,
  "currency": "USD",
  "exchange_rate_per_gbp": 1.3412,
  "exchange_rate_date": "2027-09-29"
}

If your billing currency cannot be billed right now, the estimate still returns S1 with the Ad Unit figures, and ad_unit_price, estimated_cost, exchange_rate_per_gbp and exchange_rate_date are null. That happens when the currency's exchange rate is out of date (try again later), or when your organisation registered in a currency Agilis does not bill in (an Org Admin can choose a supported billing currency in the Ad Portal). POST /offers refuses both cases with E6.

Error responses

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

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 "location[]=51.5074" \
  -F "location[]=-0.1278" \
  -F "radius=10" \
  -F "gender[]=Male" \
  -F "gender[]=Female" \
  -F "interests[]=3" \
  -F "interests[]=7" \
  -F "start_datetime=2027-08-01T09:00:00Z" \
  -F "expiry_datetime=2027-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_...",
  "currency": "GBP"
}

currency is your organisation's billing currency, the currency the card is charged in.

Direct your user to this Stripe Checkout page. Your user enters their card details and completes payment on Stripe's hosted page. The page shows one line for the offer, at the offer's price (the estimated_cost from Step 2), in your billing currency.

Minimum card payment: Stripe will not take a card payment below its minimum for the currency (for example £0.30, US$0.50 or €0.50). A card offer priced below it is refused with E1, and the message names the minimum: widen the audience, lengthen the offer, or pay from your balance.

VAT: for an organisation registered in the UK, the Stripe page adds VAT at 20% as a separate line, so the card is charged the offer's price plus VAT. Organisations registered anywhere else are charged no VAT. The offer's price, and any Unused Time later credited to your balance, are always net of VAT.

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 your organisation's balance is at least the estimated_cost returned in Step 2. That is the money figure; do not compare the balance with price_estimate, which is a number of Ad Units. 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.

The balance used is the one for your API key's mode. TEST and LIVE balances are separate: a TEST offer is paid from the TEST balance, a LIVE offer from the LIVE balance, and a TEST top-up can never pay for a LIVE offer. No VAT is added to a balance payment; where VAT applies, it was charged when the balance was topped up.

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 "location[]=51.5074" \
  -F "location[]=-0.1278" \
  -F "radius=10" \
  -F "gender[]=Male" \
  -F "gender[]=Female" \
  -F "interests[]=3" \
  -F "interests[]=7" \
  -F "start_datetime=2027-08-01T09:00:00Z" \
  -F "expiry_datetime=2027-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
}

The price of the Ad Units, in your organisation's billing currency, is deducted from your balance and your organisation's balance, and Org Admins are notified by email in both cases.

Create Offer error responses (both payment paths)

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

The environment query parameter is mandatory; use test or live (case-insensitive). It must be your API key's own mode: naming the other mode returns HTTP 403.

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 closes its Stripe payment page first; deleting a paid offer credits its Unused Time to your balance. 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).
• A key is shown once. The Ad Portal shows the full key only when you create it (or roll it). Copy it then and store it securely: Agilis does not keep a copy, so it cannot be shown again. The key list shows only its last four characters. If a key is lost or may have been exposed, use Roll key: you get a new key, shown once, and the old one stops working immediately.
• Each key works in one mode only, and this is enforced: the mode the Ad Portal was in (its test/live mode toggle) when the key was created. A pk_live_ key is a LIVE key and a pk_test_ key is a TEST key. To work in both modes, create one key in each.
• A request whose environment names the other mode is refused with HTTP 403 before anything is created or charged. The message names your key's mode: {"return_code": "E1", "status": "Error", "code": 403, "message": "This is a LIVE API key, so it can only be used with environment=LIVE. Use a TEST key (created in the Ad Portal in TEST MODE) for TEST requests."}
• Offers of the other mode are treated as not found: pause, resume, analytics and delete return HTTP 401 (E1, "Offer not found" on delete), exactly as for an offer that does not exist.
• A key with no recorded mode returns HTTP 401 with {"return_code": "E1", "message": "This API key has no environment. Create a new key in the Ad Portal."}. Create a new key.
• 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.
• Calls are recorded for 90 days. Every request made with your API key, including refused ones, is recorded with the key, the endpoint (its route, such as offers/{id}/pause, without ids or the query string), the HTTP status, the return_code, the response time and the time of the call. The request body, the query string and your IP address are not recorded. Records are deleted after 90 days. Recording does not change any request or response.

Rate limits

• 60 requests a minute per client IP address, across every endpoint.
• Every response carries X-RateLimit-Limit (the requests allowed in the current minute) and X-RateLimit-Remaining (how many are left).
• Over the limit, the API returns HTTP 429 with a Retry-After header: the number of seconds to wait before trying again. Retry a refused POST /offers with the same Idempotency-Key.

Environment Testing

Use a TEST key (created while the Ad Portal is in TEST mode) and set environment=TEST (in capitals) in the Create Offer request to create offers in a sandbox. Test offers are only returned when calling GET /offers?environment=test with a TEST key, do not appear to real Agilis users in the app, and follow the same creation, payment, and management flow as live offers. Card payments for TEST offers run in Stripe's test mode, and balance payments use the separate TEST balance. When your integration is ready, switch to a LIVE key: the Ad Portal's test/live mode toggle decides which kind of key you create.