# Attribution (Beta)

> Query multi-touch Conversion Attribution and Audience Performance conversion reports via the REST API. These endpoints are in beta.

Source: https://docs.oursprivacy.com/docs/platform-api/attribution-conversion

Query multi-touch Conversion Attribution and Audience Performance conversion reports for a conversion event over a date window. These endpoints are in **beta**, and the response shape may change before general availability.

## GET /rest/v1/attribution/conversion

Multi-touch conversion attribution: returns a source → medium → campaign hierarchy with attributed converter credits distributed according to the selected `attributionModel`. Scoped to all web sources by default; optionally narrow to a single web source via `webSourceId`. Date range is capped at 31 days; lookback window is capped at 60 days. Requires API-key scope or current OAuth user permission: web-analytics:view

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

Authentication: apiKey or oauth2.

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `from` | query | string | Yes | Inclusive lower bound of the analytics window, as a UTC calendar day in `YYYY-MM-DD` format. The window between `from` and `to` must be 31 days or fewer. |
| `to` | query | string | Yes | Inclusive upper bound of the analytics window, as a UTC calendar day in `YYYY-MM-DD` format. The window between `from` and `to` must be 31 days or fewer. |
| `eventName` | query | string | Yes | Conversion event to attribute. Must be a selectable conversion event. |
| `attributionModel` | query | string | Yes | Attribution model to apply to multi-touch conversion paths. One of: `"FIRST_TOUCH"`, `"LAST_TOUCH"`, `"LINEAR"`, `"U_SHAPED"`, `"J_SHAPED"`, `"TIME_DECAY"`. |
| `lookbackWindow` | query | string | No | How far back before each conversion to consider touchpoints. Capped at 60 days for this report. Defaults to `THIRTY_DAYS`. One of: `"SEVEN_DAYS"`, `"FOURTEEN_DAYS"`, `"THIRTY_DAYS"`, `"SIXTY_DAYS"`, `"NINETY_DAYS"`, `"ONE_HUNDRED_EIGHTY_DAYS"`, `"UNLIMITED"`. |
| `limit` | query | integer | No | Maximum number of leaf-level attribution rows to return. Defaults to 1000. |
| `webSourceId` | query | string | No | Scope to a single web source by id, or omit for all sources (account-wide). |

### Responses

- `200`: Multi-touch conversion attribution hierarchy
- `400`: Bad request — malformed `from`/`to`, window longer than 31 days, or invalid `eventName`.
- `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 |
| --- | --- | --- | --- |
| `summary` | object | Yes |  |
| `summary.totalEventConverters` | integer | Yes |  |
| `summary.scopeConverters` | integer | Yes |  |
| `summary.attributedConverters` | integer | Yes |  |
| `summary.totalSessions` | integer | Yes |  |
| `nodes` | object[] | Yes |  |
| `nodes[].level` | string | Yes | One of: `"SOURCE"`, `"MEDIUM"`, `"CAMPAIGN"`. |
| `nodes[].source` | string | Yes |  |
| `nodes[].medium` | string \| null | No |  |
| `nodes[].campaign` | string \| null | No |  |
| `nodes[].attributedConverterCredit` | number | Yes |  |
| `nodes[].converters` | integer | Yes |  |
| `nodes[].sessions` | integer | Yes |  |
| `isTruncated` | boolean | Yes |  |
| `totalLeafRows` | integer | Yes |  |
| `maxLeafRows` | integer | Yes |  |

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

## GET /rest/v1/attribution/audience-conversion

Audience performance conversion report: returns a summary of converters and conversion rate for the selected event and date window, a per-day timeseries, and a UTM source/medium/campaign breakdown. Optionally compare against the preceding period of equal length when `attributionWindow` is `IN_RANGE`. Date range is capped at 60 days. Requires API-key scope or current OAuth user permission: web-analytics:view

Request URL: `GET https://app.oursprivacy.com/rest/v1/attribution/audience-conversion`

Authentication: apiKey or oauth2.

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `from` | query | string | Yes | Inclusive lower bound of the analytics window, as a UTC calendar day in `YYYY-MM-DD` format. The window between `from` and `to` must be 60 days or fewer. |
| `to` | query | string | Yes | Inclusive upper bound of the analytics window, as a UTC calendar day in `YYYY-MM-DD` format. The window between `from` and `to` must be 60 days or fewer. |
| `eventName` | query | string | Yes | Conversion event to analyze. |
| `valueProperty` | query | string | No | Event property to sum as conversion value. |
| `attributionWindow` | query | string | No | Attribution window: `IN_RANGE` or a number of lookback days (e.g. `7`, `30`). Defaults to `IN_RANGE`. |
| `webSourceId` | query | string (uuid) | No | Filter results to a specific web source by its UUID. |
| `excludeBots` | query | string | No | Exclude bot sessions. Defaults to `true`. One of: `"true"`, `"false"`. |

### Responses

- `200`: Audience conversion report with summary, timeseries, and UTM breakdown
- `400`: Bad request — malformed `from`/`to` or window longer than 60 days.
- `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 |
| --- | --- | --- | --- |
| `summary` | object | Yes |  |
| `summary.audienceSize` | integer | Yes |  |
| `summary.conversions` | integer | Yes |  |
| `summary.totalValue` | number | Yes |  |
| `summary.converters` | integer | Yes |  |
| `summary.conversionRate` | number | Yes |  |
| `summary.avgValuePerConversion` | number | Yes |  |
| `summary.avgValuePerConvertingVisitor` | number | Yes |  |
| `previousSummary` | object \| null | No |  |
| `previousSummary.audienceSize` | integer | Yes |  |
| `previousSummary.conversions` | integer | Yes |  |
| `previousSummary.totalValue` | number | Yes |  |
| `previousSummary.converters` | integer | Yes |  |
| `previousSummary.conversionRate` | number | Yes |  |
| `previousSummary.avgValuePerConversion` | number | Yes |  |
| `previousSummary.avgValuePerConvertingVisitor` | number | Yes |  |
| `timeseries` | object[] | Yes |  |
| `timeseries[].date` | string | Yes |  |
| `timeseries[].conversions` | integer | Yes |  |
| `timeseries[].totalValue` | number | Yes |  |
| `breakdown` | object[] | Yes |  |
| `breakdown[].source` | string | Yes |  |
| `breakdown[].medium` | string | Yes |  |
| `breakdown[].campaign` | string | Yes |  |
| `breakdown[].conversions` | integer | Yes |  |
| `breakdown[].converters` | integer | Yes |  |
| `breakdown[].totalValue` | number | Yes |  |

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