API Docs

Profila is a consent-aware supply-side platform. Consumers declare purchase intent in the app — a signal — and brands respond with their own inventory over REST, MCP, or GraphQL. You receive declared, privacy-safe targeting only — never names, emails, IPs, device ids, cookies, or precise location.

What's live today

The vocabulary

Inbound — you pull matching signals and push creatives, over REST or MCP. This is the surface to start with; it is live and callable today. GraphQL — your own tooling reads billing, invoices, moments and your connected audience. Also live. Outbound — Profila sends you OpenRTB bid requests, and is not currently sending; see the notice above.

From verified brand to first call

• Get verified. Your brand account must be verified. Request it at kyb@profila.com.
• Open the API tab. Brand portal → Customers → API. The tab is always visible — until your brand is verified it shows a verify to unlock placeholder rather than the key-minting controls.
• Mint an API key. The secret is shown once — copy keyId.secret immediately. Revoke and re-mint anytime.
• Optionally register a bid endpoint for the outbound flow.

A key looks like pk_ab12cd34.sk_9f8e7d6c… — the pk_ half is the public key id, the sk_ half is the secret. Profila stores only a hash of the secret; it can be re-minted, never recovered.

Every inbound request carries the key

Either header works:

Authorization: Bearer pk_ab12cd34.sk_9f8e7d6c…

x-api-key: pk_ab12cd34.sk_9f8e7d6c…

• Scopes — minted with signals:read + creatives:write by default. Pushing creatives needs creatives:write.
• Rate limit — 120 requests / minute / brand. Over the limit → 429 rate_limited.
• Errors — 401 unauthorized · 403 forbidden · 400 invalid body · 422 validation · 429 rate_limited.

GET /api/brand/openrtb/signals

List anonymous signals that currently match your inventory. Query: limit (1–100, default 50).

curl -s "https://api.profila.com/api/brand/openrtb/signals?limit=20" \
  -H "Authorization: Bearer pk_ab12cd34.sk_9f8e7d6c…"

{
  "signals": [
    {
      "signalUuid": "0f6c8e2a-…",
      "anonymousToken": "AU-EU-3841",
      "vertical": "automotive",
      "readiness": "ready",
      "iabContentCategory": "IAB2-2",
      "iabContentCategoryName": "Auto Type",
      "preferences": ["electric", "SUV"],
      "country": "CH",
      "matchReason": "category",
      "maxPerPeriod": 5,
      "remainingSlots": 3,
      "remainingForYou": 1,
      "createdAt": "2026-06-21T10:00:00.000Z"
    }
  ]
}

No name, email, phone, IP, device id, or precise location is ever returned.

POST /api/brand/openrtb/creatives

Push a native creative for one of your matching signals. Requires creatives:write.

curl -s -X POST https://api.profila.com/api/brand/openrtb/creatives \
  -H "Authorization: Bearer pk_ab12cd34.sk_9f8e7d6c…" \
  -H "content-type: application/json" \
  -d '{
    "signalUuid": "0f6c8e2a-…",
    "communicationType": "promotion",
    "title": "BMW iX — all-electric SAV",
    "description": "Up to 600 km range. Book a test drive.",
    "imageUrl": "https://www.bmw.com/…/bmw-ix.png",
    "clickUrl": "https://www.bmw.com/en/all-models/bmw-i/ix",
    "cta": "Configure yours",
    "sponsoredBy": "BMW",
    "adomain": ["bmw.com"]
  }'

Response { "ok": true }, or 422 if the signal doesn't match or the creative isn't renderable. On success the card enters that consumer's feed as a sponsored item.

Declaring what the content is

communicationType is required and has no default. It is what this content is, and it selects the rate you are charged — so a push without it returns 422 rather than having Profila guess a price on your behalf.

advocacy   brand_building   causes   company_information   product_information   promotion   personalized_offer   special_offer   lead_generation   survey

It is the same set of ten values brands choose from when authoring a moment in the portal, so the API is a different door to the same product rather than a parallel taxonomy.

Declare it accurately. Profila reviews pushed content and may reclassify it before the month closes, which reprices that period’s events. Under-declaring buys nothing — it surfaces on the invoice you were trying to reduce.

Which band each type is priced in, and what happens if we reclassify, is in the Billing Guide.

How much you may send

The person decides, not your budget. Every signal carries how many items its owner asked for in the current period. Your budget bounds what you spend; it authorises nothing on its own.

The one-per-period rule on open signals exists so a shared signal is not a race between brands. It is not a Profila quota — whatever brands do not take, Profila’s own results fill, so the person always receives what they asked for.

