API Endpoint: Conversion Report

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:

CODE

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

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	Permissions	Description
`seq`	All types	This is a unique ID created per conversion within the Katalys system guaranteed to be unique inside of Katalys.
`order_time`	All types	Time the order was placed.
`order_id`	All types	Order ID as reported by Advertiser.
`sale_amount`	All types	The derived value of the order, as calculated as Topline Sales amount, minus tax and shipping.
`conversion_status`	All types	Attribution status for Katalys network
`aff`	All types	Name and ID of Traffic Source
`aff_id`	All types	ID of traffic source assigned by the Katalys network
`offer`	All types	Name and ID of program
`offer_id`	All types	ID of program assigned by the Katalys network
`transaction_id`	All types	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.
`cost`	Advertisers Only	Total cost to drive conversions within the Katalys network
`payout`	Partners Only	The sum owed to Partners as compensation
`aff_sub_1`	Partners Only	Partner-provided field "sub1"
`aff_sub_2`	Partners Only	Partner-provided field "sub2"
`aff_sub_3`	Partners Only	Partner-provided field "sub3"
`aff_sub_4`	Partners Only	Partner-provided field "sub4"
`aff_sub_5`	Partners Only	Partner-provided field "sub5"
`aff_sub_source`	Partners Only	Partner-provided field "source"

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.

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.

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