Saasco logoSaasco logo
Saasco logoSaasco logo

Introduction

Quick StartWhat is Saasco?

Analytics

CRM

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

Email Marketing

Knowledge

Support

Projects

Contacts

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.

contactIdsarray<string>

Restrict the result to these contact IDs.

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

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.