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 OpenRTB 2.6. You receive declared, privacy-safe targeting only — never names, emails, IPs, device ids, cookies, or precise location.

What's live today

The outbound auction only wakes once a brand registers and activates a bid endpoint. Until then the platform serves signals through its own content path and outbound counters read 0.

The vocabulary

Two directions, use either or both. Inbound — you pull matching signals and push creatives (REST or MCP). Outbound — Profila sends you OpenRTB bid requests.

From verified brand to first call

• Get verified. Your brand account must be verified. Request it at [email protected].
• Open the API tab. Brand portal → Customers → API (verified brands only).
• 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",
      "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-…",
    "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.

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}}}'

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.

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.
• 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:

{
  "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, logs it, and renders the winner in the consumer's feed. HTTPS only, no redirects, capped response size.

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.