List Contacts

Lists the host's contacts, sorted and filtered. Paginated.

Authorization

AuthorizationRequiredBearer <token>

API key as Bearer token

In: header

Query Parameters

pageNumberinteger

Page number (0-based)

Default: 0Minimum: 0Maximum: 9007199254740991

pageSizeinteger

Items per page (default 20, max 500)

Default: 20Minimum: 1Maximum: 500

sortFieldAny properties in string,string

Field to sort by. Index-backed (fast) values: mostRecentOrder, orderSum, grossSum. Other enum values + 24-char hex custom- property ids are accepted and sorted in-memory by the database — fine at per-page volumes but avoid on large hosts. Defaults to mostRecentOrder desc.

sortDirectionstring

Sort direction. Defaults to desc when sortField is provided.

Value in: "asc" | "desc"

filterstring

Quick status filter; case-insensitive. "all" or omit for no filter. ANDed with filters when both supplied.

Value in: "all" | "opted-in" | "unknown" | "unsubscribed" | "imported"

filtersstring

JSON-encoded array of filter groups for advanced filtering. Each group has "logic" ("and" | "or") and "conditions" (array of conditions or nested groups). Each condition has "field", "operator", and optional "value". Operators by type:

Text: is_equal_to_any_of, is_not_equal_to_any_of, contains, contains_exactly
Date: is_before, is_after, is_between (value: {start, end})
Number: is_equal_to, is_not_equal_to, is_greater_than, is_greater_than_or_equal_to, is_less_than, is_less_than_or_equal_to, is_between
Select: is_any_of, is_none_of
Common: is_empty, is_not_empty Conditions referencing fields outside the persisted contact schema are silently ignored. Example: [{"logic":"and","conditions":[{"field":"status","operator":"is_any_of","value":["opted-in"]},{"field":"grossSum","operator":"is_greater_than","value":1000}]}]

searchstring

Free-text search over email, firstName, lastName, fullName

GET/v1/contacts/

curl -X GET "https://api.3common.com/v1/contacts/?sortField=mostRecentOrder&sortDirection=asc&filter=all&filters=string&search=string" \
  -H "Authorization: Bearer <token>"

Default Response

Response

{
  "data": [
    {
      "id": "string",
      "firstName": "string",
      "lastName": "string",
      "fullName": "string",
      "email": "string",
      "phone": "string",
      "vendorId": "string",
      "orderSum": 0,
      "grossSum": 0,
      "firstOrder": 0,
      "lastOrder": 0,
      "createdAt": "2019-08-24T14:15:22Z",
      "status": "unsubscribed",
      "eventsAttended_IDS": [
        "string"
      ],
      "itemsPurchased_IDS": [
        "string"
      ],
      "productsPurchased_IDS": [
        "string"
      ],
      "property1": null,
      "property2": null
    }
  ],
  "hasMore": true,
  "pageNumber": -9007199254740991,
  "pageSize": -9007199254740991
}

TypeScript

export interface Response {
  data: {
    id: string;
    firstName: string;
    lastName: string;
    fullName: string;
    email: string;
    phone?: string;
    vendorId: string;
    orderSum: number;
    grossSum: number;
    /**
     * First order, ms since epoch
     */
    firstOrder?: number;
    /**
     * Most recent order, ms since epoch
     */
    lastOrder?: number;
    createdAt?: string;
    /**
     * Subset of statuses surfaced on the compact contact projection.
     */
    status: "unsubscribed" | "opted-in" | "unknown";
    eventsAttended_IDS: string[];
    itemsPurchased_IDS: string[];
    productsPurchased_IDS: string[];
    [k: string]: unknown;
  }[];
  hasMore: boolean;
  pageNumber: number;
  pageSize: number;
}