Attributed Conversions

POST

/api/public/conversions

Note: An organization-scoped API key is limited to its own advertiser and publisher. Attribution weights stay as calculated across all touches. Purchase amount, weighted purchase amount, order id, IP, device ids, user agents, postal codes, hashed email, Meta, landing and referrer URLs, and the survey response are omitted and cannot be requested back through fields. Promo rows are omitted. A purchase that has a survey answer stays.

Attributed conversions with their action, order value, credit weight, campaign, show, episode and device details.

This endpoint utilizes a task system.

Please read the description of Get status of file processing to understand how it works.

Attributed Conversions

const url = 'https://backend.podscribe.ai/api/public/conversions';
const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: '{"fields":["Advertiser","Purchased At","Action","Discount code","Purchase Amount","Weighted Purchase Amount","Conversion Weight","Order number","Media Type","Campaign","Tags","Category","Publisher","Show Last Listened To","Show Last Listened To ID","Publisher Show / Station Name","Episode","Episode ID","Last Heard Ad","Landing URL","Referer URL","New customer","Conversion UA","Impression UA","IP","Currency","ISP Weight","Mobile Ad ID","Device ID","Raw Action","Country","Hashed Email","Meta","Campaign Internal ID","Publisher ID","Product (from Campaign)","Initiative","Survey Response","Creative id","Product (from Event)","Business Line","Show iTunes ID","Campaign & Initiative","Prog. Publisher","Session Landing URL","Session Referer URL","Event URL"],"fieldsVersion":1,"fieldsMapping":{"Purchased At":"converted_at","Discount code":"promo_code"},"name":"example","startDate":"example","endDate":"example","advertiser":"example","withVisitors":false,"attributionModel":"first","excludeReferrers":["email","facebook","tiktok","instagram","twitter"],"excludeUtmMediums":["email","facebook","fb","tiktok","sms","social","klaviyo","youtube","instagram","ig"],"excludeUtmSources":["email","facebook","fb","tiktok","twitter","klaviyo","youtube","instagram","ig"],"excludePriorCustomers":false,"excludePriorVisitors":false,"timeRangeConv":false,"timeRangeConvWithWindow":false,"attributionWindow":30,"attributionStreamingWindow":14,"attributionSaiWindow":30,"attributionPreset":"any","excludePromos":false,"excludeSurveys":false,"excludeTime":false,"timeFormat":"12h","events":["example"]}'
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}

import requests

url = "https://backend.podscribe.ai/api/public/conversions"

payload = {
    "fields": ["Advertiser", "Purchased At", "Action", "Discount code", "Purchase Amount", "Weighted Purchase Amount", "Conversion Weight", "Order number", "Media Type", "Campaign", "Tags", "Category", "Publisher", "Show Last Listened To", "Show Last Listened To ID", "Publisher Show / Station Name", "Episode", "Episode ID", "Last Heard Ad", "Landing URL", "Referer URL", "New customer", "Conversion UA", "Impression UA", "IP", "Currency", "ISP Weight", "Mobile Ad ID", "Device ID", "Raw Action", "Country", "Hashed Email", "Meta", "Campaign Internal ID", "Publisher ID", "Product (from Campaign)", "Initiative", "Survey Response", "Creative id", "Product (from Event)", "Business Line", "Show iTunes ID", "Campaign & Initiative", "Prog. Publisher", "Session Landing URL", "Session Referer URL", "Event URL"],
    "fieldsVersion": 1,
    "fieldsMapping": {
        "Purchased At": "converted_at",
        "Discount code": "promo_code"
    },
    "name": "example",
    "startDate": "example",
    "endDate": "example",
    "advertiser": "example",
    "withVisitors": False,
    "attributionModel": "first",
    "excludeReferrers": ["email", "facebook", "tiktok", "instagram", "twitter"],
    "excludeUtmMediums": ["email", "facebook", "fb", "tiktok", "sms", "social", "klaviyo", "youtube", "instagram", "ig"],
    "excludeUtmSources": ["email", "facebook", "fb", "tiktok", "twitter", "klaviyo", "youtube", "instagram", "ig"],
    "excludePriorCustomers": False,
    "excludePriorVisitors": False,
    "timeRangeConv": False,
    "timeRangeConvWithWindow": False,
    "attributionWindow": 30,
    "attributionStreamingWindow": 14,
    "attributionSaiWindow": 30,
    "attributionPreset": "any",
    "excludePromos": False,
    "excludeSurveys": False,
    "excludeTime": False,
    "timeFormat": "12h",
    "events": ["example"]
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.json())

