Skip to main content
POST
Save a new query

Authorizations

Authorization
string
header
required

An API key, sent as Authorization: Bearer stfy_live_…. See Authentication for how to get one and which scopes it needs.

Path Parameters

key
string
required

The integration key, such as snowflake or salesforce

Body

application/json
name
string
required
Required string length: 1 - 200
query_type
enum<string>
required

custom_field writes field values; product_usage writes usage metrics; custom_object writes custom object records

Available options:
custom_field,
product_usage,
custom_object
sql
string
required

One SELECT, in the warehouse's own dialect. It may use {START_DATE}, {END_DATE}, {START_DATE_SQL} and {END_DATE_SQL}, which each run fills with its period's dates

Required string length: 1 - 100000
account_resolver
AccountResolverConfig · object | null

How a row finds its account. Required, except for a people query that creates no people

custom_field_mappings
CustomFieldMappingConfig · object[] | null

custom_field queries: column -> field. Each field must already exist (/v1/fields)

custom_object_config
CustomObjectConfig · object | null

custom_object queries

entity_type
enum<string>
default:account

custom_field only: write account fields, or people (contact) fields

Available options:
account,
people
expected_version
integer | null

The config version you read. Sent: a change against a version that is no longer live is a 409 and writes nothing (0 = the config was never saved). Left out, the change always lands

Required range: x >= 0
group_by_columns
string[] | null
is_active
boolean
default:true

An inactive query is kept but not run

limit
integer | null
Required range: x >= 1
order_by_columns
string[] | null
period
enum<string> | null

The window each run covers; null follows the integration's schedule (weekly by default). product_usage takes DAILY, WEEKLY or MONTHLY only

Available options:
HOURLY,
TWO_HOURS,
FOUR_HOURS,
SIX_HOURS,
TWELVE_HOURS,
DAILY,
WEEKLY,
MONTHLY
person_resolver
PersonResolverConfig · object | null

people queries: how a row finds its person

product_usage_mappings
ProductUsageMappingConfig · object[] | null

product_usage queries: column -> metric. Each metric must already exist (/v1/products)

transformers
ColumnTransformerConfig · object[] | null

Per-column value pipelines, applied after the account lookup and before writing

Response

201 - application/json

Successful Response

A saved query as stored. Its resolver, mapping and transformer objects have the same shapes a create or a change takes.

account_resolver
Account Resolver · object | null
required
custom_field_mappings
Custom Field Mappings · object[] | null
required
custom_object_config
Custom Object Config · object | null
required
entity_type
enum<string>
required
Available options:
account,
people
group_by_columns
string[] | null
required
id
string | null
required

Stable id. Null only on a query saved before ids existed: any save of the config gives it one

is_active
boolean
required
limit
integer | null
required
name
string
required
order_by_columns
string[] | null
required
period
enum<string> | null
required
Available options:
HOURLY,
TWO_HOURS,
FOUR_HOURS,
SIX_HOURS,
TWELVE_HOURS,
DAILY,
WEEKLY,
MONTHLY
person_resolver
Person Resolver · object | null
required
product_usage_mappings
Product Usage Mappings · object[] | null
required
query_type
enum<string>
required
Available options:
custom_field,
product_usage,
custom_object
sql
string
required
transformers
Transformers · object[] | null
required
version
integer
required

The config's version: send it as expected_version with a change