# Ads: accounts & measurement API

> Ad accounts, account-level ad management, tracking tags, lead gen, product catalogs and conversions.

Base URL: `https://api.socialit.com/v1`. Authenticate with `Authorization: Bearer <API key or OAuth token>`.

## Update an ads connection

`PATCH /ads/connections/{connectionId}`

Changes the local label of an ads connection or moves it (and its ad accounts) to another profile.

Access: `write` · MCP tool: `update-ad-connection`

### Path parameters

- `connectionId` (string; required; 1–80 characters): Ads connection id (adc_…)

### Body

- `name` (string | null; ≤ 100 characters)
- `profile_id` (string | null; ≤ 80 characters)

```bash
curl -X PATCH "https://api.socialit.com/v1/ads/connections/adc_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd" \
  -H "Authorization: Bearer $SOCIALIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "string",
    "profile_id": "string"
  }'
```

Response 200:

```json
{
  "object": "ad_connection",
  "id": "string",
  "platform": "string",
  "connect_flow": "string",
  "profile_id": "string",
  "social_account_id": "string",
  "external_user_id": "string",
  "name": "string",
  "display_name": "string",
  "avatar_url": "https://example.com",
  "status": "active",
  "scopes": [
    "string"
  ],
  "token_expires_at": "2026-10-13T09:00:00.000Z",
  "metadata": {},
  "ad_account_count": 1,
  "sync": {
    "status": "string",
    "error": "string",
    "last_synced_at": "2026-10-13T09:00:00.000Z",
    "initial_sync_completed_at": "2026-10-13T09:00:00.000Z"
  },
  "last_discovered_at": "2026-10-13T09:00:00.000Z",
  "created_at": "2026-10-13T09:00:00.000Z",
  "updated_at": "2026-10-13T09:00:00.000Z"
}
```

## Re-discover ad accounts

`POST /ads/connections/{connectionId}/discover`

Lists the ad accounts the connection reaches on the network now: new ones are added (selected), vanished ones become closed.

Access: `write` · MCP tool: `discover-ad-connection-accounts`

### Path parameters

- `connectionId` (string; required; 1–80 characters): Ads connection id (adc_…)

```bash
curl -X POST "https://api.socialit.com/v1/ads/connections/adc_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd/discover" \
  -H "Authorization: Bearer $SOCIALIT_API_KEY"
```

Response 200:

```json
{
  "object": "list",
  "data": [
    {
      "object": "ad_account",
      "id": "string",
      "connection_id": "string",
      "profile_id": "string",
      "platform": "string",
      "external_id": "string",
      "name": "string",
      "currency": "USD",
      "timezone": "Europe/Prague",
      "status": "string",
      "platform_status": "string",
      "business_id": "string",
      "business_name": "string",
      "manager_customer_id": "string",
      "is_manager": true,
      "is_test": true,
      "selected": true,
      "selectable": true,
      "unusable_reason": "string",
      "billing_status": "string",
      "metadata": {},
      "last_discovered_at": "2026-10-13T09:00:00.000Z",
      "last_synced_at": "2026-10-13T09:00:00.000Z",
      "created_at": "2026-10-13T09:00:00.000Z",
      "updated_at": "2026-10-13T09:00:00.000Z"
    }
  ],
  "page": 1,
  "limit": 1,
  "total": 1,
  "has_more": true,
  "next_page_url": "https://example.com",
  "previous_page_url": "https://example.com"
}
```

## List business portfolios

`GET /ads/connections/{connectionId}/businesses`

Meta business portfolios the connected user belongs to, with their verification status.

Access: `read` · MCP tool: `list-ad-businesses` · Zernio: `GET /v1/ads/businesses`

### Path parameters

- `connectionId` (string; required; 1–80 characters): Ads connection id (adc_…)

### Query parameters

- `limit` (integer; 1–100): Items per page (max 100)
- `cursor` (string; ≤ 4096 characters): next_cursor from the previous page
- `after` (string; ≤ 4096 characters): Alias of cursor

```bash
curl "https://api.socialit.com/v1/ads/connections/adc_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd/businesses" \
  -H "Authorization: Bearer $SOCIALIT_API_KEY"
```

Response 200:

```json
{
  "object": "list",
  "data": [
    {
      "object": "business",
      "id": "string",
      "name": "string",
      "verification_status": "string",
      "created_at": "2026-10-13T09:00:00.000Z",
      "permitted_tasks": [
        "string"
      ]
    }
  ],
  "page": 1,
  "limit": 1,
  "total": 1,
  "has_more": true,
  "next_page_url": "https://example.com",
  "previous_page_url": "https://example.com",
  "next_cursor": "string"
}
```

## List business users

`GET /ads/connections/{connectionId}/businesses/{businessId}/users`

People and system users of a Meta business portfolio (the ids to assign to Pages, ad accounts and pixels).

Access: `read` · MCP tool: `list-ad-business-users` · Zernio: `GET /v1/ads/businesses/users`

### Path parameters

- `connectionId` (string; required; 1–80 characters): Ads connection id (adc_…)
- `businessId` (string; required; 1–256 characters)

```bash
curl "https://api.socialit.com/v1/ads/connections/adc_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd/businesses/BUSINESS_ID/users" \
  -H "Authorization: Bearer $SOCIALIT_API_KEY"
```

Response 200:

```json
{
  "object": "list",
  "data": [
    {
      "object": "business_user",
      "id": "string",
      "name": "string",
      "email": "you@example.com",
      "role": "string",
      "type": "string"
    }
  ],
  "page": 1,
  "limit": 1,
  "total": 1,
  "has_more": true,
  "next_page_url": "https://example.com",
  "previous_page_url": "https://example.com",
  "next_cursor": "string"
}
```

## List TikTok Business Centers

`GET /ads/connections/{connectionId}/business-centers`

The TikTok Business Centers the connection can read, with their advertiser counts.

Access: `read` · MCP tool: `list-ad-business-centers` · Zernio: `GET /v1/ads/business-centers`

### Path parameters

- `connectionId` (string; required; 1–80 characters): Ads connection id (adc_…)

```bash
curl "https://api.socialit.com/v1/ads/connections/adc_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd/business-centers" \
  -H "Authorization: Bearer $SOCIALIT_API_KEY"
```

Response 200:

```json
{
  "object": "list",
  "data": [
    {
      "object": "business_center",
      "id": "string",
      "name": "string",
      "advertiser_count": 1,
      "role": "string"
    }
  ],
  "page": 1,
  "limit": 1,
  "total": 1,
  "has_more": true,
  "next_page_url": "https://example.com",
  "previous_page_url": "https://example.com",
  "next_cursor": "string"
}
```

## List Page users

`GET /ads/connections/{connectionId}/pages/{pageId}/users`

People of a business portfolio assigned to a Facebook Page.

Access: `read` · MCP tool: `list-ad-page-users` · Zernio: `GET /v1/ads/page-users`

### Path parameters

- `connectionId` (string; required; 1–80 characters): Ads connection id (adc_…)
- `pageId` (string; required; 1–256 characters)

### Query parameters

- `business_id` (string; required; 1–64 characters)

```bash
curl "https://api.socialit.com/v1/ads/connections/adc_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd/pages/PAGE_ID/users?business_id=value" \
  -H "Authorization: Bearer $SOCIALIT_API_KEY"
```

Response 200:

```json
{
  "object": "list",
  "data": [
    {
      "object": "page_user",
      "id": "string",
      "page_id": "string",
      "name": "string",
      "tasks": [
        "string"
      ]
    }
  ],
  "page": 1,
  "limit": 1,
  "total": 1,
  "has_more": true,
  "next_page_url": "https://example.com",
  "previous_page_url": "https://example.com",
  "next_cursor": "string"
}
```

## Assign a user to a Page

`POST /ads/connections/{connectionId}/pages/{pageId}/users`

Gives a business user tasks on a Facebook Page (replaces their task set). ADVERTISE is what ad creation needs.

Access: `admin` · MCP tool: `assign-ad-page-user` · Zernio: `POST /v1/ads/page-users`

### Path parameters

- `connectionId` (string; required; 1–80 characters): Ads connection id (adc_…)
- `pageId` (string; required; 1–256 characters)

### Headers

- `Idempotency-Key` (string; ≤ 255 characters): Unique key (for example a UUID) that makes retries safe: a repeated request with the same key and body returns the first response (Idempotent-Replayed: true) for 24 hours.

### Body

- `business_id` (string; required; 1–64 characters)
- `user_id` (string; required; 1–64 characters)
- `tasks` (array of string; required; ≥ 1 items)

```bash
curl -X POST "https://api.socialit.com/v1/ads/connections/adc_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd/pages/PAGE_ID/users" \
  -H "Authorization: Bearer $SOCIALIT_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "business_id": "string",
    "user_id": "string",
    "tasks": [
      "MANAGE"
    ]
  }'
```

Response 201:

```json
{
  "object": "page_user",
  "id": "string",
  "page_id": "string",
  "name": "string",
  "tasks": [
    "string"
  ]
}
```

## Remove a user from a Page

`DELETE /ads/connections/{connectionId}/pages/{pageId}/users/{userId}`

Access: `admin` · MCP tool: `remove-ad-page-user` · Zernio: `DELETE /v1/ads/page-users`

### Path parameters

- `connectionId` (string; required; 1–80 characters): Ads connection id (adc_…)
- `pageId` (string; required; 1–256 characters)
- `userId` (string; required; 1–256 characters)

### Query parameters

- `business_id` (string; 1–64 characters)

```bash
curl -X DELETE "https://api.socialit.com/v1/ads/connections/adc_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd/pages/PAGE_ID/users/USER_ID" \
  -H "Authorization: Bearer $SOCIALIT_API_KEY"
```

Response 200:

```json
{
  "object": "page_user",
  "id": "string",
  "deleted": true
}
```

## Get the Google Ads manager hierarchy

`GET /ads/connections/{connectionId}/hierarchy`

Live manager (MCC) and client tree of a Google Ads connection, with pending invitations and link status.

Access: `read` · MCP tool: `get-ad-manager-hierarchy` · Zernio: `GET /v1/ads/accounts/hierarchy`

### Path parameters

- `connectionId` (string; required; 1–80 characters): Ads connection id (adc_…)

```bash
curl "https://api.socialit.com/v1/ads/connections/adc_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd/hierarchy" \
  -H "Authorization: Bearer $SOCIALIT_API_KEY"
```

Response 200:

```json
{
  "object": "manager_hierarchy",
  "connection_id": "string",
  "roots": [
    {
      "customer_id": "string",
      "name": "string",
      "currency": "USD",
      "time_zone": "string",
      "manager": true,
      "test_account": true,
      "status": "string",
      "manager_links": [
        {
          "manager_customer_id": "string",
          "manager_link_id": "string",
          "status": "string"
        }
      ],
      "clients": [
        {
          "customer_id": "string",
          "name": "string",
          "currency": "USD",
          "time_zone": "string",
          "manager": true,
          "test_account": true
        }
      ]
    }
  ],
  "direct_customers": [
    {
      "customer_id": "string",
      "manager": true,
      "pending_invitations": [
        {
          "manager_customer_id": "string",
          "manager_link_id": "string"
        }
      ]
    }
  ],
  "unavailable": [
    {
      "customer_id": "string",
      "reason": "string"
    }
  ],
  "truncated": true
}
```

## Invite a client account to a manager

`POST /ads/connections/{connectionId}/manager-links`

Sends a manager-to-client link invitation (Google Ads). The link stays PENDING until the client accepts.

Access: `admin` · MCP tool: `create-ad-manager-link` · Zernio: `POST /v1/ads/accounts/manager-links`

### Path parameters

- `connectionId` (string; required; 1–80 characters): Ads connection id (adc_…)

### Headers

- `Idempotency-Key` (string; ≤ 255 characters): Unique key (for example a UUID) that makes retries safe: a repeated request with the same key and body returns the first response (Idempotent-Replayed: true) for 24 hours.

### Body

- `manager_customer_id` (string; required; 1–20 characters)
- `client_customer_id` (string; required; 1–20 characters)
- `validate_only` (boolean)

```bash
curl -X POST "https://api.socialit.com/v1/ads/connections/adc_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd/manager-links" \
  -H "Authorization: Bearer $SOCIALIT_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "manager_customer_id": "string",
    "client_customer_id": "string",
    "validate_only": true
  }'
```

Response 201:

```json
{
  "object": "manager_link",
  "manager_customer_id": "string",
  "client_customer_id": "string",
  "manager_link_id": "string",
  "status": "string",
  "validate_only": true
}
```

## Accept, decline, cancel or end a manager link

`PATCH /ads/connections/{connectionId}/manager-links/{managerLinkId}`

Access: `admin` · MCP tool: `update-ad-manager-link` · Zernio: `PATCH /v1/ads/accounts/manager-links`

### Path parameters

- `connectionId` (string; required; 1–80 characters): Ads connection id (adc_…)
- `managerLinkId` (string; required; 1–256 characters)

### Body

- `manager_customer_id` (string; required; 1–20 characters)
- `client_customer_id` (string; required; 1–20 characters)
- `action` (string; required; one of accept, decline, cancel, unlink)
- `validate_only` (boolean)

```bash
curl -X PATCH "https://api.socialit.com/v1/ads/connections/adc_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd/manager-links/MANAGER_LINK_ID" \
  -H "Authorization: Bearer $SOCIALIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "manager_customer_id": "string",
    "client_customer_id": "string",
    "action": "accept",
    "validate_only": true
  }'
```

Response 200:

```json
{
  "object": "manager_link",
  "manager_customer_id": "string",
  "client_customer_id": "string",
  "manager_link_id": "string",
  "status": "string",
  "validate_only": true
}
```

## List ad accounts

`GET /ads/accounts`

The platform ad accounts reached by the workspace ads connections. refresh=true re-discovers the matching connections live first.

Access: `read` · MCP tool: `list-ad-accounts` · Zernio: `GET /v1/ads/accounts`

### Query parameters

- `page` (integer; ≥ 1)
- `limit` (integer; 1–100)
- `connection_id` (string; 1–80 characters)
- `platform` (string; 1–40 characters)
- `profile_id` (string; 1–80 characters)
- `status` (string; one of active, pending, disabled, closed, unknown)
- `selected` (boolean)
- `external_id` (string; 1–256 characters)
- `search` (string; 1–200 characters)
- `refresh` (boolean)
- `in_scope_only` (boolean)
- `sort` (string; one of name, created_at, platform, status)
- `order` (string; one of asc, desc)

```bash
curl "https://api.socialit.com/v1/ads/accounts" \
  -H "Authorization: Bearer $SOCIALIT_API_KEY"
```

Response 200:

```json
{
  "object": "list",
  "data": [
    {
      "object": "ad_account",
      "id": "string",
      "connection_id": "string",
      "profile_id": "string",
      "platform": "string",
      "external_id": "string",
      "name": "string",
      "currency": "USD",
      "timezone": "Europe/Prague",
      "status": "string",
      "platform_status": "string",
      "business_id": "string",
      "business_name": "string",
      "manager_customer_id": "string",
      "is_manager": true,
      "is_test": true,
      "selected": true,
      "selectable": true,
      "unusable_reason": "string",
      "billing_status": "string",
      "metadata": {},
      "last_discovered_at": "2026-10-13T09:00:00.000Z",
      "last_synced_at": "2026-10-13T09:00:00.000Z",
      "created_at": "2026-10-13T09:00:00.000Z",
      "updated_at": "2026-10-13T09:00:00.000Z"
    }
  ],
  "page": 1,
  "limit": 1,
  "total": 1,
  "has_more": true,
  "next_page_url": "https://example.com",
  "previous_page_url": "https://example.com"
}
```

## Create a Meta ad account

`POST /ads/accounts`

Creates an ad account in a Meta business portfolio (a payment method must then be added in Ads Manager).

Access: `admin` · MCP tool: `create-ad-account` · Zernio: `POST /v1/ads/accounts`

### Headers

- `Idempotency-Key` (string; ≤ 255 characters): Unique key (for example a UUID) that makes retries safe: a repeated request with the same key and body returns the first response (Idempotent-Replayed: true) for 24 hours.

### Body

- `connection_id` (string; required; 1–80 characters)
- `business_id` (string; required; 1–64 characters)
- `name` (string; required; 1–100 characters)
- `currency` (string; required; pattern ^[A-Za-z]{3}$)
- `timezone_id` (integer; required)
- `end_advertiser` (string; 1–64 characters)
- `media_agency` (string; 1–64 characters)
- `partner` (string; 1–64 characters)
- `invoice` (boolean)
- `invoice_group_id` (string; 1–64 characters)
- `invoicing_emails` (array of string (email); ≤ 20 items)
- `io` (boolean)
- `po_number` (string; 1–64 characters)
- `funding_id` (string; 1–64 characters)

```bash
curl -X POST "https://api.socialit.com/v1/ads/accounts" \
  -H "Authorization: Bearer $SOCIALIT_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "connection_id": "string",
    "business_id": "string",
    "name": "string",
    "currency": "USD",
    "timezone_id": 0
  }'
```

Response 201:

```json
{
  "object": "ad_account",
  "id": "string",
  "connection_id": "string",
  "profile_id": "string",
  "platform": "string",
  "external_id": "string",
  "name": "string",
  "currency": "USD",
  "timezone": "Europe/Prague",
  "status": "string",
  "platform_status": "string",
  "business_id": "string",
  "business_name": "string",
  "manager_customer_id": "string",
  "is_manager": true,
  "is_test": true,
  "selected": true,
  "selectable": true,
  "unusable_reason": "string",
  "billing_status": "string",
  "metadata": {},
  "last_discovered_at": "2026-10-13T09:00:00.000Z",
  "last_synced_at": "2026-10-13T09:00:00.000Z",
  "created_at": "2026-10-13T09:00:00.000Z",
  "updated_at": "2026-10-13T09:00:00.000Z",
  "payment_method_required": true,
  "ads_manager_url": "https://example.com",
  "next_steps": "string",
  "warnings": [
    "string"
  ]
}
```

## Get an ad account

`GET /ads/accounts/{adAccountId}`

Access: `read` · MCP tool: `get-ad-account`

### Path parameters

- `adAccountId` (string; required; 1–80 characters): Ad account id (ada_…)

```bash
curl "https://api.socialit.com/v1/ads/accounts/ada_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd" \
  -H "Authorization: Bearer $SOCIALIT_API_KEY"
```

Response 200:

```json
{
  "object": "ad_account",
  "id": "string",
  "connection_id": "string",
  "profile_id": "string",
  "platform": "string",
  "external_id": "string",
  "name": "string",
  "currency": "USD",
  "timezone": "Europe/Prague",
  "status": "string",
  "platform_status": "string",
  "business_id": "string",
  "business_name": "string",
  "manager_customer_id": "string",
  "is_manager": true,
  "is_test": true,
  "selected": true,
  "selectable": true,
  "unusable_reason": "string",
  "billing_status": "string",
  "metadata": {},
  "last_discovered_at": "2026-10-13T09:00:00.000Z",
  "last_synced_at": "2026-10-13T09:00:00.000Z",
  "created_at": "2026-10-13T09:00:00.000Z",
  "updated_at": "2026-10-13T09:00:00.000Z"
}
```

## Select or move an ad account

`PATCH /ads/accounts/{adAccountId}`

Local settings: selected (managed, synced, billed) and profile_id.

Access: `write` · MCP tool: `update-ad-account`

### Path parameters

- `adAccountId` (string; required; 1–80 characters): Ad account id (ada_…)

### Body

- `selected` (boolean)
- `profile_id` (string | null; ≤ 80 characters)

```bash
curl -X PATCH "https://api.socialit.com/v1/ads/accounts/ada_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd" \
  -H "Authorization: Bearer $SOCIALIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "selected": true,
    "profile_id": "string"
  }'
```

Response 200:

```json
{
  "object": "ad_account",
  "id": "string",
  "connection_id": "string",
  "profile_id": "string",
  "platform": "string",
  "external_id": "string",
  "name": "string",
  "currency": "USD",
  "timezone": "Europe/Prague",
  "status": "string",
  "platform_status": "string",
  "business_id": "string",
  "business_name": "string",
  "manager_customer_id": "string",
  "is_manager": true,
  "is_test": true,
  "selected": true,
  "selectable": true,
  "unusable_reason": "string",
  "billing_status": "string",
  "metadata": {},
  "last_discovered_at": "2026-10-13T09:00:00.000Z",
  "last_synced_at": "2026-10-13T09:00:00.000Z",
  "created_at": "2026-10-13T09:00:00.000Z",
  "updated_at": "2026-10-13T09:00:00.000Z"
}
```

## Update ad account settings on the network

`PATCH /ads/accounts/{adAccountId}/settings`

Meta: name, spend cap, amount-spent reset, default DSA beneficiary / payor. Google: account tracking template and final URL suffix.

Access: `write` · MCP tool: `update-ad-account-settings` · Zernio: `PATCH /v1/ads/accounts`

### Path parameters

- `adAccountId` (string; required; 1–80 characters): Ad account id (ada_…)

### Body

- `name` (string; 1–100 characters)
- `spend_cap` (number | null)
- `reset_amount_spent` (boolean)
- `default_dsa_beneficiary` (string; 1–512 characters)
- `default_dsa_payor` (string; 1–512 characters)
- `tracking_url_template` (string; ≤ 2048 characters)
- `final_url_suffix` (string; ≤ 2048 characters)

```bash
curl -X PATCH "https://api.socialit.com/v1/ads/accounts/ada_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd/settings" \
  -H "Authorization: Bearer $SOCIALIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "string",
    "spend_cap": 0,
    "reset_amount_spent": true,
    "default_dsa_beneficiary": "string",
    "default_dsa_payor": "string"
  }'
```

Response 200:

```json
{
  "object": "ad_account_settings",
  "ad_account_id": "string",
  "platform": "string",
  "name": "string",
  "spend_cap": 1.5,
  "url_tracking": {
    "tracking_url_template": "string",
    "final_url_suffix": "string"
  },
  "dsa_defaults": {
    "beneficiary": "string",
    "payor": "string"
  },
  "finance": {
    "object": "ad_account_finance",
    "ad_account_id": "string",
    "currency": "USD",
    "balance": 1.5,
    "amount_spent": 1.5,
    "spend_cap": 1.5,
    "funding_source": {
      "display_string": "string",
      "type": 1.5
    }
  }
}
```

## Get ad account finances

`GET /ads/accounts/{adAccountId}/finance`

Balance, total spend, spend cap and funding source (Meta).

Access: `read` · MCP tool: `get-ad-account-finance` · Zernio: `GET /v1/ads/accounts/finance`

### Path parameters

- `adAccountId` (string; required; 1–80 characters): Ad account id (ada_…)

```bash
curl "https://api.socialit.com/v1/ads/accounts/ada_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd/finance" \
  -H "Authorization: Bearer $SOCIALIT_API_KEY"
```

Response 200:

```json
{
  "object": "ad_account_finance",
  "ad_account_id": "string",
  "currency": "USD",
  "balance": 1.5,
  "amount_spent": 1.5,
  "spend_cap": 1.5,
  "funding_source": {
    "display_string": "string",
    "type": 1.5
  }
}
```

## Read campaigns and ad sets live

`GET /ads/accounts/{adAccountId}/live`

Reads campaigns and ad sets straight from the network (Meta, TikTok), e.g. to check budgets before a write.

Access: `read` · MCP tool: `get-ad-account-live` · Zernio: `GET /v1/ads/accounts/live`

### Path parameters

- `adAccountId` (string; required; 1–80 characters): Ad account id (ada_…)

### Query parameters

- `status` (string; 1–200 characters)
- `level` (string; one of campaign, ad_set)
- `limit` (integer; 1–200)
- `campaigns_cursor` (string; 1–4096 characters)
- `ad_sets_cursor` (string; 1–4096 characters)

```bash
curl "https://api.socialit.com/v1/ads/accounts/ada_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd/live" \
  -H "Authorization: Bearer $SOCIALIT_API_KEY"
```

Response 200:

```json
{
  "object": "ad_account_live",
  "ad_account_id": "string",
  "platform": "string",
  "currency": "USD",
  "read_at": "2026-10-13T09:00:00.000Z",
  "campaigns": [
    {
      "id": "string",
      "name": "string",
      "status": "string",
      "platform_status": "string",
      "configured_status": "string",
      "budget": {
        "amount": 1.5,
        "type": "string"
      },
      "daily_budget": 1.5,
      "lifetime_budget": 1.5,
      "budget_remaining": 1.5,
      "bid_strategy": "string",
      "spend_cap": 1.5
    }
  ],
  "ad_sets": [
    {
      "id": "string",
      "name": "string",
      "status": "string",
      "platform_status": "string",
      "configured_status": "string",
      "budget": {
        "amount": 1.5,
        "type": "string"
      },
      "daily_budget": 1.5,
      "lifetime_budget": 1.5,
      "budget_remaining": 1.5,
      "bid_strategy": "string",
      "campaign_id": "string",
      "bid_amount": 1.5,
      "optimization_goal": "string",
      "billing_event": "string",
      "promoted_object": {},
      "targeting": {},
      "start_time": "2026-10-13T09:00:00.000Z",
      "end_time": "2026-10-13T09:00:00.000Z"
    }
  ],
  "next_cursors": {
    "campaigns": "string",
    "ad_sets": "string"
  }
}
```

