# Attribution Report {% hint style="info" %} The Attribution API is currently a beta feature. For early access, please reach out to {% 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 `POST` `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\* | string | YYYY-MM-DD (ISO8601) formatted date for the start of the reporting window. | | campaign\_id | string |

The ID of the campaign for the report.

If not set, the report will contain all campaigns

| | end\_date\* | string |

YYYY-MM-DD (ISO8601) for the end of the reporting window.

Must be no more than 180 days after start\_date

| {% 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
{% 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 webhook**.** 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.
FieldDescription
campaign_idThe ID of the campaign for the report (if provided)
start_dateThe starting date for the report window
end_dateThe end date for the report window
batch_indexThe index of the current batch of results
total_batchesThe total number of batches contained in the report
attribution_dataAn array of up to 100 attribution match objects.

For more details about match objects, see our raw matches documentation.
#### 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 . ```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}" }, { ... } ] } ```
(Optional) Webhook HMAC Verification 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. 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 ```
--- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.heypoplar.com/api/endpoints/attribution-report.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.