Raw Attributed Conversions

POST

/api/public/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","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"],"fieldsVersion":1,"fieldsMapping":{"Purchased At":"converted_at","Discount code":"promo_code"},"name":"example","startDate":"2026-04-15","endDate":"2026-04-15","advertiser":"example","withVisitors":true,"attributionModel":"first","excludeReferrers":["example"],"excludeUtmMediums":["example"],"excludeUtmSources":["example"],"excludePriorCustomers":false,"excludePriorVisitors":false,"timeRangeConv":false,"timeRangeConvWithWindow":false,"attributionWindow":1,"attributionStreamingWindow":1,"attributionSaiWindow":1,"attributionPreset":"any","excludePromos":true,"excludeSurveys":true,"excludeTime":true,"events":["example"]}'
};

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

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", "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" ], "fieldsVersion": 1, "fieldsMapping": { "Purchased At": "converted_at", "Discount code": "promo_code" }, "name": "example", "startDate": "2026-04-15", "endDate": "2026-04-15", "advertiser": "example", "withVisitors": true, "attributionModel": "first", "excludeReferrers": [ "example" ], "excludeUtmMediums": [ "example" ], "excludeUtmSources": [ "example" ], "excludePriorCustomers": false, "excludePriorVisitors": false, "timeRangeConv": false, "timeRangeConvWithWindow": false, "attributionWindow": 1, "attributionStreamingWindow": 1, "attributionSaiWindow": 1, "attributionPreset": "any", "excludePromos": true, "excludeSurveys": true, "excludeTime": true, "events": [ "example" ] }'

This endpoint utilizes a task system.

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

Result file format:

Field	Type	Example	Description
Advertiser	string	demoAdvertiser
Purchased At	string	2023-12-23 9:58 AM	Date and time of purchase in the format YYYY-mm-DD HH:MM tt
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.
Publisher	string	Some Publisher	Name of the publisher.
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	123	Currency used for the transaction.
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/User 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	{“some”: “generic data”}	Custom parameters from tag.
Campaign Internal ID	string	mycampaign	Podscribe campaign lookup_name.
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.
Prog. Publisher	string	Some publisher	Name of the Prog. Publisher from pixel. With `fieldsVersion: 2` the header is `Programmatic Publisher (from Macro)`.
IPv4	string	123.123.123.123	IPv4 address when available.

Authorizations

BearerAuth

Request Body

application/json

object

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<string>

default: 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,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

Allowed values: 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

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 (currently applied by default): 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)

integer

default: 1

Allowed values: 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.

object

key

additional properties

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 characters

startDate

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

string format: date

endDate

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

string format: date

advertiser

required

Advertiser name. This field is required.

string

withVisitors

If true, the results file will also contain visitors. Default is false.

boolean

attributionModel

Attribution model. Default is multi_timedecay.

string

Allowed values: first last multi_linear multi_timedecay

excludeReferrers

Referrers to exclude. Default: [“email”, “facebook”, “tiktok”, “instagram”, “twitter”].

Array<string>

excludeUtmMediums

UTM mediums to exclude. Default: [“email”, “facebook”, “fb”, “tiktok”, “sms”, “social”, “klaviyo”, “youtube”, “instagram”, “ig”].

Array<string>

excludeUtmSources

UTM sources to exclude. Default: [“email”, “facebook”, “fb”, “tiktok”, “twitter”, “klaviyo”, “youtube”, “instagram”, “ig”].

Array<string>

excludePriorCustomers

If true, the results will exclude prior customers.

boolean

excludePriorVisitors

If true, the results will exclude prior visitors.

boolean

timeRangeConv

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

boolean

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

attributionWindow

Days between converted_at and touched_at. Default is 30.

number

attributionStreamingWindow

Days between converted_at and touched_at for streaming. Default is 14.

number

attributionSaiWindow

Days between converted_at and touched_at for SAI. Default is 14.

number

attributionPreset

Device-graph attribution preset, matching the Device Graph Usage control in the UI. Omitted: the default preset is resolved from the first entry in advertisers. Most advertisers default to any; a small number are configured differently. Expands into the internal device-graph filters, including any advertiser-specific model version.

string

default: any

Allowed values: any all none

excludePromos

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

boolean

excludeSurveys

If true, the results will exclude survey purchases. Default is false.

boolean

excludeTime

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

boolean

events

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

Array<string>

Responses

200

application/json

object

string

status

string

url

string

Example^generated

{
  "id": "example",
  "status": "example",
  "url": "example"
}

400

Invalid data

500

Unexpected error.

application/json

object

message

Nodejs Error

object

Example^generated

{
  "message": {}
}

Raw Attributed Conversions

Authorizations

Request Body

Example

Responses

200

Examplegenerated

400

500

Examplegenerated

Example^generated

Example^generated