Saasco logoSaasco logo
Saasco logoSaasco logo

Introduction

OverviewGetting startedWhat is Saasco?

SDK

Quick startTrackingIdentifyConfigurationWidgetsProperties

MCP

Quick startHow it worksAuthorizationTool reference

REST API

Quick start
Set up CRMLoad an audience
postList ContactsgetGet ContactgetGet By EmailgetList RelatedpostUpsert ContactpatchUpdate ContactdelDelete ContactpostGet PropertiespostCount SubscribedpostMigrate Distinct Id
CRMContacts

List Contacts

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

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 filters combined with 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 filters evaluated over the last 24 hours only.

eventNamerequiredstring

Analytics event name.

operatorrequiredstring

Whether the contact performed the event in the last 24 hours.

Value in: "performed" | "notPerformed"
groupTyperequiredstring

How filters in this group are combined.

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

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

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://www.saasco.com/api/v2/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
  }
}
{
  "code": "BAD_REQUEST",
  "message": "Invalid input data",
  "issues": []
}
{
  "code": "UNAUTHORIZED",
  "message": "Authorization not provided",
  "issues": []
}
{
  "code": "FORBIDDEN",
  "message": "Insufficient access",
  "issues": []
}
{
  "code": "INTERNAL_SERVER_ERROR",
  "message": "Internal server error",
  "issues": []
}

Load an audience

What an agent needs to upsert real contacts and create lists through the MCP.

Get Contact

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