SQsquarespace
Contacts

Query contacts

Returns a paginated list of contacts matching filters and sort options in the request body. Requires OAuth website scope website.contacts.read or website.contacts, or API key scope CONTACT_READONLY or CONTACT, or OAuth website scope website.profiles.read or website.profiles (OAuth only).

post/v1/contacts/query

Request

Headers

Authorizationstring required

API key or OAuth access token

User-Agentstring required

User Agent

Request body

cursorstring

The cursor for the next page of results. Use the value of pagination.nextPageCursor from the previous response.

pageSizeinteger

The number of contacts to return per request.

searchStringstring

Search string for Name and Email address

sortDirection'ASCENDING' | 'DESCENDING'

Direction to sort results, ASCENDING or DESCENDING

sortField'ID' | 'CREATED_ON' | 'EMAIL' | 'ACCEPTS_MARKETING_JOINED_ON' | 'FIRST_NAME' | 'LAST_NAME' | 'ORDER_COUNT' | 'LAST_ORDER_ON' | 'ORDER_AMOUNT' | 'DONATION_COUNT' | 'LAST_DONATION_ON' | 'DONATION_AMOUNT'

Field to sort results by

Example request

{
  "acceptsMarketingWithDate": {
    "acceptsMarketing": true,
    "joinedOn": {
      "before": "2025-11-21T10:00:00Z",
      "after": "2020-11-26T14:30:00Z"
    }
  },
  "searchString": "jane",
  "firstOrderOn": {
    "before": "2025-11-21T10:00:00Z",
    "after": "2025-11-26T14:30:00Z"
  },
  "lastOrderOn": {
    "before": "2025-11-21T10:00:00Z",
    "after": "2025-11-26T14:30:00Z"
  },
  "orderCount": {
    "min": 1,
    "max": 10
  },
  "firstDonationOn": {
    "before": "2025-11-21T10:00:00Z",
    "after": "2025-11-26T14:30:00Z"
  },
  "lastDonationOn": {
    "before": "2025-11-21T10:00:00Z",
    "after": "2025-11-26T14:30:00Z"
  },
  "donationCount": {
    "min": 1,
    "max": 10
  },
  "pageSize": 50,
  "cursor": "abc",
  "sortField": "createdOn",
  "sortDirection": "ASCENDING"
}

Response

A paginated list of contacts matching the query.

Example response

{
  "contacts": [
    {
      "defaultShippingAddress": {
        "address": {
          "city": "Springfield",
          "countryCode": "US",
          "firstName": "John",
          "lastName": "Doe",
          "line1": "100 Main St",
          "line2": "Apt 1A",
          "phoneNumber": "215-555-4321",
          "postalCode": "10900",
          "region": "IL"
        },
        "id": "5f8d0d55b54764421b7156aa"
      },
      "id": "64a7e3d2c8f1b95e30a14d2b",
      "locale": "en-US",
      "primaryEmail": {
        "email": "jane.doe@example.com"
      }
    }
  ],
  "pagination": {
    "hasNextPage": true,
    "nextPageCursor": "ewogICJhIiA6ICI2OWNhOWExZjgxNGMwYTY0MmIwMTIzYzkiLAogICJiIiA6ICJJRCIKfQ",
    "nextPageUrl": "/v1/contacts?cursor=ewogICJhIiA6ICI2OWNhOWExZjgxNGMwYTY0MmIwMTIzYzkiLAogICJiIiA6ICJJRCIKfQ"
  }
}

Changes

No recorded changes to this operation across all 1 revision of this API.