> ## Documentation Index
> Fetch the complete documentation index at: https://docs.sapt.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Server-side conversions (CAPI)

> Send conversions to Meta's Conversions API server-side through Sapt, or connect a pixel-scoped CAPI token for your own integration.

Sapt can deliver conversions to Meta's Conversions API (CAPI) for you — server-side, deduped against your browser pixel, with customer data hashed before it leaves Sapt. You connect a pixel once, then either send conversions through the API or let Sapt fire them automatically from Shopify/Stripe and your tracked site.

There are two ways to power the pixel's token, and both are Meta-compliant:

* **OAuth-sourced** — Sapt derives the token from your connected Meta account. Nothing to paste.
* **Pasted token** — you generate a pixel-scoped CAPI token in Meta Events Manager and store it here. Use this when your pixel lives in a Business Manager that isn't the one you connected, or when you want an explicit, scoped token.

<Warning>
  Use a **pixel-scoped CAPI access token** (generated in Events Manager) — not a broad ad-account token. Meta's terms prohibit sharing general access tokens; a CAPI token tied to a single pixel is the supported credential for server events.
</Warning>

## Before you start

You need three things in place. The whole setup, end to end:

1. **An API key** — create one in your [Sapt dashboard](https://app.sapt.ai) under Account → API Keys (starts with `sapt_`). See [Authentication](/docs/mintlify/guides/authentication).
2. **Meta connected** to the project, with ads permissions — see [Connecting integrations](/docs/mintlify/api/connect-integrations). This is what lets Sapt discover your pixels.
3. **A pixel connected for CAPI** — steps 1–2 below.

Once connected, sending conversions (step 3) is a single call you can make from anywhere.

## 1. Find your pixel

List the Meta pixels discoverable through your connected Meta account:

```bash theme={null}
curl https://api.sapt.ai/projects/$PROJECT_ID/pixels \
  -H "Authorization: ApiKey sapt_your_api_key"
```

```json theme={null}
{
  "pixels": [
    { "id": "1234567890", "name": "My Pixel", "adAccountId": "act_…", "adAccountName": "Brand", "isActive": true, "lastFiredTime": "2026-06-20T…" }
  ],
  "adAccountsScanned": 2
}
```

If the list is empty, connect Meta with ads permissions first (see [Connecting integrations](/docs/mintlify/api/connect-integrations)), or create a pixel in Events Manager.

## 2. Connect the pixel

Pin a pixel for CAPI. Either paste a pixel-scoped token, or set `useOauthToken: true` to source it from your Meta connection.

```bash theme={null}
# Option A — paste a token generated in Events Manager
curl -X PUT https://api.sapt.ai/projects/$PROJECT_ID/capi-pixel \
  -H "Authorization: ApiKey sapt_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{ "pixelId": "1234567890", "accessToken": "EAAB…", "testEventCode": "TEST12345" }'

# Option B — use the connected Meta account as the token source
curl -X PUT https://api.sapt.ai/projects/$PROJECT_ID/capi-pixel \
  -H "Authorization: ApiKey sapt_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{ "pixelId": "1234567890", "useOauthToken": true }'
```

Check or remove the connection any time:

```bash theme={null}
curl https://api.sapt.ai/projects/$PROJECT_ID/capi-pixel \
  -H "Authorization: ApiKey sapt_your_api_key"
# → { "connected": true, "pixelId": "1234567890", "tokenSource": "paste", "testEventCode": "TEST12345", "updatedAt": "…" }

curl -X DELETE https://api.sapt.ai/projects/$PROJECT_ID/capi-pixel \
  -H "Authorization: ApiKey sapt_your_api_key"
```

The access token is **never** returned by `GET /capi-pixel`.

<Note>
  **Generating a pixel-scoped token in Events Manager:** open [Events Manager](https://business.facebook.com/events_manager2), pick your pixel → **Settings** → **Conversions API** → **Generate access token**. That token is scoped to the one pixel — paste it into `accessToken` above.
</Note>

## 3. Send a conversion

Send a conversion server-side. Sapt hashes the customer data and delivers it to Meta.

```bash theme={null}
curl -X POST https://api.sapt.ai/projects/$PROJECT_ID/conversions \
  -H "Authorization: ApiKey sapt_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "kind": "Purchase",
    "value": 49.99,
    "currency": "USD",
    "email": "buyer@example.com",
    "eventId": "your-order-id-123"
  }'
```

```json theme={null}
{ "eventId": "your-order-id-123" }
```

* **`kind`** — one of `Lead`, `Purchase`, `CompleteRegistration`, `AddToCart`, `InitiateCheckout`, `ViewContent`, `Subscribe`, `PageView`.
* **`eventId`** — send the **same** id from your browser pixel (`fbq`) so Meta dedupes the browser and server events. If you omit it, Sapt mints one and returns it in the response.
* Other optional fields: `value`, `currency`, `phone`, `visitorId`, `personId`, `sourceUrl`.

A `202` means the conversion was accepted and queued for delivery. Connect a pixel first (step 2) — events sent without a connected pixel are dropped.

## 4. Verify with a test event

Fire a synthetic event and watch for it in Events Manager → **Test Events**:

```bash theme={null}
curl -X POST https://api.sapt.ai/projects/$PROJECT_ID/capi-pixel/test-event \
  -H "Authorization: ApiKey sapt_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{ "eventName": "Lead", "testEventCode": "TEST12345" }'
# → { "eventId": "…", "eventName": "Lead" }
```

## Keep going

<CardGroup cols={2}>
  <Card title="Connecting integrations" href="/docs/mintlify/api/connect-integrations" description="Connect Meta and other providers over the API." />

  <Card title="REST API Reference" href="/docs/mintlify/api/overview" description="Full endpoint reference for pixels, capi-pixel, and conversions." />

  <Card title="Ads" href="/docs/mintlify/platform/ads" description="What server-side conversions improve." />
</CardGroup>