nodestash
Contacts

Update a contact

Partially updates a contact. Only the provided fields are changed — omitted fields remain untouched. `custom_fields` are **merged** with existing values (not replaced). If `email` is changed, uniqueness within the workspace is enforced.

PATCH
/contacts/{id}

Authorization

apiKey
AuthorizationBearer <token>

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

In: header

Path Parameters

id*string

Contact ID (prefixed with ct_).

Match^ct_

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

curl -X PATCH "https://api.nodestash.io/v1/contacts/ct_5hJ3kM9pQrVwXyZaB2cD4" \  -H "Content-Type: application/json" \  -d '{    "first_name": "Janet",    "tags": [      "vip",      "early-adopter",      "champion"    ]  }'
{
  "data": {
    "id": "ct_5hJ3kM9pQrVwXyZaB2cD4",
    "type": "contact",
    "attributes": {
      "id": "ct_5hJ3kM9pQrVwXyZaB2cD4",
      "email": "jane@acme.com",
      "first_name": "Janet",
      "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",
        "champion"
      ],
      "created_at": "2026-01-15T10:30:00Z",
      "updated_at": "2026-01-16T14:22:00Z"
    }
  }
}
{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Request validation failed",
    "details": [
      {
        "field": "email",
        "message": "Invalid email"
      }
    ]
  },
  "meta": {
    "request_id": "req_abc123def456"
  }
}
{
  "error": {
    "code": "INVALID_API_KEY",
    "message": "Missing or invalid Authorization header"
  },
  "meta": {
    "request_id": "req_abc123def456"
  }
}
{
  "error": {
    "code": "NOT_FOUND",
    "message": "Contact not found"
  },
  "meta": {
    "request_id": "req_abc123def456"
  }
}
{
  "error": {
    "code": "CONFLICT",
    "message": "A contact with email 'jane@acme.com' already exists in this workspace"
  },
  "meta": {
    "request_id": "req_abc123def456"
  }
}
{
  "error": {
    "code": "RATE_LIMITED",
    "message": "Rate limit exceeded"
  },
  "meta": {
    "request_id": "req_abc123def456"
  }
}

List contacts

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

Create a custom field definition

Creates a new custom field definition in the authenticated workspace. The `slug` is auto-generated from `name` when omitted. The combination of `entity_type` + `slug` must be unique within the workspace. For `select` and `multi_select` field types, `options` must be provided.