## Get DSA defaults

`GET /ads/accounts/{adAccountId}/dsa-defaults`

Access: `read` · MCP tool: `get-ad-account-dsa-defaults` · Zernio: `GET /v1/ads/dsa-defaults`

### Path parameters

- `adAccountId` (string; required; 1–80 characters): Ad account id (ada_…)

```bash
curl "https://api.socialit.com/v1/ads/accounts/ada_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd/dsa-defaults" \
  -H "Authorization: Bearer $SOCIALIT_API_KEY"
```

Response 200:

```json
{
  "object": "dsa_defaults",
  "ad_account_id": "string",
  "beneficiary": "string",
  "payor": "string"
}
```

## Get DSA recommendations

`GET /ads/accounts/{adAccountId}/dsa-recommendations`

Suggested beneficiary / payor names for EU DSA disclosures (never applied automatically).

Access: `read` · MCP tool: `get-ad-account-dsa-recommendations` · Zernio: `GET /v1/ads/dsa-recommendations`

### Path parameters

- `adAccountId` (string; required; 1–80 characters): Ad account id (ada_…)

```bash
curl "https://api.socialit.com/v1/ads/accounts/ada_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd/dsa-recommendations" \
  -H "Authorization: Bearer $SOCIALIT_API_KEY"
```

Response 200:

```json
{
  "object": "dsa_recommendations",
  "ad_account_id": "string",
  "recommendations": [
    "string"
  ]
}
```

## List ad account users

`GET /ads/accounts/{adAccountId}/users`

Access: `read` · MCP tool: `list-ad-account-users` · Zernio: `GET /v1/ads/accounts/users`

### Path parameters

- `adAccountId` (string; required; 1–80 characters): Ad account id (ada_…)

### Query parameters

- `business_id` (string; 1–64 characters)

```bash
curl "https://api.socialit.com/v1/ads/accounts/ada_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd/users" \
  -H "Authorization: Bearer $SOCIALIT_API_KEY"
```

Response 200:

```json
{
  "object": "list",
  "data": [
    {
      "object": "ad_account_user",
      "id": "string",
      "name": "string",
      "email": "you@example.com",
      "role": "string",
      "tasks": [
        "string"
      ]
    }
  ],
  "page": 1,
  "limit": 1,
  "total": 1,
  "has_more": true,
  "next_page_url": "https://example.com",
  "previous_page_url": "https://example.com",
  "next_cursor": "string"
}
```

## Assign a user to an ad account

`POST /ads/accounts/{adAccountId}/users`

MANAGE = admin, ADVERTISE creates ads, ANALYZE reads reports, DRAFT edits drafts. Replaces the user’s task set.

Access: `admin` · MCP tool: `assign-ad-account-user` · Zernio: `POST /v1/ads/accounts/users`

### Path parameters

- `adAccountId` (string; required; 1–80 characters): Ad account id (ada_…)

### Headers

- `Idempotency-Key` (string; ≤ 255 characters): Unique key (for example a UUID) that makes retries safe: a repeated request with the same key and body returns the first response (Idempotent-Replayed: true) for 24 hours.

### Body

- `user_id` (string; required; 1–64 characters)
- `tasks` (array of string; required; ≥ 1 items)
- `business_id` (string; 1–64 characters)

```bash
curl -X POST "https://api.socialit.com/v1/ads/accounts/ada_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd/users" \
  -H "Authorization: Bearer $SOCIALIT_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "user_id": "string",
    "tasks": [
      "MANAGE"
    ],
    "business_id": "string"
  }'
```

Response 201:

```json
{
  "object": "ad_account_user",
  "id": "string",
  "name": "string",
  "email": "you@example.com",
  "role": "string",
  "tasks": [
    "string"
  ]
}
```

## Remove a user from an ad account

`DELETE /ads/accounts/{adAccountId}/users/{userId}`

Access: `admin` · MCP tool: `remove-ad-account-user` · Zernio: `DELETE /v1/ads/accounts/users`

### Path parameters

- `adAccountId` (string; required; 1–80 characters): Ad account id (ada_…)
- `userId` (string; required; 1–256 characters)

```bash
curl -X DELETE "https://api.socialit.com/v1/ads/accounts/ada_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd/users/USER_ID" \
  -H "Authorization: Bearer $SOCIALIT_API_KEY"
```

Response 200:

```json
{
  "object": "ad_account_user",
  "id": "string",
  "deleted": true
}
```

## Ad account change log

`GET /ads/accounts/{adAccountId}/activity`

Who changed what and when (Meta activities, Google change history: last 30 days).

Access: `read` · MCP tool: `list-ad-account-activity` · Zernio: `GET /v1/ads/activity`

### Path parameters

- `adAccountId` (string; required; 1–80 characters): Ad account id (ada_…)

### Query parameters

- `since` (string; pattern ^\d{4}-\d{2}-\d{2}$): YYYY-MM-DD
- `until` (string; pattern ^\d{4}-\d{2}-\d{2}$): YYYY-MM-DD
- `object_id` (string; 1–64 characters)
- `limit` (integer; 1–100): Items per page (max 100)
- `cursor` (string; ≤ 4096 characters): next_cursor from the previous page
- `after` (string; ≤ 4096 characters): Alias of cursor

```bash
curl "https://api.socialit.com/v1/ads/accounts/ada_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd/activity" \
  -H "Authorization: Bearer $SOCIALIT_API_KEY"
```

Response 200:

```json
{
  "object": "list",
  "data": [
    {
      "object": "ad_activity",
      "id": "string",
      "event_type": "string",
      "event_time": "2026-10-13T09:00:00.000Z",
      "actor_id": "string",
      "actor_name": "string",
      "object_type": "string",
      "object_id": "string",
      "object_name": "string",
      "application_name": "string",
      "translated_event_type": "string",
      "extra_data": {}
    }
  ],
  "page": 1,
  "limit": 1,
  "total": 1,
  "has_more": true,
  "next_page_url": "https://example.com",
  "previous_page_url": "https://example.com",
  "next_cursor": "string"
}
```

## List A/B tests and lift studies

`GET /ads/accounts/{adAccountId}/studies`

Access: `read` · MCP tool: `list-ad-studies` · Zernio: `GET /v1/ads/studies`

### Path parameters

- `adAccountId` (string; required; 1–80 characters): Ad account id (ada_…)

### Query parameters

- `fields` (string; 1–2000 characters)
- `limit` (integer; 1–100): Items per page (max 100)
- `cursor` (string; ≤ 4096 characters): next_cursor from the previous page
- `after` (string; ≤ 4096 characters): Alias of cursor

```bash
curl "https://api.socialit.com/v1/ads/accounts/ada_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd/studies" \
  -H "Authorization: Bearer $SOCIALIT_API_KEY"
```

Response 200:

```json
{
  "object": "list",
  "data": [
    {
      "object": "ad_study",
      "id": "string",
      "name": "string",
      "type": "string",
      "description": "string",
      "start_time": "2026-10-13T09:00:00.000Z",
      "end_time": "2026-10-13T09:00:00.000Z",
      "cells": [
        {}
      ],
      "raw": {}
    }
  ],
  "page": 1,
  "limit": 1,
  "total": 1,
  "has_more": true,
  "next_page_url": "https://example.com",
  "previous_page_url": "https://example.com",
  "next_cursor": "string"
}
```

## List Instagram ad identities

`GET /ads/accounts/{adAccountId}/instagram-accounts`

Access: `read` · MCP tool: `list-ad-instagram-accounts` · Zernio: `GET /v1/ads/instagram-accounts`

### Path parameters

- `adAccountId` (string; required; 1–80 characters): Ad account id (ada_…)

```bash
curl "https://api.socialit.com/v1/ads/accounts/ada_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd/instagram-accounts" \
  -H "Authorization: Bearer $SOCIALIT_API_KEY"
```

Response 200:

```json
{
  "object": "instagram_identities",
  "ad_account_id": "string",
  "accounts": [
    {
      "ig_user_id": "string",
      "username": "string",
      "profile_picture_url": "https://example.com",
      "is_page_backed": true,
      "source": "string"
    }
  ],
  "pages": [
    {
      "page_id": "string",
      "name": "string",
      "instagram_business_account": {
        "ig_user_id": "string",
        "username": "string",
        "profile_picture_url": "https://example.com"
      },
      "connected_instagram_account": {
        "ig_user_id": "string",
        "username": "string",
        "profile_picture_url": "https://example.com"
      }
    }
  ],
  "resolved": {
    "page_id": "string",
    "ig_user_id": "string",
    "source": "string"
  }
}
```

## List Instagram posts to boost

`GET /ads/accounts/{adAccountId}/instagram-posts`

Access: `read` · MCP tool: `list-ad-instagram-posts` · Zernio: `GET /v1/ads/instagram-posts`

### Path parameters

- `adAccountId` (string; required; 1–80 characters): Ad account id (ada_…)

### Query parameters

- `ig_user_id` (string; 1–64 characters)
- `limit` (integer; 1–100): Items per page (max 100)
- `cursor` (string; ≤ 4096 characters): next_cursor from the previous page
- `after` (string; ≤ 4096 characters): Alias of cursor

```bash
curl "https://api.socialit.com/v1/ads/accounts/ada_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd/instagram-posts" \
  -H "Authorization: Bearer $SOCIALIT_API_KEY"
```

Response 200:

```json
{
  "object": "list",
  "data": [
    {
      "object": "instagram_post",
      "id": "string",
      "caption": "string",
      "media_type": "string",
      "media_url": "https://example.com",
      "thumbnail_url": "https://example.com",
      "permalink": "string",
      "timestamp": "2026-10-13T09:00:00.000Z"
    }
  ],
  "page": 1,
  "limit": 1,
  "total": 1,
  "has_more": true,
  "next_page_url": "https://example.com",
  "previous_page_url": "https://example.com",
  "next_cursor": "string",
  "ig_user_id": "string",
  "username": "string"
}
```

## List advertisable apps

`GET /ads/accounts/{adAccountId}/advertisable-applications`

Access: `read` · MCP tool: `list-advertisable-applications` · Zernio: `GET /v1/ads/advertisable-applications`

### Path parameters

- `adAccountId` (string; required; 1–80 characters): Ad account id (ada_…)

```bash
curl "https://api.socialit.com/v1/ads/accounts/ada_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd/advertisable-applications" \
  -H "Authorization: Bearer $SOCIALIT_API_KEY"
```

Response 200:

```json
{
  "object": "list",
  "data": [
    {
      "object": "advertisable_application",
      "id": "string",
      "name": "string",
      "supported_platforms": [
        "string"
      ],
      "store_urls": {}
    }
  ],
  "page": 1,
  "limit": 1,
  "total": 1,
  "has_more": true,
  "next_page_url": "https://example.com",
  "previous_page_url": "https://example.com",
  "next_cursor": "string"
}
```

## Get iOS 14 campaign limits

`GET /ads/accounts/{adAccountId}/ios-campaign-limits`

Access: `read` · MCP tool: `get-ios-campaign-limits` · Zernio: `GET /v1/ads/ios-fourteen-campaign-limits`

### Path parameters

- `adAccountId` (string; required; 1–80 characters): Ad account id (ada_…)

### Query parameters

- `application_id` (string; required; 1–64 characters)

```bash
curl "https://api.socialit.com/v1/ads/accounts/ada_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd/ios-campaign-limits?application_id=value" \
  -H "Authorization: Bearer $SOCIALIT_API_KEY"
```

Response 200:

```json
{
  "object": "ios_campaign_limits",
  "application_id": "string",
  "campaign_group_limit": 1.5,
  "campaign_limit": 1.5,
  "details": [
    {}
  ]
}
```

## List TikTok pixels

`GET /ads/accounts/{adAccountId}/pixels`

TikTok pixels with their supported optimization events.

Access: `read` · MCP tool: `list-ad-pixels` · Zernio: `GET /v1/ads/pixels`

### Path parameters

- `adAccountId` (string; required; 1–80 characters): Ad account id (ada_…)

### Query parameters

- `code` (string; 1–64 characters)

```bash
curl "https://api.socialit.com/v1/ads/accounts/ada_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd/pixels" \
  -H "Authorization: Bearer $SOCIALIT_API_KEY"
```

Response 200:

```json
{
  "object": "list",
  "data": [
    {
      "object": "ad_pixel",
      "id": "string",
      "code": "string",
      "name": "string",
      "events": [
        "string"
      ],
      "event_details": [
        {
          "name": "string",
          "optimization_event": "string",
          "custom": true
        }
      ]
    }
  ],
  "page": 1,
  "limit": 1,
  "total": 1,
  "has_more": true,
  "next_page_url": "https://example.com",
  "previous_page_url": "https://example.com",
  "next_cursor": "string"
}
```

## List custom conversions

`GET /ads/accounts/{adAccountId}/custom-conversions`

Meta custom conversions of the ad account, archived included.

Access: `read` · MCP tool: `list-custom-conversions` · Zernio: `GET /v1/accounts/{accountId}/custom-conversions`

### Path parameters

- `adAccountId` (string; required; 1–80 characters): Ad account id (ada_…)

```bash
curl "https://api.socialit.com/v1/ads/accounts/ada_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd/custom-conversions" \
  -H "Authorization: Bearer $SOCIALIT_API_KEY"
```

Response 200:

```json
{
  "object": "list",
  "data": [
    {
      "object": "custom_conversion",
      "id": "string",
      "name": "string",
      "rule": {},
      "custom_event_type": "string",
      "pixel_id": "string",
      "is_archived": true,
      "default_conversion_value": 1.5,
      "reused": true
    }
  ],
  "page": 1,
  "limit": 1,
  "total": 1,
  "has_more": true,
  "next_page_url": "https://example.com",
  "previous_page_url": "https://example.com",
  "next_cursor": "string"
}
```

## Create a custom conversion

`POST /ads/accounts/{adAccountId}/custom-conversions`

Creates a Meta custom conversion, or returns the existing non-archived one with the same name on the same pixel (reused: true, 200).

Access: `write` · MCP tool: `create-custom-conversion` · Zernio: `POST /v1/accounts/{accountId}/custom-conversions`

### Path parameters

- `adAccountId` (string; required; 1–80 characters): Ad account id (ada_…)

### Headers

- `Idempotency-Key` (string; ≤ 255 characters): Unique key (for example a UUID) that makes retries safe: a repeated request with the same key and body returns the first response (Idempotent-Replayed: true) for 24 hours.

### Body

- `name` (string; required; 1–100 characters)
- `pixel_id` (string; required; 1–64 characters)
- `custom_event_type` (string; required; 1–64 characters)
- `rule` (object; required)
- `default_conversion_value` (number)

```bash
curl -X POST "https://api.socialit.com/v1/ads/accounts/ada_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd/custom-conversions" \
  -H "Authorization: Bearer $SOCIALIT_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "string",
    "pixel_id": "string",
    "custom_event_type": "string",
    "rule": {},
    "default_conversion_value": 1.5
  }'
```

Response 200:

```json
{
  "object": "custom_conversion",
  "id": "string",
  "name": "string",
  "rule": {},
  "custom_event_type": "string",
  "pixel_id": "string",
  "is_archived": true,
  "default_conversion_value": 1.5,
  "reused": true
}
```

## List ad labels

`GET /ads/accounts/{adAccountId}/labels`

Access: `read` · MCP tool: `list-ad-labels` · Zernio: `GET /v1/ads/labels`

### Path parameters

- `adAccountId` (string; required; 1–80 characters): Ad account id (ada_…)

### Query parameters

- `limit` (integer; 1–100): Items per page (max 100)
- `cursor` (string; ≤ 4096 characters): next_cursor from the previous page
- `after` (string; ≤ 4096 characters): Alias of cursor

```bash
curl "https://api.socialit.com/v1/ads/accounts/ada_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd/labels" \
  -H "Authorization: Bearer $SOCIALIT_API_KEY"
```

Response 200:

```json
{
  "object": "list",
  "data": [
    {
      "object": "ad_label",
      "id": "string",
      "name": "string",
      "status": "string",
      "background_color": "string",
      "description": "string",
      "resource_name": "string",
      "created_at": "2026-10-13T09:00:00.000Z",
      "updated_at": "2026-10-13T09:00:00.000Z"
    }
  ],
  "page": 1,
  "limit": 1,
  "total": 1,
  "has_more": true,
  "next_page_url": "https://example.com",
  "previous_page_url": "https://example.com",
  "next_cursor": "string"
}
```

## Create an ad label

`POST /ads/accounts/{adAccountId}/labels`

Access: `write` · MCP tool: `create-ad-label` · Zernio: `POST /v1/ads/labels`

### Path parameters

- `adAccountId` (string; required; 1–80 characters): Ad account id (ada_…)

### Headers

- `Idempotency-Key` (string; ≤ 255 characters): Unique key (for example a UUID) that makes retries safe: a repeated request with the same key and body returns the first response (Idempotent-Replayed: true) for 24 hours.

### Body

