List custom field definitions

Returns a paginated list of custom field definitions in the authenticated workspace. Optionally filter by `entity_type`.

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 definitions to return per page.

Default"20"

entity_type?string

Filter by entity type.

Value in"contact" | "company" | "deal" | "activity"

sort?string

Comma-separated sort fields. Prefix with - for descending order. Supported fields: created_at, updated_at, name, display_order. Default: -created_at.

Response Body

`application/json`

curl -X GET "https://api.nodestash.io/v1/custom-fields?entity_type=contact&sort=-created_at"

{
  "data": [
    {
      "id": "cf_5hJ3kM9pQrVwXyZaB2cD4",
      "type": "custom_field_definition",
      "attributes": {
        "id": "cf_5hJ3kM9pQrVwXyZaB2cD4",
        "entity_type": "contact",
        "name": "Plan",
        "slug": "plan",
        "field_type": "select",
        "description": "Subscription plan of the contact",
        "is_required": false,
        "options": [
          "free",
          "starter",
          "pro",
          "enterprise"
        ],
        "display_order": 0,
        "created_at": "2026-01-15T10:30:00Z",
        "updated_at": "2026-01-15T10:30:00Z"
      }
    },
    {
      "id": "cf_9xK7mN2qTsYvAzCe4fG6",
      "type": "custom_field_definition",
      "attributes": {
        "id": "cf_9xK7mN2qTsYvAzCe4fG6",
        "entity_type": "contact",
        "name": "Region",
        "slug": "region",
        "field_type": "text",
        "description": null,
        "is_required": false,
        "options": null,
        "display_order": 1,
        "created_at": "2026-01-14T08:00:00Z",
        "updated_at": "2026-01-14T08:00:00Z"
      }
    }
  ],
  "meta": {
    "request_id": "req_abc123def456",
    "pagination": {
      "next_cursor": "eyJjcmVhdGVkX2F0IjoiMjAyNi0wMS0xNFQwODowMDowMFoiLCJpZCI6ImNmZF85eEs3bU4ycVRzWXZBekNlNGZHNiJ9",
      "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"
  }
}

List custom field definitions

Authorization

Query Parameters

Response Body

200application/json

401application/json

429application/json

`application/json`

`application/json`

`application/json`