Saasco logoSaasco logo
Saasco logoSaasco logo

Introduction

OverviewGetting startedAgent setupWhat is Saasco?

SDK

Quick startTrackingIdentifyConfigurationWidgetsProperties

MCP

Quick startHow it worksAuthorizationTool reference
Skills for agents

REST API

Quick start
postList ContactsgetGet ContactgetGet By EmailgetList RelatedpostUpsert ContactpatchUpdate ContactdelDelete ContactpostGet PropertiespostCount SubscribedpostMigrate Distinct Id
CRMContacts

List Contacts

View as MarkdownAgent setup

Queries contacts with attribute and event filters, returning a page of contacts plus the total count matching the filter. A POST because the filter structure is too rich for a query string. This is the endpoint behind audience building. The same filter shape defines a dynamic contact list or a campaign audience.

POST
/projects/{projectId}/crm/contacts/query

Authorization

Authorization
AuthorizationBearer <token>

In: header

Path Parameters

projectIdrequiredstring

ID of the project to list contacts from.

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

attributesarray<string>

Property names to include on each contact. Omit for the default set. Narrowing this is the main lever for making large queries cheaper.

responseAttributesarray<string>

After Tinybird returns, keep only these property keys on the wire. Does not change the Tinybird SQL. The All Contacts table uses this so first paint is not the full identify map.

contactIdsarray<string>

Restrict the result to these contact IDs.

includeCountboolean

When false, skip the Tinybird uniqExact count and return the page length. Use a follow-up take:0 request for the exact total.

Default: true
contactsFilterGroupobject

Attribute and event conditions the contact must satisfy. Omit to match every contact in the project.

filtersrequiredarray<object>

Attribute conditions, combined with oneDayEventFilters by groupType.

attributeDistinctIdrequiredstring

Contact attribute distinct id to filter on.

attributeTypestring

Attribute type. Defaults to string when omitted.

Default: "string"Value in: "string" | "number" | "boolean" | "date" | "url" | "email"
operatorrequiredstring

Comparison operator for the attribute value.

Value in: "equals" | "contains" | "notEquals" | "notContains" | "gt" | "gte" | "lt" | "lte" | "on" | "since" | "before" | "between" | "last"
valuerequiredstring

Value to compare the attribute against.

oneDayEventFiltersarray<object>

Event conditions over a rolling 24 hour window (not configurable). Each one is a condition in the group alongside filters, so AND, OR, and NOT apply to both. Used the same way by CRM lists, campaign audiences, workflow entry filters, and Audience Filter steps.

eventNamerequiredstring

Analytics event name from analytics_queryEvents with groupBy action, or Sent email, Delivered email, Opened email, Clicked email, Bounced email, Complained email, or Suppressed email. Those seven read email activity for the same 24 hour window, not analytics.

operatorrequiredstring

performed: the contact has at least one event with this name in the last 24 hours. notPerformed: a contact in the project with no such event in the last 24 hours, including contacts with no events at all.

Value in: "performed" | "notPerformed"
groupTyperequiredstring

How the conditions in filters and oneDayEventFilters combine: AND all true, OR any true, NOT none true.

Value in: "AND" | "OR" | "NOT"
requireSubscribedboolean

When true, the group is ANDed with $subscribed == true. Set by email sending, not the filter UI.

requireUnvalidatedEmailboolean

When true, the group is ANDed with $emailValidated != true. Set by email validation, not the filter UI. The user's AND, OR, and NOT are unchanged.

orderBystring

Contact property to sort by, e.g. $lastSeen or email.

orderDirectionstring

Sort direction. Ignored unless orderBy is set.

Value in: "asc" | "desc"
skipnumber

Number of contacts to skip before collecting results. Deep offsets get progressively slower, so prefer narrowing the filter over paging far into a large audience.

Default: 0
takenumber

Maximum number of contacts to return.

Default: 24

Response Body

application/json

application/json

application/json

application/json

application/json

curl -X POST "https://example.com/projects/string/crm/contacts/query" \  -H "Content-Type: application/json" \  -d '{}'
{  "count": 0,  "data": [    {      "id": "string",      "createdAt": "string",      "updatedAt": "string",      "projectId": "string",      "distinctId": "string",      "email": "string",      "toDelete": true,      "properties": {        "age": 0,        "avatar": "http://example.com",        "birthday": "string",        "createdAt": "string",        "description": "string",        "displayName": "string",        "email": "user@example.com",        "firstName": "string",        "gender": "string",        "id": "string",        "lastName": "string",        "name": "string",        "phone": "string",        "title": "string",        "username": "string",        "website": "string",        "$id": "string",        "$lastSeen": "string",        "$lastIdentifiedAt": "string",        "$processedAt": "string",        "$unsubscribed": true,        "$subscribed": true,        "$unsubscribeReason": "manual",        "$unsubscribeSource": "string",        "$emailValidated": true,        "$lastEmailValidatedAt": "string",        "$emailValidationResult": "string",        "$emailScore": 0,        "$stripeCustomerId": "string",        "$os": "string",        "$browser": "string",        "$browserVersion": "string",        "$screenHeight": 0,        "$screenWidth": 0,        "$screenDpi": 0,        "$device": "string",        "$userAgent": "string",        "$ip": "string",        "$timezone": "string",        "$city": "string",        "$country": "string",        "$countryCode": "string",        "$continent": "string",        "$region": "string",        "$locale": "string",        "$latitude": 0,        "$longitude": 0,        "$referrer": "string",        "$referringDomain": "string",        "$initialReferrer": "string",        "$initialReferringDomain": "string",        "$utmSource": "string",        "$utmMedium": "string",        "$utmCampaign": "string",        "$utmTerm": "string",        "$utmContent": "string",        "$initialUtmSource": "string",        "$initialUtmMedium": "string",        "$initialUtmCampaign": "string",        "$initialUtmTerm": "string",        "$initialUtmContent": "string",        "$_toDelete": true,        "$_emailScoreActions": "string",        "property1": "string",        "property2": "string"      }    }  ],  "usage": {    "cost": 0,    "duration": 0,    "metricCount": 0  }}

Get Usage

Returns metered spend for the project over a date window, broken down by day, app, and upstream service. This is the cost side of the ledger. See Get Balance Transactions for how that spend drew down the credit balance.

Get Contact

Fetches a single contact by distinct ID, including its merged property bag. Returns 404 if no contact matches.