API Endpoint: Conversion Report | Katalys Marketing Knowledge Base

This page describes how to use the Katalys API to generate an aggregated Statistics Report to download analytics data. You use this method when you want click or behavioral information about your traffic.

URL: https://api.katalys.com/v1/report/conversions
Method: POST with a JSON payload
Authentication: Authorization header with a Katalys API key is required
Response: JSON object with keys rows containing your data

Example using cURL:

curl -H 'Authorization: Apikey YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{ "dimensions":[...], "filters":[...] }' \
  https://api.katalys.com/v1/report/conversions

If you are having issues seeing the data you expect, please refer to the API Debugging Guide.

Specification

This API method receives a JSON object with the following required objects.

dimensions: Array of strings.
String values are named columns that can be included in a report. All columns specify one additional value to include in each JSON object, returned in the rows array.
filters: Array of Filter objects.
Objects must define field, type, and values.
- Filter.field is a string specifying one of the defined available filters.
- Filter.type is “include", ”exclude”, or ”range”. The range type is typically used for filtering on time.
- Filter.values is a list of string values. Even numeric types, such as epoch times, must be passed as strings.

Every query must include a filter on the time field.

If you use TypeScript, you can validate your query using the following TypeScript interface.

TypeScript

export interface KatalysApiRequest {
  dimensions: string[];
  filters: KatalysFilter[];
}
interface KatalysFilter {
  field: string;
  type: KatalysFilterType | `${KatalysFilterType}`;
  values: string[];
}
enum KatalysFilterType {
  INCLUDE = "include",
  EXCLUDE = "exclude",
  RANGE = "range",
}

Permissions for Dimensions

A reporting API request can include Partner-only dimensions, or Advertiser-only dimensions, but not both types at once. If any report includes both Advertiser and Partner dimensions, your request will fail.

The types Partner or Advertiser come from the type of Profiles owned by your Katalys organization. If your account owns an Advertiser profile, then you can select Advertiser dimensions. If your account owns a Partner profile, then you can select Partner dimensions.

If you wish to limit the reporting to just Advertiser-scoped or Publisher-scoped dimensions, it is recommended to define the org_id filter and list the profiles you own of that type. This will ensure the expected permissions match the dimension types you are requesting.

Available Dimensions

Field	Available To	Description
`action_type`	Everyone	Advertiser-provided conversion type, such as “online-sale” or “lead”
`aff`	Everyone	Name and ID of Traffic Source
`aff_id`	Everyone	ID of traffic source assigned by the Katalys network
`aff_sub_1`	Everyone	Partner-provided field "sub1"
`aff_sub_2`	Everyone	Partner-provided field "sub2"
`aff_sub_3`	Everyone	Partner-provided field "sub3"
`aff_sub_4`	Everyone	Partner-provided field "sub4"
`aff_sub_5`	Everyone	Partner-provided field "sub5"
`aff_sub_source`	Everyone	Partner-provided field "source"
`conversion_status`	Everyone	Attribution status for Katalys network, as a number. Values are documented here.
`cost`	Advertisers Only	Total cost to drive conversions within the Katalys network
`offer`	Everyone	Name and ID of program
`offer_id`	Everyone	ID of program assigned by the Katalys network
`order_id`	Everyone	Order ID as reported by Advertiser.
`order_time`	Everyone	Time the order was placed as an epoch-millisecond timestamp.
`payout`	Partners Only	The sum owed to Partners as compensation
`product_sku`	Everyone	The SKU-list associated with the conversion, separated by a comma and space, e.g. `", "`. Product details are sometimes `null` because a Program does not require this information to manage payouts.
`product_name`	Everyone	The product name-list associated with the conversion, separated by a comma and space, e.g. `", "`. Product details are sometimes `null` because a Program does not require this information to manage payouts.
`product_category`	Everyone	The product category-list associated with the conversion, separated by a comma and space, e.g. `", "`. Product details are sometimes `null` because a Program does not require this information to manage payouts.
`sale_amount`	Everyone	The derived value of the order, as calculated as Topline Sales amount, minus tax and shipping.
`seq`	Everyone	Recommended This is a unique ID created per conversion within the Katalys system, guaranteed to be unique inside of Katalys.
`transaction_id`	Everyone	A non-unique ID that is used for short-term attribution to a user event, like a click, used to look up session info when a conversion happens, but not for events like coupon or direct link tracking. Can assist partners with downstream performance tracking.

Available Filters

Field	Valid Types	Description
`time`	`range`	Required for all API calls. Limits your report query to the epoch times specified in the range. See Working with Timestamps to understand how to pass values and match the KMP reporting portal. Example: `{ "field":"time", "type":"range", "values":["1740457060","1740457900"] }`
`status`	`include` or `exclude`	(Recommended) Limits your report query to include only valid conversions. This will skip rejected conversions and conversions that were processed by Katalys but were not attributed to a Katalys affiliate. Acceptable values are numbers-as-strings, documented on Conversion Statuses. Example: `{ "field":"status", "type":"include", "values":["1"] }`
`org_id`	`include`	Limits your results to the specified Profiles. Your Profile’s org_id value can be found in the URL of your KMP account. Example: The URL `https://app.katalys.com/adv/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/dashboard` contains an Advertiser-type Profile ID. When extracted from the URL, it can be used in the `org_id` filter like this: `{ "field":"org_id", "type":"include", "values":["xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"] }`
`aff_id`	`include` or `exclude`	Limits your results to include or exclude the given Traffic Source IDs. Example: `{ "field":"aff_id", "type":"include", "values":["1234"] }`
`offer_id`	`include` or `exclude`	Limits your results to include or exclude the given Program IDs. Example: `{ "field":"offer_id", "type":"include", "values":["1234"] }`