- `name` (string; required; 1–80 characters)
- `background_color` (string; pattern ^#[0-9A-Fa-f]{6}$)
- `description` (string; 1–200 characters)

```bash
curl -X POST "https://api.socialit.com/v1/ads/accounts/ada_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd/labels" \
  -H "Authorization: Bearer $SOCIALIT_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "string",
    "background_color": "string",
    "description": "string"
  }'
```

Response 201:

```json
{
  "object": "ad_label",
  "id": "string",
  "name": "string",
  "status": "string",
  "background_color": "string",
  "description": "string",
  "resource_name": "string",
  "created_at": "2026-10-13T09:00:00.000Z",
  "updated_at": "2026-10-13T09:00:00.000Z"
}
```

## Update an ad label

`PATCH /ads/accounts/{adAccountId}/labels/{labelId}`

Access: `write` · MCP tool: `update-ad-label` · Zernio: `PATCH /v1/ads/labels/{labelId}`

### Path parameters

- `adAccountId` (string; required; 1–80 characters): Ad account id (ada_…)
- `labelId` (string; required; 1–256 characters)

### Body

- `name` (string; 1–80 characters)
- `background_color` (string; pattern ^#[0-9A-Fa-f]{6}$)
- `description` (string; 1–200 characters)

```bash
curl -X PATCH "https://api.socialit.com/v1/ads/accounts/ada_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd/labels/LABEL_ID" \
  -H "Authorization: Bearer $SOCIALIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "string",
    "background_color": "string",
    "description": "string"
  }'
```

Response 200:

```json
{
  "object": "ad_label",
  "id": "string",
  "name": "string",
  "status": "string",
  "background_color": "string",
  "description": "string",
  "resource_name": "string",
  "created_at": "2026-10-13T09:00:00.000Z",
  "updated_at": "2026-10-13T09:00:00.000Z"
}
```

## Remove an ad label

`DELETE /ads/accounts/{adAccountId}/labels/{labelId}`

Access: `write` · MCP tool: `delete-ad-label` · Zernio: `DELETE /v1/ads/labels/{labelId}`

### Path parameters

- `adAccountId` (string; required; 1–80 characters): Ad account id (ada_…)
- `labelId` (string; required; 1–256 characters)

```bash
curl -X DELETE "https://api.socialit.com/v1/ads/accounts/ada_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd/labels/LABEL_ID" \
  -H "Authorization: Bearer $SOCIALIT_API_KEY"
```

Response 200:

```json
{
  "object": "ad_label",
  "id": "string",
  "deleted": true
}
```

## Attach a label

`POST /ads/accounts/{adAccountId}/labels/{labelId}/assignments`

Attaches a Google Ads label to campaigns, ad groups, ads and keywords; targets that already carry it count as unchanged.

Access: `write` · MCP tool: `attach-ad-label` · Zernio: `POST /v1/ads/labels/{labelId}/assignments`

### Path parameters

- `adAccountId` (string; required; 1–80 characters): Ad account id (ada_…)
- `labelId` (string; required; 1–256 characters)

### Headers

- `Idempotency-Key` (string; ≤ 255 characters): Unique key (for example a UUID) that makes retries safe: a repeated request with the same key and body returns the first response (Idempotent-Replayed: true) for 24 hours.

### Body

- `campaign_ids` (array of string; ≤ 1000 items)
- `ad_set_ids` (array of string; ≤ 1000 items)
- `ad_ids` (array of string; ≤ 1000 items)
- `keyword_ids` (array of string; ≤ 1000 items)

```bash
curl -X POST "https://api.socialit.com/v1/ads/accounts/ada_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd/labels/LABEL_ID/assignments" \
  -H "Authorization: Bearer $SOCIALIT_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "campaign_ids": [
      "string"
    ],
    "ad_set_ids": [
      "string"
    ],
    "ad_ids": [
      "string"
    ],
    "keyword_ids": [
      "string"
    ]
  }'
```

Response 200:

```json
{
  "object": "label_assignment_result",
  "label_id": "string",
  "attached": 1,
  "detached": 1,
  "unchanged": 1
}
```

## Detach a label

`DELETE /ads/accounts/{adAccountId}/labels/{labelId}/assignments`

Access: `write` · MCP tool: `detach-ad-label` · Zernio: `DELETE /v1/ads/labels/{labelId}/assignments`

### Path parameters

- `adAccountId` (string; required; 1–80 characters): Ad account id (ada_…)
- `labelId` (string; required; 1–256 characters)

### Query parameters

- `campaign_ids` (string; ≤ 10000 characters): Comma separated ids
- `ad_set_ids` (string; ≤ 10000 characters): Comma separated ids
- `ad_ids` (string; ≤ 10000 characters): Comma separated ids
- `keyword_ids` (string; ≤ 10000 characters): Comma separated ids

```bash
curl -X DELETE "https://api.socialit.com/v1/ads/accounts/ada_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd/labels/LABEL_ID/assignments" \
  -H "Authorization: Bearer $SOCIALIT_API_KEY"
```

Response 200:

```json
{
  "object": "label_assignment_result",
  "label_id": "string",
  "attached": 1,
  "detached": 1,
  "unchanged": 1
}
```

## List high-demand periods

`GET /ads/accounts/{adAccountId}/high-demand-periods`

Scheduled budget increases on a Meta campaign or ad set (exactly one of campaign_id / ad_set_id).

Access: `read` · MCP tool: `list-high-demand-periods` · Zernio: `GET /v1/ads/high-demand-periods`

### Path parameters

- `adAccountId` (string; required; 1–80 characters): Ad account id (ada_…)

### Query parameters

- `campaign_id` (string; 1–64 characters)
- `ad_set_id` (string; 1–64 characters)
- `limit` (integer; 1–100): Items per page (max 100)
- `cursor` (string; ≤ 4096 characters): next_cursor from the previous page
- `after` (string; ≤ 4096 characters): Alias of cursor

```bash
curl "https://api.socialit.com/v1/ads/accounts/ada_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd/high-demand-periods" \
  -H "Authorization: Bearer $SOCIALIT_API_KEY"
```

Response 200:

```json
{
  "object": "list",
  "data": [
    {
      "object": "high_demand_period",
      "id": "string",
      "target_id": "string",
      "budget_value": 1.5,
      "budget_value_type": "string",
      "time_start": "2026-10-13T09:00:00.000Z",
      "time_end": "2026-10-13T09:00:00.000Z",
      "recurrence_type": "string",
      "raw": {}
    }
  ],
  "page": 1,
  "limit": 1,
  "total": 1,
  "has_more": true,
  "next_page_url": "https://example.com",
  "previous_page_url": "https://example.com",
  "next_cursor": "string"
}
```

## Schedule a budget increase

`POST /ads/accounts/{adAccountId}/high-demand-periods`

Access: `write` · MCP tool: `create-high-demand-period` · Zernio: `POST /v1/ads/high-demand-periods`

### Path parameters

- `adAccountId` (string; required; 1–80 characters): Ad account id (ada_…)

### Headers

- `Idempotency-Key` (string; ≤ 255 characters): Unique key (for example a UUID) that makes retries safe: a repeated request with the same key and body returns the first response (Idempotent-Replayed: true) for 24 hours.

### Body

- `campaign_id` (string; 1–64 characters)
- `ad_set_id` (string; 1–64 characters)
- `budget_value` (number; required)
- `budget_value_type` (string; required; one of ABSOLUTE, MULTIPLIER)
- `time_start` (string | integer; required): ISO 8601 date-time or unix seconds
- `time_end` (string | integer; required): ISO 8601 date-time or unix seconds
- `recurrence_type` (string; one of ONE_TIME, WEEKLY, MONTHLY)

```bash
curl -X POST "https://api.socialit.com/v1/ads/accounts/ada_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd/high-demand-periods" \
  -H "Authorization: Bearer $SOCIALIT_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "campaign_id": "string",
    "budget_value": 1.5,
    "budget_value_type": "ABSOLUTE",
    "time_start": "string",
    "time_end": "string"
  }'
```

Response 201:

```json
{
  "object": "high_demand_period",
  "id": "string",
  "target_id": "string",
  "budget_value": 1.5,
  "budget_value_type": "string",
  "time_start": "2026-10-13T09:00:00.000Z",
  "time_end": "2026-10-13T09:00:00.000Z",
  "recurrence_type": "string",
  "raw": {}
}
```

## List value rule sets

`GET /ads/accounts/{adAccountId}/value-rule-sets`

Access: `read` · MCP tool: `list-value-rule-sets` · Zernio: `GET /v1/ads/value-rule-sets`

### Path parameters

- `adAccountId` (string; required; 1–80 characters): Ad account id (ada_…)

### Query parameters

- `limit` (integer; 1–100): Items per page (max 100)
- `cursor` (string; ≤ 4096 characters): next_cursor from the previous page
- `after` (string; ≤ 4096 characters): Alias of cursor

```bash
curl "https://api.socialit.com/v1/ads/accounts/ada_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd/value-rule-sets" \
  -H "Authorization: Bearer $SOCIALIT_API_KEY"
```

Response 200:

```json
{
  "object": "list",
  "data": [
    {
      "object": "value_rule_set",
      "id": "string",
      "name": "string",
      "rules": [
        {
          "id": "string",
          "name": "string",
          "adjust_sign": "string",
          "adjust_value": 1.5,
          "status": "string",
          "criteria": []
        }
      ]
    }
  ],
  "page": 1,
  "limit": 1,
  "total": 1,
  "has_more": true,
  "next_page_url": "https://example.com",
  "previous_page_url": "https://example.com",
  "next_cursor": "string"
}
```

## Create a value rule set

`POST /ads/accounts/{adAccountId}/value-rule-sets`

Access: `write` · MCP tool: `create-value-rule-set` · Zernio: `POST /v1/ads/value-rule-sets`

### Path parameters

- `adAccountId` (string; required; 1–80 characters): Ad account id (ada_…)

### Headers

- `Idempotency-Key` (string; ≤ 255 characters): Unique key (for example a UUID) that makes retries safe: a repeated request with the same key and body returns the first response (Idempotent-Replayed: true) for 24 hours.

### Body

- `name` (string; required; 1–100 characters)
- `rules` (array of object; required; 1–50 items)
  - `rules[].id` (string | null; ≤ 64 characters)
  - `rules[].name` (string; required; 1–100 characters)
  - `rules[].adjust_sign` (string; required; one of INCREASE, DECREASE)
  - `rules[].adjust_value` (integer; required; 1–1000)
  - `rules[].status` (string; 1–32 characters)
  - `rules[].criteria` (array of object; required; ≥ 1 items)
    - `rules[].criteria[].id` (string | null; ≤ 64 characters)
    - `rules[].criteria[].criteria_type` (string; required; one of AGE, GENDER, OS_TYPE, DEVICE_PLATFORM, LOCATION, PLACEMENT, OMNI_CHANNEL, AUDIENCE_LABEL)
    - `rules[].criteria[].operator` (string; one of CONTAINS)
    - `rules[].criteria[].criteria_values` (array of string; required; ≥ 1 items)
    - `rules[].criteria[].criteria_value_types` (array of string)

```bash
curl -X POST "https://api.socialit.com/v1/ads/accounts/ada_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd/value-rule-sets" \
  -H "Authorization: Bearer $SOCIALIT_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "string",
    "rules": [
      {
        "name": "string",
        "adjust_sign": "INCREASE",
        "adjust_value": 1,
        "criteria": [
          {
            "criteria_type": "AGE",
            "criteria_values": []
          }
        ]
      }
    ]
  }'
```

Response 201:

```json
{
  "object": "value_rule_set",
  "id": "string",
  "name": "string",
  "rules": [
    {
      "id": "string",
      "name": "string",
      "adjust_sign": "string",
      "adjust_value": 1.5,
      "status": "string",
      "criteria": [
        {
          "id": "string",
          "criteria_type": "string",
          "operator": "string",
          "criteria_values": [],
          "criteria_value_types": []
        }
      ]
    }
  ]
}
```

## Read a value rule set

`GET /ads/accounts/{adAccountId}/value-rule-sets/{valueRuleSetId}`

Access: `read` · MCP tool: `get-value-rule-set` · Zernio: `GET /v1/ads/value-rule-sets/{valueRuleSetId}`

### Path parameters

- `adAccountId` (string; required; 1–80 characters): Ad account id (ada_…)
- `valueRuleSetId` (string; required; 1–256 characters)

```bash
curl "https://api.socialit.com/v1/ads/accounts/ada_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd/value-rule-sets/VALUE_RULE_SET_ID" \
  -H "Authorization: Bearer $SOCIALIT_API_KEY"
```

Response 200:

```json
{
  "object": "value_rule_set",
  "id": "string",
  "name": "string",
  "rules": [
    {
      "id": "string",
      "name": "string",
      "adjust_sign": "string",
      "adjust_value": 1.5,
      "status": "string",
      "criteria": [
        {
          "id": "string",
          "criteria_type": "string",
          "operator": "string",
          "criteria_values": [],
          "criteria_value_types": []
        }
      ]
    }
  ]
}
```

## Replace a value rule set

`PATCH /ads/accounts/{adAccountId}/value-rule-sets/{valueRuleSetId}`

Full replace: keep a rule or criterion by echoing its id, omit it to delete it.

Access: `write` · MCP tool: `replace-value-rule-set` · Zernio: `PUT /v1/ads/value-rule-sets/{valueRuleSetId}`

### Path parameters

- `adAccountId` (string; required; 1–80 characters): Ad account id (ada_…)
- `valueRuleSetId` (string; required; 1–256 characters)

### Body

- `name` (string; required; 1–100 characters)
- `rules` (array of object; required; 1–50 items)
  - `rules[].id` (string | null; ≤ 64 characters)
  - `rules[].name` (string; required; 1–100 characters)
  - `rules[].adjust_sign` (string; required; one of INCREASE, DECREASE)
  - `rules[].adjust_value` (integer; required; 1–1000)
  - `rules[].status` (string; 1–32 characters)
  - `rules[].criteria` (array of object; required; ≥ 1 items)
    - `rules[].criteria[].id` (string | null; ≤ 64 characters)
    - `rules[].criteria[].criteria_type` (string; required; one of AGE, GENDER, OS_TYPE, DEVICE_PLATFORM, LOCATION, PLACEMENT, OMNI_CHANNEL, AUDIENCE_LABEL)
    - `rules[].criteria[].operator` (string; one of CONTAINS)
    - `rules[].criteria[].criteria_values` (array of string; required; ≥ 1 items)
    - `rules[].criteria[].criteria_value_types` (array of string)

```bash
curl -X PATCH "https://api.socialit.com/v1/ads/accounts/ada_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd/value-rule-sets/VALUE_RULE_SET_ID" \
  -H "Authorization: Bearer $SOCIALIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "string",
    "rules": [
      {
        "name": "string",
        "adjust_sign": "INCREASE",
        "adjust_value": 1,
        "criteria": [
          {
            "criteria_type": "AGE",
            "criteria_values": []
          }
        ]
      }
    ]
  }'
```

Response 200:

```json
{
  "object": "value_rule_set",
  "id": "string",
  "name": "string",
  "rules": [
    {
      "id": "string",
      "name": "string",
      "adjust_sign": "string",
      "adjust_value": 1.5,
      "status": "string",
      "criteria": [
        {
          "id": "string",
          "criteria_type": "string",
          "operator": "string",
          "criteria_values": [],
          "criteria_value_types": []
        }
      ]
    }
  ]
}
```

## Delete a value rule set

`DELETE /ads/accounts/{adAccountId}/value-rule-sets/{valueRuleSetId}`

Access: `write` · MCP tool: `delete-value-rule-set` · Zernio: `DELETE /v1/ads/value-rule-sets/{valueRuleSetId}`

### Path parameters

- `adAccountId` (string; required; 1–80 characters): Ad account id (ada_…)
- `valueRuleSetId` (string; required; 1–256 characters)

```bash
curl -X DELETE "https://api.socialit.com/v1/ads/accounts/ada_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd/value-rule-sets/VALUE_RULE_SET_ID" \
  -H "Authorization: Bearer $SOCIALIT_API_KEY"
```

Response 200:

```json
{
  "object": "value_rule_set",
  "id": "string",
  "deleted": true
}
```

## List negative keyword lists

`GET /ads/accounts/{adAccountId}/negative-keyword-lists`

Google Ads shared negative keyword lists.

Access: `read` · MCP tool: `list-negative-keyword-lists` · Zernio: `GET /v1/ads/accounts/negative-keyword-lists`

### Path parameters

- `adAccountId` (string; required; 1–80 characters): Ad account id (ada_…)

```bash
curl "https://api.socialit.com/v1/ads/accounts/ada_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd/negative-keyword-lists" \
  -H "Authorization: Bearer $SOCIALIT_API_KEY"
```

Response 200:

```json
{
  "object": "list",
  "data": [
    {
      "object": "negative_keyword_list",
      "id": "string",
      "resource_name": "string",
      "name": "string",
      "member_count": 1,
      "reference_count": 1,
      "keywords": [
        {
          "criterion_id": "string",
          "text": "string",
          "match_type": "string"
        }
      ],
      "created": 1,
      "removed": 1
    }
  ],
  "page": 1,
  "limit": 1,
  "total": 1,
  "has_more": true,
  "next_page_url": "https://example.com",
  "previous_page_url": "https://example.com",
  "next_cursor": "string"
}
```

## Create a negative keyword list

`POST /ads/accounts/{adAccountId}/negative-keyword-lists`

Access: `write` · MCP tool: `create-negative-keyword-list` · Zernio: `POST /v1/ads/accounts/negative-keyword-lists`

### Path parameters

- `adAccountId` (string; required; 1–80 characters): Ad account id (ada_…)

### Headers

- `Idempotency-Key` (string; ≤ 255 characters): Unique key (for example a UUID) that makes retries safe: a repeated request with the same key and body returns the first response (Idempotent-Replayed: true) for 24 hours.

### Body

- `name` (string; required; 1–255 characters)
- `keywords` (array of string | object; ≤ 5000 items)
  - one of: Option 1 (string)
  - one of: Option 2 (object)
    - `keywords.text` (string; required; 1–80 characters)
    - `keywords.match_type` (string; one of exact, phrase, broad)

```bash
curl -X POST "https://api.socialit.com/v1/ads/accounts/ada_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd/negative-keyword-lists" \
  -H "Authorization: Bearer $SOCIALIT_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "string",
    "keywords": [
      "string"
    ]
  }'
```

Response 201:

```json
{
  "object": "negative_keyword_list",
  "id": "string",
  "resource_name": "string",
  "name": "string",
  "member_count": 1,
  "reference_count": 1,
  "keywords": [
    {
      "criterion_id": "string",
      "text": "string",
      "match_type": "string"
    }
  ],
  "created": 1,
  "removed": 1
}
```

## Get a negative keyword list

`GET /ads/accounts/{adAccountId}/negative-keyword-lists/{listId}`

Access: `read` · MCP tool: `get-negative-keyword-list` · Zernio: `GET /v1/ads/accounts/negative-keyword-lists/{listId}`

### Path parameters

- `adAccountId` (string; required; 1–80 characters): Ad account id (ada_…)
- `listId` (string; required; 1–256 characters)

```bash
curl "https://api.socialit.com/v1/ads/accounts/ada_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd/negative-keyword-lists/LIST_ID" \
  -H "Authorization: Bearer $SOCIALIT_API_KEY"
```

Response 200:

```json
{
  "object": "negative_keyword_list",
  "id": "string",
  "resource_name": "string",
  "name": "string",
  "member_count": 1,
  "reference_count": 1,
  "keywords": [
    {
      "criterion_id": "string",
      "text": "string",
      "match_type": "string"
    }
  ],
  "created": 1,
  "removed": 1
}
```

## Rename a negative keyword list

`PATCH /ads/accounts/{adAccountId}/negative-keyword-lists/{listId}`

Access: `write` · MCP tool: `rename-negative-keyword-list` · Zernio: `PUT /v1/ads/accounts/negative-keyword-lists/{listId}`

### Path parameters

- `adAccountId` (string; required; 1–80 characters): Ad account id (ada_…)
- `listId` (string; required; 1–256 characters)

### Body

- `name` (string; required; 1–255 characters)

```bash
curl -X PATCH "https://api.socialit.com/v1/ads/accounts/ada_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd/negative-keyword-lists/LIST_ID" \
  -H "Authorization: Bearer $SOCIALIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "string"
  }'
```

Response 200:

```json
{
  "object": "negative_keyword_list",
  "id": "string",
  "resource_name": "string",
  "name": "string",
  "member_count": 1,
  "reference_count": 1,
  "keywords": [
    {
      "criterion_id": "string",
      "text": "string",
      "match_type": "string"
    }
  ],
  "created": 1,
  "removed": 1
}
```

## Delete a negative keyword list

`DELETE /ads/accounts/{adAccountId}/negative-keyword-lists/{listId}`

Access: `write` · MCP tool: `delete-negative-keyword-list` · Zernio: `DELETE /v1/ads/accounts/negative-keyword-lists/{listId}`

### Path parameters

- `adAccountId` (string; required; 1–80 characters): Ad account id (ada_…)
- `listId` (string; required; 1–256 characters)

```bash
curl -X DELETE "https://api.socialit.com/v1/ads/accounts/ada_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd/negative-keyword-lists/LIST_ID" \
  -H "Authorization: Bearer $SOCIALIT_API_KEY"
```

Response 200:

```json
{
  "object": "negative_keyword_list",
  "id": "string",
  "deleted": true
}
```

## Replace negative list keywords

`PATCH /ads/accounts/{adAccountId}/negative-keyword-lists/{listId}/keywords`

Diffs by normalized text + match type; [] clears the list. Affects every campaign using it.

Access: `write` · MCP tool: `replace-negative-keyword-list-keywords` · Zernio: `PUT /v1/ads/accounts/negative-keyword-lists/{listId}/keywords`

### Path parameters

- `adAccountId` (string; required; 1–80 characters): Ad account id (ada_…)
- `listId` (string; required; 1–256 characters)

### Body

- `keywords` (array of string | object; required; ≤ 5000 items)
  - one of: Option 1 (string)
  - one of: Option 2 (object)
    - `keywords.text` (string; required; 1–80 characters)
    - `keywords.match_type` (string; one of exact, phrase, broad)

```bash
curl -X PATCH "https://api.socialit.com/v1/ads/accounts/ada_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd/negative-keyword-lists/LIST_ID/keywords" \
  -H "Authorization: Bearer $SOCIALIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "keywords": [
      "string"
    ]
  }'
```

Response 200:

```json
{
  "object": "negative_keyword_list",
  "id": "string",
  "resource_name": "string",
  "name": "string",
  "member_count": 1,
  "reference_count": 1,
  "keywords": [
    {
      "criterion_id": "string",
      "text": "string",
      "match_type": "string"
    }
  ],
  "created": 1,
  "removed": 1
}
```

## List account callouts

`GET /ads/accounts/{adAccountId}/callouts`

Google Ads callouts attached at account level.

Access: `read` · MCP tool: `list-account-callouts` · Zernio: `GET /v1/ads/accounts/callouts`

### Path parameters

- `adAccountId` (string; required; 1–80 characters): Ad account id (ada_…)

```bash
curl "https://api.socialit.com/v1/ads/accounts/ada_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd/callouts" \
  -H "Authorization: Bearer $SOCIALIT_API_KEY"
```

Response 200:

```json
{
  "object": "list",
  "data": [
    {
      "object": "callout",
      "id": "string",
      "status": "string",
      "resource_name": "string",
      "customer_asset_resource_name": "string",
      "text": "string"
    }
  ],
  "page": 1,
  "limit": 1,
  "total": 1,
  "has_more": true,
  "next_page_url": "https://example.com",
  "previous_page_url": "https://example.com",
  "next_cursor": "string"
}
```

## Add account callouts

`POST /ads/accounts/{adAccountId}/callouts`

Access: `write` · MCP tool: `add-account-callouts` · Zernio: `POST /v1/ads/accounts/callouts`

### Path parameters

- `adAccountId` (string; required; 1–80 characters): Ad account id (ada_…)

### Headers

- `Idempotency-Key` (string; ≤ 255 characters): Unique key (for example a UUID) that makes retries safe: a repeated request with the same key and body returns the first response (Idempotent-Replayed: true) for 24 hours.

### Body

- `callouts` (array of string; required; 1–20 items)

```bash
curl -X POST "https://api.socialit.com/v1/ads/accounts/ada_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd/callouts" \
  -H "Authorization: Bearer $SOCIALIT_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "callouts": [
      "string"
    ]
  }'
```

Response 201:

```json
{
  "object": "list",
  "data": [
    {
      "object": "callout",
      "id": "string",
      "status": "string",
      "resource_name": "string",
      "customer_asset_resource_name": "string",
      "text": "string"
    }
  ],
  "page": 1,
  "limit": 1,
  "total": 1,
  "has_more": true,
  "next_page_url": "https://example.com",
  "previous_page_url": "https://example.com",
  "next_cursor": "string"
}
```

## Update account callouts

`PATCH /ads/accounts/{adAccountId}/callouts`

Edits existing callout assets in place (shared assets change everywhere they are used).

Access: `write` · MCP tool: `update-account-callouts` · Zernio: `PUT /v1/ads/accounts/callouts`

### Path parameters

- `adAccountId` (string; required; 1–80 characters): Ad account id (ada_…)

### Body

- `updates` (array of object; required; ≥ 1 items)
  - `updates[].asset_id` (string; required; 1–32 characters)
  - `updates[].text` (string; required; 1–25 characters)

```bash
curl -X PATCH "https://api.socialit.com/v1/ads/accounts/ada_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd/callouts" \
  -H "Authorization: Bearer $SOCIALIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "updates": [
      {
        "asset_id": "string",
        "text": "string"
      }
    ]
  }'
```

Response 200:

```json
{
  "object": "asset_update_result",
  "updated": 1
}
```

## Remove an account callout

`DELETE /ads/accounts/{adAccountId}/callouts/{assetId}`

Detaches it from the account level only; campaign and ad group attachments stay.

Access: `write` · MCP tool: `remove-account-callout` · Zernio: `DELETE /v1/ads/accounts/callouts`

### Path parameters

- `adAccountId` (string; required; 1–80 characters): Ad account id (ada_…)
- `assetId` (string; required; 1–256 characters)

```bash
curl -X DELETE "https://api.socialit.com/v1/ads/accounts/ada_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd/callouts/ASSET_ID" \
  -H "Authorization: Bearer $SOCIALIT_API_KEY"
```

Response 200:

```json
{
  "object": "callout",
  "id": "string",
  "deleted": true
}
```

## List account sitelinks

`GET /ads/accounts/{adAccountId}/sitelinks`

Google Ads sitelinks attached at account level.

Access: `read` · MCP tool: `list-account-sitelinks` · Zernio: `GET /v1/ads/accounts/sitelinks`

### Path parameters

- `adAccountId` (string; required; 1–80 characters): Ad account id (ada_…)

```bash
curl "https://api.socialit.com/v1/ads/accounts/ada_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd/sitelinks" \
  -H "Authorization: Bearer $SOCIALIT_API_KEY"
```

Response 200:

```json
{
  "object": "list",
  "data": [
    {
      "object": "sitelink",
      "id": "string",
      "status": "string",
      "resource_name": "string",
      "customer_asset_resource_name": "string",
      "text": "string",
      "link_url": "https://example.com",
      "description1": "string",
      "description2": "string"
    }
  ],
  "page": 1,
  "limit": 1,
  "total": 1,
  "has_more": true,
  "next_page_url": "https://example.com",
  "previous_page_url": "https://example.com",
  "next_cursor": "string"
}
```

## Add account sitelinks

`POST /ads/accounts/{adAccountId}/sitelinks`

Access: `write` · MCP tool: `add-account-sitelinks` · Zernio: `POST /v1/ads/accounts/sitelinks`

### Path parameters

- `adAccountId` (string; required; 1–80 characters): Ad account id (ada_…)

### Headers

- `Idempotency-Key` (string; ≤ 255 characters): Unique key (for example a UUID) that makes retries safe: a repeated request with the same key and body returns the first response (Idempotent-Replayed: true) for 24 hours.

### Body

- `sitelinks` (array of object; required; 1–20 items)
  - `sitelinks[].text` (string; required; 1–25 characters)
  - `sitelinks[].link_url` (string (uri); required; ≤ 2048 characters)
  - `sitelinks[].description1` (string; 1–35 characters)
  - `sitelinks[].description2` (string; 1–35 characters)

```bash
curl -X POST "https://api.socialit.com/v1/ads/accounts/ada_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd/sitelinks" \
  -H "Authorization: Bearer $SOCIALIT_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "sitelinks": [
      {
        "text": "string",
        "link_url": "https://example.com"
      }
    ]
  }'
```

Response 201:

```json
{
  "object": "list",
  "data": [
    {
      "object": "sitelink",
      "id": "string",
      "status": "string",
      "resource_name": "string",
      "customer_asset_resource_name": "string",
      "text": "string",
      "link_url": "https://example.com",
      "description1": "string",
      "description2": "string"
    }
  ],
  "page": 1,
  "limit": 1,
  "total": 1,
  "has_more": true,
  "next_page_url": "https://example.com",
  "previous_page_url": "https://example.com",
  "next_cursor": "string"
}
```

## Update account sitelinks

`PATCH /ads/accounts/{adAccountId}/sitelinks`

Edits existing sitelink assets in place (shared assets change everywhere they are used).

Access: `write` · MCP tool: `update-account-sitelinks` · Zernio: `PUT /v1/ads/accounts/sitelinks`

### Path parameters

- `adAccountId` (string; required; 1–80 characters): Ad account id (ada_…)

### Body

- `updates` (array of object; required; ≥ 1 items)
  - `updates[].asset_id` (string; required; 1–32 characters)
  - `updates[].text` (string; 1–25 characters)
  - `updates[].link_url` (string (uri); ≤ 2048 characters)
  - `updates[].description1` (string; 1–35 characters)
  - `updates[].description2` (string; 1–35 characters)

```bash
curl -X PATCH "https://api.socialit.com/v1/ads/accounts/ada_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd/sitelinks" \
  -H "Authorization: Bearer $SOCIALIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "updates": [
      {
        "asset_id": "string",
        "text": "string"
      }
    ]
  }'
```

Response 200:

```json
{
  "object": "asset_update_result",
  "updated": 1
}
```

## Remove an account sitelink

`DELETE /ads/accounts/{adAccountId}/sitelinks/{assetId}`

Detaches it from the account level only; campaign and ad group attachments stay.

Access: `write` · MCP tool: `remove-account-sitelink` · Zernio: `DELETE /v1/ads/accounts/sitelinks`

### Path parameters

- `adAccountId` (string; required; 1–80 characters): Ad account id (ada_…)
- `assetId` (string; required; 1–256 characters)

```bash
curl -X DELETE "https://api.socialit.com/v1/ads/accounts/ada_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd/sitelinks/ASSET_ID" \
  -H "Authorization: Bearer $SOCIALIT_API_KEY"
```

Response 200:

```json
{
  "object": "sitelink",
  "id": "string",
  "deleted": true
}
```

## List account structured snippets

`GET /ads/accounts/{adAccountId}/structured-snippets`

Google Ads structured snippets attached at account level.

Access: `read` · MCP tool: `list-account-structured-snippets` · Zernio: `GET /v1/ads/accounts/structured-snippets`

### Path parameters

- `adAccountId` (string; required; 1–80 characters): Ad account id (ada_…)

```bash
curl "https://api.socialit.com/v1/ads/accounts/ada_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd/structured-snippets" \
  -H "Authorization: Bearer $SOCIALIT_API_KEY"
```

Response 200:

```json
{
  "object": "list",
  "data": [
    {
      "object": "structured_snippet",
      "id": "string",
      "status": "string",
      "resource_name": "string",
      "customer_asset_resource_name": "string",
      "header": "string",
      "values": [
        "string"
      ]
    }
  ],
  "page": 1,
  "limit": 1,
  "total": 1,
  "has_more": true,
  "next_page_url": "https://example.com",
  "previous_page_url": "https://example.com",
  "next_cursor": "string"
}
```

## Add account structured snippets

`POST /ads/accounts/{adAccountId}/structured-snippets`

Access: `write` · MCP tool: `add-account-structured-snippets` · Zernio: `POST /v1/ads/accounts/structured-snippets`

### Path parameters

- `adAccountId` (string; required; 1–80 characters): Ad account id (ada_…)

### Headers

- `Idempotency-Key` (string; ≤ 255 characters): Unique key (for example a UUID) that makes retries safe: a repeated request with the same key and body returns the first response (Idempotent-Replayed: true) for 24 hours.

### Body

- `structured_snippets` (array of object; required; 1–20 items)
  - `structured_snippets[].header` (string; required; one of Amenities, Brands, Courses, Degree programs, Destinations, Featured hotels, Insurance coverage, Models, Neighborhoods, Service catalog, Shows, Styles, …)
  - `structured_snippets[].values` (array of string; required; 3–10 items)

```bash
curl -X POST "https://api.socialit.com/v1/ads/accounts/ada_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd/structured-snippets" \
  -H "Authorization: Bearer $SOCIALIT_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "structured_snippets": [
      {
        "header": "Amenities",
        "values": [
          "string"
        ]
      }
    ]
  }'
```

Response 201:

```json
{
  "object": "list",
  "data": [
    {
      "object": "structured_snippet",
      "id": "string",
      "status": "string",
      "resource_name": "string",
      "customer_asset_resource_name": "string",
      "header": "string",
      "values": [
        "string"
      ]
    }
  ],
  "page": 1,
  "limit": 1,
  "total": 1,
  "has_more": true,
  "next_page_url": "https://example.com",
  "previous_page_url": "https://example.com",
  "next_cursor": "string"
}
```

## Update account structured snippets

`PATCH /ads/accounts/{adAccountId}/structured-snippets`

Edits existing structured snippet assets in place (shared assets change everywhere they are used).

Access: `write` · MCP tool: `update-account-structured-snippets` · Zernio: `PUT /v1/ads/accounts/structured-snippets`

### Path parameters

- `adAccountId` (string; required; 1–80 characters): Ad account id (ada_…)

### Body

- `updates` (array of object; required; ≥ 1 items)
  - `updates[].asset_id` (string; required; 1–32 characters)
  - `updates[].header` (string; one of Amenities, Brands, Courses, Degree programs, Destinations, Featured hotels, Insurance coverage, Models, Neighborhoods, Service catalog, Shows, Styles, …)
  - `updates[].values` (array of string; 3–10 items)

```bash
curl -X PATCH "https://api.socialit.com/v1/ads/accounts/ada_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd/structured-snippets" \
  -H "Authorization: Bearer $SOCIALIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "updates": [
      {
        "asset_id": "string",
        "header": "Amenities"
      }
    ]
  }'
```

Response 200:

```json
{
  "object": "asset_update_result",
  "updated": 1
}
```

## Remove an account structured snippet

`DELETE /ads/accounts/{adAccountId}/structured-snippets/{assetId}`

Detaches it from the account level only; campaign and ad group attachments stay.

Access: `write` · MCP tool: `remove-account-structured-snippet` · Zernio: `DELETE /v1/ads/accounts/structured-snippets`

### Path parameters

- `adAccountId` (string; required; 1–80 characters): Ad account id (ada_…)
- `assetId` (string; required; 1–256 characters)

```bash
curl -X DELETE "https://api.socialit.com/v1/ads/accounts/ada_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd/structured-snippets/ASSET_ID" \
  -H "Authorization: Bearer $SOCIALIT_API_KEY"
```

Response 200:

```json
{
  "object": "structured_snippet",
  "id": "string",
  "deleted": true
}
```

## List comments on an ad

`GET /ads/{adId}/comments`

Comments on the ad’s post, dark posts included (Meta: Facebook or Instagram placement; TikTok).

Access: `read` · MCP tool: `list-ad-comments` · Zernio: `GET /v1/ads/{adId}/comments`

### Path parameters

- `adId` (string; required; 1–256 characters)

### Query parameters

- `ad_account_id` (string; ≤ 80 characters): Ad account (ada_…)
- `connection_id` (string; ≤ 80 characters): Ads connection (adc_…), with platform_ad_account_id when it has several ad accounts
- `platform_ad_account_id` (string; ≤ 256 characters): Network ad account id (act_…, customer id, advertiser id …)
- `placement` (string; one of facebook, instagram)
- `since` (string; pattern ^\d{4}-\d{2}-\d{2}$): YYYY-MM-DD
- `until` (string; pattern ^\d{4}-\d{2}-\d{2}$): YYYY-MM-DD
- `limit` (integer; 1–100): Items per page (max 100)
- `cursor` (string; ≤ 4096 characters): next_cursor from the previous page
- `after` (string; ≤ 4096 characters): Alias of cursor

```bash
curl "https://api.socialit.com/v1/ads/AD_ID/comments" \
  -H "Authorization: Bearer $SOCIALIT_API_KEY"
```

Response 200:

```json
{
  "object": "list",
  "data": [
    {
      "object": "ad_comment",
      "id": "string",
      "ad_id": "string",
      "platform": "string",
      "placement": "string",
      "parent_id": "string",
      "text": "string",
      "author": {
        "id": "string",
        "name": "string",
        "username": "string"
      },
      "like_count": 1,
      "reply_count": 1,
      "hidden": true,
      "can_reply": true,
      "can_hide": true,
      "can_delete": true,
      "created_at": "2026-10-13T09:00:00.000Z"
    }
  ],
  "page": 1,
  "limit": 1,
  "total": 1,
  "has_more": true,
  "next_page_url": "https://example.com",
  "previous_page_url": "https://example.com",
  "next_cursor": "string"
}
```

## Reply to an ad comment

`POST /ads/{adId}/comments/{commentId}/reply`

Access: `write` · MCP tool: `reply-ad-comment` · Zernio: `POST /v1/ads/{adId}/comments/{commentId}/reply`

### Path parameters

- `adId` (string; required; 1–256 characters)
- `commentId` (string; required; 1–256 characters)

### Headers

- `Idempotency-Key` (string; ≤ 255 characters): Unique key (for example a UUID) that makes retries safe: a repeated request with the same key and body returns the first response (Idempotent-Replayed: true) for 24 hours.

### Body

- `ad_account_id` (string; ≤ 80 characters): Ad account (ada_…)
- `connection_id` (string; ≤ 80 characters): Ads connection (adc_…), with platform_ad_account_id when it has several ad accounts
- `platform_ad_account_id` (string; ≤ 256 characters): Network ad account id (act_…, customer id, advertiser id …)
- `text` (string; required; 1–500 characters)
- `placement` (string; one of facebook, instagram)

```bash
curl -X POST "https://api.socialit.com/v1/ads/AD_ID/comments/COMMENT_ID/reply" \
  -H "Authorization: Bearer $SOCIALIT_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "ad_account_id": "ada_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd",
    "connection_id": "adc_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd",
    "platform_ad_account_id": "string",
    "text": "string",
    "placement": "facebook"
  }'
```

Response 201:

```json
{
  "object": "ad_comment",
  "id": "string",
  "ad_id": "string",
  "platform": "string",
  "placement": "string",
  "parent_id": "string",
  "text": "string",
  "author": {
    "id": "string",
    "name": "string",
    "username": "string"
  },
  "like_count": 1,
  "reply_count": 1,
  "hidden": true,
  "can_reply": true,
  "can_hide": true,
  "can_delete": true,
  "created_at": "2026-10-13T09:00:00.000Z"
}
```

## Hide or unhide an ad comment

`POST /ads/{adId}/comments/{commentId}/hide`

Access: `write` · MCP tool: `hide-ad-comment` · Zernio: `POST /v1/ads/{adId}/comments/{commentId}/hide`

### Path parameters

- `adId` (string; required; 1–256 characters)
- `commentId` (string; required; 1–256 characters)

### Headers

- `Idempotency-Key` (string; ≤ 255 characters): Unique key (for example a UUID) that makes retries safe: a repeated request with the same key and body returns the first response (Idempotent-Replayed: true) for 24 hours.

### Body

- `ad_account_id` (string; ≤ 80 characters): Ad account (ada_…)
- `connection_id` (string; ≤ 80 characters): Ads connection (adc_…), with platform_ad_account_id when it has several ad accounts
- `platform_ad_account_id` (string; ≤ 256 characters): Network ad account id (act_…, customer id, advertiser id …)
- `hidden` (boolean; required)
- `placement` (string; one of facebook, instagram)

```bash
curl -X POST "https://api.socialit.com/v1/ads/AD_ID/comments/COMMENT_ID/hide" \
  -H "Authorization: Bearer $SOCIALIT_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "ad_account_id": "ada_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd",
    "connection_id": "adc_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd",
    "platform_ad_account_id": "string",
    "hidden": true,
    "placement": "facebook"
  }'
```

Response 200:

```json
{
  "object": "ad_comment",
  "id": "string",
  "hidden": true
}
```

## Delete an ad comment

`DELETE /ads/{adId}/comments/{commentId}`

Access: `write` · MCP tool: `delete-ad-comment` · Zernio: `DELETE /v1/ads/{adId}/comments/{commentId}`

### Path parameters

- `adId` (string; required; 1–256 characters)
- `commentId` (string; required; 1–256 characters)

### Query parameters

- `ad_account_id` (string; ≤ 80 characters): Ad account (ada_…)
- `connection_id` (string; ≤ 80 characters): Ads connection (adc_…), with platform_ad_account_id when it has several ad accounts
- `platform_ad_account_id` (string; ≤ 256 characters): Network ad account id (act_…, customer id, advertiser id …)
- `placement` (string; one of facebook, instagram)

```bash
curl -X DELETE "https://api.socialit.com/v1/ads/AD_ID/comments/COMMENT_ID" \
  -H "Authorization: Bearer $SOCIALIT_API_KEY"
```

Response 200:

```json
{
  "object": "ad_comment",
  "id": "string",
  "deleted": true
}
```

## Get ad URL tracking params

`GET /ads/{adId}/tracking-tags`

Click-URL tracking parameters (UTMs), not pixels: Meta creative url_tags, Google campaign tracking template / final URL suffix, LinkedIn Dynamic UTMs.

Access: `read` · MCP tool: `get-ad-tracking-params` · Zernio: `GET /v1/ads/{adId}/tracking-tags`

### Path parameters

- `adId` (string; required; 1–256 characters)

### Query parameters

- `ad_account_id` (string; ≤ 80 characters): Ad account (ada_…)
- `connection_id` (string; ≤ 80 characters): Ads connection (adc_…), with platform_ad_account_id when it has several ad accounts
- `platform_ad_account_id` (string; ≤ 256 characters): Network ad account id (act_…, customer id, advertiser id …)
- `campaign_id` (string; 1–64 characters)

```bash
curl "https://api.socialit.com/v1/ads/AD_ID/tracking-tags" \
  -H "Authorization: Bearer $SOCIALIT_API_KEY"
```

Response 200:

```json
{
  "object": "ad_tracking_params",
  "ad_id": "string",
  "platform": "string",
  "level": "string",
  "url_tags": "string",
  "template_url_spec": {},
  "tracking_url_template": "string",
  "final_url_suffix": "string",
  "dynamic_value_parameters": {},
  "custom_value_parameters": {}
}
```

## Set ad URL tracking params

`PATCH /ads/{adId}/tracking-tags`

Meta rebuilds the (immutable) creative with the new url_tags and repoints the ad.

Access: `write` · MCP tool: `set-ad-tracking-params` · Zernio: `PATCH /v1/ads/{adId}/tracking-tags`

### Path parameters

- `adId` (string; required; 1–256 characters)

### Body

- `ad_account_id` (string; ≤ 80 characters): Ad account (ada_…)
- `connection_id` (string; ≤ 80 characters): Ads connection (adc_…), with platform_ad_account_id when it has several ad accounts
- `platform_ad_account_id` (string; ≤ 256 characters): Network ad account id (act_…, customer id, advertiser id …)
- `campaign_id` (string; 1–64 characters)
- `url_tags` (array of object; ≤ 50 items)
  - `url_tags[].key` (string; required; 1–100 characters)
  - `url_tags[].value` (string; required; ≤ 500 characters)
- `creative` (object)
  - `creative.headline` (string; required; 1–255 characters)
  - `creative.body` (string; required; ≤ 5000 characters)
  - `creative.call_to_action` (string; required; 1–64 characters)
  - `creative.link_url` (string (uri); required; ≤ 2048 characters)
  - `creative.image_url` (string (uri); ≤ 2048 characters)
  - `creative.video_url` (string (uri); ≤ 2048 characters)
  - `creative.video_id` (string; 1–64 characters)
- `tracking_url_template` (string; ≤ 2048 characters)
- `final_url_suffix` (string; ≤ 2048 characters)
- `dynamic_value_parameters` (map of string)
- `custom_value_parameters` (map of string)

```bash
curl -X PATCH "https://api.socialit.com/v1/ads/AD_ID/tracking-tags" \
  -H "Authorization: Bearer $SOCIALIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "ad_account_id": "ada_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd",
    "connection_id": "adc_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd",
    "platform_ad_account_id": "string",
    "campaign_id": "string",
    "url_tags": [
      {
        "key": "string",
        "value": "string"
      }
    ]
  }'
```

Response 200:

```json
{
  "object": "ad_tracking_params",
  "ad_id": "string",
  "platform": "string",
  "level": "string",
  "url_tags": "string",
  "template_url_spec": {},
  "tracking_url_template": "string",
  "final_url_suffix": "string",
  "dynamic_value_parameters": {},
  "custom_value_parameters": {}
}
```

## List tracking tags

`GET /ads/accounts/{adAccountId}/tracking-tags`

Pixels and measurement tags of the ad account (install code omitted).

Access: `read` · MCP tool: `list-tracking-tags` · Zernio: `GET /v1/accounts/{accountId}/tracking-tags`

### Path parameters

- `adAccountId` (string; required; 1–80 characters): Ad account id (ada_…)

```bash
curl "https://api.socialit.com/v1/ads/accounts/ada_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd/tracking-tags" \
  -H "Authorization: Bearer $SOCIALIT_API_KEY"
```

Response 200:

```json
{
  "object": "list",
  "data": [
    {
      "object": "tracking_tag",
      "id": "string",
      "site_tag_id": "string",
      "platform": "string",
      "kind": "string",
      "name": "string",
      "status": "string",
      "code": "string",
      "last_fired_at": "2026-10-13T09:00:00.000Z",
      "is_unavailable": true,
      "created_at": "2026-10-13T09:00:00.000Z",
      "automatic_matching_fields": [
        "string"
      ],
      "owner_business_id": "string",
      "owner_ad_account_id": "string",
      "auto_tagging": true,
      "events": [
        {
          "object": "tracking_tag_event",
          "id": "string",
          "name": "string",
          "type": "string",
          "site_event": "string",
          "site_event_id": "string"
        }
      ]
    }
  ],
  "page": 1,
  "limit": 1,
  "total": 1,
  "has_more": true,
  "next_page_url": "https://example.com",
  "previous_page_url": "https://example.com",
  "next_cursor": "string"
}
```

## Create a tracking tag

`POST /ads/accounts/{adAccountId}/tracking-tags`

Not idempotent on the networks: send an Idempotency-Key and never retry blindly.

Access: `write` · MCP tool: `create-tracking-tag` · Zernio: `POST /v1/accounts/{accountId}/tracking-tags`

### Path parameters

- `adAccountId` (string; required; 1–80 characters): Ad account id (ada_…)

### Headers

- `Idempotency-Key` (string; ≤ 255 characters): Unique key (for example a UUID) that makes retries safe: a repeated request with the same key and body returns the first response (Idempotent-Replayed: true) for 24 hours.

### Body

- `name` (string; required; 1–100 characters)
- `automatic_matching_fields` (array of string)
- `default_event_type` (string; 1–64 characters)
- `domain` (string; 1–255 characters)
- `partner_name` (string; 1–64 characters)

```bash
curl -X POST "https://api.socialit.com/v1/ads/accounts/ada_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd/tracking-tags" \
  -H "Authorization: Bearer $SOCIALIT_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "string",
    "automatic_matching_fields": [
      "em"
    ],
    "default_event_type": "string",
    "domain": "string",
    "partner_name": "string"
  }'
```

Response 201:

```json
{
  "object": "tracking_tag",
  "id": "string",
  "site_tag_id": "string",
  "platform": "string",
  "kind": "string",
  "name": "string",
  "status": "string",
  "code": "string",
  "last_fired_at": "2026-10-13T09:00:00.000Z",
  "is_unavailable": true,
  "created_at": "2026-10-13T09:00:00.000Z",
  "automatic_matching_fields": [
    "string"
  ],
  "owner_business_id": "string",
  "owner_ad_account_id": "string",
  "auto_tagging": true,
  "events": [
    {
      "object": "tracking_tag_event",
      "id": "string",
      "name": "string",
      "type": "string",
      "site_event": "string",
      "site_event_id": "string",
      "status": "string",
      "default_value": 1.5,
      "currency": "USD",
      "click_window_days": 1.5,
      "view_window_days": 1.5,
      "url_contains": "string",
      "always_use_default_value": true,
      "primary": true,
      "counting_type": "string"
    }
  ]
}
```

## Get a tracking tag

`GET /ads/accounts/{adAccountId}/tracking-tags/{tagId}`

The tag with its install code and conversion events.

Access: `read` · MCP tool: `get-tracking-tag` · Zernio: `GET /v1/accounts/{accountId}/tracking-tags/{tagId}`

### Path parameters

- `adAccountId` (string; required; 1–80 characters): Ad account id (ada_…)
- `tagId` (string; required; 1–256 characters)

```bash
curl "https://api.socialit.com/v1/ads/accounts/ada_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd/tracking-tags/TAG_ID" \
  -H "Authorization: Bearer $SOCIALIT_API_KEY"
```

Response 200:

```json
{
  "object": "tracking_tag",
  "id": "string",
  "site_tag_id": "string",
  "platform": "string",
  "kind": "string",
  "name": "string",
  "status": "string",
  "code": "string",
  "last_fired_at": "2026-10-13T09:00:00.000Z",
  "is_unavailable": true,
  "created_at": "2026-10-13T09:00:00.000Z",
  "automatic_matching_fields": [
    "string"
  ],
  "owner_business_id": "string",
  "owner_ad_account_id": "string",
  "auto_tagging": true,
  "events": [
    {
      "object": "tracking_tag_event",
      "id": "string",
      "name": "string",
      "type": "string",
      "site_event": "string",
      "site_event_id": "string",
      "status": "string",
      "default_value": 1.5,
      "currency": "USD",
      "click_window_days": 1.5,
      "view_window_days": 1.5,
      "url_contains": "string",
      "always_use_default_value": true,
      "primary": true,
      "counting_type": "string"
    }
  ]
}
```

## Update a tracking tag

`PATCH /ads/accounts/{adAccountId}/tracking-tags/{tagId}`

Access: `write` · MCP tool: `update-tracking-tag` · Zernio: `PATCH /v1/accounts/{accountId}/tracking-tags/{tagId}`

### Path parameters

- `adAccountId` (string; required; 1–80 characters): Ad account id (ada_…)
- `tagId` (string; required; 1–256 characters)

### Body

- `name` (string; 1–100 characters)
- `enable_automatic_matching` (boolean)
- `automatic_matching_fields` (array of string)
- `first_party_cookie_status` (string; one of empty, first_party_cookie_disabled, first_party_cookie_enabled)
- `data_use_setting` (string; one of advertising_and_analytics, analytics_only, empty)
- `auto_tagging` (boolean)

```bash
curl -X PATCH "https://api.socialit.com/v1/ads/accounts/ada_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd/tracking-tags/TAG_ID" \
  -H "Authorization: Bearer $SOCIALIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "string",
    "enable_automatic_matching": true,
    "automatic_matching_fields": [
      "em"
    ],
    "first_party_cookie_status": "empty",
    "data_use_setting": "advertising_and_analytics"
  }'
```

Response 200:

```json
{
  "object": "tracking_tag",
  "id": "string",
  "site_tag_id": "string",
  "platform": "string",
  "kind": "string",
  "name": "string",
  "status": "string",
  "code": "string",
  "last_fired_at": "2026-10-13T09:00:00.000Z",
  "is_unavailable": true,
  "created_at": "2026-10-13T09:00:00.000Z",
  "automatic_matching_fields": [
    "string"
  ],
  "owner_business_id": "string",
  "owner_ad_account_id": "string",
  "auto_tagging": true,
  "events": [
    {
      "object": "tracking_tag_event",
      "id": "string",
      "name": "string",
      "type": "string",
      "site_event": "string",
      "site_event_id": "string",
      "status": "string",
      "default_value": 1.5,
      "currency": "USD",
      "click_window_days": 1.5,
      "view_window_days": 1.5,
      "url_contains": "string",
      "always_use_default_value": true,
      "primary": true,
      "counting_type": "string"
    }
  ]
}
```

## List accounts a tag is shared with

`GET /ads/accounts/{adAccountId}/tracking-tags/{tagId}/shared-accounts`

Access: `read` · MCP tool: `list-tracking-tag-shared-accounts` · Zernio: `GET /v1/accounts/{accountId}/tracking-tags/{tagId}/shared-accounts`

### Path parameters

- `adAccountId` (string; required; 1–80 characters): Ad account id (ada_…)
- `tagId` (string; required; 1–256 characters)

### Query parameters

- `business_id` (string; 1–64 characters)

```bash
curl "https://api.socialit.com/v1/ads/accounts/ada_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd/tracking-tags/TAG_ID/shared-accounts" \
  -H "Authorization: Bearer $SOCIALIT_API_KEY"
```

Response 200:

```json
{
  "object": "list",
  "data": [
    {
      "object": "tracking_tag_shared_account",
      "id": "string",
      "name": "string",
      "business_id": "string",
      "role": "string"
    }
  ],
  "page": 1,
  "limit": 1,
  "total": 1,
  "has_more": true,
  "next_page_url": "https://example.com",
  "previous_page_url": "https://example.com",
  "next_cursor": "string"
}
```

## Share a tag with an ad account

`POST /ads/accounts/{adAccountId}/tracking-tags/{tagId}/shared-accounts`

Access: `write` · MCP tool: `share-tracking-tag` · Zernio: `POST /v1/accounts/{accountId}/tracking-tags/{tagId}/shared-accounts`

### Path parameters

- `adAccountId` (string; required; 1–80 characters): Ad account id (ada_…)
- `tagId` (string; required; 1–256 characters)

### Headers

- `Idempotency-Key` (string; ≤ 255 characters): Unique key (for example a UUID) that makes retries safe: a repeated request with the same key and body returns the first response (Idempotent-Replayed: true) for 24 hours.

### Body

- `ad_account_id` (string; required; 1–256 characters)
- `business_id` (string; 1–64 characters)

```bash
curl -X POST "https://api.socialit.com/v1/ads/accounts/ada_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd/tracking-tags/TAG_ID/shared-accounts" \
  -H "Authorization: Bearer $SOCIALIT_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "ad_account_id": "string",
    "business_id": "string"
  }'
```

Response 201:

```json
{
  "object": "tracking_tag_shared_account",
  "id": "string",
  "name": "string",
  "business_id": "string",
  "role": "string"
}
```

## Stop sharing a tag with an account

`DELETE /ads/accounts/{adAccountId}/tracking-tags/{tagId}/shared-accounts/{sharedAccountId}`

Access: `write` · MCP tool: `unshare-tracking-tag` · Zernio: `DELETE /v1/accounts/{accountId}/tracking-tags/{tagId}/shared-accounts`

### Path parameters

- `adAccountId` (string; required; 1–80 characters): Ad account id (ada_…)
- `tagId` (string; required; 1–256 characters)
- `sharedAccountId` (string; required; 1–256 characters)

### Query parameters

- `business_id` (string; 1–64 characters)

```bash
curl -X DELETE "https://api.socialit.com/v1/ads/accounts/ada_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd/tracking-tags/TAG_ID/shared-accounts/SHARED_ACCOUNT_ID" \
  -H "Authorization: Bearer $SOCIALIT_API_KEY"
```

Response 200:

```json
{
  "object": "tracking_tag_shared_account",
  "id": "string",
  "deleted": true
}
```

## List conversion events of a tag

`GET /ads/accounts/{adAccountId}/tracking-tags/{tagId}/events`

Access: `read` · MCP tool: `list-tracking-tag-events` · Zernio: `GET /v1/accounts/{accountId}/tracking-tags/{tagId}/events`

### Path parameters

- `adAccountId` (string; required; 1–80 characters): Ad account id (ada_…)
- `tagId` (string; required; 1–256 characters)

```bash
curl "https://api.socialit.com/v1/ads/accounts/ada_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd/tracking-tags/TAG_ID/events" \
  -H "Authorization: Bearer $SOCIALIT_API_KEY"
```

Response 200:

```json
{
  "object": "list",
  "data": [
    {
      "object": "tracking_tag_event",
      "id": "string",
      "name": "string",
      "type": "string",
      "site_event": "string",
      "site_event_id": "string",
      "status": "string",
      "default_value": 1.5,
      "currency": "USD",
      "click_window_days": 1.5,
      "view_window_days": 1.5,
      "url_contains": "string",
      "always_use_default_value": true,
      "primary": true,
      "counting_type": "string"
    }
  ],
  "page": 1,
  "limit": 1,
  "total": 1,
  "has_more": true,
  "next_page_url": "https://example.com",
  "previous_page_url": "https://example.com",
  "next_cursor": "string"
}
```

## Create a conversion event

`POST /ads/accounts/{adAccountId}/tracking-tags/{tagId}/events`

Not idempotent on the networks. A field the network does not store → 422.

Access: `write` · MCP tool: `create-tracking-tag-event` · Zernio: `POST /v1/accounts/{accountId}/tracking-tags/{tagId}/events`

### Path parameters

- `adAccountId` (string; required; 1–80 characters): Ad account id (ada_…)
- `tagId` (string; required; 1–256 characters)

### Headers

- `Idempotency-Key` (string; ≤ 255 characters): Unique key (for example a UUID) that makes retries safe: a repeated request with the same key and body returns the first response (Idempotent-Replayed: true) for 24 hours.

### Body

- `name` (string; required; 1–100 characters)
- `type` (string; 1–64 characters)
- `site_event` (string; one of page_view, view_content, add_to_cart, search, initiate_checkout, add_payment_info, purchase)
- `enabled` (boolean)
- `default_value` (number)
- `currency` (string; pattern ^[A-Za-z]{3}$)
- `click_window_days` (integer; 1–365)
- `view_window_days` (integer; 0–365)
- `url_contains` (string; 1–500 characters)
- `counting_type` (string; one of one, every)

```bash
curl -X POST "https://api.socialit.com/v1/ads/accounts/ada_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd/tracking-tags/TAG_ID/events" \
  -H "Authorization: Bearer $SOCIALIT_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "string",
    "type": "string",
    "site_event": "page_view",
    "enabled": true,
    "default_value": 0
  }'
```

Response 201:

```json
{
  "object": "tracking_tag_event",
  "id": "string",
  "name": "string",
  "type": "string",
  "site_event": "string",
  "site_event_id": "string",
  "status": "string",
  "default_value": 1.5,
  "currency": "USD",
  "click_window_days": 1.5,
  "view_window_days": 1.5,
  "url_contains": "string",
  "always_use_default_value": true,
  "primary": true,
  "counting_type": "string"
}
```

## Update a conversion event

`PATCH /ads/accounts/{adAccountId}/tracking-tags/{tagId}/events/{eventId}`

Access: `write` · MCP tool: `update-tracking-tag-event` · Zernio: `PATCH /v1/accounts/{accountId}/tracking-tags/{tagId}/events/{eventId}`

### Path parameters

- `adAccountId` (string; required; 1–80 characters): Ad account id (ada_…)
- `tagId` (string; required; 1–256 characters)
- `eventId` (string; required; 1–256 characters)

### Body

- `name` (string; 1–100 characters)
- `type` (string; 1–64 characters)
- `site_event` (string; one of page_view, view_content, add_to_cart, search, initiate_checkout, add_payment_info, purchase)
- `enabled` (boolean)
- `default_value` (number)
- `currency` (string; pattern ^[A-Za-z]{3}$)
- `click_window_days` (integer; 1–365)
- `view_window_days` (integer; 0–365)
- `url_contains` (string; 1–500 characters)
- `counting_type` (string; one of one, every)

```bash
curl -X PATCH "https://api.socialit.com/v1/ads/accounts/ada_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd/tracking-tags/TAG_ID/events/EVENT_ID" \
  -H "Authorization: Bearer $SOCIALIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "string",
    "type": "string",
    "site_event": "page_view",
    "enabled": true,
    "default_value": 0
  }'
```

Response 200:

```json
{
  "object": "tracking_tag_event",
  "id": "string",
  "name": "string",
  "type": "string",
  "site_event": "string",
  "site_event_id": "string",
  "status": "string",
  "default_value": 1.5,
  "currency": "USD",
  "click_window_days": 1.5,
  "view_window_days": 1.5,
  "url_contains": "string",
  "always_use_default_value": true,
  "primary": true,
  "counting_type": "string"
}
```

## Delete a conversion event

`DELETE /ads/accounts/{adAccountId}/tracking-tags/{tagId}/events/{eventId}`

Archives or disables it on networks without a hard delete (state).

Access: `write` · MCP tool: `delete-tracking-tag-event` · Zernio: `DELETE /v1/accounts/{accountId}/tracking-tags/{tagId}/events/{eventId}`

### Path parameters

- `adAccountId` (string; required; 1–80 characters): Ad account id (ada_…)
- `tagId` (string; required; 1–256 characters)
- `eventId` (string; required; 1–256 characters)

```bash
curl -X DELETE "https://api.socialit.com/v1/ads/accounts/ada_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd/tracking-tags/TAG_ID/events/EVENT_ID" \
  -H "Authorization: Bearer $SOCIALIT_API_KEY"
```

Response 200:

```json
{
  "object": "tracking_tag_event",
  "id": "string",
  "deleted": true,
  "state": "string"
}
```

## List tag users

`GET /ads/accounts/{adAccountId}/tracking-tags/{tagId}/users`

Access: `read` · MCP tool: `list-tracking-tag-users` · Zernio: `GET /v1/accounts/{accountId}/tracking-tags/{tagId}/users`

### Path parameters

- `adAccountId` (string; required; 1–80 characters): Ad account id (ada_…)
- `tagId` (string; required; 1–256 characters)

```bash
curl "https://api.socialit.com/v1/ads/accounts/ada_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd/tracking-tags/TAG_ID/users" \
  -H "Authorization: Bearer $SOCIALIT_API_KEY"
```

Response 200:

```json
{
  "object": "list",
  "data": [
    {
      "object": "tracking_tag_user",
      "id": "string",
      "name": "string",
      "tasks": [
        "string"
      ]
    }
  ],
  "page": 1,
  "limit": 1,
  "total": 1,
  "has_more": true,
  "next_page_url": "https://example.com",
  "previous_page_url": "https://example.com",
  "next_cursor": "string"
}
```

## Assign a user to a tag

`POST /ads/accounts/{adAccountId}/tracking-tags/{tagId}/users`

Access: `admin` · MCP tool: `assign-tracking-tag-user` · Zernio: `POST /v1/accounts/{accountId}/tracking-tags/{tagId}/users`

### Path parameters

- `adAccountId` (string; required; 1–80 characters): Ad account id (ada_…)
- `tagId` (string; required; 1–256 characters)

### Headers

- `Idempotency-Key` (string; ≤ 255 characters): Unique key (for example a UUID) that makes retries safe: a repeated request with the same key and body returns the first response (Idempotent-Replayed: true) for 24 hours.

### Body

- `user_id` (string; required; 1–64 characters)
- `tasks` (array of string; required; ≥ 1 items)
- `business_id` (string; 1–64 characters)

```bash
curl -X POST "https://api.socialit.com/v1/ads/accounts/ada_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd/tracking-tags/TAG_ID/users" \
  -H "Authorization: Bearer $SOCIALIT_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "user_id": "string",
    "tasks": [
      "AA_ANALYZE"
    ],
    "business_id": "string"
  }'
```

Response 201:

```json
{
  "object": "tracking_tag_user",
  "id": "string",
  "name": "string",
  "tasks": [
    "string"
  ]
}
```

## Remove a user from a tag

`DELETE /ads/accounts/{adAccountId}/tracking-tags/{tagId}/users/{userId}`

Access: `admin` · MCP tool: `remove-tracking-tag-user` · Zernio: `DELETE /v1/accounts/{accountId}/tracking-tags/{tagId}/users/{userId}`

### Path parameters

- `adAccountId` (string; required; 1–80 characters): Ad account id (ada_…)
- `tagId` (string; required; 1–256 characters)
- `userId` (string; required; 1–256 characters)

```bash
curl -X DELETE "https://api.socialit.com/v1/ads/accounts/ada_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd/tracking-tags/TAG_ID/users/USER_ID" \
  -H "Authorization: Bearer $SOCIALIT_API_KEY"
```

Response 200:

```json
{
  "object": "tracking_tag_user",
  "id": "string",
  "deleted": true
}
```

## List partner businesses of a tag

`GET /ads/accounts/{adAccountId}/tracking-tags/{tagId}/partners`

Access: `read` · MCP tool: `list-tracking-tag-partners` · Zernio: `GET /v1/accounts/{accountId}/tracking-tags/{tagId}/partners`

### Path parameters

- `adAccountId` (string; required; 1–80 characters): Ad account id (ada_…)
- `tagId` (string; required; 1–256 characters)

```bash
curl "https://api.socialit.com/v1/ads/accounts/ada_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd/tracking-tags/TAG_ID/partners" \
  -H "Authorization: Bearer $SOCIALIT_API_KEY"
```

Response 200:

```json
{
  "object": "list",
  "data": [
    {
      "object": "tracking_tag_partner",
      "id": "string",
      "name": "string"
    }
  ],
  "page": 1,
  "limit": 1,
  "total": 1,
  "has_more": true,
  "next_page_url": "https://example.com",
  "previous_page_url": "https://example.com",
  "next_cursor": "string"
}
```

## Get tag diagnostics

`GET /ads/accounts/{adAccountId}/tracking-tags/{tagId}/diagnostics`

Access: `read` · MCP tool: `get-tracking-tag-diagnostics` · Zernio: `GET /v1/accounts/{accountId}/tracking-tags/{tagId}/diagnostics`

### Path parameters

- `adAccountId` (string; required; 1–80 characters): Ad account id (ada_…)
- `tagId` (string; required; 1–256 characters)

```bash
curl "https://api.socialit.com/v1/ads/accounts/ada_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd/tracking-tags/TAG_ID/diagnostics" \
  -H "Authorization: Bearer $SOCIALIT_API_KEY"
```

Response 200:

```json
{
  "object": "list",
  "data": [
    {
      "object": "tracking_tag_diagnostic",
      "key": "string",
      "title": "string",
      "description": "string",
      "result": "string",
      "action_url": "https://example.com"
    }
  ],
  "page": 1,
  "limit": 1,
  "total": 1,
  "has_more": true,
  "next_page_url": "https://example.com",
  "previous_page_url": "https://example.com",
  "next_cursor": "string"
}
```

## Get aggregated tag stats

`GET /ads/accounts/{adAccountId}/tracking-tags/{tagId}/stats`

Access: `read` · MCP tool: `get-tracking-tag-stats` · Zernio: `GET /v1/accounts/{accountId}/tracking-tags/{tagId}/stats`

### Path parameters

- `adAccountId` (string; required; 1–80 characters): Ad account id (ada_…)
- `tagId` (string; required; 1–256 characters)

### Query parameters

- `aggregation` (string; one of event, host, url, url_by_rule, pixel_fire, device_type, device_os, browser_type, had_pii, custom_data_field, match_keys, event_source, …)
- `start_time` (string | integer): ISO 8601 date-time or unix seconds
- `end_time` (string | integer): ISO 8601 date-time or unix seconds

```bash
curl "https://api.socialit.com/v1/ads/accounts/ada_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd/tracking-tags/TAG_ID/stats" \
  -H "Authorization: Bearer $SOCIALIT_API_KEY"
```

Response 200:

```json
{
  "object": "tracking_tag_stats",
  "tag_id": "string",
  "platform": "string",
  "aggregation": "string",
  "start_time": "2026-10-13T09:00:00.000Z",
  "end_time": "2026-10-13T09:00:00.000Z",
  "rows": [
    {}
  ]
}
```

## List leads

`GET /ads/leads`

Stored lead-gen submissions (leadgen webhooks, live form reads, LinkedIn polling).

Access: `read` · MCP tool: `list-leads` · Zernio: `GET /v1/ads/leads`

### Query parameters

- `page` (integer; ≥ 1)
- `limit` (integer; 1–100)
- `ad_account_id` (string; 1–80 characters)
- `connection_id` (string; 1–80 characters)
- `form_id` (string; 1–64 characters)
- `platform` (string; 1–40 characters)
- `ad_id` (string; 1–64 characters)
- `campaign_id` (string; 1–64 characters)
- `is_test` (boolean)
- `is_organic` (boolean)
- `source` (string; one of webhook, sync, api)
- `since` (string; 1–40 characters)
- `until` (string; 1–40 characters)
- `sort` (string; one of submitted_at, created_at)
- `order` (string; one of asc, desc)

```bash
curl "https://api.socialit.com/v1/ads/leads" \
  -H "Authorization: Bearer $SOCIALIT_API_KEY"
```

Response 200:

```json
{
  "object": "list",
  "data": [
    {
      "object": "lead",
      "id": "string",
      "external_id": "string",
      "platform": "string",
      "connection_id": "string",
      "ad_account_id": "string",
      "profile_id": "string",
      "contact_id": "string",
      "form_id": "string",
      "form_name": "string",
      "page_id": "string",
      "ad_id": "string",
      "ad_set_id": "string",
      "campaign_id": "string",
      "is_organic": true,
      "is_test": true,
      "fields": {},
      "field_data": [
        {
          "name": "string",
          "values": []
        }
      ],
      "source": "string",
      "submitted_at": "2026-10-13T09:00:00.000Z",
      "created_at": "2026-10-13T09:00:00.000Z",
      "updated_at": "2026-10-13T09:00:00.000Z"
    }
  ],
  "page": 1,
  "limit": 1,
  "total": 1,
  "has_more": true,
  "next_page_url": "https://example.com",
  "previous_page_url": "https://example.com"
}
```

## Get a lead

`GET /ads/leads/{leadId}`

Access: `read` · MCP tool: `get-lead`

### Path parameters

- `leadId` (string; required; 1–80 characters)

```bash
curl "https://api.socialit.com/v1/ads/leads/LEAD_ID" \
  -H "Authorization: Bearer $SOCIALIT_API_KEY"
```

Response 200:

```json
{
  "object": "lead",
  "id": "string",
  "external_id": "string",
  "platform": "string",
  "connection_id": "string",
  "ad_account_id": "string",
  "profile_id": "string",
  "contact_id": "string",
  "form_id": "string",
  "form_name": "string",
  "page_id": "string",
  "ad_id": "string",
  "ad_set_id": "string",
  "campaign_id": "string",
  "is_organic": true,
  "is_test": true,
  "fields": {
    "key": "string"
  },
  "field_data": [
    {
      "name": "string",
      "values": [
        "string"
      ]
    }
  ],
  "source": "string",
  "submitted_at": "2026-10-13T09:00:00.000Z",
  "created_at": "2026-10-13T09:00:00.000Z",
  "updated_at": "2026-10-13T09:00:00.000Z"
}
```

## List lead forms

`GET /ads/lead-forms`

Meta instant forms of a Page, LinkedIn Lead Gen Forms of a sponsored account.

Access: `read` · MCP tool: `list-lead-forms` · Zernio: `GET /v1/ads/lead-forms`

### Query parameters

- `ad_account_id` (string; ≤ 80 characters): Ad account (ada_…)
- `connection_id` (string; ≤ 80 characters): Ads connection (adc_…), with platform_ad_account_id when it has several ad accounts
- `platform_ad_account_id` (string; ≤ 256 characters): Network ad account id (act_…, customer id, advertiser id …)
- `page_id` (string; 1–64 characters)
- `status` (string; 1–32 characters)
- `limit` (integer; 1–100): Items per page (max 100)
- `cursor` (string; ≤ 4096 characters): next_cursor from the previous page
- `after` (string; ≤ 4096 characters): Alias of cursor

```bash
curl "https://api.socialit.com/v1/ads/lead-forms" \
  -H "Authorization: Bearer $SOCIALIT_API_KEY"
```

Response 200:

```json
{
  "object": "list",
  "data": [
    {
      "object": "lead_form",
      "id": "string",
      "platform": "string",
      "name": "string",
      "status": "string",
      "locale": "en",
      "page_id": "string",
      "ad_account_id": "string",
      "leads_count": 1,
      "privacy_policy_url": "https://example.com",
      "follow_up_action_url": "https://example.com",
      "headline": "string",
      "description": "string",
      "questions": [
        {
          "id": "string",
          "key": "string",
          "label": "string",
          "type": "string",
          "options": []
        }
      ],
      "thank_you_page": {
        "title": "string",
        "body": "string",
        "button_text": "string",
        "button_type": "string",
        "website_url": "https://example.com"
      },
      "created_at": "2026-10-13T09:00:00.000Z",
      "raw": {}
    }
  ],
  "page": 1,
  "limit": 1,
  "total": 1,
  "has_more": true,
  "next_page_url": "https://example.com",
  "previous_page_url": "https://example.com",
  "next_cursor": "string"
}
```

## Create a lead form

`POST /ads/lead-forms`

Access: `write` · MCP tool: `create-lead-form` · Zernio: `POST /v1/ads/lead-forms`

### Headers

- `Idempotency-Key` (string; ≤ 255 characters): Unique key (for example a UUID) that makes retries safe: a repeated request with the same key and body returns the first response (Idempotent-Replayed: true) for 24 hours.

### Body

- `ad_account_id` (string; ≤ 80 characters): Ad account (ada_…)
- `connection_id` (string; ≤ 80 characters): Ads connection (adc_…), with platform_ad_account_id when it has several ad accounts
- `platform_ad_account_id` (string; ≤ 256 characters): Network ad account id (act_…, customer id, advertiser id …)
- `name` (string; required; 1–255 characters)
- `page_id` (string; 1–64 characters)
- `questions` (array of object; required; 1–30 items)
  - `questions[].type` (string; required; 1–64 characters)
  - `questions[].key` (string; 1–100 characters)
  - `questions[].label` (string; 1–500 characters)
  - `questions[].inline_context` (string; 1–500 characters)
  - `questions[].options` (array of object; ≤ 50 items)
    - `questions[].options[].value` (string; required; 1–200 characters)
    - `questions[].options[].key` (string; 1–100 characters)
- `privacy_policy_url` (string (uri); required; ≤ 2048 characters)
- `privacy_policy_link_text` (string; 1–70 characters)
- `follow_up_action_url` (string (uri); ≤ 2048 characters)
- `locale` (string; pattern ^[a-z]{2}_[A-Z]{2}$)
- `thank_you_title` (string; 1–60 characters)
- `thank_you_body` (string; 1–500 characters)
- `thank_you_button_text` (string; 1–60 characters)
- `thank_you_button_type` (string; 1–64 characters)
- `thank_you_website_url` (string (uri); ≤ 2048 characters)
- `is_optimized_for_quality` (boolean)
- `headline` (string; 1–60 characters)
- `description` (string; 1–160 characters)
- `state` (string; one of DRAFT, PUBLISHED)
- `platform_data` (object)

```bash
curl -X POST "https://api.socialit.com/v1/ads/lead-forms" \
  -H "Authorization: Bearer $SOCIALIT_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "ad_account_id": "ada_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd",
    "connection_id": "adc_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd",
    "name": "string",
    "questions": [
      {
        "type": "string",
        "key": "string"
      }
    ],
    "privacy_policy_url": "https://example.com"
  }'
```

Response 201:

```json
{
  "object": "lead_form",
  "id": "string",
  "platform": "string",
  "name": "string",
  "status": "string",
  "locale": "en",
  "page_id": "string",
  "ad_account_id": "string",
  "leads_count": 1,
  "privacy_policy_url": "https://example.com",
  "follow_up_action_url": "https://example.com",
  "headline": "string",
  "description": "string",
  "questions": [
    {
      "id": "string",
      "key": "string",
      "label": "string",
      "type": "string",
      "options": [
        {
          "value": "string",
          "key": "string"
        }
      ]
    }
  ],
  "thank_you_page": {
    "title": "string",
    "body": "string",
    "button_text": "string",
    "button_type": "string",
    "website_url": "https://example.com"
  },
  "created_at": "2026-10-13T09:00:00.000Z",
  "raw": {}
}
```

## Get a lead form

`GET /ads/lead-forms/{formId}`

Access: `read` · MCP tool: `get-lead-form` · Zernio: `GET /v1/ads/lead-forms/{formId}`

### Path parameters

- `formId` (string; required; 1–256 characters)

### Query parameters

- `ad_account_id` (string; ≤ 80 characters): Ad account (ada_…)
- `connection_id` (string; ≤ 80 characters): Ads connection (adc_…), with platform_ad_account_id when it has several ad accounts
- `platform_ad_account_id` (string; ≤ 256 characters): Network ad account id (act_…, customer id, advertiser id …)
- `page_id` (string; 1–64 characters)

```bash
curl "https://api.socialit.com/v1/ads/lead-forms/FORM_ID" \
  -H "Authorization: Bearer $SOCIALIT_API_KEY"
```

Response 200:

```json
{
  "object": "lead_form",
  "id": "string",
  "platform": "string",
  "name": "string",
  "status": "string",
  "locale": "en",
  "page_id": "string",
  "ad_account_id": "string",
  "leads_count": 1,
  "privacy_policy_url": "https://example.com",
  "follow_up_action_url": "https://example.com",
  "headline": "string",
  "description": "string",
  "questions": [
    {
      "id": "string",
      "key": "string",
      "label": "string",
      "type": "string",
      "options": [
        {
          "value": "string",
          "key": "string"
        }
      ]
    }
  ],
  "thank_you_page": {
    "title": "string",
    "body": "string",
    "button_text": "string",
    "button_type": "string",
    "website_url": "https://example.com"
  },
  "created_at": "2026-10-13T09:00:00.000Z",
  "raw": {}
}
```

## Archive a lead form

`DELETE /ads/lead-forms/{formId}`

Access: `write` · MCP tool: `archive-lead-form` · Zernio: `DELETE /v1/ads/lead-forms/{formId}`

### Path parameters

- `formId` (string; required; 1–256 characters)

### Query parameters

- `ad_account_id` (string; ≤ 80 characters): Ad account (ada_…)
- `connection_id` (string; ≤ 80 characters): Ads connection (adc_…), with platform_ad_account_id when it has several ad accounts
- `platform_ad_account_id` (string; ≤ 256 characters): Network ad account id (act_…, customer id, advertiser id …)
- `page_id` (string; 1–64 characters)

```bash
curl -X DELETE "https://api.socialit.com/v1/ads/lead-forms/FORM_ID" \
  -H "Authorization: Bearer $SOCIALIT_API_KEY"
```

Response 200:

```json
{
  "object": "lead_form",
  "id": "string",
  "archived": true,
  "deleted": true
}
```

## List the leads of a form

`GET /ads/lead-forms/{formId}/leads`

Reads the form’s leads live and stores them (new leads emit lead.received).

Access: `read` · MCP tool: `list-lead-form-leads` · Zernio: `GET /v1/ads/lead-forms/{formId}/leads`

### Path parameters

- `formId` (string; required; 1–256 characters)

### Query parameters

- `ad_account_id` (string; ≤ 80 characters): Ad account (ada_…)
- `connection_id` (string; ≤ 80 characters): Ads connection (adc_…), with platform_ad_account_id when it has several ad accounts
- `platform_ad_account_id` (string; ≤ 256 characters): Network ad account id (act_…, customer id, advertiser id …)
- `page_id` (string; 1–64 characters)
- `since` (string | integer): ISO 8601 date-time or unix seconds
- `limit` (integer; 1–100): Items per page (max 100)
- `cursor` (string; ≤ 4096 characters): next_cursor from the previous page
- `after` (string; ≤ 4096 characters): Alias of cursor

```bash
curl "https://api.socialit.com/v1/ads/lead-forms/FORM_ID/leads" \
  -H "Authorization: Bearer $SOCIALIT_API_KEY"
```

Response 200:

```json
{
  "object": "list",
  "data": [
    {
      "object": "lead",
      "id": "string",
      "external_id": "string",
      "platform": "string",
      "connection_id": "string",
      "ad_account_id": "string",
      "profile_id": "string",
      "contact_id": "string",
      "form_id": "string",
      "form_name": "string",
      "page_id": "string",
      "ad_id": "string",
      "ad_set_id": "string",
      "campaign_id": "string",
      "is_organic": true,
      "is_test": true,
      "fields": {},
      "field_data": [
        {
          "name": "string",
          "values": []
        }
      ],
      "source": "string",
      "submitted_at": "2026-10-13T09:00:00.000Z",
      "created_at": "2026-10-13T09:00:00.000Z",
      "updated_at": "2026-10-13T09:00:00.000Z"
    }
  ],
  "page": 1,
  "limit": 1,
  "total": 1,
  "has_more": true,
  "next_page_url": "https://example.com",
  "previous_page_url": "https://example.com",
  "next_cursor": "string"
}
```

## Create a test lead

`POST /ads/lead-forms/{formId}/test-leads`

Access: `write` · MCP tool: `create-test-lead` · Zernio: `POST /v1/ads/lead-forms/{formId}/test-leads`

### Path parameters

- `formId` (string; required; 1–256 characters)

### Headers

- `Idempotency-Key` (string; ≤ 255 characters): Unique key (for example a UUID) that makes retries safe: a repeated request with the same key and body returns the first response (Idempotent-Replayed: true) for 24 hours.

### Body

- `ad_account_id` (string; ≤ 80 characters): Ad account (ada_…)
- `connection_id` (string; ≤ 80 characters): Ads connection (adc_…), with platform_ad_account_id when it has several ad accounts
- `platform_ad_account_id` (string; ≤ 256 characters): Network ad account id (act_…, customer id, advertiser id …)
- `page_id` (string; 1–64 characters)
- `field_data` (array of object; required; 1–50 items)
  - `field_data[].name` (string; required; 1–100 characters)
  - `field_data[].values` (array of string; required; ≥ 1 items)

```bash
curl -X POST "https://api.socialit.com/v1/ads/lead-forms/FORM_ID/test-leads" \
  -H "Authorization: Bearer $SOCIALIT_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "ad_account_id": "ada_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd",
    "connection_id": "adc_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd",
    "platform_ad_account_id": "string",
    "page_id": "string",
    "field_data": [
      {
        "name": "string",
        "values": [
          "string"
        ]
      }
    ]
  }'
```

Response 201:

```json
{
  "object": "test_lead",
  "id": "string",
  "form_id": "string"
}
```

## Delete test leads

`DELETE /ads/lead-forms/{formId}/test-leads`

Access: `write` · MCP tool: `delete-test-leads` · Zernio: `DELETE /v1/ads/lead-forms/{formId}/test-leads`

### Path parameters

- `formId` (string; required; 1–256 characters)

### Query parameters

- `ad_account_id` (string; ≤ 80 characters): Ad account (ada_…)
- `connection_id` (string; ≤ 80 characters): Ads connection (adc_…), with platform_ad_account_id when it has several ad accounts
- `platform_ad_account_id` (string; ≤ 256 characters): Network ad account id (act_…, customer id, advertiser id …)
- `page_id` (string; 1–64 characters)
- `lead_id` (string; 1–64 characters)

```bash
curl -X DELETE "https://api.socialit.com/v1/ads/lead-forms/FORM_ID/test-leads" \
  -H "Authorization: Bearer $SOCIALIT_API_KEY"
```

Response 200:

```json
{
  "object": "test_lead",
  "deleted": true,
  "ids": [
    "string"
  ]
}
```

## List product catalogs

`GET /ads/catalogs`

Meta Commerce catalogs owned by (or shared with) a business portfolio.

Access: `read` · MCP tool: `list-catalogs` · Zernio: `GET /v1/ads/catalogs`

### Query parameters

- `ad_account_id` (string; ≤ 80 characters): Ad account (ada_…)
- `connection_id` (string; ≤ 80 characters): Ads connection (adc_…), with platform_ad_account_id when it has several ad accounts
- `platform_ad_account_id` (string; ≤ 256 characters): Network ad account id (act_…, customer id, advertiser id …)
- `business_id` (string; 1–64 characters)
- `limit` (integer; 1–100): Items per page (max 100)
- `cursor` (string; ≤ 4096 characters): next_cursor from the previous page
- `after` (string; ≤ 4096 characters): Alias of cursor

```bash
curl "https://api.socialit.com/v1/ads/catalogs" \
  -H "Authorization: Bearer $SOCIALIT_API_KEY"
```

Response 200:

```json
{
  "object": "list",
  "data": [
    {
      "object": "catalog",
      "id": "string",
      "name": "string",
      "vertical": "string",
      "product_count": 1,
      "business_id": "string"
    }
  ],
  "page": 1,
  "limit": 1,
  "total": 1,
  "has_more": true,
  "next_page_url": "https://example.com",
  "previous_page_url": "https://example.com",
  "next_cursor": "string",
  "business_id": "string"
}
```

## Create a product catalog

`POST /ads/catalogs`

Access: `write` · MCP tool: `create-catalog` · Zernio: `POST /v1/ads/catalogs`

### Headers

- `Idempotency-Key` (string; ≤ 255 characters): Unique key (for example a UUID) that makes retries safe: a repeated request with the same key and body returns the first response (Idempotent-Replayed: true) for 24 hours.

### Body

- `ad_account_id` (string; ≤ 80 characters): Ad account (ada_…)
- `connection_id` (string; ≤ 80 characters): Ads connection (adc_…), with platform_ad_account_id when it has several ad accounts
- `platform_ad_account_id` (string; ≤ 256 characters): Network ad account id (act_…, customer id, advertiser id …)
- `business_id` (string; 1–64 characters)
- `name` (string; required; 1–200 characters)
- `vertical` (string; one of commerce, vehicles, hotels, flights, destinations, home_listings, local_service_business, offline_commerce, ticketed_experiences, transactable_items)

```bash
curl -X POST "https://api.socialit.com/v1/ads/catalogs" \
  -H "Authorization: Bearer $SOCIALIT_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "ad_account_id": "ada_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd",
    "connection_id": "adc_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd",
    "platform_ad_account_id": "string",
    "business_id": "string",
    "name": "string"
  }'
```

Response 201:

```json
{
  "object": "catalog",
  "id": "string",
  "name": "string",
  "vertical": "string",
  "product_count": 1,
  "business_id": "string"
}
```

## Get a product catalog

`GET /ads/catalogs/{catalogId}`

Access: `read` · MCP tool: `get-catalog` · Zernio: `GET /v1/ads/catalogs/{catalogId}`

### Path parameters

- `catalogId` (string; required; 1–256 characters)

### Query parameters

- `ad_account_id` (string; ≤ 80 characters): Ad account (ada_…)
- `connection_id` (string; ≤ 80 characters): Ads connection (adc_…), with platform_ad_account_id when it has several ad accounts
- `platform_ad_account_id` (string; ≤ 256 characters): Network ad account id (act_…, customer id, advertiser id …)
- `business_id` (string; 1–64 characters)
- `limit` (integer; 1–100): Items per page (max 100)
- `cursor` (string; ≤ 4096 characters): next_cursor from the previous page
- `after` (string; ≤ 4096 characters): Alias of cursor

```bash
curl "https://api.socialit.com/v1/ads/catalogs/CATALOG_ID" \
  -H "Authorization: Bearer $SOCIALIT_API_KEY"
```

Response 200:

```json
{
  "object": "catalog",
  "id": "string",
  "name": "string",
  "vertical": "string",
  "product_count": 1,
  "business_id": "string"
}
```

## Delete a product catalog

`DELETE /ads/catalogs/{catalogId}`

Access: `write` · MCP tool: `delete-catalog` · Zernio: `DELETE /v1/ads/catalogs/{catalogId}`

### Path parameters

- `catalogId` (string; required; 1–256 characters)

### Query parameters

- `ad_account_id` (string; ≤ 80 characters): Ad account (ada_…)
- `connection_id` (string; ≤ 80 characters): Ads connection (adc_…), with platform_ad_account_id when it has several ad accounts
- `platform_ad_account_id` (string; ≤ 256 characters): Network ad account id (act_…, customer id, advertiser id …)
- `business_id` (string; 1–64 characters)
- `limit` (integer; 1–100): Items per page (max 100)
- `cursor` (string; ≤ 4096 characters): next_cursor from the previous page
- `after` (string; ≤ 4096 characters): Alias of cursor

```bash
curl -X DELETE "https://api.socialit.com/v1/ads/catalogs/CATALOG_ID" \
  -H "Authorization: Bearer $SOCIALIT_API_KEY"
```

Response 200:

```json
{
  "object": "catalog",
  "id": "string",
  "deleted": true
}
```

## List catalog products

`GET /ads/catalogs/{catalogId}/products`

Access: `read` · MCP tool: `list-catalog-products` · Zernio: `GET /v1/ads/catalogs/{catalogId}/products`

### Path parameters

- `catalogId` (string; required; 1–256 characters)

### Query parameters

- `ad_account_id` (string; ≤ 80 characters): Ad account (ada_…)
- `connection_id` (string; ≤ 80 characters): Ads connection (adc_…), with platform_ad_account_id when it has several ad accounts
- `platform_ad_account_id` (string; ≤ 256 characters): Network ad account id (act_…, customer id, advertiser id …)
- `retailer_id` (string; 1–100 characters)
- `limit` (integer; 1–100): Items per page (max 100)
- `cursor` (string; ≤ 4096 characters): next_cursor from the previous page
- `after` (string; ≤ 4096 characters): Alias of cursor

```bash
curl "https://api.socialit.com/v1/ads/catalogs/CATALOG_ID/products" \
  -H "Authorization: Bearer $SOCIALIT_API_KEY"
```

Response 200:

```json
{
  "object": "list",
  "data": [
    {
      "object": "catalog_product",
      "id": "string",
      "retailer_id": "string",
      "name": "string",
      "description": "string",
      "url": "https://example.com",
      "image_url": "https://example.com",
      "additional_image_urls": [
        "string"
      ],
      "price": "string",
      "sale_price": "string",
      "currency": "USD",
      "availability": "string",
      "condition": "string",
      "brand": "string",
      "category": "string",
      "product_type": "string",
      "gtin": "string",
      "inventory": 1,
      "visibility": "string",
      "color": "string",
      "size": "string",
      "gender": "string",
      "material": "string",
      "pattern": "string",
      "custom_labels": [
        "string"
      ],
      "review_status": "string",
      "review_rejection_reasons": [
        "string"
      ]
    }
  ],
  "page": 1,
  "limit": 1,
  "total": 1,
  "has_more": true,
  "next_page_url": "https://example.com",
  "previous_page_url": "https://example.com",
  "next_cursor": "string"
}
```

## Add a product

`POST /ads/catalogs/{catalogId}/products`

Access: `write` · MCP tool: `create-catalog-product` · Zernio: `POST /v1/ads/catalogs/{catalogId}/products`

### Path parameters

- `catalogId` (string; required; 1–256 characters)

### Headers

- `Idempotency-Key` (string; ≤ 255 characters): Unique key (for example a UUID) that makes retries safe: a repeated request with the same key and body returns the first response (Idempotent-Replayed: true) for 24 hours.

### Body

- `ad_account_id` (string; ≤ 80 characters): Ad account (ada_…)
- `connection_id` (string; ≤ 80 characters): Ads connection (adc_…), with platform_ad_account_id when it has several ad accounts
- `platform_ad_account_id` (string; ≤ 256 characters): Network ad account id (act_…, customer id, advertiser id …)
- `product` (object; required)
  - `product.retailer_id` (string; 1–100 characters)
  - `product.name` (string; 1–200 characters)
  - `product.description` (string; 1–9999 characters)
  - `product.url` (string (uri); ≤ 2048 characters)
  - `product.image_url` (string (uri); ≤ 2048 characters)
  - `product.additional_image_urls` (array of string (uri); ≤ 20 items)
  - `product.price` (number)
  - `product.currency` (string; pattern ^[A-Za-z]{3}$)
  - `product.sale_price` (number)
  - `product.sale_price_start_date` (string; 1–40 characters)
  - `product.sale_price_end_date` (string; 1–40 characters)
  - `product.availability` (string; one of in stock, out of stock, preorder, available for order, discontinued, pending)
  - `product.condition` (string; one of new, refurbished, used)
  - `product.brand` (string; 1–100 characters)
  - `product.category` (string; 1–250 characters)
  - `product.google_product_category` (string; 1–250 characters)
  - `product.product_type` (string; 1–750 characters)
  - `product.gtin` (string; 1–70 characters)
  - `product.mpn` (string; 1–100 characters)
  - `product.inventory` (integer)
  - `product.visibility` (string; one of published, staging)
  - `product.color` (string; 1–200 characters)
  - `product.size` (string; 1–200 characters)
  - `product.gender` (string; one of female, male, unisex)
  - `product.material` (string; 1–200 characters)
  - `product.pattern` (string; 1–100 characters)
  - `product.custom_label_0` (string; 1–100 characters)
  - `product.custom_label_1` (string; 1–100 characters)
  - `product.custom_label_2` (string; 1–100 characters)
  - `product.custom_label_3` (string; 1–100 characters)
  - `product.custom_label_4` (string; 1–100 characters)

```bash
curl -X POST "https://api.socialit.com/v1/ads/catalogs/CATALOG_ID/products" \
  -H "Authorization: Bearer $SOCIALIT_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "ad_account_id": "ada_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd",
    "connection_id": "adc_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd",
    "platform_ad_account_id": "string",
    "product": {
      "retailer_id": "string",
      "name": "string"
    }
  }'
```

Response 201:

```json
{
  "object": "catalog_product",
  "id": "string",
  "retailer_id": "string",
  "name": "string",
  "description": "string",
  "url": "https://example.com",
  "image_url": "https://example.com",
  "additional_image_urls": [
    "string"
  ],
  "price": "string",
  "sale_price": "string",
  "currency": "USD",
  "availability": "string",
  "condition": "string",
  "brand": "string",
  "category": "string",
  "product_type": "string",
  "gtin": "string",
  "inventory": 1,
  "visibility": "string",
  "color": "string",
  "size": "string",
  "gender": "string",
  "material": "string",
  "pattern": "string",
  "custom_labels": [
    "string"
  ],
  "review_status": "string",
  "review_rejection_reasons": [
    "string"
  ]
}
```

## Create, update or delete products in bulk

`POST /ads/catalogs/{catalogId}/products/batch`

Up to 5,000 requests keyed by retailer_id, processed asynchronously (202).

Access: `write` · MCP tool: `batch-catalog-products` · Zernio: `POST /v1/ads/catalogs/{catalogId}/products/batch`

### Path parameters

- `catalogId` (string; required; 1–256 characters)

### Headers

- `Idempotency-Key` (string; ≤ 255 characters): Unique key (for example a UUID) that makes retries safe: a repeated request with the same key and body returns the first response (Idempotent-Replayed: true) for 24 hours.

### Body

- `ad_account_id` (string; ≤ 80 characters): Ad account (ada_…)
- `connection_id` (string; ≤ 80 characters): Ads connection (adc_…), with platform_ad_account_id when it has several ad accounts
- `platform_ad_account_id` (string; ≤ 256 characters): Network ad account id (act_…, customer id, advertiser id …)
- `requests` (array of object; required; 1–5000 items)
  - `requests[].method` (string; required; one of CREATE, UPDATE, DELETE)
  - `requests[].product` (object; required)
    - `requests[].product.retailer_id` (string; 1–100 characters)
    - `requests[].product.name` (string; 1–200 characters)
    - `requests[].product.description` (string; 1–9999 characters)
    - `requests[].product.url` (string (uri); ≤ 2048 characters)
    - `requests[].product.image_url` (string (uri); ≤ 2048 characters)
    - `requests[].product.additional_image_urls` (array of string (uri); ≤ 20 items)
    - `requests[].product.price` (number)
    - `requests[].product.currency` (string; pattern ^[A-Za-z]{3}$)
    - `requests[].product.sale_price` (number)
    - `requests[].product.sale_price_start_date` (string; 1–40 characters)
    - `requests[].product.sale_price_end_date` (string; 1–40 characters)
    - `requests[].product.availability` (string; one of in stock, out of stock, preorder, available for order, discontinued, pending)
    - `requests[].product.condition` (string; one of new, refurbished, used)
    - `requests[].product.brand` (string; 1–100 characters)
    - `requests[].product.category` (string; 1–250 characters)
    - `requests[].product.google_product_category` (string; 1–250 characters)
    - `requests[].product.product_type` (string; 1–750 characters)
    - `requests[].product.gtin` (string; 1–70 characters)
    - `requests[].product.mpn` (string; 1–100 characters)
    - `requests[].product.inventory` (integer)
    - `requests[].product.visibility` (string; one of published, staging)
    - `requests[].product.color` (string; 1–200 characters)
    - `requests[].product.size` (string; 1–200 characters)
    - `requests[].product.gender` (string; one of female, male, unisex)
    - `requests[].product.material` (string; 1–200 characters)
    - `requests[].product.pattern` (string; 1–100 characters)
    - `requests[].product.custom_label_0` (string; 1–100 characters)
    - `requests[].product.custom_label_1` (string; 1–100 characters)
    - `requests[].product.custom_label_2` (string; 1–100 characters)
    - `requests[].product.custom_label_3` (string; 1–100 characters)
    - `requests[].product.custom_label_4` (string; 1–100 characters)

```bash
curl -X POST "https://api.socialit.com/v1/ads/catalogs/CATALOG_ID/products/batch" \
  -H "Authorization: Bearer $SOCIALIT_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "ad_account_id": "ada_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd",
    "connection_id": "adc_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd",
    "platform_ad_account_id": "string",
    "requests": [
      {
        "method": "CREATE",
        "product": {
          "retailer_id": "string",
          "name": "string"
        }
      }
    ]
  }'
```

Response 202:

```json
{
  "object": "catalog_batch_request",
  "catalog_id": "string",
  "handles": [
    "string"
  ],
  "status_url": "https://example.com"
}
```

## Get a bulk request’s status

`GET /ads/catalogs/{catalogId}/batches/{handle}`

Access: `read` · MCP tool: `get-catalog-batch` · Zernio: `GET /v1/ads/catalogs/{catalogId}/batches/{handle}`

### Path parameters

- `catalogId` (string; required; 1–256 characters)
- `handle` (string; required; 1–256 characters)

### Query parameters

- `ad_account_id` (string; ≤ 80 characters): Ad account (ada_…)
- `connection_id` (string; ≤ 80 characters): Ads connection (adc_…), with platform_ad_account_id when it has several ad accounts
- `platform_ad_account_id` (string; ≤ 256 characters): Network ad account id (act_…, customer id, advertiser id …)
- `business_id` (string; 1–64 characters)
- `limit` (integer; 1–100): Items per page (max 100)
- `cursor` (string; ≤ 4096 characters): next_cursor from the previous page
- `after` (string; ≤ 4096 characters): Alias of cursor

```bash
curl "https://api.socialit.com/v1/ads/catalogs/CATALOG_ID/batches/HANDLE" \
  -H "Authorization: Bearer $SOCIALIT_API_KEY"
```

Response 200:

```json
{
  "object": "catalog_batch",
  "handle": "string",
  "status": "string",
  "errors_total_count": 1,
  "errors": [
    {
      "retailer_id": "string",
      "message": "string"
    }
  ]
}
```

## Get a product

`GET /ads/catalogs/{catalogId}/products/{productId}`

Access: `read` · MCP tool: `get-catalog-product` · Zernio: `GET /v1/ads/catalogs/{catalogId}/products/{productId}`

### Path parameters

- `catalogId` (string; required; 1–256 characters)
- `productId` (string; required; 1–256 characters)

### Query parameters

- `ad_account_id` (string; ≤ 80 characters): Ad account (ada_…)
- `connection_id` (string; ≤ 80 characters): Ads connection (adc_…), with platform_ad_account_id when it has several ad accounts
- `platform_ad_account_id` (string; ≤ 256 characters): Network ad account id (act_…, customer id, advertiser id …)
- `business_id` (string; 1–64 characters)
- `limit` (integer; 1–100): Items per page (max 100)
- `cursor` (string; ≤ 4096 characters): next_cursor from the previous page
- `after` (string; ≤ 4096 characters): Alias of cursor

```bash
curl "https://api.socialit.com/v1/ads/catalogs/CATALOG_ID/products/PRODUCT_ID" \
  -H "Authorization: Bearer $SOCIALIT_API_KEY"
```

Response 200:

```json
{
  "object": "catalog_product",
  "id": "string",
  "retailer_id": "string",
  "name": "string",
  "description": "string",
  "url": "https://example.com",
  "image_url": "https://example.com",
  "additional_image_urls": [
    "string"
  ],
  "price": "string",
  "sale_price": "string",
  "currency": "USD",
  "availability": "string",
  "condition": "string",
  "brand": "string",
  "category": "string",
  "product_type": "string",
  "gtin": "string",
  "inventory": 1,
  "visibility": "string",
  "color": "string",
  "size": "string",
  "gender": "string",
  "material": "string",
  "pattern": "string",
  "custom_labels": [
    "string"
  ],
  "review_status": "string",
  "review_rejection_reasons": [
    "string"
  ]
}
```

## Update a product

`PATCH /ads/catalogs/{catalogId}/products/{productId}`

Access: `write` · MCP tool: `update-catalog-product` · Zernio: `PUT /v1/ads/catalogs/{catalogId}/products/{productId}`

### Path parameters

- `catalogId` (string; required; 1–256 characters)
- `productId` (string; required; 1–256 characters)

### Body

- `ad_account_id` (string; ≤ 80 characters): Ad account (ada_…)
- `connection_id` (string; ≤ 80 characters): Ads connection (adc_…), with platform_ad_account_id when it has several ad accounts
- `platform_ad_account_id` (string; ≤ 256 characters): Network ad account id (act_…, customer id, advertiser id …)
- `product` (object; required)
  - `product.retailer_id` (string; 1–100 characters)
  - `product.name` (string; 1–200 characters)
  - `product.description` (string; 1–9999 characters)
  - `product.url` (string (uri); ≤ 2048 characters)
  - `product.image_url` (string (uri); ≤ 2048 characters)
  - `product.additional_image_urls` (array of string (uri); ≤ 20 items)
  - `product.price` (number)
  - `product.currency` (string; pattern ^[A-Za-z]{3}$)
  - `product.sale_price` (number)
  - `product.sale_price_start_date` (string; 1–40 characters)
  - `product.sale_price_end_date` (string; 1–40 characters)
  - `product.availability` (string; one of in stock, out of stock, preorder, available for order, discontinued, pending)
  - `product.condition` (string; one of new, refurbished, used)
  - `product.brand` (string; 1–100 characters)
  - `product.category` (string; 1–250 characters)
  - `product.google_product_category` (string; 1–250 characters)
  - `product.product_type` (string; 1–750 characters)
  - `product.gtin` (string; 1–70 characters)
  - `product.mpn` (string; 1–100 characters)
  - `product.inventory` (integer)
  - `product.visibility` (string; one of published, staging)
  - `product.color` (string; 1–200 characters)
  - `product.size` (string; 1–200 characters)
  - `product.gender` (string; one of female, male, unisex)
  - `product.material` (string; 1–200 characters)
  - `product.pattern` (string; 1–100 characters)
  - `product.custom_label_0` (string; 1–100 characters)
  - `product.custom_label_1` (string; 1–100 characters)
  - `product.custom_label_2` (string; 1–100 characters)
  - `product.custom_label_3` (string; 1–100 characters)
  - `product.custom_label_4` (string; 1–100 characters)

```bash
curl -X PATCH "https://api.socialit.com/v1/ads/catalogs/CATALOG_ID/products/PRODUCT_ID" \
  -H "Authorization: Bearer $SOCIALIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "ad_account_id": "ada_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd",
    "connection_id": "adc_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd",
    "platform_ad_account_id": "string",
    "product": {
      "retailer_id": "string",
      "name": "string"
    }
  }'
```

Response 200:

```json
{
  "object": "catalog_product",
  "id": "string",
  "retailer_id": "string",
  "name": "string",
  "description": "string",
  "url": "https://example.com",
  "image_url": "https://example.com",
  "additional_image_urls": [
    "string"
  ],
  "price": "string",
  "sale_price": "string",
  "currency": "USD",
  "availability": "string",
  "condition": "string",
  "brand": "string",
  "category": "string",
  "product_type": "string",
  "gtin": "string",
  "inventory": 1,
  "visibility": "string",
  "color": "string",
  "size": "string",
  "gender": "string",
  "material": "string",
  "pattern": "string",
  "custom_labels": [
    "string"
  ],
  "review_status": "string",
  "review_rejection_reasons": [
    "string"
  ]
}
```

## Delete a product

`DELETE /ads/catalogs/{catalogId}/products/{productId}`

Access: `write` · MCP tool: `delete-catalog-product` · Zernio: `DELETE /v1/ads/catalogs/{catalogId}/products/{productId}`

### Path parameters

- `catalogId` (string; required; 1–256 characters)
- `productId` (string; required; 1–256 characters)

### Query parameters

- `ad_account_id` (string; ≤ 80 characters): Ad account (ada_…)
- `connection_id` (string; ≤ 80 characters): Ads connection (adc_…), with platform_ad_account_id when it has several ad accounts
- `platform_ad_account_id` (string; ≤ 256 characters): Network ad account id (act_…, customer id, advertiser id …)
- `business_id` (string; 1–64 characters)
- `limit` (integer; 1–100): Items per page (max 100)
- `cursor` (string; ≤ 4096 characters): next_cursor from the previous page
- `after` (string; ≤ 4096 characters): Alias of cursor

```bash
curl -X DELETE "https://api.socialit.com/v1/ads/catalogs/CATALOG_ID/products/PRODUCT_ID" \
  -H "Authorization: Bearer $SOCIALIT_API_KEY"
```

Response 200:

```json
{
  "object": "catalog_product",
  "id": "string",
  "deleted": true
}
```

## List product feeds

`GET /ads/catalogs/{catalogId}/feeds`

Access: `read` · MCP tool: `list-catalog-feeds` · Zernio: `GET /v1/ads/catalogs/{catalogId}/feeds`

### Path parameters

- `catalogId` (string; required; 1–256 characters)

### Query parameters

- `ad_account_id` (string; ≤ 80 characters): Ad account (ada_…)
- `connection_id` (string; ≤ 80 characters): Ads connection (adc_…), with platform_ad_account_id when it has several ad accounts
- `platform_ad_account_id` (string; ≤ 256 characters): Network ad account id (act_…, customer id, advertiser id …)
- `business_id` (string; 1–64 characters)
- `limit` (integer; 1–100): Items per page (max 100)
- `cursor` (string; ≤ 4096 characters): next_cursor from the previous page
- `after` (string; ≤ 4096 characters): Alias of cursor

```bash
curl "https://api.socialit.com/v1/ads/catalogs/CATALOG_ID/feeds" \
  -H "Authorization: Bearer $SOCIALIT_API_KEY"
```

Response 200:

```json
{
  "object": "list",
  "data": [
    {
      "object": "catalog_feed",
      "id": "string",
      "name": "string",
      "product_count": 1,
      "schedule": {
        "interval": "string",
        "url": "https://example.com",
        "hour": 1,
        "day_of_week": "string"
      },
      "created_at": "2026-10-13T09:00:00.000Z",
      "latest_upload": {
        "object": "catalog_feed_upload",
        "id": "string",
        "url": "https://example.com",
        "start_time": "2026-10-13T09:00:00.000Z",
        "end_time": "2026-10-13T09:00:00.000Z",
        "error_count": 1
      }
    }
  ],
  "page": 1,
  "limit": 1,
  "total": 1,
  "has_more": true,
  "next_page_url": "https://example.com",
  "previous_page_url": "https://example.com",
  "next_cursor": "string"
}
```

## Create a product feed

`POST /ads/catalogs/{catalogId}/feeds`

Access: `write` · MCP tool: `create-catalog-feed` · Zernio: `POST /v1/ads/catalogs/{catalogId}/feeds`

### Path parameters

- `catalogId` (string; required; 1–256 characters)

### Headers

- `Idempotency-Key` (string; ≤ 255 characters): Unique key (for example a UUID) that makes retries safe: a repeated request with the same key and body returns the first response (Idempotent-Replayed: true) for 24 hours.

### Body

- `ad_account_id` (string; ≤ 80 characters): Ad account (ada_…)
- `connection_id` (string; ≤ 80 characters): Ads connection (adc_…), with platform_ad_account_id when it has several ad accounts
- `platform_ad_account_id` (string; ≤ 256 characters): Network ad account id (act_…, customer id, advertiser id …)
- `name` (string; required; 1–200 characters)
- `schedule` (object)
  - `schedule.interval` (string; required; one of HOURLY, DAILY, WEEKLY)
  - `schedule.url` (string (uri); required; ≤ 2048 characters)
  - `schedule.hour` (integer; 0–23)
  - `schedule.day_of_week` (string; one of SUNDAY, MONDAY, TUESDAY, WEDNESDAY, THURSDAY, FRIDAY, SATURDAY)

```bash
curl -X POST "https://api.socialit.com/v1/ads/catalogs/CATALOG_ID/feeds" \
  -H "Authorization: Bearer $SOCIALIT_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "ad_account_id": "ada_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd",
    "connection_id": "adc_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd",
    "platform_ad_account_id": "string",
    "name": "string",
    "schedule": {
      "interval": "HOURLY",
      "url": "https://example.com"
    }
  }'
```

Response 201:

```json
{
  "object": "catalog_feed",
  "id": "string",
  "name": "string",
  "product_count": 1,
  "schedule": {
    "interval": "string",
    "url": "https://example.com",
    "hour": 1,
    "day_of_week": "string"
  },
  "created_at": "2026-10-13T09:00:00.000Z",
  "latest_upload": {
    "object": "catalog_feed_upload",
    "id": "string",
    "url": "https://example.com",
    "start_time": "2026-10-13T09:00:00.000Z",
    "end_time": "2026-10-13T09:00:00.000Z",
    "error_count": 1,
    "warning_count": 1,
    "items_detected": 1,
    "items_deleted": 1
  }
}
```

## List a feed’s uploads

`GET /ads/catalogs/{catalogId}/feeds/{feedId}/uploads`

Access: `read` · MCP tool: `list-catalog-feed-uploads` · Zernio: `GET /v1/ads/catalogs/{catalogId}/feeds/{feedId}/uploads`

### Path parameters

- `catalogId` (string; required; 1–256 characters)
- `feedId` (string; required; 1–256 characters)

### Query parameters

- `ad_account_id` (string; ≤ 80 characters): Ad account (ada_…)
- `connection_id` (string; ≤ 80 characters): Ads connection (adc_…), with platform_ad_account_id when it has several ad accounts
- `platform_ad_account_id` (string; ≤ 256 characters): Network ad account id (act_…, customer id, advertiser id …)
- `business_id` (string; 1–64 characters)
- `limit` (integer; 1–100): Items per page (max 100)
- `cursor` (string; ≤ 4096 characters): next_cursor from the previous page
- `after` (string; ≤ 4096 characters): Alias of cursor

```bash
curl "https://api.socialit.com/v1/ads/catalogs/CATALOG_ID/feeds/FEED_ID/uploads" \
  -H "Authorization: Bearer $SOCIALIT_API_KEY"
```

Response 200:

```json
{
  "object": "list",
  "data": [
    {
      "object": "catalog_feed_upload",
      "id": "string",
      "url": "https://example.com",
      "start_time": "2026-10-13T09:00:00.000Z",
      "end_time": "2026-10-13T09:00:00.000Z",
      "error_count": 1,
      "warning_count": 1,
      "items_detected": 1,
      "items_deleted": 1
    }
  ],
  "page": 1,
  "limit": 1,
  "total": 1,
  "has_more": true,
  "next_page_url": "https://example.com",
  "previous_page_url": "https://example.com",
  "next_cursor": "string"
}
```

## Fetch a feed file now

`POST /ads/catalogs/{catalogId}/feeds/{feedId}/uploads`

Access: `write` · MCP tool: `create-catalog-feed-upload` · Zernio: `POST /v1/ads/catalogs/{catalogId}/feeds/{feedId}/uploads`

### Path parameters

- `catalogId` (string; required; 1–256 characters)
- `feedId` (string; required; 1–256 characters)

### Headers

- `Idempotency-Key` (string; ≤ 255 characters): Unique key (for example a UUID) that makes retries safe: a repeated request with the same key and body returns the first response (Idempotent-Replayed: true) for 24 hours.

### Body

- `ad_account_id` (string; ≤ 80 characters): Ad account (ada_…)
- `connection_id` (string; ≤ 80 characters): Ads connection (adc_…), with platform_ad_account_id when it has several ad accounts
- `platform_ad_account_id` (string; ≤ 256 characters): Network ad account id (act_…, customer id, advertiser id …)
- `url` (string (uri); required; ≤ 2048 characters)

```bash
curl -X POST "https://api.socialit.com/v1/ads/catalogs/CATALOG_ID/feeds/FEED_ID/uploads" \
  -H "Authorization: Bearer $SOCIALIT_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "ad_account_id": "ada_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd",
    "connection_id": "adc_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd",
    "platform_ad_account_id": "string",
    "url": "https://example.com"
  }'
```

Response 202:

```json
{
  "object": "catalog_feed_upload",
  "id": "string",
  "url": "https://example.com",
  "start_time": "2026-10-13T09:00:00.000Z",
  "end_time": "2026-10-13T09:00:00.000Z",
  "error_count": 1,
  "warning_count": 1,
  "items_detected": 1,
  "items_deleted": 1
}
```

## List product sets

`GET /ads/catalogs/{catalogId}/product-sets`

Access: `read` · MCP tool: `list-product-sets` · Zernio: `GET /v1/ads/catalogs/{catalogId}/product-sets`

### Path parameters

- `catalogId` (string; required; 1–256 characters)

### Query parameters

- `ad_account_id` (string; ≤ 80 characters): Ad account (ada_…)
- `connection_id` (string; ≤ 80 characters): Ads connection (adc_…), with platform_ad_account_id when it has several ad accounts
- `platform_ad_account_id` (string; ≤ 256 characters): Network ad account id (act_…, customer id, advertiser id …)
- `business_id` (string; 1–64 characters)
- `limit` (integer; 1–100): Items per page (max 100)
- `cursor` (string; ≤ 4096 characters): next_cursor from the previous page
- `after` (string; ≤ 4096 characters): Alias of cursor

```bash
curl "https://api.socialit.com/v1/ads/catalogs/CATALOG_ID/product-sets" \
  -H "Authorization: Bearer $SOCIALIT_API_KEY"
```

Response 200:

```json
{
  "object": "list",
  "data": [
    {
      "object": "product_set",
      "id": "string",
      "name": "string",
      "product_count": 1,
      "filter": {}
    }
  ],
  "page": 1,
  "limit": 1,
  "total": 1,
  "has_more": true,
  "next_page_url": "https://example.com",
  "previous_page_url": "https://example.com",
  "next_cursor": "string"
}
```

## Create a product set

`POST /ads/catalogs/{catalogId}/product-sets`

Access: `write` · MCP tool: `create-product-set` · Zernio: `POST /v1/ads/catalogs/{catalogId}/product-sets`

### Path parameters

- `catalogId` (string; required; 1–256 characters)

### Headers

- `Idempotency-Key` (string; ≤ 255 characters): Unique key (for example a UUID) that makes retries safe: a repeated request with the same key and body returns the first response (Idempotent-Replayed: true) for 24 hours.

### Body

- `ad_account_id` (string; ≤ 80 characters): Ad account (ada_…)
- `connection_id` (string; ≤ 80 characters): Ads connection (adc_…), with platform_ad_account_id when it has several ad accounts
- `platform_ad_account_id` (string; ≤ 256 characters): Network ad account id (act_…, customer id, advertiser id …)
- `name` (string; required; 1–200 characters)
- `filter` (object; required)

```bash
curl -X POST "https://api.socialit.com/v1/ads/catalogs/CATALOG_ID/product-sets" \
  -H "Authorization: Bearer $SOCIALIT_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "ad_account_id": "ada_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd",
    "connection_id": "adc_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd",
    "platform_ad_account_id": "string",
    "name": "string",
    "filter": {}
  }'
```

Response 201:

```json
{
  "object": "product_set",
  "id": "string",
  "name": "string",
  "product_count": 1,
  "filter": {}
}
```

## Update a product set

`PATCH /ads/catalogs/{catalogId}/product-sets/{productSetId}`

Access: `write` · MCP tool: `update-product-set` · Zernio: `PUT /v1/ads/catalogs/{catalogId}/product-sets/{productSetId}`

### Path parameters

- `catalogId` (string; required; 1–256 characters)
- `productSetId` (string; required; 1–256 characters)

### Body

- `ad_account_id` (string; ≤ 80 characters): Ad account (ada_…)
- `connection_id` (string; ≤ 80 characters): Ads connection (adc_…), with platform_ad_account_id when it has several ad accounts
- `platform_ad_account_id` (string; ≤ 256 characters): Network ad account id (act_…, customer id, advertiser id …)
- `name` (string; 1–200 characters)
- `filter` (object)

```bash
curl -X PATCH "https://api.socialit.com/v1/ads/catalogs/CATALOG_ID/product-sets/PRODUCT_SET_ID" \
  -H "Authorization: Bearer $SOCIALIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "ad_account_id": "ada_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd",
    "connection_id": "adc_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd",
    "platform_ad_account_id": "string",
    "name": "string",
    "filter": {}
  }'
```

Response 200:

```json
{
  "object": "product_set",
  "id": "string",
  "name": "string",
  "product_count": 1,
  "filter": {}
}
```

## Delete a product set

`DELETE /ads/catalogs/{catalogId}/product-sets/{productSetId}`

Access: `write` · MCP tool: `delete-product-set` · Zernio: `DELETE /v1/ads/catalogs/{catalogId}/product-sets/{productSetId}`

### Path parameters

- `catalogId` (string; required; 1–256 characters)
- `productSetId` (string; required; 1–256 characters)

### Query parameters

- `ad_account_id` (string; ≤ 80 characters): Ad account (ada_…)
- `connection_id` (string; ≤ 80 characters): Ads connection (adc_…), with platform_ad_account_id when it has several ad accounts
- `platform_ad_account_id` (string; ≤ 256 characters): Network ad account id (act_…, customer id, advertiser id …)
- `business_id` (string; 1–64 characters)
- `limit` (integer; 1–100): Items per page (max 100)
- `cursor` (string; ≤ 4096 characters): next_cursor from the previous page
- `after` (string; ≤ 4096 characters): Alias of cursor

```bash
curl -X DELETE "https://api.socialit.com/v1/ads/catalogs/CATALOG_ID/product-sets/PRODUCT_SET_ID" \
  -H "Authorization: Bearer $SOCIALIT_API_KEY"
```

Response 200:

```json
{
  "object": "product_set",
  "id": "string",
  "deleted": true
}
```

## Send conversion events

`POST /ads/conversions`

Relays server-side conversion events (PII normalized + SHA-256 hashed, never stored) to the network Conversions API.

Access: `write` · MCP tool: `send-conversions` · Zernio: `POST /v1/ads/conversions`

### Headers

- `Idempotency-Key` (string; ≤ 255 characters): Unique key (for example a UUID) that makes retries safe: a repeated request with the same key and body returns the first response (Idempotent-Replayed: true) for 24 hours.

### Body

- `ad_account_id` (string; ≤ 80 characters): Ad account (ada_…)
- `connection_id` (string; ≤ 80 characters): Ads connection (adc_…), with platform_ad_account_id when it has several ad accounts
- `platform_ad_account_id` (string; ≤ 256 characters): Network ad account id (act_…, customer id, advertiser id …)
- `destination_id` (string; required; 1–256 characters)
- `events` (array of object; required; 1–1000 items)
  - `events[].event_name` (string; required; 1–100 characters)
  - `events[].event_time` (string | integer; required): ISO 8601 date-time or unix seconds
  - `events[].event_id` (string; required; 1–100 characters)
  - `events[].value` (number)
  - `events[].currency` (string; pattern ^[A-Za-z]{3}$)
  - `events[].user` (object; required)
    - `events[].user.email` (string; 1–320 characters)
    - `events[].user.emails` (array of string; ≤ 10 items)
    - `events[].user.phone` (string; 1–64 characters)
    - `events[].user.phones` (array of string; ≤ 10 items)
    - `events[].user.first_name` (string; 1–200 characters)
    - `events[].user.last_name` (string; 1–200 characters)
    - `events[].user.city` (string; 1–200 characters)
    - `events[].user.state` (string; 1–100 characters)
    - `events[].user.zip` (string; 1–32 characters)
    - `events[].user.country` (string; 1–64 characters)
    - `events[].user.date_of_birth` (string; 1–16 characters)
    - `events[].user.gender` (string; 1–16 characters)
    - `events[].user.external_id` (string; 1–256 characters)
    - `events[].user.external_ids` (array of string; ≤ 10 items)
    - `events[].user.ip_address` (string; 1–64 characters)
    - `events[].user.user_agent` (string; 1–1024 characters)
    - `events[].user.company_name` (string; 1–200 characters)
    - `events[].user.title` (string; 1–200 characters)
    - `events[].user.fbc` (string; 1–500 characters)
    - `events[].user.fbp` (string; 1–500 characters)
    - `events[].user.gclid` (string; 1–500 characters)
    - `events[].user.gbraid` (string; 1–500 characters)
    - `events[].user.wbraid` (string; 1–500 characters)
    - `events[].user.ttclid` (string; 1–500 characters)
    - `events[].user.ttp` (string; 1–500 characters)
    - `events[].user.li_fat_id` (string; 1–500 characters)
    - `events[].user.epik` (string; 1–500 characters)
    - `events[].user.sc_click_id` (string; 1–500 characters)
    - `events[].user.sc_cookie1` (string; 1–500 characters)
    - `events[].user.rdt_cid` (string; 1–500 characters)
    - `events[].user.twclid` (string; 1–500 characters)
    - `events[].user.click_id` (string; 1–500 characters)
    - `events[].user.lead_id` (string; 1–64 characters)
    - `events[].user.uuid` (string; 1–200 characters)
    - `events[].user.hashed` (boolean)
  - `events[].items` (array of object; ≤ 200 items)
    - `events[].items[].id` (string; required; 1–100 characters)
    - `events[].items[].quantity` (integer; ≥ 1)
    - `events[].items[].price` (number)
    - `events[].items[].name` (string; 1–200 characters)
    - `events[].items[].category` (string; 1–200 characters)
  - `events[].source_url` (string (uri); ≤ 2048 characters)
  - `events[].action_source` (string; one of web, app, offline, crm, phone_call, system_generated)
  - `events[].order_id` (string; 1–100 characters)
  - `events[].platform_data` (object)
- `test_code` (string; 1–100 characters)
- `consent` (object)
  - `consent.ad_user_data` (string; one of GRANTED, DENIED)
  - `consent.ad_personalization` (string; one of GRANTED, DENIED)

```bash
curl -X POST "https://api.socialit.com/v1/ads/conversions" \
  -H "Authorization: Bearer $SOCIALIT_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "ad_account_id": "ada_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd",
    "connection_id": "adc_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd",
    "platform_ad_account_id": "string",
    "destination_id": "string",
    "events": [
      {
        "event_name": "string",
        "event_time": "string",
        "event_id": "string",
        "user": {
          "email": "you@example.com",
          "emails": [
            "string"
          ]
        }
      }
    ]
  }'
```

Response 200:

```json
{
  "object": "conversion_result",
  "platform": "string",
  "ad_account_id": "string",
  "destination_id": "string",
  "test": true,
  "events_received": 1,
  "events_failed": 1,
  "failures": [
    {
      "index": 1,
      "event_id": "string",
      "message": "string",
      "code": "string"
    }
  ],
  "trace_id": "string"
}
```

## Adjust uploaded conversions

`POST /ads/conversions/adjustments`

Retract, restate or enhance conversions already sent (Google Ads).

Access: `write` · MCP tool: `adjust-conversions` · Zernio: `POST /v1/ads/conversions/adjustments`

### Headers

- `Idempotency-Key` (string; ≤ 255 characters): Unique key (for example a UUID) that makes retries safe: a repeated request with the same key and body returns the first response (Idempotent-Replayed: true) for 24 hours.

### Body

- `ad_account_id` (string; ≤ 80 characters): Ad account (ada_…)
- `connection_id` (string; ≤ 80 characters): Ads connection (adc_…), with platform_ad_account_id when it has several ad accounts
- `platform_ad_account_id` (string; ≤ 256 characters): Network ad account id (act_…, customer id, advertiser id …)
- `destination_id` (string; required; 1–64 characters)
- `adjustments` (array of object; required; 1–2000 items)
  - `adjustments[].adjustment_type` (string; required; one of RETRACTION, RESTATEMENT, ENHANCEMENT)
  - `adjustments[].adjustment_time` (string | integer; required): ISO 8601 date-time or unix seconds
  - `adjustments[].order_id` (string; 1–100 characters)
  - `adjustments[].gclid` (string; 1–500 characters)
  - `adjustments[].conversion_time` (string | integer): ISO 8601 date-time or unix seconds
  - `adjustments[].restatement_value` (number)
  - `adjustments[].currency` (string; pattern ^[A-Za-z]{3}$)
  - `adjustments[].user` (object)
    - `adjustments[].user.email` (string; 1–320 characters)
    - `adjustments[].user.emails` (array of string; ≤ 10 items)
    - `adjustments[].user.phone` (string; 1–64 characters)
    - `adjustments[].user.phones` (array of string; ≤ 10 items)
    - `adjustments[].user.first_name` (string; 1–200 characters)
    - `adjustments[].user.last_name` (string; 1–200 characters)
    - `adjustments[].user.city` (string; 1–200 characters)
    - `adjustments[].user.state` (string; 1–100 characters)
    - `adjustments[].user.zip` (string; 1–32 characters)
    - `adjustments[].user.country` (string; 1–64 characters)
    - `adjustments[].user.date_of_birth` (string; 1–16 characters)
    - `adjustments[].user.gender` (string; 1–16 characters)
    - `adjustments[].user.external_id` (string; 1–256 characters)
    - `adjustments[].user.external_ids` (array of string; ≤ 10 items)
    - `adjustments[].user.ip_address` (string; 1–64 characters)
    - `adjustments[].user.user_agent` (string; 1–1024 characters)
    - `adjustments[].user.company_name` (string; 1–200 characters)
    - `adjustments[].user.title` (string; 1–200 characters)
    - `adjustments[].user.fbc` (string; 1–500 characters)
    - `adjustments[].user.fbp` (string; 1–500 characters)
    - `adjustments[].user.gclid` (string; 1–500 characters)
    - `adjustments[].user.gbraid` (string; 1–500 characters)
    - `adjustments[].user.wbraid` (string; 1–500 characters)
    - `adjustments[].user.ttclid` (string; 1–500 characters)
    - `adjustments[].user.ttp` (string; 1–500 characters)
    - `adjustments[].user.li_fat_id` (string; 1–500 characters)
    - `adjustments[].user.epik` (string; 1–500 characters)
    - `adjustments[].user.sc_click_id` (string; 1–500 characters)
    - `adjustments[].user.sc_cookie1` (string; 1–500 characters)
    - `adjustments[].user.rdt_cid` (string; 1–500 characters)
    - `adjustments[].user.twclid` (string; 1–500 characters)
    - `adjustments[].user.click_id` (string; 1–500 characters)
    - `adjustments[].user.lead_id` (string; 1–64 characters)
    - `adjustments[].user.uuid` (string; 1–200 characters)
    - `adjustments[].user.hashed` (boolean)
  - `adjustments[].user_agent` (string; 1–1024 characters)

```bash
curl -X POST "https://api.socialit.com/v1/ads/conversions/adjustments" \
  -H "Authorization: Bearer $SOCIALIT_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "ad_account_id": "ada_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd",
    "connection_id": "adc_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd",
    "platform_ad_account_id": "string",
    "destination_id": "string",
    "adjustments": [
      {
        "adjustment_type": "RETRACTION",
        "adjustment_time": "string"
      }
    ]
  }'
```

Response 200:

```json
{
  "object": "conversion_adjustment_result",
  "platform": "string",
  "ad_account_id": "string",
  "destination_id": "string",
  "adjustments_received": 1,
  "adjustments_failed": 1,
  "failures": [
    {
      "index": 1,
      "message": "string",
      "code": "string"
    }
  ],
  "trace_id": "string"
}
```

## Get Event Match Quality

`GET /ads/conversions/quality`

Access: `read` · MCP tool: `get-event-match-quality` · Zernio: `GET /v1/ads/conversions/quality`

### Query parameters

- `ad_account_id` (string; ≤ 80 characters): Ad account (ada_…)
- `connection_id` (string; ≤ 80 characters): Ads connection (adc_…), with platform_ad_account_id when it has several ad accounts
- `platform_ad_account_id` (string; ≤ 256 characters): Network ad account id (act_…, customer id, advertiser id …)
- `destination_id` (string; 1–256 characters)

```bash
curl "https://api.socialit.com/v1/ads/conversions/quality" \
  -H "Authorization: Bearer $SOCIALIT_API_KEY"
```

Response 200:

```json
{
  "object": "event_match_quality",
  "platform": "string",
  "destination_id": "string",
  "rows": [
    {
      "event_name": "string",
      "composite_score": 1.5,
      "match_keys": [
        {
          "identifier": "string",
          "coverage_percentage": 1.5
        }
      ],
      "event_coverage_percentage": 1.5
    }
  ]
}
```

## List conversion actions

`GET /ads/accounts/{adAccountId}/conversion-actions`

Google Ads conversion actions with their tag snippets.

Access: `read` · MCP tool: `list-conversion-actions` · Zernio: `GET /v1/ads/conversions/actions`

### Path parameters

- `adAccountId` (string; required; 1–80 characters): Ad account id (ada_…)

### Query parameters

- `type` (string; 1–64 characters)

```bash
curl "https://api.socialit.com/v1/ads/accounts/ada_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd/conversion-actions" \
  -H "Authorization: Bearer $SOCIALIT_API_KEY"
```

Response 200:

```json
{
  "object": "list",
  "data": [
    {
      "object": "conversion_action",
      "id": "string",
      "name": "string",
      "type": "string",
      "status": "string",
      "category": "string",
      "origin": "string",
      "primary_for_goal": true,
      "default_value": 1.5,
      "default_currency": "string",
      "always_use_default_value": true,
      "counting_type": "string",
      "click_through_lookback_window_days": 1.5,
      "view_through_lookback_window_days": 1.5,
      "resource_name": "string",
      "tag_snippets": [
        {
          "type": "string",
          "page_format": "string",
          "global_site_tag": "string",
          "event_snippet": "string"
        }
      ]
    }
  ],
  "page": 1,
  "limit": 1,
  "total": 1,
  "has_more": true,
  "next_page_url": "https://example.com",
  "previous_page_url": "https://example.com",
  "next_cursor": "string"
}
```

## Create a website conversion action

`POST /ads/accounts/{adAccountId}/conversion-actions`

Access: `write` · MCP tool: `create-conversion-action` · Zernio: `POST /v1/ads/conversions/actions`

### Path parameters

- `adAccountId` (string; required; 1–80 characters): Ad account id (ada_…)

### Headers

- `Idempotency-Key` (string; ≤ 255 characters): Unique key (for example a UUID) that makes retries safe: a repeated request with the same key and body returns the first response (Idempotent-Replayed: true) for 24 hours.

### Body

- `name` (string; required; 1–255 characters)
- `category` (string; one of DEFAULT, PAGE_VIEW, PURCHASE, SIGNUP, DOWNLOAD, ADD_TO_CART, BEGIN_CHECKOUT, SUBSCRIBE_PAID, PHONE_CALL_LEAD, IMPORTED_LEAD, SUBMIT_LEAD_FORM, BOOK_APPOINTMENT, …)
- `default_value` (number)
- `default_currency` (string; pattern ^[A-Za-z]{3}$)
- `always_use_default_value` (boolean)
- `counting_type` (string; one of ONE_PER_CLICK, MANY_PER_CLICK)
- `click_through_lookback_window_days` (integer; 1–90)
- `view_through_lookback_window_days` (integer; 1–30)
- `primary_for_goal` (boolean)
- `type` (string; one of WEBPAGE)

```bash
curl -X POST "https://api.socialit.com/v1/ads/accounts/ada_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd/conversion-actions" \
  -H "Authorization: Bearer $SOCIALIT_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "string",
    "category": "DEFAULT",
    "default_value": 0,
    "default_currency": "string",
    "always_use_default_value": true
  }'
```

Response 201:

```json
{
  "object": "conversion_action",
  "id": "string",
  "name": "string",
  "type": "string",
  "status": "string",
  "category": "string",
  "origin": "string",
  "primary_for_goal": true,
  "default_value": 1.5,
  "default_currency": "string",
  "always_use_default_value": true,
  "counting_type": "string",
  "click_through_lookback_window_days": 1.5,
  "view_through_lookback_window_days": 1.5,
  "resource_name": "string",
  "tag_snippets": [
    {
      "type": "string",
      "page_format": "string",
      "global_site_tag": "string",
      "event_snippet": "string"
    }
  ]
}
```

## Update a conversion action

`PATCH /ads/accounts/{adAccountId}/conversion-actions/{actionId}`

Access: `write` · MCP tool: `update-conversion-action` · Zernio: `PATCH /v1/ads/conversions/actions/{actionId}`

### Path parameters

- `adAccountId` (string; required; 1–80 characters): Ad account id (ada_…)
- `actionId` (string; required; 1–256 characters)

### Body

- `name` (string; 1–255 characters)
- `category` (string; one of DEFAULT, PAGE_VIEW, PURCHASE, SIGNUP, DOWNLOAD, ADD_TO_CART, BEGIN_CHECKOUT, SUBSCRIBE_PAID, PHONE_CALL_LEAD, IMPORTED_LEAD, SUBMIT_LEAD_FORM, BOOK_APPOINTMENT, …)
- `default_value` (number)
- `default_currency` (string; pattern ^[A-Za-z]{3}$)
- `always_use_default_value` (boolean)
- `counting_type` (string; one of ONE_PER_CLICK, MANY_PER_CLICK)
- `click_through_lookback_window_days` (integer; 1–90)
- `view_through_lookback_window_days` (integer; 1–30)
- `primary_for_goal` (boolean)
- `status` (string; one of ENABLED, REMOVED)

```bash
curl -X PATCH "https://api.socialit.com/v1/ads/accounts/ada_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd/conversion-actions/ACTION_ID" \
  -H "Authorization: Bearer $SOCIALIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "string",
    "category": "DEFAULT",
    "default_value": 0,
    "default_currency": "string",
    "always_use_default_value": true
  }'
```

Response 200:

```json
{
  "object": "conversion_action",
  "id": "string",
  "name": "string",
  "type": "string",
  "status": "string",
  "category": "string",
  "origin": "string",
  "primary_for_goal": true,
  "default_value": 1.5,
  "default_currency": "string",
  "always_use_default_value": true,
  "counting_type": "string",
  "click_through_lookback_window_days": 1.5,
  "view_through_lookback_window_days": 1.5,
  "resource_name": "string",
  "tag_snippets": [
    {
      "type": "string",
      "page_format": "string",
      "global_site_tag": "string",
      "event_snippet": "string"
    }
  ]
}
```

## List account conversion goals

`GET /ads/accounts/{adAccountId}/conversion-goals`

Access: `read` · MCP tool: `list-conversion-goals` · Zernio: `GET /v1/ads/conversions/goals`

### Path parameters

- `adAccountId` (string; required; 1–80 characters): Ad account id (ada_…)

```bash
curl "https://api.socialit.com/v1/ads/accounts/ada_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd/conversion-goals" \
  -H "Authorization: Bearer $SOCIALIT_API_KEY"
```

Response 200:

```json
{
  "object": "list",
  "data": [
    {
      "object": "conversion_goal",
      "category": "string",
      "origin": "string",
      "biddable": true,
      "resource_name": "string",
      "conversion_actions": [
        {
          "id": "string",
          "name": "string",
          "status": "string",
          "primary_for_goal": true
        }
      ]
    }
  ],
  "page": 1,
  "limit": 1,
  "total": 1,
  "has_more": true,
  "next_page_url": "https://example.com",
  "previous_page_url": "https://example.com",
  "next_cursor": "string"
}
```

## Update account conversion goals

`PATCH /ads/accounts/{adAccountId}/conversion-goals`

Access: `write` · MCP tool: `update-conversion-goals` · Zernio: `PATCH /v1/ads/conversions/goals`

### Path parameters

- `adAccountId` (string; required; 1–80 characters): Ad account id (ada_…)

### Body

- `goals` (array of object; required; 1–100 items)
  - `goals[].category` (string; required; 1–64 characters)
  - `goals[].origin` (string; required; 1–64 characters)
  - `goals[].biddable` (boolean; required)

```bash
curl -X PATCH "https://api.socialit.com/v1/ads/accounts/ada_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd/conversion-goals" \
  -H "Authorization: Bearer $SOCIALIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "goals": [
      {
        "category": "string",
        "origin": "string",
        "biddable": true
      }
    ]
  }'
```

Response 200:

```json
{
  "object": "list",
  "data": [
    {
      "object": "conversion_goal",
      "category": "string",
      "origin": "string",
      "biddable": true,
      "resource_name": "string",
      "conversion_actions": [
        {
          "id": "string",
          "name": "string",
          "status": "string",
          "primary_for_goal": true
        }
      ]
    }
  ],
  "page": 1,
  "limit": 1,
  "total": 1,
  "has_more": true,
  "next_page_url": "https://example.com",
  "previous_page_url": "https://example.com",
  "next_cursor": "string"
}
```

## List custom conversion goals

`GET /ads/accounts/{adAccountId}/custom-conversion-goals`

Access: `read` · MCP tool: `list-custom-conversion-goals` · Zernio: `GET /v1/ads/conversions/custom-goals`

### Path parameters

- `adAccountId` (string; required; 1–80 characters): Ad account id (ada_…)

```bash
curl "https://api.socialit.com/v1/ads/accounts/ada_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd/custom-conversion-goals" \
  -H "Authorization: Bearer $SOCIALIT_API_KEY"
```

Response 200:

```json
{
  "object": "list",
  "data": [
    {
      "object": "custom_conversion_goal",
      "id": "string",
      "resource_name": "string",
      "name": "string",
      "status": "string",
      "conversion_action_ids": [
        "string"
      ]
    }
  ],
  "page": 1,
  "limit": 1,
  "total": 1,
  "has_more": true,
  "next_page_url": "https://example.com",
  "previous_page_url": "https://example.com",
  "next_cursor": "string"
}
```

## Create a custom conversion goal

`POST /ads/accounts/{adAccountId}/custom-conversion-goals`

Access: `write` · MCP tool: `create-custom-conversion-goal` · Zernio: `POST /v1/ads/conversions/custom-goals`

### Path parameters

- `adAccountId` (string; required; 1–80 characters): Ad account id (ada_…)

### Headers

- `Idempotency-Key` (string; ≤ 255 characters): Unique key (for example a UUID) that makes retries safe: a repeated request with the same key and body returns the first response (Idempotent-Replayed: true) for 24 hours.

### Body

- `name` (string; required; 1–255 characters)
- `conversion_action_ids` (array of string; required; 1–100 items)

```bash
curl -X POST "https://api.socialit.com/v1/ads/accounts/ada_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd/custom-conversion-goals" \
  -H "Authorization: Bearer $SOCIALIT_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "string",
    "conversion_action_ids": [
      "string"
    ]
  }'
```

Response 201:

```json
{
  "object": "custom_conversion_goal",
  "id": "string",
  "resource_name": "string",
  "name": "string",
  "status": "string",
  "conversion_action_ids": [
    "string"
  ]
}
```

## Update a custom conversion goal

`PATCH /ads/accounts/{adAccountId}/custom-conversion-goals/{goalId}`

Access: `write` · MCP tool: `update-custom-conversion-goal` · Zernio: `PATCH /v1/ads/conversions/custom-goals/{goalId}`

### Path parameters

- `adAccountId` (string; required; 1–80 characters): Ad account id (ada_…)
- `goalId` (string; required; 1–256 characters)

### Body

- `name` (string; 1–255 characters)
- `conversion_action_ids` (array of string; 1–100 items)

```bash
curl -X PATCH "https://api.socialit.com/v1/ads/accounts/ada_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd/custom-conversion-goals/GOAL_ID" \
  -H "Authorization: Bearer $SOCIALIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "string",
    "conversion_action_ids": [
      "string"
    ]
  }'
```

Response 200:

```json
{
  "object": "custom_conversion_goal",
  "id": "string",
  "resource_name": "string",
  "name": "string",
  "status": "string",
  "conversion_action_ids": [
    "string"
  ]
}
```

## Remove a custom conversion goal

`DELETE /ads/accounts/{adAccountId}/custom-conversion-goals/{goalId}`

Access: `write` · MCP tool: `delete-custom-conversion-goal` · Zernio: `DELETE /v1/ads/conversions/custom-goals/{goalId}`

### Path parameters

- `adAccountId` (string; required; 1–80 characters): Ad account id (ada_…)
- `goalId` (string; required; 1–256 characters)

```bash
curl -X DELETE "https://api.socialit.com/v1/ads/accounts/ada_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd/custom-conversion-goals/GOAL_ID" \
  -H "Authorization: Bearer $SOCIALIT_API_KEY"
```

Response 200:

```json
{
  "object": "custom_conversion_goal",
  "id": "string",
  "deleted": true
}
```

## List conversion destinations

`GET /ads/accounts/{adAccountId}/conversion-destinations`

Where the ad account can receive conversion events (pixels, conversion actions, conversion rules, …): use id as destination_id.

Access: `read` · MCP tool: `list-conversion-destinations` · Zernio: `GET /v1/accounts/{accountId}/conversion-destinations`

### Path parameters

- `adAccountId` (string; required; 1–80 characters): Ad account id (ada_…)

### Query parameters

- `include_inactive` (boolean)

```bash
curl "https://api.socialit.com/v1/ads/accounts/ada_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd/conversion-destinations" \
  -H "Authorization: Bearer $SOCIALIT_API_KEY"
```

Response 200:

```json
{
  "object": "list",
  "data": [
    {
      "object": "conversion_destination",
      "id": "string",
      "name": "string",
      "type": "string",
      "status": "string",
      "platform": "string",
      "ad_account_id": "string",
      "conversion_events": [
        {
          "id": "string",
          "name": "string",
          "event_type": "string",
          "custom_event_name": "string",
          "archived": true,
          "optimizable": true
        }
      ],
      "attribution_type": "string",
      "post_click_attribution_window_size": 1.5,
      "view_through_attribution_window_size": 1.5,
      "value_type": "string",
      "value": {
        "currency_code": "string",
        "amount": "string"
      },
      "enabled": true
    }
  ],
  "page": 1,
  "limit": 1,
  "total": 1,
  "has_more": true,
  "next_page_url": "https://example.com",
  "previous_page_url": "https://example.com",
  "next_cursor": "string"
}
```

## Create a conversion destination

`POST /ads/accounts/{adAccountId}/conversion-destinations`

LinkedIn conversion rule (not idempotent) or Google Ads conversion action (reused by name).

Access: `write` · MCP tool: `create-conversion-destination` · Zernio: `POST /v1/accounts/{accountId}/conversion-destinations`

### Path parameters

- `adAccountId` (string; required; 1–80 characters): Ad account id (ada_…)

### Headers

- `Idempotency-Key` (string; ≤ 255 characters): Unique key (for example a UUID) that makes retries safe: a repeated request with the same key and body returns the first response (Idempotent-Replayed: true) for 24 hours.

### Body

- `name` (string; required; 1–255 characters)
- `attribution_type` (string; one of LAST_TOUCH_BY_CAMPAIGN, LAST_TOUCH_BY_CONVERSION)
- `post_click_attribution_window_size` (integer; one of 1, 7, 30, 90, 365)
- `view_through_attribution_window_size` (integer; one of 1, 7, 30, 90, 365)
- `value_type` (string; one of DYNAMIC, FIXED, NO_VALUE)
- `value` (object)
  - `value.currency_code` (string; required; pattern ^[A-Za-z]{3}$)
  - `value.amount` (string | number; required)
- `type` (string; required; 1–64 characters)
- `auto_association_type` (string; one of ALL_CAMPAIGNS, OBJECTIVE_BASED, NONE)
- `counting_type` (string; one of MANY_PER_CLICK, ONE_PER_CLICK)
- `primary_for_goal` (boolean)

```bash
curl -X POST "https://api.socialit.com/v1/ads/accounts/ada_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd/conversion-destinations" \
  -H "Authorization: Bearer $SOCIALIT_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "string",
    "attribution_type": "LAST_TOUCH_BY_CAMPAIGN",
    "post_click_attribution_window_size": 1,
    "view_through_attribution_window_size": 1,
    "type": "string"
  }'
```

Response 201:

```json
{
  "object": "conversion_destination",
  "id": "string",
  "name": "string",
  "type": "string",
  "status": "string",
  "platform": "string",
  "ad_account_id": "string",
  "conversion_events": [
    {
      "id": "string",
      "name": "string",
      "event_type": "string",
      "custom_event_name": "string",
      "archived": true,
      "optimizable": true
    }
  ],
  "attribution_type": "string",
  "post_click_attribution_window_size": 1.5,
  "view_through_attribution_window_size": 1.5,
  "value_type": "string",
  "value": {
    "currency_code": "string",
    "amount": "string"
  },
  "enabled": true
}
```

## Get a conversion destination

`GET /ads/accounts/{adAccountId}/conversion-destinations/{destinationId}`

Access: `read` · MCP tool: `get-conversion-destination` · Zernio: `GET /v1/accounts/{accountId}/conversion-destinations/{destinationId}`

### Path parameters

- `adAccountId` (string; required; 1–80 characters): Ad account id (ada_…)
- `destinationId` (string; required; 1–256 characters)

```bash
curl "https://api.socialit.com/v1/ads/accounts/ada_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd/conversion-destinations/DESTINATION_ID" \
  -H "Authorization: Bearer $SOCIALIT_API_KEY"
```

Response 200:

```json
{
  "object": "conversion_destination",
  "id": "string",
  "name": "string",
  "type": "string",
  "status": "string",
  "platform": "string",
  "ad_account_id": "string",
  "conversion_events": [
    {
      "id": "string",
      "name": "string",
      "event_type": "string",
      "custom_event_name": "string",
      "archived": true,
      "optimizable": true
    }
  ],
  "attribution_type": "string",
  "post_click_attribution_window_size": 1.5,
  "view_through_attribution_window_size": 1.5,
  "value_type": "string",
  "value": {
    "currency_code": "string",
    "amount": "string"
  },
  "enabled": true
}
```

## Update a conversion destination

`PATCH /ads/accounts/{adAccountId}/conversion-destinations/{destinationId}`

Access: `write` · MCP tool: `update-conversion-destination` · Zernio: `PATCH /v1/accounts/{accountId}/conversion-destinations/{destinationId}`

### Path parameters

- `adAccountId` (string; required; 1–80 characters): Ad account id (ada_…)
- `destinationId` (string; required; 1–256 characters)

### Body

- `name` (string; 1–255 characters)
- `attribution_type` (string; one of LAST_TOUCH_BY_CAMPAIGN, LAST_TOUCH_BY_CONVERSION)
- `post_click_attribution_window_size` (integer; one of 1, 7, 30, 90, 365)
- `view_through_attribution_window_size` (integer; one of 1, 7, 30, 90, 365)
- `value_type` (string; one of DYNAMIC, FIXED, NO_VALUE)
- `value` (object)
  - `value.currency_code` (string; required; pattern ^[A-Za-z]{3}$)
  - `value.amount` (string | number; required)
- `enabled` (boolean)

```bash
curl -X PATCH "https://api.socialit.com/v1/ads/accounts/ada_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd/conversion-destinations/DESTINATION_ID" \
  -H "Authorization: Bearer $SOCIALIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "string",
    "attribution_type": "LAST_TOUCH_BY_CAMPAIGN",
    "post_click_attribution_window_size": 1,
    "view_through_attribution_window_size": 1,
    "value_type": "DYNAMIC"
  }'
```

Response 200:

```json
{
  "object": "conversion_destination",
  "id": "string",
  "name": "string",
  "type": "string",
  "status": "string",
  "platform": "string",
  "ad_account_id": "string",
  "conversion_events": [
    {
      "id": "string",
      "name": "string",
      "event_type": "string",
      "custom_event_name": "string",
      "archived": true,
      "optimizable": true
    }
  ],
  "attribution_type": "string",
  "post_click_attribution_window_size": 1.5,
  "view_through_attribution_window_size": 1.5,
  "value_type": "string",
  "value": {
    "currency_code": "string",
    "amount": "string"
  },
  "enabled": true
}
```

## Delete (disable) a conversion destination

`DELETE /ads/accounts/{adAccountId}/conversion-destinations/{destinationId}`

Access: `write` · MCP tool: `delete-conversion-destination` · Zernio: `DELETE /v1/accounts/{accountId}/conversion-destinations/{destinationId}`

### Path parameters

- `adAccountId` (string; required; 1–80 characters): Ad account id (ada_…)
- `destinationId` (string; required; 1–256 characters)

```bash
curl -X DELETE "https://api.socialit.com/v1/ads/accounts/ada_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd/conversion-destinations/DESTINATION_ID" \
  -H "Authorization: Bearer $SOCIALIT_API_KEY"
```

Response 200:

```json
{
  "object": "conversion_destination",
  "id": "string",
  "deleted": true,
  "state": "string"
}
```

## List associated campaigns

`GET /ads/accounts/{adAccountId}/conversion-destinations/{destinationId}/associations`

Access: `read` · MCP tool: `list-conversion-associations` · Zernio: `GET /v1/accounts/{accountId}/conversion-destinations/{destinationId}/associations`

### Path parameters

- `adAccountId` (string; required; 1–80 characters): Ad account id (ada_…)
- `destinationId` (string; required; 1–256 characters)

```bash
curl "https://api.socialit.com/v1/ads/accounts/ada_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd/conversion-destinations/DESTINATION_ID/associations" \
  -H "Authorization: Bearer $SOCIALIT_API_KEY"
```

Response 200:

```json
{
  "object": "list",
  "data": [
    {
      "object": "conversion_association",
      "campaign_id": "string",
      "conversion_id": "string",
      "associated_at": "2026-10-13T09:00:00.000Z"
    }
  ],
  "page": 1,
  "limit": 1,
  "total": 1,
  "has_more": true,
  "next_page_url": "https://example.com",
  "previous_page_url": "https://example.com",
  "next_cursor": "string"
}
```

## Associate campaigns

`POST /ads/accounts/{adAccountId}/conversion-destinations/{destinationId}/associations`

Access: `write` · MCP tool: `add-conversion-associations` · Zernio: `POST /v1/accounts/{accountId}/conversion-destinations/{destinationId}/associations`

### Path parameters

- `adAccountId` (string; required; 1–80 characters): Ad account id (ada_…)
- `destinationId` (string; required; 1–256 characters)

### Headers

- `Idempotency-Key` (string; ≤ 255 characters): Unique key (for example a UUID) that makes retries safe: a repeated request with the same key and body returns the first response (Idempotent-Replayed: true) for 24 hours.

### Body

- `campaign_ids` (array of string; required; 1–500 items)

```bash
curl -X POST "https://api.socialit.com/v1/ads/accounts/ada_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd/conversion-destinations/DESTINATION_ID/associations" \
  -H "Authorization: Bearer $SOCIALIT_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "campaign_ids": [
      "string"
    ]
  }'
```

Response 200:

```json
{
  "object": "conversion_association_result",
  "succeeded": [
    "string"
  ],
  "failed": [
    {
      "campaign_id": "string",
      "reason": "string"
    }
  ]
}
```

## Remove associated campaigns

`DELETE /ads/accounts/{adAccountId}/conversion-destinations/{destinationId}/associations`

Access: `write` · MCP tool: `remove-conversion-associations` · Zernio: `DELETE /v1/accounts/{accountId}/conversion-destinations/{destinationId}/associations`

### Path parameters

- `adAccountId` (string; required; 1–80 characters): Ad account id (ada_…)
- `destinationId` (string; required; 1–256 characters)

### Query parameters

- `campaign_ids` (string; required; ≤ 10000 characters): Comma separated ids

```bash
curl -X DELETE "https://api.socialit.com/v1/ads/accounts/ada_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd/conversion-destinations/DESTINATION_ID/associations?campaign_ids=value" \
  -H "Authorization: Bearer $SOCIALIT_API_KEY"
```

Response 200:

```json
{
  "object": "conversion_association_result",
  "succeeded": [
    "string"
  ],
  "failed": [
    {
      "campaign_id": "string",
      "reason": "string"
    }
  ]
}
```

## Get attribution metrics

`GET /ads/accounts/{adAccountId}/conversion-destinations/{destinationId}/metrics`

Access: `read` · MCP tool: `get-conversion-metrics` · Zernio: `GET /v1/accounts/{accountId}/conversion-destinations/{destinationId}/metrics`

### Path parameters

- `adAccountId` (string; required; 1–80 characters): Ad account id (ada_…)
- `destinationId` (string; required; 1–256 characters)

### Query parameters

- `start_date` (string; required; pattern ^\d{4}-\d{2}-\d{2}$): YYYY-MM-DD
- `end_date` (string; pattern ^\d{4}-\d{2}-\d{2}$): YYYY-MM-DD
- `granularity` (string; one of ALL, DAILY, MONTHLY, YEARLY)

```bash
curl "https://api.socialit.com/v1/ads/accounts/ada_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd/conversion-destinations/DESTINATION_ID/metrics?start_date=value" \
  -H "Authorization: Bearer $SOCIALIT_API_KEY"
```

Response 200:

```json
{
  "object": "conversion_metrics",
  "destination_id": "string",
  "granularity": "string",
  "rows": [
    {
      "start": "string",
      "end": "string",
      "metrics": {
        "external_website_conversions": 1.5,
        "external_website_post_click_conversions": 1.5,
        "external_website_post_view_conversions": 1.5,
        "conversion_value_in_local_currency": 1.5,
        "qualified_leads": 1.5,
        "cost_in_local_currency": 1.5
      }
    }
  ]
}
```


---

Source: https://socialit.com/docs/api-reference/ads-accounts-measurement/
