Attribution Report

The Attribution API is currently a beta feature. For early access, please reach out to [email protected]

The Attribution Report endpoint enables you to generate an Attribution Report for up to 6 months of data. The resulting report will be delivered in batches to a webhook URL of your choosing (see below).

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 that will be delivered through a webhook.

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

201: Created New report created

{
  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"]
}

202: Accepted Processing - report was previously created but has not finished sending.

{
  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"]
}

200: OK Resending report - same report was created on that day. Will not recalculate report.

{
  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"]
}

422: Unprocessable Entity Attribution report response webhook needs to be setup (see below)

200: OK No attribution data available for the specified campaign

200: OK No attribution data available for the organization. Transaction data upload required

400: Bad Request Date range cannot exceed 180 days

Webhook Setup

This page will only appear if the Attribution API has been enabled for your account

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.

Field	Description
campaign_id	The ID of the campaign for the report (if provided)
start_date	The starting date for the report window
end_date	The end date for the report window
batch_index	The index of the current batch of results
total_batches	The total number of batches contained in the report
attribution_data	An 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 on the transactions page https://app.heypoplar.com/transaction.

{ 
  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.

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