Hillwinds API
Get access
API Reference

Tags

Tag entities for your team's workflow.

Tags are scoped to the authenticated API user
Tag filters and tag management use the user linked to the API key. Reads require tags:read; writes require tags:write. Sandbox/test keys cannot create or delete tags.
Body field aliases
Write endpoints accept either entity_type (canonical, per the OpenAPI spec) or resource (alias). Responses always return entity_type. Examples on this page use entity_type; either works.

Body schema (write endpoints)

POST /v1/tags, DELETE /v1/tags, and POST /v1/tags/bulk share the same body fields:

ParameterTypeDescription
entity_idrequiredstringID of the entity to tag. For bulk, use entity_ids (array) instead.
entity_idsstring[]Bulk endpoint only. Up to 100 entities per call.
entity_typerequiredstringOne of: companies, personnel, broker-offices, brokers. Alias: resource.
tagrequiredstringTag name. Free-text; normalized on write and filter (leading # stripped, casing folded).

List Tags

GET/v1/tags0 credits

Returns tag names for the authenticated API user, optionally filtered by entity type or tag name. One entity can hold many tags.

ParameterTypeDescription
tagstringFilter to one tag name. Normalized the same way as writes (leading # stripped, casing folded).
entity_typestringFilter to one entity type. Alias: resource.
resourcestringAlias of entity_type.
pageintegerZero-indexed page.
page_sizeintegerDefault 25, max 500.
bash
curl -H "Authorization: Bearer ss_live_..." \
  "https://api.hillwinds.ai/v1/tags?entity_type=companies&page_size=3"
json
{
  "ok": true,
  "data": [
    {
      "entity_id": "452990868",
      "entity_type": "companies",
      "tag": "q2-2026-outreach",
      "tag_id": "cde98e19-fbb6-40f1-adf9-225d3dcd9f06"
    },
    {
      "entity_id": "71038294",
      "entity_type": "companies",
      "tag": "renewals",
      "tag_id": "afb60fb8-b651-4afa-89c2-4d133fae264d"
    }
  ],
  "meta": {
    "total_count": 5,
    "page": 0,
    "page_size": 3,
    "returned": 2,
    "has_more": true,
    "credits_charged": 0
  }
}

List Tags for One Entity

GET/v1/{resource}/{id}/tags0 credits

Returns the authenticated API user's tags for one entity. Supported resources are companies, personnel, broker-offices, and brokers.

bash
curl -H "Authorization: Bearer ss_live_..." \
  "https://api.hillwinds.ai/v1/companies/452990868/tags"

Add Tag

POST/v1/tags0 credits

Add a single tag to a single entity. Idempotent — re-tagging is a no-op.

bash
curl -X POST -H "Authorization: Bearer ss_live_..." \
  -H "Content-Type: application/json" \
  -d '{"entity_type": "companies", "entity_id": "84629153", "tag": "q2-2026-outreach"}' \
  "https://api.hillwinds.ai/v1/tags"
json
{
  "ok": true,
  "data": {
    "id": "d9118921-fcf7-4e85-8f96-4473763884ff",
    "entity_id": "84629153",
    "entity_type": "companies",
    "tag": "q2-2026-outreach",
    "created_at": "2026-06-10T02:06:37.015041+00:00",
    "user_id": null
  },
  "meta": { "credits_charged": 0 }
}

Remove Tag

DELETE/v1/tags0 credits

Removes a (entity, tag) pair. Body matches POST /v1/tags. There is also a by-id form: DELETE /v1/tags/{id} takes the tag record UUID in the path — useful when you already have the id from a list call.

bash
curl -X DELETE -H "Authorization: Bearer ss_live_..." \
  -H "Content-Type: application/json" \
  -d '{"entity_type": "companies", "entity_id": "84629153", "tag": "q2-2026-outreach"}' \
  "https://api.hillwinds.ai/v1/tags"

Bulk Tag

POST/v1/tags/bulk0 credits

Apply a single tag to up to 100 entities in one request. Idempotent per entity.

bash
curl -X POST -H "Authorization: Bearer ss_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "entity_type": "companies",
    "entity_ids": ["84629153", "71038294", "452990868"],
    "tag": "q2-2026-outreach"
  }' \
  "https://api.hillwinds.ai/v1/tags/bulk"
json
{
  "ok": true,
  "data": {
    "created": 3,
    "matched": 3,
    "tags": [
      {
        "id": "33c77e89-c2cd-46d7-951d-fd5d1277e9a0",
        "entity_id": "84629153",
        "entity_type": "companies",
        "tag": "q2-2026-outreach",
        "created_at": "2026-06-10T02:41:52.769579+00:00"
      }
      /* ... one entry per entity_id ... */
    ]
  },
  "meta": { "credits_charged": 0 }
}

created counts newly inserted tag rows; matched counts every entity the call touched (including ones that were already tagged).

List Entities for a Tag

GET/v1/tags/entities0 credits

The read-side counterpart to POST /v1/tags/bulk: fetch every entity that shares a tag. Look up by either tag (name) or tag_id (UUID).

To go the other way — every tag on one entity — use the per-entity read GET /v1/personnel/:id/tags. Contacts also expose their tags inline as the tags field on GET /v1/personnel/:id?mode=full.

Per-entity tag reads are personnel-only
GET /v1/personnel/:id/tags is the only per-entity tag read endpoint today. Companies, broker offices, and brokers do not expose /:id/tags routes; use GET /v1/tags or GET /v1/tags/entities with entity_type filters instead.
ParameterTypeDescription
tagstringTag name. Provide tag or tag_id.
tag_idstringTag record UUID. Provide tag or tag_id.
entity_typestringRestrict to one entity type. Alias: resource.
pageintegerZero-indexed page.
page_sizeintegerDefault 25, max 500.
bash
curl -H "Authorization: Bearer ss_live_..." \
  "https://api.hillwinds.ai/v1/tags/entities?tag=q2-2026-outreach&entity_type=companies"
json
{
  "ok": true,
  "data": [
    {
      "id": "d9118921-fcf7-4e85-8f96-4473763884ff",
      "entity_id": "84629153",
      "entity_type": "companies",
      "tag": "q2-2026-outreach",
      "created_at": "2026-06-10T02:06:37.015041+00:00"
    }
  ],
  "meta": {
    "total_count": 1,
    "page": 0,
    "page_size": 25,
    "returned": 1,
    "has_more": false,
    "credits_charged": 0
  }
}
PreviousFilter OptionsNext Dynamic Tags
Need a key?

Keys are issued by our team, not a signup form. Book a 25-minute walkthrough and you'll leave with sandbox and live credentials.

Get accessExplore the platform