# Attribution Report

{% hint style="info" %}
The Attribution API is currently a beta feature. For early access, please reach out to <support@heypoplar.com>
{% endhint %}

The Attribution Report endpoint enables you to generate an [Attribution Report](https://docs.heypoplar.com/article/240-understanding-attribution-reports) for up to 6 months of data. The resulting report will be delivered in batches to a webhook URL of your choosing ([see below](#webhook-setup)).

## Generate attribution report

<mark style="color:green;">`POST`</mark> `https://api.heypoplar.com/v1/reports/attribution`

This endpoint allows you to generate an attribution report from a specified [reporting window](https://docs.heypoplar.com/article/240-understanding-attribution-reports#reporting-window) that will be delivered through a [webhook](#webhook-setup).

#### Request Body

| Name                                          | Type   | Description                                                                                                                    |
| --------------------------------------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------ |
| start\_date<mark style="color:red;">\*</mark> | string | YYYY-MM-DD (ISO8601) formatted date for the start of the reporting window.                                                     |
| campaign\_id                                  | string | <p>The ID of the campaign for the report.</p><p></p><p>If not set, the report will contain all campaigns</p>                   |
| end\_date<mark style="color:red;">\*</mark>   | string | <p>YYYY-MM-DD (ISO8601) for the end of the reporting window. </p><p></p><p>Must be no more than 180 days after start\_date</p> |

{% tabs %}
{% tab title="201: Created New report created" %}

```json
{
  start_date: "YYYY-MM-DD",
  end_date: "YYYY-MM-DD",
  status: "created",
  campaign_scope: "b01cdd5e-5b83-4345-826a-094c823f894b",
  campaign_name: "Campaign Name 1",
  response_webhooks: ["api.yourwebhook.com/attribution_report"]
}

```

{% endtab %}

{% tab title="202: Accepted Processing - report was previously created but has not finished sending." %}

```json
{
  start_date: "YYYY-MM-DD",
  end_date: "YYYY-MM-DD",
  status: "processing",
  campaign_scope: "b01cdd5e-5b83-4345-826a-094c823f894b",
  campaign_name: "Campaign Name 1",
  response_webhooks: ["api.yourwebhook.com/attribution_report"]
}
```

{% endtab %}

{% tab title="200: OK Resending report - same report was created on that day. Will not recalculate report. " %}

```json
{
  start_date: "YYYY-MM-DD",
  end_date: "YYYY-MM-DD",
  status: "resending_report",
  campaign_scope: "b01cdd5e-5b83-4345-826a-094c823f894b",
  campaign_name: "Campaign Name 1",
  response_webhooks: ["api.yourwebhook.com/attribution_report"]
}
```

{% endtab %}

{% tab title="422: Unprocessable Entity Attribution report response webhook needs to be setup (see below)" %}

{% endtab %}

{% tab title="200: OK No attribution data available for the specified campaign" %}

{% endtab %}

{% tab title="200: OK No attribution data available for the organization. Transaction data upload required" %}

{% endtab %}

{% tab title="400: Bad Request Date range cannot exceed 180 days" %}

{% endtab %}
{% endtabs %}

### Webhook Setup

<figure><img src="https://content.gitbook.com/content/xfN4IIBsOUuqBd0ERnDW/blobs/x2fjSid7bkYMfMbOnzfS/attribution-webhook-setup.png" alt=""><figcaption></figcaption></figure>

{% hint style="warning" %}
This page will only appear if the Attribution API has been enabled for your account
{% endhint %}

To setup your Attribution API webhook, navigate to **Integrations > Attribution Report** and click the button to create a new webhoo&#x6B;**.** From here, enter a webhook destination URL of your choosing. To verify the webhook has been setup correctly, use the "Send Test" link and ensure that a `200` response is returned.

### Webhook Payload

When the report has finished generating, it will be sent through the webhook that was previously setup.

<table><thead><tr><th width="236">Field</th><th>Description</th></tr></thead><tbody><tr><td><code>campaign_id</code></td><td>The ID of the campaign for the report (if provided)</td></tr><tr><td><code>start_date</code></td><td>The starting date for the report window</td></tr><tr><td><code>end_date</code></td><td>The end date for the report window</td></tr><tr><td><code>batch_index</code></td><td>The index of the current batch of results</td></tr><tr><td><code>total_batches</code></td><td>The total number of batches contained in the report</td></tr><tr><td><code>attribution_data</code></td><td>An array of up to 100 attribution match objects.<br><br>For more details about match objects, see our <a href="https://docs.heypoplar.com/article/241-download-raw-matches">raw matches documentation</a>.</td></tr></tbody></table>

#### Example Payload

This sample response shows one complete set of data for a "match." Payloads will hold up to 100 matches per batch. The keys found in `attribution_data` are the same keys used in [Download Raw Matches](https://docs.heypoplar.com/article/241-download-raw-matches) on the transactions page <https://app.heypoplar.com/transaction>.

```json
{ 
  campaign_id: "b01cdd5e-5b83-4345-826a-094c823f894b",
  start_date: "YYYY-MM-DD",
  end_date: "YYYY-MM-DD",
  batch_index: 0,
  total_batches: 5
  attribution_data: [
    {
      match_id: "b01cdd5e-5b83-4345-826a-094c823f894b",
      campaign_id: "b01cdd5e-5b83-4345-826a-094c823f894b",
      campaign_name: "Campaign Name 1",
      creative_id: "b01cdd5e-5b83-4345-826a-094c823f894b",
      mailing_id: "b01cdd5e-5b83-4345-826a-094c823f894b",
      order_id: "b01cdd5e-5b83-4345-826a-094c823f894b",
      customer_id: "b01cdd5e-5b83-4345-826a-094c823f894b",
      order_date: "2021-12-19 00:00:00 UTC",
      order_total: "283.0",
      order_currency: "USD",
      mailing_cost: 0.46,
      mailing_state: "delivered",
      send_date: "2021-12-16",
      in_home_date: "2021-12-23",
      match_type: "M",
      unique: "false",
      new_buyer: "false",
      email_match: "true",
      billing_address_match: "false",
      shipping_address_match: "true",
      manual_send_id: "b01cdd5e-5b83-4345-826a-094c823f894b",
      manual_send_name: "first send",
      metadata: "{\"new_buyer\"=>false}"
    },
    {
      ...
    }
  ]
}
```

<details>

<summary><mark style="color:blue;">(Optional)</mark> Webhook HMAC Verification</summary>

HTTP `POST` payloads contain an `X-SLM-Signature` HTTP header. This is the HMAC hex digest of the response body. It is generated using the SHA1 hash function with the secret displayed on **Integrations > Attribution Report** as the HMAC key. You can use this in order to verify the authenticity and integrity of a payload.&#x20;

Here is an example of verifying authenticity and integrity of a request body using the Ruby library [OpenSSL::HMAC](https://ruby-doc.org/stdlib-2.4.0/libdoc/openssl/rdoc/OpenSSL/HMAC.html).

```ruby
require 'openssl'
require 'json'

SHARED_SECRET = '591f827adf2f1e348ec3dc2a07e61e59' # found on heypoplar.com Integrations > Attribution Report

request = {
  headers: {
    'X-SLM-Signature': '8b3f7dad2f29e5921d3b36487b16eeaa52c8448e'
  },
  body: {
    'start_date': 'YYYY-MM-DD',
    'end_date': 'YYYY-MM-DD',
    'batch_index': 0,
    'total_batches': 1,
    'attribution_data': []
  }
}

expected_signature = OpenSSL::HMAC.hexdigest(
  OpenSSL::Digest.new('sha1'),
  SHARED_SECRET,
  request[:body].to_json
)
# => '8b3f7dad2f29e5921d3b36487b16eeaa52c8448e'

if request[:headers][:'X-SLM-Signature'] == expected_signature
  # Request verified
end
  
```

</details>