Every signal in GET /api/brand/openrtb/signals reports this, so you never have to push to find out. remainingSlots is the person’s, remainingForYou is yours, and null in either means they set no ceiling.

A push beyond the limit returns 422 with a code you can match on, not a string:

GET /api/brand/openrtb/logs

Recent bid requests Profila sent to your endpoints (outbound flow). Query: limit.

Each entry: requestId, dspEndpointId, categoryIds, impCount, responseTimeMs, hadBid, createdAt.

The same inbound surface, over MCP

Streamable-HTTP JSON-RPC 2.0 for LLM/agent runtimes. Endpoint POST https://api.profila.com/mcp, same key on Authorization or x-api-key, protocol version 2024-11-05.

# Handshake
curl -s -X POST https://api.profila.com/mcp -H "content-type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize"}'

# List tools
curl -s -X POST https://api.profila.com/mcp \
  -H "Authorization: Bearer pk_ab12cd34.sk_…" -H "content-type: application/json" \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/list"}'

# Call a tool
curl -s -X POST https://api.profila.com/mcp \
  -H "Authorization: Bearer pk_ab12cd34.sk_…" -H "content-type: application/json" \
  -d '{"jsonrpc":"2.0","id":3,"method":"tools/call",
       "params":{"name":"list_matching_signals","arguments":{"limit":5}}}'

POST /graphql

The surface your own tooling drives: billing and invoices, moments and what they cost, your brand profile, and your connected audience. It is live today.

Because introspection is off, a client that expects to discover the schema at runtime will come up empty. Work from this page and the operations below rather than from a generated client, and ask us for anything you need that is not listed — an omission here is an omission, not a prohibition.

Billing and invoices, in eight queries

No pricing numbers appear anywhere in these docs. Rates, country multipliers, size bands and benchmarks are all editable without a deploy, so a number written down here would be a second source of truth that drifts. Read yours from brandRateCardView.

Five fields that do not mean what they look like

• budgetMinor: 0 is a closed channel, not an unlimited one. Read isEnabled rather than inferring the state from the number.
• isCapped: true means delivery has stopped, not slowed. A capped brand is invisible, not free. The budget is a hard cap, not a spend limit.
• reclassifiedCount is worth polling. Profila reviews the communicationType you declared and may reclassify before the month closes, which reprices that period. It is surfaced so you find out while you can still ask about it, rather than on the invoice.
• pricingCategory: null means the moment predates pricing, not that it is free. It is frozen at creation, so moments made before billing existed carry no category.
• estimate: null means we did not quote you a number — not zero. Expected for a brand with no rate card yet, or a dynamic moment that started with an empty audience.

The person initiates a connection, never the brand. There is no operation that connects a brand to someone who did not choose it. That is the product, not a permission you can be granted.

What you are charged for

Content you push through the API is billed on the same basis as a moment authored in the portal: by what the content is, at the rate on your rate card for that category. The API is a different door to the same product, not a cheaper one.

Two events are billable, exactly as on-platform: an impression and a click-through. Dwell, saves, shares and reactions are recorded and never charged. Impressions are metered end to end and priced at zero.

• Your API budget is set by Profila, and it is a hard cap. A standing amount across everything you push. When it is reached your content stops being delivered, not merely stops being billed.
• A brand with no API budget cannot push at all. The push returns an error rather than delivering something that could never be invoiced. With no billing country set, likewise. These are the two most common reasons a new integration delivers nothing.

The commercial explanation — rate cards, price bands, budgets, invoices — is in the Billing Guide.

POST /api/brand/events

A reported event is a claim, not a fact. Profila is the system of record, so a claim is only billable when it arrives with a delivery token Profila itself issued.

POST /api/brand/events
Authorization: Bearer <keyId>.<secret>

{
  "tokenId": "…",              // issued when Profila serves — see the notice
  "idempotencyKey": "…",       // YOUR id for this event. Required.
  "eventType": "ENGAGEMENT",   // or IMPRESSION
  "engagementKind": "click_through",
  "occurredAt": "2026-04-14T09:30:00Z"
}

idempotencyKey is required and has no default. Retry a timed-out request with the same key and it is recorded once; send a new key and it is a new event. A generated default would make every network retry a double-bill, which is exactly what this endpoint exists to prevent.

The response is 200 whether or not the claim was billable — a rejected claim was still successfully processed — and the reason comes back inline, so you find out within the request rather than at month end.

{ "accepted": false, "rejectionCode": "TOKEN_UNKNOWN", "message": "…" }

Delivery tokens, and reconciling

