List contacts

Returns a paginated list of contacts in the authenticated workspace. Supports cursor-based pagination, filtering by multiple fields, and configurable sorting.

Authorization

apiKey

AuthorizationBearer <token>

API key from your nodestash dashboard. Pass as a Bearer token in the Authorization header.

In: header

Query Parameters

cursor?string

Opaque pagination cursor returned as next_cursor in a previous response. Pass this to fetch the next page.

limit?string

Maximum number of contacts to return per page.

Default"20"

email?string

Filter by email address (case-insensitive substring match).

first_name?string

Filter by first name (case-insensitive substring match).

last_name?string

Filter by last name (case-insensitive substring match).

company_id?string

Filter by company ID (exact match).

Match^co_

source?string

Filter by source (exact match).

tags?string

Filter by tags (comma-separated). Contacts must contain all specified tags.

sort?string

Comma-separated sort fields. Prefix with - for descending order. Supported fields: created_at, updated_at, email, first_name, last_name. Default: -created_at.

Response Body

`application/json`

curl -X GET "https://api.nodestash.io/v1/contacts?email=jane%40acme&first_name=Jane&last_name=Doe&company_id=co_xyz789&source=website&tags=vip%2Cearly-adopter&sort=-created_at"

{
  "data": [
    {
      "id": "ct_5hJ3kM9pQrVwXyZaB2cD4",
      "type": "contact",
      "attributes": {
        "id": "ct_5hJ3kM9pQrVwXyZaB2cD4",
        "email": "jane@acme.com",
        "first_name": "Jane",
        "last_name": "Doe",
        "phone": "+1-555-0100",
        "company_id": "co_xyz789",
        "title": "VP of Engineering",
        "source": "website",
        "custom_fields": {
          "plan": "enterprise"
        },
        "tags": [
          "vip",
          "early-adopter"
        ],
        "created_at": "2026-01-15T10:30:00Z",
        "updated_at": "2026-01-15T10:30:00Z"
      }
    },
    {
      "id": "ct_9xK7mN2qTsYvAzCe4fG6",
      "type": "contact",
      "attributes": {
        "id": "ct_9xK7mN2qTsYvAzCe4fG6",
        "email": "john@example.com",
        "first_name": "John",
        "last_name": "Smith",
        "phone": null,
        "company_id": null,
        "title": "Engineer",
        "source": "api",
        "custom_fields": {},
        "tags": [
          "lead"
        ],
        "created_at": "2026-01-14T08:00:00Z",
        "updated_at": "2026-01-14T08:00:00Z"
      }
    }
  ],
  "meta": {
    "request_id": "req_abc123def456",
    "pagination": {
      "next_cursor": "eyJjcmVhdGVkX2F0IjoiMjAyNi0wMS0xNFQwODowMDowMFoiLCJpZCI6ImN0Xzl4SzdtTjJxVHNZdkF6Q2U0Zkc2In0",
      "has_more": true
    }
  }
}

{
  "error": {
    "code": "INVALID_API_KEY",
    "message": "Missing or invalid Authorization header"
  },
  "meta": {
    "request_id": "req_abc123def456"
  }
}

{
  "error": {
    "code": "RATE_LIMITED",
    "message": "Rate limit exceeded"
  },
  "meta": {
    "request_id": "req_abc123def456"
  }
}

Authorization

Query Parameters

Response Body

200application/json

401application/json

429application/json

`application/json`

`application/json`

`application/json`