Standard holders page

Produced by POST /api/v2/bulk/standards/holders/search; the task reports "requestType": "BulkGetStandardHolders". One file per page of companies — by default a single page holds up to 100,000 companies, so most results arrive as one file — each a complete document; see Result files for how pages are delivered and the conventions they share. The certified companies workflow shows how to build a badge from it.

Each company row carries the company id, its held standards, and the custom properties the request named in customPropertyIds — your own identifier for the company among them, which is what joins this export to your records without a second search. Names, websites and addresses come from the companies page, joined on id.

Top level

Field	Type	Notes
standards	StandardCatalogEntry[]	The standards referenced by this page's holdings.
validators	ValidatorCatalogEntry[]	{ id, name } for the validators referenced by this page's holdings. Absent when no holding carries a validation.
customProperties	CustomProperty[]	{ id, name } for the requested properties that at least one company in the export holds a value for. Drawn from the whole export and identical on every page, so every key in this page's companies[].fields resolves here — and the catalog may also name a property only another page's companies hold. Absent when the request asked for no custom properties.
companies	StandardHolderCompany[]	The page's companies.

StandardCatalogEntry

Field	Type	Notes
id	uuid	What heldStandards[].standardId points to. The same id the standards search and the request's searchBy.certifications use.
name	string
levels	Level[]	{ id, name, level } — the standard's levels, level being its 1-based rank. Absent for standards without levels.

StandardHolderCompany

Field	Type	Notes
id	uuid	The company id the rest of the API uses.
fields	object	Keyed by custom-property id, each value a string[] of that property's values for the company. Holds only the ids the request listed in customPropertyIds; absent when none apply.
heldStandards	HeldStandard[]	One entry per standard the company holds.

HeldStandard

Field	Type	Notes
standardId	uuid	Resolves in the page's standards.
standardHolderId	uuid	The id of this holding itself — stable across re-runs, distinct from the standard and the company.
startDateUtc	date-time	Start of the current issued period. Absent when not set.
endDateUtc	date-time	End of the current issued period. Absent when not set.
levelId	uuid	Resolves in the standard's levels. Absent when the standard has no levels or none was issued.
firstIssuedYear	integer	The year the company first obtained the standard. Absent when unknown.
certificationStatus	"Certified" or "NotCertified"	Certified means the holding has a valid validation from an external validator and a currently active issued period with an expiry date. Anything else is NotCertified.
applicationStatus	"InProgress" or "NotInProgress"	Whether the company has an active application — initial or re-certification — for this standard. Absent when not known.
validations	Validation[]	{ validatorId, validationState } — who validated the holding. At most one entry today, the validation BeCause considers definitive; the list shape leaves room for more. validatorId resolves in the page's validators; validationState is one of Unvalidated, Valid, Invalid, Revoked or None. Absent on holdings that have no validation yet, such as in-progress ones admitted by includeInProgress.

Only validated holdings are returned unless the request widens the search: "includeExpired": true admits lapsed holdings, "includeInProgress": true admits applications still in progress. Presence in the export is therefore itself a signal; certificationStatus, the dates and validations let you verify it.

Example

{
  "standards": [
    {
      "id": "3c7f2f64-0d3a-4b7e-9a11-2f66afa60001",
      "name": "Green Stay Certification",
      "levels": [
        { "id": "5a1c8e02-93d4-4f6b-8c7e-2b9d0f4a6e21", "name": "Silver", "level": 1 },
        { "id": "5a1c8e02-93d4-4f6b-8c7e-2b9d0f4a6e22", "name": "Gold", "level": 2 }
      ]
    }
  ],
  "validators": [
    { "id": "b83f0a2e-4c1d-4e9a-b7f2-9a8c7d6e5f04", "name": "Green Stay Foundation" }
  ],
  "customProperties": [
    { "id": "0992e704-5c3b-4b6e-8a1d-7f2e9c4b6d18", "name": "Partner hotel ID" }
  ],
  "companies": [
    {
      "id": "9c56d3a1-8b0f-4c7a-9e2d-5b1a7f3e0c11",
      "fields": {
        "0992e704-5c3b-4b6e-8a1d-7f2e9c4b6d18": ["HTL-12345"]
      },
      "heldStandards": [
        {
          "standardId": "3c7f2f64-0d3a-4b7e-9a11-2f66afa60001",
          "standardHolderId": "6e9b2c40-77aa-4f0e-8f3d-1d2c3b4a5f66",
          "startDateUtc": "2026-01-01T00:00:00Z",
          "endDateUtc": "2027-01-01T00:00:00Z",
          "levelId": "5a1c8e02-93d4-4f6b-8c7e-2b9d0f4a6e22",
          "firstIssuedYear": 2024,
          "certificationStatus": "Certified",
          "applicationStatus": "NotInProgress",
          "validations": [
            {
              "validatorId": "b83f0a2e-4c1d-4e9a-b7f2-9a8c7d6e5f04",
              "validationState": "Valid"
            }
          ]
        }
      ]
    }
  ]
}