curl --request POST \
  --url https://backend.podscribe.ai/api/public/conversions \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "fields": [ "Advertiser", "Purchased At", "Action", "Discount code", "Purchase Amount", "Weighted Purchase Amount", "Conversion Weight", "Order number", "Media Type", "Campaign", "Tags", "Category", "Publisher", "Show Last Listened To", "Show Last Listened To ID", "Publisher Show / Station Name", "Episode", "Episode ID", "Last Heard Ad", "Landing URL", "Referer URL", "New customer", "Conversion UA", "Impression UA", "IP", "Currency", "ISP Weight", "Mobile Ad ID", "Device ID", "Raw Action", "Country", "Hashed Email", "Meta", "Campaign Internal ID", "Publisher ID", "Product (from Campaign)", "Initiative", "Survey Response", "Creative id", "Product (from Event)", "Business Line", "Show iTunes ID", "Campaign & Initiative", "Prog. Publisher", "Session Landing URL", "Session Referer URL", "Event URL" ], "fieldsVersion": 1, "fieldsMapping": { "Purchased At": "converted_at", "Discount code": "promo_code" }, "name": "example", "startDate": "example", "endDate": "example", "advertiser": "example", "withVisitors": false, "attributionModel": "first", "excludeReferrers": [ "email", "facebook", "tiktok", "instagram", "twitter" ], "excludeUtmMediums": [ "email", "facebook", "fb", "tiktok", "sms", "social", "klaviyo", "youtube", "instagram", "ig" ], "excludeUtmSources": [ "email", "facebook", "fb", "tiktok", "twitter", "klaviyo", "youtube", "instagram", "ig" ], "excludePriorCustomers": false, "excludePriorVisitors": false, "timeRangeConv": false, "timeRangeConvWithWindow": false, "attributionWindow": 30, "attributionStreamingWindow": 14, "attributionSaiWindow": 30, "attributionPreset": "any", "excludePromos": false, "excludeSurveys": false, "excludeTime": false, "timeFormat": "12h", "events": [ "example" ] }'

Request Body

application/json

fields

