---
title: "Register AI Referrals Connection"
method: POST
path: "/{brand_id}/ai-referrals/connections"
tags: ["ai-referrals"]
---

# Register AI Referrals Connection

`POST /{brand_id}/ai-referrals/connections`

## Request

- Base URL: `https://api.scrunchai.com/v1`
- URL: `https://api.scrunchai.com/v1/{brand_id}/ai-referrals/connections`
- Auth: HTTP bearer
- TypeScript: <https://skmtc.dev/scrunch/apis/scrunch-data-api/docs/:brand_id/ai-referrals/connections/post.ts> (a function with typed inputs; its response is checked against the schema)

Register one of the brand's websites to send AI referral rows for. Rows can only be sent once a connection exists.

A website reads from one source at a time: one with Google Analytics connected, or an active connection already, returns `409`.

Use provider `custom` for any analytics tool; `adobe_analytics` is also accepted.

## Path parameters

- `brand_id` integer, required

## Request body

- AiReferralsConnectionCreate: Payload to register a new AI Referrals connection.
  - `website` string, required: Hostname or URL of the website whose referrals will be pushed.
  - `provider` 'custom' | 'adobe_analytics', required: Where the data comes from: "custom" for any analytics tool, or "adobe_analytics". Both are read the same way.

## Response `201`

Connection registered.

- AiReferralsConnection: A registered AI Referrals push connection.
  - `id` string, required: ULID identifier for the connection.
  - `brand_id` integer, required
  - `website` string, required: Hostname or URL of the website whose referrals are pushed against this connection.
  - `provider` 'custom' | 'adobe_analytics', required: Where the data comes from: "custom" for any analytics tool, or "adobe_analytics". Both are read the same way.
  - `status` 'active' | 'disabled', required
  - `created_at` string, date-time, required
  - `last_pushed_at` string, date-time, nullable
  - `last_push_error` string, nullable
  - `sends_engagement` boolean: Whether the connection's rows carry users, engagement and key events. Set by its first push.

## Other responses

- `400`: Invalid provider or payload.
- `404`: Brand not found, or the AI Referrals API isn't enabled for it.
- `409`: A connection or conflicting integration already exists for this (brand, website).
- `422`: Validation Error

## Changes

- **2026-11-05** `3c6aa69a6595`: 1 breaking, 2 warning, 4 info
  - request property `provider` was restricted to a list of enum values
  - added the new `adobe_analytics` enum value to the `provider` response property for the response status `201`
  - added the new `custom` enum value to the `provider` response property for the response status `201`
  - added the new `adobe_analytics` enum value to the request property `provider`
  - …3 more

[Operation history](https://skmtc.dev/scrunch/apis/scrunch-data-api/changes/:brand_id/ai-referrals/connections/post.md)

---

[API](https://skmtc.dev/scrunch/apis/scrunch-data-api.md) - [All operations](https://skmtc.dev/scrunch/apis/scrunch-data-api/llms.txt) - [OpenAPI document](https://skmtc.dev/scrunch/apis/scrunch-data-api/revisions/e28a10a186bf?raw)