# Sources

> Manage data collection sources. Create, list, update, and delete sources in your Ours Privacy account, including pixel tokens and install scripts.

Source: https://docs.oursprivacy.com/docs/platform-api/sources

Manage data collection sources. Create, list, update, and delete sources in your account.

## Where this fits in the dispatch flow

Sources are the entry point:

Event dispatch flow: **Source (this page)** → [Allowed Events](https://docs.oursprivacy.com/docs/platform-api/allowed-events) → [Data Governance](https://docs.oursprivacy.com/docs/platform-api/data-governance) → [Mappings](https://docs.oursprivacy.com/docs/platform-api/mappings) → [Destination](https://docs.oursprivacy.com/docs/platform-api/destinations)

Configuration changes at any stage take effect once you publish a [new version](https://docs.oursprivacy.com/docs/platform-api/versions).

Events leave a source and are evaluated against [Allowed Events](https://docs.oursprivacy.com/docs/platform-api/allowed-events) (does the event name match an allow-list entry?), then [Data Governance](https://docs.oursprivacy.com/docs/platform-api/data-governance) (do any consent rules stop dispatch?), then per-destination [Mappings](https://docs.oursprivacy.com/docs/platform-api/mappings) (which fields go where?), before reaching the configured [destinations](https://docs.oursprivacy.com/docs/platform-api/destinations).

## Operational fields

Every source response includes `isPublished`: whether this source is included in the currently published version. A source accepts inbound events once it is published.

To confirm events are flowing, call [destination health](https://docs.oursprivacy.com/docs/platform-api/destinations) for a destination that receives this source's events: a non-zero `successCount` means events are arriving and being delivered.

## PATCH semantics

`PATCH /rest/v1/sources/{id}` is a partial update. Fields you omit are left unchanged. Send explicit `null` to clear a nullable field (e.g. `"redirectUrl": null`). The response returns the full source entity after the update.

## Source tokens (`/tokens`)

`GET /rest/v1/sources/{id}/tokens` returns different shapes depending on the source type:

**Pixel sources** (`WebSource`, `PixelImage`, `HTTPApiSource`, and similar) return:

```json
{
  "sourceType": "pixel",
  "token": "...",
  "testToken": "...",
  "installScript": "<script>...</script>",
  "testInstallScript": "<script>...</script>"
}
```

**Webhook sources** (`Webhook`, `CallRail`, `Formstack`, `Healthie`, `TypeformWebhooks`, `JotFormWebhooks`, `CalendlyWebhook`, `WhatConverts`, `HubspotAppActions`, and all other `*Webhook` types) return:

```json
{
  "sourceType": "webhook",
  "token": "...",
  "testToken": "...",
  "ingestUrl": "https://api.oursprivacy.com/source/...",
  "testIngestUrl": "https://api.oursprivacy.com/source/...",
  "sampleCurl": "curl -X POST 'https://api.oursprivacy.com/source/...' ..."
}
```

Use the `sourceType` field to discriminate between the two response shapes. Webhook sources do not have an `installScript`; pixel sources do not have an `ingestUrl`.

## Building webhook mappers

Webhook sources accept arbitrary JSON payloads. You can map those inbound fields to Ours Privacy event names and properties using the [Mappings](https://docs.oursprivacy.com/docs/platform-api/mappings) API with `entityId` set to the source id and `templateId` set to `"webhook"` (or the relevant per-vendor template such as `"typeform"`, `"jotform"`, `"calendly"`, etc.).

To discover the exact JSON structure your webhook is sending, send a test request and inspect the recent payloads in the platform dashboard.

## GET /rest/v1/sources

List all sources for this account. Supports cursor pagination and optional filters for `type`, `status`, and `nameContains`. Results are sorted by creation date descending. Requires API-key scope or current OAuth user permission: source:list

Request URL: `GET https://app.oursprivacy.com/rest/v1/sources`

Authentication: apiKey or oauth2.

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `limit` | query | integer \| null | No | Maximum number of sources to return. Defaults to 25; values below 1 are clamped to 1 and values above 200 are clamped to 200. |
| `cursor` | query | string | No | Opaque pagination cursor from pagination.nextCursor in the previous response. Do not decode or modify it. Malformed cursors return 400 Bad Request. Opaque pagination cursor from pagination.nextCursor in the previous response. Do not decode or modify it. Malformed cursors return 400 Bad Request. |
| `excludeShortLinks` | query | boolean \| string | No | Exclude redirects with a short-link design. Defaults to false. |
| `type` | query | string | No | Filter by source type. One of: `"AlchemerWebhook"`, `"AndroidNativeApi"`, `"Branch"`, `"CSharpApi"`, `"CalComWebhooks"`, `"CalendlyWebhook"`, `"CallRail"`, `"CallTrackingMetrics"`, `"DotNetApi"`, `"FacebookLeadAds"`, `"FlutterApi"`, `"FormsortWebhooks"`, `"Formstack"`, `"GoLangApi"`, `"HTTPApiSource"`, `"Healthie"`, `"Heyflow"`, `"HubspotAppActions"`, `"HubspotFormWebhook"`, `"JotFormWebhooks"`, `"KotlinApi"`, `"NodejsApi"`, `"PHPApi"`, `"PixelImage"`, `"PythonApi"`, `"ReactNativeApi"`, `"RedirectSource"`, `"RubyApi"`, `"SegmentWebPlugin"`, `"TypeformWebhooks"`, `"WebSource"`, `"Webhook"`, `"WhatConverts"`, `"iOSNativeApi"`. |
| `status` | query | string | No | Filter by source status. One of: `"Disabled"`, `"Enabled"`. |
| `nameContains` | query | string | No | Case-insensitive substring filter on the source name. |

### Responses

- `200`: Paginated list of sources
- `400`: Bad Request
- `401`: Unauthorized — missing, invalid, or expired API key or OAuth access token
- `403`: Forbidden — credential does not have the required current Ours permission
- `404`: Not Found
- `500`: Internal Server Error

#### `200` response body

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `entities` | object[] | Yes |  |
| `entities[].settings` | object \| null | No | Type-specific source settings. settings.dataImport contains a draft file, warehouse or HTTP import definition, with transformation, schedule and credential references. Account publication activates imports. |
| `entities[].id` | string | Yes |  |
| `entities[].name` | string \| null | No |  |
| `entities[].type` | string | Yes | One of: `"AlchemerWebhook"`, `"AndroidNativeApi"`, `"Branch"`, `"CSharpApi"`, `"CalComWebhooks"`, `"CalendlyWebhook"`, `"CallRail"`, `"CallTrackingMetrics"`, `"DotNetApi"`, `"FacebookLeadAds"`, `"FlutterApi"`, `"FormsortWebhooks"`, `"Formstack"`, `"GoLangApi"`, `"HTTPApiSource"`, `"Healthie"`, `"Heyflow"`, `"HubspotAppActions"`, `"HubspotFormWebhook"`, `"JotFormWebhooks"`, `"KotlinApi"`, `"NodejsApi"`, `"PHPApi"`, `"PixelImage"`, `"PythonApi"`, `"ReactNativeApi"`, `"RedirectSource"`, `"RubyApi"`, `"SegmentWebPlugin"`, `"TypeformWebhooks"`, `"WebSource"`, `"Webhook"`, `"WhatConverts"`, `"iOSNativeApi"`. |
| `entities[].status` | string | Yes | One of: `"Disabled"`, `"Enabled"`. |
| `entities[].createdAt` | string | Yes |  |
| `entities[].accountId` | string | Yes | Organization id that owns this source. |
| `entities[].isPublished` | boolean \| null | No | Whether this source exists in the currently published version. A source that is not published will not accept events. |
| `entities[].selectedAccountId` | string \| null | No |  |
| `entities[].whitelistDomains` | string[] \| null | No | Limits which domains can send events to the CDP. When set, only requests from these domains are accepted for this source. Separate from experiment settings `whitelistDomains`, which limits which domains can load your experiments. |
| `entities[].whitelistIps` | string[] \| null | No |  |
| `entities[].botControlMode` | string \| null | No | One of: `"Allow"`, `"Block"`, `"Threshold"`, `null`. |
| `entities[].botScoreThreshold` | number \| null | No |  |
| `entities[].excludeRequestContext` | boolean \| null | No |  |
| `entities[].redirectUrl` | string \| null | No |  |
| `entities[].forwardUtmToDestination` | boolean | Yes | Whether published short-link campaign tags are forwarded to missing destination UTM keys. Existing sources default to false. |
| `entities[].projectAPIKey` | string \| null | No |  |
| `entities[].probabilisticIdentity` | object \| null | No |  |
| `entities[].probabilisticIdentity.enabled` | boolean | Yes |  |
| `entities[].probabilisticIdentity.matchWindowMinutes` | integer | Yes |  |
| `entities[].probabilisticIdentity.maxMatchesPerIp` | integer | Yes |  |
| `pagination` | object | Yes |  |
| `pagination.nextCursor` | string \| null | No |  |
| `pagination.hasMore` | boolean | Yes |  |

Full schema: [OpenAPI specification](https://docs.oursprivacy.com/openapi-platform.json).

## POST /rest/v1/sources

Create a new source. Returns the full source entity (same shape as GET /sources/{id}) so callers can read all server-assigned fields without a follow-up GET. Requires API-key scope or current OAuth user permission: source:create

Request URL: `POST https://app.oursprivacy.com/rest/v1/sources`

Authentication: apiKey or oauth2.

### Request body (`application/json`, required)

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `name` | string \| null | No |  |
| `type` | string | Yes | One of: `"AlchemerWebhook"`, `"AndroidNativeApi"`, `"Branch"`, `"CSharpApi"`, `"CalComWebhooks"`, `"CalendlyWebhook"`, `"CallRail"`, `"CallTrackingMetrics"`, `"DotNetApi"`, `"FacebookLeadAds"`, `"FlutterApi"`, `"FormsortWebhooks"`, `"Formstack"`, `"GoLangApi"`, `"HTTPApiSource"`, `"Healthie"`, `"Heyflow"`, `"HubspotAppActions"`, `"HubspotFormWebhook"`, `"JotFormWebhooks"`, `"KotlinApi"`, `"NodejsApi"`, `"PHPApi"`, `"PixelImage"`, `"PythonApi"`, `"ReactNativeApi"`, `"RedirectSource"`, `"RubyApi"`, `"SegmentWebPlugin"`, `"TypeformWebhooks"`, `"WebSource"`, `"Webhook"`, `"WhatConverts"`, `"iOSNativeApi"`. |
| `redirectUrl` | string \| null (uri) | No | Destination URL for a RedirectSource (short link). Ignored by other source types. Must be a valid http(s) URL. |

### Responses

- `200`: Created source
- `400`: Bad Request
- `401`: Unauthorized — missing, invalid, or expired API key or OAuth access token
- `403`: Forbidden — credential does not have the required current Ours permission
- `404`: Not Found
- `500`: Internal Server Error

#### `200` response body

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `settings` | object \| null | No | Type-specific source settings. settings.dataImport contains a draft file, warehouse or HTTP import definition, with transformation, schedule and credential references. Account publication activates imports. |
| `id` | string | Yes |  |
| `name` | string \| null | No |  |
| `type` | string | Yes | One of: `"AlchemerWebhook"`, `"AndroidNativeApi"`, `"Branch"`, `"CSharpApi"`, `"CalComWebhooks"`, `"CalendlyWebhook"`, `"CallRail"`, `"CallTrackingMetrics"`, `"DotNetApi"`, `"FacebookLeadAds"`, `"FlutterApi"`, `"FormsortWebhooks"`, `"Formstack"`, `"GoLangApi"`, `"HTTPApiSource"`, `"Healthie"`, `"Heyflow"`, `"HubspotAppActions"`, `"HubspotFormWebhook"`, `"JotFormWebhooks"`, `"KotlinApi"`, `"NodejsApi"`, `"PHPApi"`, `"PixelImage"`, `"PythonApi"`, `"ReactNativeApi"`, `"RedirectSource"`, `"RubyApi"`, `"SegmentWebPlugin"`, `"TypeformWebhooks"`, `"WebSource"`, `"Webhook"`, `"WhatConverts"`, `"iOSNativeApi"`. |
| `status` | string | Yes | One of: `"Disabled"`, `"Enabled"`. |
| `createdAt` | string | Yes |  |
| `accountId` | string | Yes | Organization id that owns this source. |
| `isPublished` | boolean \| null | No | Whether this source exists in the currently published version. A source that is not published will not accept events. |
| `selectedAccountId` | string \| null | No |  |
| `whitelistDomains` | string[] \| null | No | Limits which domains can send events to the CDP. When set, only requests from these domains are accepted for this source. Separate from experiment settings `whitelistDomains`, which limits which domains can load your experiments. |
| `whitelistIps` | string[] \| null | No |  |
| `botControlMode` | string \| null | No | One of: `"Allow"`, `"Block"`, `"Threshold"`, `null`. |
| `botScoreThreshold` | number \| null | No |  |
| `excludeRequestContext` | boolean \| null | No |  |
| `redirectUrl` | string \| null | No |  |
| `forwardUtmToDestination` | boolean | Yes | Whether published short-link campaign tags are forwarded to missing destination UTM keys. Existing sources default to false. |
| `projectAPIKey` | string \| null | No |  |
| `probabilisticIdentity` | object \| null | No |  |
| `probabilisticIdentity.enabled` | boolean | Yes |  |
| `probabilisticIdentity.matchWindowMinutes` | integer | Yes |  |
| `probabilisticIdentity.maxMatchesPerIp` | integer | Yes |  |

Full schema: [OpenAPI specification](https://docs.oursprivacy.com/openapi-platform.json).

## GET /rest/v1/sources/{id}

Find a single source by ID. Requires API-key scope or current OAuth user permission: source:view

Request URL: `GET https://app.oursprivacy.com/rest/v1/sources/{id}`

Authentication: apiKey or oauth2.

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | string | Yes |  |

### Responses

- `200`: Source details
- `400`: Bad Request
- `401`: Unauthorized — missing, invalid, or expired API key or OAuth access token
- `403`: Forbidden — credential does not have the required current Ours permission
- `404`: Not Found
- `500`: Internal Server Error

#### `200` response body

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `settings` | object \| null | No | Type-specific source settings. settings.dataImport contains a draft file, warehouse or HTTP import definition, with transformation, schedule and credential references. Account publication activates imports. |
| `id` | string | Yes |  |
| `name` | string \| null | No |  |
| `type` | string | Yes | One of: `"AlchemerWebhook"`, `"AndroidNativeApi"`, `"Branch"`, `"CSharpApi"`, `"CalComWebhooks"`, `"CalendlyWebhook"`, `"CallRail"`, `"CallTrackingMetrics"`, `"DotNetApi"`, `"FacebookLeadAds"`, `"FlutterApi"`, `"FormsortWebhooks"`, `"Formstack"`, `"GoLangApi"`, `"HTTPApiSource"`, `"Healthie"`, `"Heyflow"`, `"HubspotAppActions"`, `"HubspotFormWebhook"`, `"JotFormWebhooks"`, `"KotlinApi"`, `"NodejsApi"`, `"PHPApi"`, `"PixelImage"`, `"PythonApi"`, `"ReactNativeApi"`, `"RedirectSource"`, `"RubyApi"`, `"SegmentWebPlugin"`, `"TypeformWebhooks"`, `"WebSource"`, `"Webhook"`, `"WhatConverts"`, `"iOSNativeApi"`. |
| `status` | string | Yes | One of: `"Disabled"`, `"Enabled"`. |
| `createdAt` | string | Yes |  |
| `accountId` | string | Yes | Organization id that owns this source. |
| `isPublished` | boolean \| null | No | Whether this source exists in the currently published version. A source that is not published will not accept events. |
| `selectedAccountId` | string \| null | No |  |
| `whitelistDomains` | string[] \| null | No | Limits which domains can send events to the CDP. When set, only requests from these domains are accepted for this source. Separate from experiment settings `whitelistDomains`, which limits which domains can load your experiments. |
| `whitelistIps` | string[] \| null | No |  |
| `botControlMode` | string \| null | No | One of: `"Allow"`, `"Block"`, `"Threshold"`, `null`. |
| `botScoreThreshold` | number \| null | No |  |
| `excludeRequestContext` | boolean \| null | No |  |
| `redirectUrl` | string \| null | No |  |
| `forwardUtmToDestination` | boolean | Yes | Whether published short-link campaign tags are forwarded to missing destination UTM keys. Existing sources default to false. |
| `projectAPIKey` | string \| null | No |  |
| `probabilisticIdentity` | object \| null | No |  |
| `probabilisticIdentity.enabled` | boolean | Yes |  |
| `probabilisticIdentity.matchWindowMinutes` | integer | Yes |  |
| `probabilisticIdentity.maxMatchesPerIp` | integer | Yes |  |

Full schema: [OpenAPI specification](https://docs.oursprivacy.com/openapi-platform.json).

## PATCH /rest/v1/sources/{id}

Partially update a source. Only the fields you send are changed; omitted fields are unchanged. Send explicit `null` to clear a nullable field. Returns the full source entity after the update. Requires API-key scope or current OAuth user permission: source:update

Request URL: `PATCH https://app.oursprivacy.com/rest/v1/sources/{id}`

Authentication: apiKey or oauth2.

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | string | Yes |  |

### Request body (`application/json`, required)

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `settings` | object \| null | No | Type-specific source settings. Omitted keys remain unchanged; null clears all settings. settings.dataImport configures an import on an HTTP API source; null clears just that definition. Publish the source to activate import changes. |
| `status` | string \| null | No | One of: `"Disabled"`, `"Enabled"`, `null`. |
| `botControlMode` | string \| null | No | One of: `"Allow"`, `"Block"`, `"Threshold"`, `null`. |
| `botScoreThreshold` | number \| null | No |  |
| `excludeRequestContext` | boolean \| null | No |  |
| `name` | string \| null | No |  |
| `probabilisticIdentity` | object \| null | No |  |
| `probabilisticIdentity.enabled` | boolean | Yes |  |
| `probabilisticIdentity.matchWindowMinutes` | integer \| null | No |  |
| `probabilisticIdentity.maxMatchesPerIp` | integer \| null | No |  |
| `projectAPIKey` | string \| null | No |  |
| `redirectUrl` | string \| null (uri) | No |  |
| `selectedAccountId` | string \| null | No |  |
| `whitelistDomains` | string[] \| null | No |  |
| `whitelistIps` | string[] \| null | No |  |

### Responses

- `200`: Updated source
- `400`: Bad Request
- `401`: Unauthorized — missing, invalid, or expired API key or OAuth access token
- `403`: Forbidden — credential does not have the required current Ours permission
- `404`: Not Found
- `500`: Internal Server Error

#### `200` response body

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `settings` | object \| null | No | Type-specific source settings. settings.dataImport contains a draft file, warehouse or HTTP import definition, with transformation, schedule and credential references. Account publication activates imports. |
| `id` | string | Yes |  |
| `name` | string \| null | No |  |
| `type` | string | Yes | One of: `"AlchemerWebhook"`, `"AndroidNativeApi"`, `"Branch"`, `"CSharpApi"`, `"CalComWebhooks"`, `"CalendlyWebhook"`, `"CallRail"`, `"CallTrackingMetrics"`, `"DotNetApi"`, `"FacebookLeadAds"`, `"FlutterApi"`, `"FormsortWebhooks"`, `"Formstack"`, `"GoLangApi"`, `"HTTPApiSource"`, `"Healthie"`, `"Heyflow"`, `"HubspotAppActions"`, `"HubspotFormWebhook"`, `"JotFormWebhooks"`, `"KotlinApi"`, `"NodejsApi"`, `"PHPApi"`, `"PixelImage"`, `"PythonApi"`, `"ReactNativeApi"`, `"RedirectSource"`, `"RubyApi"`, `"SegmentWebPlugin"`, `"TypeformWebhooks"`, `"WebSource"`, `"Webhook"`, `"WhatConverts"`, `"iOSNativeApi"`. |
| `status` | string | Yes | One of: `"Disabled"`, `"Enabled"`. |
| `createdAt` | string | Yes |  |
| `accountId` | string | Yes | Organization id that owns this source. |
| `isPublished` | boolean \| null | No | Whether this source exists in the currently published version. A source that is not published will not accept events. |
| `selectedAccountId` | string \| null | No |  |
| `whitelistDomains` | string[] \| null | No | Limits which domains can send events to the CDP. When set, only requests from these domains are accepted for this source. Separate from experiment settings `whitelistDomains`, which limits which domains can load your experiments. |
| `whitelistIps` | string[] \| null | No |  |
| `botControlMode` | string \| null | No | One of: `"Allow"`, `"Block"`, `"Threshold"`, `null`. |
| `botScoreThreshold` | number \| null | No |  |
| `excludeRequestContext` | boolean \| null | No |  |
| `redirectUrl` | string \| null | No |  |
| `forwardUtmToDestination` | boolean | Yes | Whether published short-link campaign tags are forwarded to missing destination UTM keys. Existing sources default to false. |
| `projectAPIKey` | string \| null | No |  |
| `probabilisticIdentity` | object \| null | No |  |
| `probabilisticIdentity.enabled` | boolean | Yes |  |
| `probabilisticIdentity.matchWindowMinutes` | integer | Yes |  |
| `probabilisticIdentity.maxMatchesPerIp` | integer | Yes |  |

Full schema: [OpenAPI specification](https://docs.oursprivacy.com/openapi-platform.json).

## DELETE /rest/v1/sources/{id}

Delete a source. Requires API-key scope or current OAuth user permission: source:delete

Request URL: `DELETE https://app.oursprivacy.com/rest/v1/sources/{id}`

Authentication: apiKey or oauth2.

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | string | Yes |  |

### Responses

- `200`: Deleted successfully
- `400`: Bad Request
- `401`: Unauthorized — missing, invalid, or expired API key or OAuth access token
- `403`: Forbidden — credential does not have the required current Ours permission
- `404`: Not Found
- `500`: Internal Server Error

#### `200` response body

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `deleted` | boolean | Yes | One of: `true`. |

Full schema: [OpenAPI specification](https://docs.oursprivacy.com/openapi-platform.json).

## GET /rest/v1/sources/{id}/tokens

Returns the install or ingest tokens for a source. The response is a discriminated union on `sourceType`: pixel sources return `{ sourceType: "pixel", token, testToken, installScript, testInstallScript }`, and webhook sources return `{ sourceType: "webhook", token, testToken, ingestUrl, testIngestUrl, sampleCurl }`. Inspect the source's `type` field (`GET /rest/v1/sources/{id}`) to know which variant to expect. Requires API-key scope or current OAuth user permission: source:view

Request URL: `GET https://app.oursprivacy.com/rest/v1/sources/{id}/tokens`

Authentication: apiKey or oauth2.

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | string | Yes |  |

### Responses

- `200`: Source tokens. The shape depends on the source — pixel/web sources return an `installScript`; webhook sources return an `ingestUrl` and `sampleCurl`. The `sourceType` field discriminates between the two variants.
- `400`: Bad Request
- `401`: Unauthorized — missing, invalid, or expired API key or OAuth access token
- `403`: Forbidden — credential does not have the required current Ours permission
- `404`: Not Found
- `500`: Internal Server Error

Full schema: [OpenAPI specification](https://docs.oursprivacy.com/openapi-platform.json).
