# Attribution

> Query initial (first-touch) attribution, last-touch attribution, and UTM Performance Comparison reports over the public REST API.

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

Query computed attribution reports (first-touch, last-touch, and side-by-side UTM comparison) for a conversion event over a date window.

## GET /rest/v1/attribution/initial

Returns the top-15 values for each UTM dimension (source, medium, campaign, content, term, name) and referring domain attributed to the conversion event on a first-touch basis for the given date window. Use `from`/`to` to set the analysis window (max 60 days). Optionally filter to a specific UTM combo with `utmSource`, `utmMedium`, etc. The counts represent unique visitors who performed the specified `eventName` and were attributed to each UTM value. Requires API-key scope or current OAuth user permission: web-analytics:view

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

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 count. Must be a selectable conversion event. |
| `attributionType` | query | string | No | Attribution type for UTM filter matching. Defaults to `INITIAL`. One of: `"INITIAL"`, `"LAST_TOUCH"`. |
| `utmSource` | query | string | No | Filter by UTM source. |
| `utmMedium` | query | string | No | Filter by UTM medium. |
| `utmCampaign` | query | string | No | Filter by UTM campaign. |
| `utmContent` | query | string | No | Filter by UTM content. |
| `utmTerm` | query | string | No | Filter by UTM term. |
| `utmName` | query | string | No | Filter by UTM name. |

### Responses

- `200`: Initial (first-touch) attribution breakdown by UTM dimension and referring domain
- `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 |
| --- | --- | --- | --- |
| `initial_utm_source` | object[] | Yes |  |
| `initial_utm_source[].value` | string | Yes |  |
| `initial_utm_source[].count` | integer | Yes |  |
| `initial_utm_medium` | object[] | Yes |  |
| `initial_utm_medium[].value` | string | Yes |  |
| `initial_utm_medium[].count` | integer | Yes |  |
| `initial_utm_campaign` | object[] | Yes |  |
| `initial_utm_campaign[].value` | string | Yes |  |
| `initial_utm_campaign[].count` | integer | Yes |  |
| `initial_utm_content` | object[] | Yes |  |
| `initial_utm_content[].value` | string | Yes |  |
| `initial_utm_content[].count` | integer | Yes |  |
| `initial_utm_term` | object[] | Yes |  |
| `initial_utm_term[].value` | string | Yes |  |
| `initial_utm_term[].count` | integer | Yes |  |
| `initial_utm_name` | object[] | Yes |  |
| `initial_utm_name[].value` | string | Yes |  |
| `initial_utm_name[].count` | integer | Yes |  |
| `initial_referring_domain` | object[] | Yes |  |
| `initial_referring_domain[].value` | string | Yes |  |
| `initial_referring_domain[].count` | integer | Yes |  |

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

## GET /rest/v1/attribution/last-touch

Returns the top-15 values for each UTM dimension (source, medium, campaign, content, term, name) and referring domain attributed to the conversion event on a last-touch basis for the given date window. Use `from`/`to` to set the analysis window (max 60 days). The counts represent unique visitors who performed the specified `eventName` and were attributed to each UTM value on their most recent session. Requires API-key scope or current OAuth user permission: web-analytics:view

Request URL: `GET https://app.oursprivacy.com/rest/v1/attribution/last-touch`

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 count. Must be a selectable conversion event. |
| `attributionType` | query | string | No | Attribution type for UTM filter matching. Defaults to `LAST_TOUCH`. One of: `"INITIAL"`, `"LAST_TOUCH"`. |
| `utmSource` | query | string | No | Filter by UTM source. |
| `utmMedium` | query | string | No | Filter by UTM medium. |
| `utmCampaign` | query | string | No | Filter by UTM campaign. |
| `utmContent` | query | string | No | Filter by UTM content. |
| `utmTerm` | query | string | No | Filter by UTM term. |
| `utmName` | query | string | No | Filter by UTM name. |

### Responses

- `200`: Last-touch attribution breakdown by UTM dimension and referring domain
- `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 |
| --- | --- | --- | --- |
| `utm_source` | object[] | Yes |  |
| `utm_source[].value` | string | Yes |  |
| `utm_source[].count` | integer | Yes |  |
| `utm_medium` | object[] | Yes |  |
| `utm_medium[].value` | string | Yes |  |
| `utm_medium[].count` | integer | Yes |  |
| `utm_campaign` | object[] | Yes |  |
| `utm_campaign[].value` | string | Yes |  |
| `utm_campaign[].count` | integer | Yes |  |
| `utm_content` | object[] | Yes |  |
| `utm_content[].value` | string | Yes |  |
| `utm_content[].count` | integer | Yes |  |
| `utm_term` | object[] | Yes |  |
| `utm_term[].value` | string | Yes |  |
| `utm_term[].count` | integer | Yes |  |
| `utm_name` | object[] | Yes |  |
| `utm_name[].value` | string | Yes |  |
| `utm_name[].count` | integer | Yes |  |
| `referring_domain` | object[] | Yes |  |
| `referring_domain[].value` | string | Yes |  |
| `referring_domain[].count` | integer | Yes |  |

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

## GET /rest/v1/attribution/utm-comparison

Compare up to 5 UTM dimension combinations side-by-side for a single conversion event. Each combo returns the unique visitors, sessions, total events, and derived conversion rate for that UTM filter within the window. Requires both `web-analytics:view` and `report:event-count-by-day` API-key scopes. Date range is capped at 31 days. Pass `combos` as a single JSON-encoded array: `combos=[{"utmSource":"google","utmMedium":"cpc"},{"utmSource":"meta"}]`. Requires API-key scope or current OAuth user permission: web-analytics:view

Request URL: `GET https://app.oursprivacy.com/rest/v1/attribution/utm-comparison`

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 compare across UTM combos. |
| `combos` | query | string | Yes | JSON-encoded array of UTM dimension combos to compare side-by-side (min 1, max 5). Each combo is an object with optional `utmSource`, `utmMedium`, `utmCampaign`, `utmContent`, `utmTerm` fields. |

### Responses

- `200`: Side-by-side UTM performance comparison for up to 5 UTM combos
- `400`: Bad request — malformed `from`/`to`, window longer than 31 days, malformed `combos` JSON, or more than 5 combos.
- `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 |
| --- | --- | --- | --- |
| `combos` | object[] | Yes | Per-combo metrics in the same order as the input `combos` array. |
| `combos[].combo` | object | Yes |  |
| `combos[].combo.utmSource` | string \| null | No |  |
| `combos[].combo.utmMedium` | string \| null | No |  |
| `combos[].combo.utmCampaign` | string \| null | No |  |
| `combos[].combo.utmContent` | string \| null | No |  |
| `combos[].combo.utmTerm` | string \| null | No |  |
| `combos[].visitors` | integer | Yes |  |
| `combos[].sessions` | integer | Yes |  |
| `combos[].events` | integer | Yes |  |
| `combos[].conversionRate` | number | Yes |  |
| `range` | object | Yes | The requested date range as returned by the server. |
| `range.from` | string | Yes |  |
| `range.to` | string | Yes |  |
| `eventName` | string | Yes | The conversion event that was analyzed. |

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