• Tokens are single-use and narrowly bound. One moment, one creative, one person. A token cannot be replayed against a different moment’s budget.
• Billing happens on redemption, not on issue. Issuing is a delivery attempt, and an ad that never rendered is not something you should pay for.
• Redemption decides the service period, not your timestamp. Your occurredAt is recorded; it simply does not choose which month the event lands in. Trust the server on timing.
• Test traffic is derived from your brand record, never from anything you send. Events from a brand marked as test are recorded, never billed, and reported back as TEST_TRAFFIC so you can see the integration working without generating an invoice.

GET /api/brand/billing/usage?period=2026-04-01

Returns what you reported, what was accepted, and what was rejected broken down by reason. This is the endpoint to reconcile against — it is live and callable now, unlike event reporting above. Check it daily rather than discovering a gap at month end: a discrepancy found on the 3rd is a config fix; the same one found at month end is a support ticket about an invoice.

Register a bid endpoint

Profila POSTs an OpenRTB 2.6 bid request to your responder whenever a matching signal appears, then ingests your winning creative. Register in the portal (API tab → Register endpoint):

• Bid URL — your responder, e.g. https://dsp.yourbrand.com/openrtb/bid
• Routing — brand + category / brand only / category only
• Auth — None / Bearer token / API-key header
• Categories — IAB codes you serve, e.g. IAB2, IAB20

New endpoints start pending — click Activate to receive traffic. First-price (at: 1), tmax default 200 ms, and the request carries x-openrtb-version: 2.6.

The bid request Profila sends

{
  "id": "<request uuid>",
  "at": 1,
  "tmax": 200,
  "imp": [{
    "id": "1",
    "banner": { "format": [{ "w": 300, "h": 250 }] },
    "bidfloor": 0, "bidfloorcur": "USD", "secure": 1,
    "ext": { "profilaBrandDomains": ["bmw.com"] }
  }],
  "site": {
    "id": "profila-web", "name": "Profila", "domain": "app.profila.com",
    "cat": ["IAB2-2"], "publisher": { "id": "profila", "name": "Profila GmbH" }
  },
  "device": { "devicetype": 2, "os": "Unknown", "dnt": 0, "lmt": 1 },
  "user": {
    "id": "<daily-rotating opaque hash>",
    "data": [
      { "name": "profila-declared-categories",
        "segment": [{ "id": "IAB2-2", "name": "IAB2-2" }] },
      { "name": "profila-classified-intent", "segment": [
        { "name": "vertical", "value": "automotive" },
        { "name": "readiness", "value": "ready" },
        { "name": "intent_type", "value": "purchase" },
        { "name": "timeframe", "value": "this_month" },
        { "name": "budget_range", "value": "40000-60000 CHF" }
      ] }
    ]
  },
  "regs": { "coppa": 0, "ext": { "gdpr": 1, "us_privacy": "1YNN" } },
  "source": { "schain": { "ver": "1.0", "complete": 1,
    "nodes": [{ "asi": "profila.com", "sid": "profila-ssp", "hp": 1 }] } }
}

• bidfloor is always 0 — Profila does not charge per impression. Impressions are metered end to end and priced at zero: they appear on an invoice with their quantity and an amount of 0.00, so the number is auditable rather than merely asserted. If that ever changes, your rate card will show the price before an invoice does.
• user.id is a daily-rotating SHA-256 hash — no buyeruid, IP, or device id.
• lmt: 1 and regs.ext.gdpr: 1 are always set.

The bid response Profila expects

Return a standard BidResponse. The winning creative is read from bid.ext, or from a Native 1.2 adm JSON if you prefer to send one:

{
  "id": "<same request id>",
  "cur": "USD",
  "seatbid": [{
    "seat": "your-seat",
    "bid": [{
      "id": "b1", "impid": "1", "price": 6.5,
      "adomain": ["bmw.com"],
      "crid": "creative-123",
      "ext": {
        "title": "BMW iX — all-electric SAV",
        "description": "Up to 600 km range. Book a test drive.",
        "imageUrl": "https://www.bmw.com/…/bmw-ix.png",
        "clickUrl": "https://www.bmw.com/en/all-models/bmw-i/ix",
        "cta": "Configure yours",
        "sponsoredBy": "BMW"
      }
    }]
  }]
}

Empty seatbid (or HTTP 204) to no-bid. Profila validates the bid against the signal — brand domain for brand_specific, IAB category otherwise — logs it, and renders the winner in the consumer's feed. HTTPS only, no redirects followed on the bid call, capped response size.

Values and counters

What's sent, what's never sent

Enforced in the bid-request builder and creative-ingest path, and asserted by automated tests. Every consumer sees, in-app, exactly what declared data was sent.