Exact CSV column header names to include, in order. If omitted, all CSV columns not excluded by default are included. Allowed values list all built-in static columns using the current default (v1) names. The new (v2) publisher names (Publisher (from Campaign), Publisher's Show / Station Name, Programmatic Publisher (from Macro)) are also accepted here regardless of fieldsVersion; the value of fieldsVersion only controls the header names written to the output CSV. See fieldsVersion.

Array

42 moreLess

Advertiser Purchased At Action Discount code Purchase Amount Weighted Purchase Amount Conversion Weight Order number Media Type Campaign Tags Category Publisher Show Last Listened To Show Last Listened To ID Publisher Show / Station Name Episode Episode ID Last Heard Ad Landing URL Referer URL New customer Conversion UA Impression UA IP Currency ISP Weight Mobile Ad ID Device ID Raw Action Country DMA Zip Hashed Email Meta Campaign Internal ID Podscribe Campaign ID Publisher ID Product (from Campaign) Initiative Survey Response Creative id Product (from Event) Business Line Show iTunes ID Campaign & Initiative Prog. Publisher Session Landing URL Session Referer URL Event URL Genre Impression Zip Impression Region (State) Impression City Ad Server Impression Normalized User Agent Conversion Device Device Ad Position (from Ad Server) Ad Zone ID Privacy Device (Ad Server) Prog. Supply Vendor Campaign Promo IPv6 Weight Campaign ID Site Impression UUID IPv4 Publisher (from Campaign) Publisher's Show / Station Name Programmatic Publisher (from Macro)

67 moreLess

fieldsVersion

Controls the header names of the publisher-related columns in the output CSV. The underlying data is identical for both versions — this is a label-only change.

1: the legacy column names.
2: the new, clarified column names shown in the app. This will become the default in a future release; set fieldsVersion: 2 now to adopt the new names early.

Column name by version (v1 legacy → v2 new):

Publisher → Publisher (from Campaign)
Publisher Show / Station Name → Publisher's Show / Station Name
Prog. Publisher → Programmatic Publisher (from Macro)

1 2

fieldsMapping

Object to customize column headers in the CSV output (keys are default header names). Both legacy (v1) and current (v2) header names are accepted as keys.

Record<string, string>

Example

{
  "Purchased At": "converted_at",
  "Discount code": "promo_code"
}

name

Optional display name for the generated report. Shown in the Reports UI. Ignored when an identical cached report is reused; pass a new request (or wait for cache expiry) to apply a new name.

string

(≤ 255 chars)

startDate

Start date timestamp (e.g., “2023-10-10”). Default is 3 months ago.

string

endDate

End date timestamp (e.g., “2023-10-10”). Default is one week forward.

string

advertiser

required

Advertiser name. This field is required.

string

withVisitors

If true, the results file will also contain visitors.

boolean

false

attributionModel

Attribution model.

multi_timedecay

first last multi_linear multi_timedecay

excludeReferrers

Referrers to exclude.

Array<string>

email, facebook, tiktok, instagram, twitter

excludeUtmMediums

UTM mediums to exclude.

Array<string>

email facebook fb tiktok sms social klaviyo youtube instagram ig

5 moreLess

excludeUtmSources

UTM sources to exclude.

Array<string>

email facebook fb tiktok twitter klaviyo youtube instagram ig

4 moreLess

excludePriorCustomers

If true, the results will exclude prior customers.

boolean

false

excludePriorVisitors

If true, the results will exclude prior visitors.

boolean

false

timeRangeConv

If true, the results will only include conversions from impressions in this time range (strict when timeRangeConvWithWindow is omitted or false).

boolean

false

timeRangeConvWithWindow

Used with timeRangeConv. If true, only impressions inside the selected report date range are eligible and attributed conversions extend through the configured conversion window after the report end date.

boolean

false

attributionWindow

Days between converted_at and touched_at.

number

attributionStreamingWindow

Days between converted_at and touched_at for streaming.

number

attributionSaiWindow

Days between converted_at and touched_at for SAI.

number

attributionPreset

Device-graph attribution preset, matching the Device Graph Usage control in the UI. Omitted: the default preset is resolved from advertiser. Most advertisers default to any; a small number are configured differently.

any

any all none

excludePromos

If true, the results will exclude conversions from promo codes.

boolean

false

excludeSurveys

If true, the results will exclude survey purchases.

boolean

false

excludeTime

If true, ‘Purchased At’ column will contain only the date.

boolean

false

timeFormat

Clock format for Purchased At. 12h writes YYYY-MM-DD h:mm AM/PM (for example, 2016-04-05 9:58 AM). 24h and YYYY-MM-DD HH:MM write 24-hour time (for example, 2016-04-05 22:30). YYYY-MM-DD HH:MM:SS writes seconds (for example, 2016-04-05 11:30:05). Every other value writes that pattern with zero-padded day and month numbers (for example, MM-DD-YYYY writes 04-05-2016 and D-Mon-YYYY writes 05-Apr-2016). Ignored when excludeTime is true.

12h

12h 24h YYYY-MM-DD YYYY-MM-DD HH:MM YYYY-MM-DD HH:MM:SS MM-DD-YYYY M-D-Y M-D D-Mon-YYYY DMon Mon-D-YYYY Month-D-YYYY Day of Week, Month D, YYYY Day of Wk, Month D, YYYY Day of Week, Mon D, YYYY Day of Wk, Mon D, YYYY

11 moreLess

events

List of events to include in the output. If none specified, all are included.

Array<string>

Response Body

application/json

ID of the file processing task.

string<uuid>

status

Task status: pending, done or failed.

pending done failed

url

Link to download the result file. Returned once the file is ready.

string<uri>

Response example

{
  "status": "pending"
}

Result file

Field	Type	Example	Description
Advertiser	string	demoAdvertiser	Name of the advertiser the conversion belongs to.
Purchased At	string	2023-12-23 9:58 AM	Date and time of purchase. Default is YYYY-MM-DD h:mm AM/PM. `timeFormat` selects another pattern. `excludeTime` writes the date only.
Action	string	install	Type of action performed. Nullable only for promo.
Discount code	string	someCode	Discount code used.
Purchase Amount	number	123	Amount of purchase.
Weighted Purchase Amount	number	123	Weighted value of the purchase: Conversion Weight * Purchase Amount.
Conversion Weight	number	0.05	Conversion weight (0-1) based on attribution mode (first, last, multi-linear, multi-time decay) for credit distribution within exposures.
Order number	string	aaa-bbb-ccc	Unique identifier for the order.
Media Type	string	podcast	Type of media where the ad was run; values include “podcast”, “podcast and youtube”, “youtube”, “simulcast”, “streaming”
Campaign	string	My campaign	Name of the advertising campaign.
Tags	string	Retail	Tags associated with the ad.
Category	string	baked-in	Type of ad category; values include “baked-in”, “dai”, “promo code”
Publisher	string	Some publisher	Name of the ad publisher. With `fieldsVersion: 2` the header is `Publisher (from Campaign)`.
Show Last Listened To	string	Some show	Name of the last show listened to by the user.
Show Last Listened To ID	string	show-id	Podscribe ID of the last show listened to by the user.
Publisher Show / Station Name	string	Some station	Name of the show or station for streaming ads. Only for streaming. With `fieldsVersion: 2` the header is `Publisher's Show / Station Name`.
Episode	string	Some Ep	Episode where the ad was run.
Episode ID	string	episode-id	Podscribe ID of the episode where the ad was run.
Last Heard Ad	string	2023-12-18 9:23 AM	Time and date of the last heard ad, in the format YYYY-mm-DD HH:MM tt
Landing URL	string	https://example.com	URL of the landing page after the ad.
Referer URL	string	https://example.com/buy	Referrer URL of the purchase page.
New customer	bool	false	Boolean indicating if the customer is new.
Conversion UA	string	Mozilla/5.0 (<system-information>) <platform> (<platform-details>) <extensions>	User agent string of the conversion.
Impression UA	string	Mozilla/5.0 (<system-information>) <platform> (<platform-details>) <extensions>	User agent string at the time of ad impression.
IP	string	123.123.123.123	IP address of the user on their conversion.
Currency	string	USD	Currency code, always USD.
ISP Weight	number	2	The inversion of the fraction of the campaign’s impressions were residential.
Mobile Ad ID	string	aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee	Converting device’s Google Advertising ID (Android) or Identifier for Advertisers. (IOS)
Device ID	string	aaa-bbb-ccc	Unique identifier for the user’s device; typically the Podscribe cookie ID.
Raw Action	string	event1	Raw action data (if input action is different than Podscribe action name). Nullable only for promo
Country	string	us	Country obtained from the conversion IP address.
DMA	string	COLUMBIA-JEFFERSON CITY	DMA obtained from the conversion IP address.
Zip	string	12345	Zip obtained from the conversion IP address.
Hashed Email	string		Hash code sha256 or md5.
Meta	string	JSON `{ “some”: “generic data” }`	Custom parameters from tag.
Campaign Internal ID	string	mycampaign	The campaign’s identifier in Podscribe.
Podscribe Campaign ID	string	3105cc60-3970-11f1-a827-67ac2fdfebc6	Unique Podscribe campaign request ID.
Publisher ID	string	123	Podscribe publisher ID.
Product (from Campaign)	string	some-product-from-campaign	The product name from campaign.
Initiative	string	some-initiative	The initiative name.
Survey Response	string	Idk. Steve-o	The Survey Response which was matched with the Podcast name by ChatGPT
Creative id	string	creative-id	Creative ID
Product (from Event)	string	some-product-from-event	The product name from event.
Business Line	string	some-business-line	The business line name.
Show iTunes ID	string	123	The iTunes ID of the show.
Campaign & Initiative	string	Campaign / Initiative	Combined campaign and initiative label.
Prog. Publisher	string	Some publisher	Name of the Prog. Publisher from pixel. With `fieldsVersion: 2` the header is `Programmatic Publisher (from Macro)`.
Session Landing URL	string	https://example.com/session	Landing URL recorded for the converting session.
Session Referer URL	string	https://example.com/ref	Referrer URL recorded for the converting session.
Event URL	string	https://example.com/event	URL associated with the conversion event.
Genre	string	Comedy	Genre of the last show listened to. Excluded by default; request via `fields`.
Impression Zip	string	10001	ZIP code of the attributed impression. Excluded by default; request via `fields`.
Impression Region (State)	string	NY	Region/state of the attributed impression. Excluded by default; request via `fields`.
Impression City	string	New York	City of the attributed impression. Excluded by default; request via `fields`.
Ad Server	string	megaphone	Ad server that served the impression. Excluded by default; request via `fields`.
Impression Normalized User Agent	string	Chrome	Normalized user agent of the attributed impression. Excluded by default; request via `fields`.
Conversion Device	string	iPhone	Device class of the conversion. Excluded by default; request via `fields`.
Device	string	iPhone	Device class of the attributed impression. Excluded by default; request via `fields`.
Ad Position (from Ad Server)	string	preroll	Ad position from the ad server. Excluded by default; request via `fields`.
Ad Zone ID	string	zone-1	Ad zone ID from the ad server. Excluded by default; request via `fields`.
Privacy	string	LAT	Privacy signal from the impression. Excluded by default; request via `fields`.
Device (Ad Server)	string	iOS	Device reported by the ad server. Excluded by default; request via `fields`.
Prog. Supply Vendor	string	some-vendor	Programmatic supply vendor from the impression. Excluded by default; request via `fields`.
Campaign Promo	string	SALE20	Promotional code associated with the campaign. Excluded by default; request via `fields`.
IPv6 Weight	number	1	Weight applied for IPv6 impressions. Excluded by default; request via `fields`.
Campaign ID	string	some-campaign-id	Internal campaign identifier. Excluded by default; request via `fields`.
Site	string	example.com	Site associated with the impression. Excluded by default; request via `fields`.
Impression UUID	string	3105cc60-3970-11f1-a827-67ac2fdfebc6	UUID of the attributed impression. Excluded by default; request via `fields`.
IPv4	string	123.123.123.123	IPv4 address when available. Excluded by default; request via `fields`.