Getting Started

This guide takes you from zero to your first successful Adlyfy API call.

The journey has two parts:

One-time setup in the Adlyfy portal — create an account, register your app, and get an API key.

Make API calls — mint an access token, then call any platform endpoint.

Base URL. All API requests go to the Adlyfy production API:
https://<adlyfy-api-host>/api/v1
Every endpoint path in this documentation is relative to this base URL.

Part 1 — Set up in the Adlyfy portal

Step 1 — Create your Adlyfy account

Sign up for an account on the Adlyfy portal. This creates your tenant — the isolated workspace that owns all your apps, connections, and API keys.

📹 Watch how: [PASTE SCRIBE LINK — "How to register an account on the Adlyfy portal"]

Step 2 — Register your app

Register your platform app (Meta, Google Ads, or TikTok) in the portal. Adlyfy is bring-your-own-app: you provide your own platform developer-app credentials, and Adlyfy uses them to run OAuth on your behalf.

📹 Watch how: [PASTE SCRIBE LINK — "How to register an app"]

Step 3 — Get your API key

Generate an API key for your tenant. This key (x-api-key) authenticates your integration with Adlyfy. It is shown only once — store it securely.

📹 Watch how: [PASTE SCRIBE LINK — "How to get an API key"]

Part 2 — Make your first API call

Adlyfy uses a two-step authentication for integrators:

You hold a long-lived API key (x-api-key) that identifies your tenant.

You exchange it for a short-lived access token (a JWT) that identifies an external user within that tenant.

Every platform call is sent with both the API key and the access token.

The full reference is in Authentication — this page just gets you moving.

Step 4 — Mint an access token

Exchange your API key for an access token. externalUserId is any stable identifier your integration uses for the end user (a plain string).

Response:

{
  "success": true,
  "data": {
    "accessToken": "eyJhbGciOi...",
    "refreshToken": "eyJhbGciOi..."
  }
}

Keep the accessToken for your API calls and the refreshToken to obtain a new access token when it expires (see Authentication).

Step 5 — Make an authenticated call

Send both the API key and the access token. Here we list Meta campaigns for an ad account:

Response:

{
  "success": true,
  "data": {
    "data": [
      {
        "id": "120000000001",
        "name": "Lead Gen - March",
        "status": "ACTIVE",
        "objective": "OUTCOME_LEADS"
      }
    ],
    "paging": {
      "before": "QVFI...",
      "after": "QVFI..."
    }
  }
}

That's it — you've made an authenticated, platform-backed call through Adlyfy.

Understanding the response envelope

Every Adlyfy response — success or error — uses a consistent envelope, so you can handle them uniformly.

Success:

{
  "success": true,
  "data": { }
}

Error:

{
  "success": false,
  "error": {
    "code": "BAD_REQUEST",
    "message": "Validation failed",
    "details": ["adAccountId is required"]
  },
  "statusCode": 400,
  "path": "/api/v1/meta/campaigns",
  "timestamp": "2026-06-30T12:00:00.000Z"
}

Always check success first. On errors, error.code is stable for programmatic handling, while error.message / error.details are for humans. See Errors & Status Codes for the full list.

Interactive API reference

Adlyfy serves live, interactive API docs generated from the gateway itself:

Swagger UI: https://<adlyfy-api-host>/api

OpenAPI JSON: https://<adlyfy-api-host>/api-json

Note: the Swagger UI lives at /api (not /api/v1/api) — the docs are mounted outside the version prefix.

Next steps

Authentication — token lifetimes, refreshing tokens, and the headers every call needs.

Connections & OAuth — register a platform app and authorize an ad account so data endpoints work.

Pagination — how to page through large result sets with cursors.

Quick Start

Getting Started#

Part 1 — Set up in the Adlyfy portal#

Step 1 — Create your Adlyfy account#

Step 2 — Register your app#

Step 3 — Get your API key#

Part 2 — Make your first API call#

Step 4 — Mint an access token#

Step 5 — Make an authenticated call#

Understanding the response envelope#

Interactive API reference#

Next steps#