GET /v1/organizations

Lists the organization structure your token can read. ShipDiff has one canonical, effective-dated graph spanning organizations, material legal entities, business units, brands, product families and products. This route returns its non-product nodes; use /v1/products for products.

curl -H "Authorization: Bearer YOUR_TOKEN" \
  "https://api.docsignal.app/v1/organizations?as_of=2026-07-31"

as_of is an optional YYYY-MM-DD. It defaults to today. Results and relationships are those effective on that date.

Collection filters are geography_type, country_code, subdivision_code, locality and region_name. geography_type is required whenever a place filter is supplied. Geography matches only attributes explicitly attached to the returned node; it never inherits through the graph.

{
  "organizations": [
    {
      "id": "ogn_01ARZ3NDEKTSV4RRFFQ69G5FAV",
      "type": "organization",
      "name": "Acme",
      "domains": ["acme.example"],
      "parent_id": null,
      "relationship": null,
      "active_from": "2020-01-01",
      "active_to": null,
      "geography": [
        {
          "id": "oga_01ARZ3NDEKTSV4RRFFQ69G5FAW",
          "type": "headquarters",
          "country_code": "US",
          "subdivision_code": "US-CA",
          "locality": "San Francisco",
          "region_name": null,
          "effective_from": "2024-01-01",
          "effective_to": null,
          "evidence": []
        }
      ]
    }
  ],
  "query": {
    "as_of": "2026-07-31"
  }
}

Node types are organization, legal_entity, business_unit, brand and product_family. IDs are opaque and stable across renames, domain changes, reparenting and mergers. Names and domains are effective-dated aliases. Active, directly attributed geography is embedded at the requested as_of. Its evidence records are included with each geographic attribute.

GET /v1/organizations/:id

Returns one node, its aliases, current parent relationship and children at the requested as_of date.

curl -H "Authorization: Bearer YOUR_TOKEN" \
  "https://api.docsignal.app/v1/organizations/ogn_01ARZ3NDEKTSV4RRFFQ69G5FAV?as_of=2026-07-31"

The graph records customer-relevant operating structure and material, publicly evidenced legal ownership. It is not a list of every shell company. Each assertion is evidence-backed; a node missing from a newer page is not treated as removed without affirmative evidence.

Geography is normally an attribute. A named regional legal entity or business unit becomes a node only when it changes ownership, control, reporting, leadership or product responsibility. Country, region and office nodes do not exist.

Compatibility

These routes are additive. /v1/companies, domain aliases and domain-based /v1/events filters continue unchanged.