Skip to main content

Get a task

GET 
/api/v2/bulk/tasks/:correlationId

Returns immediately; poll until the status is terminal — Success, PartialSuccess, Error or Cancelled. A finished bulk search carries a paged result: one entry per page file, in order, each a gzipped JSON document of at most pageSize companies that is complete on its own (catalogs included), with page URLs as SAS links valid for 30 days. A finished upsert — framework answers, companies or standard holders — carries no result body: the task reports its status and, on failure, the error, which lists every failed row. A framework-answers upsert reports failed omissions in the error's omissionRowErrors, keyed by question id rather than by data point id and separate from the answers' rowErrors. The row-level record of an upsert, successful rows included, is available to the owning company in the BeCause app, on the API usage tab under Company manager → Import & export → API.

Every failed row carries a reason to branch on and a message whose wording may change. Because company resolution fails an entry's answers, its omissions and a standard-holders upsert row alike, all three share these reasons: InvalidCompanyTarget, the entry gives both a company id and identifiedBy, or neither — exactly one is required; CompanyNotFound, no company exists with that id; NotPropertyOwner, the custom property is not one your profile owns, which is also what you get for a property id that does not exist, as we do not distinguish the two; NotAStringProperty, the property exists but is not String-typed and cannot identify a company; NoCompanyMatchedIdentifier, no company stores that value; MultipleCompaniesMatchedIdentifier, more than one does; DuplicateCompanyRows, another entry in the same request resolved to the same company; InternalError, the row failed on our side. A standard-holders upsert row also reports CertificationNotFound, no certification exists with that id; UnauthorizedCertificationAccess, the certification exists but your API key's profile does not have write access to it; MissingRequiredCompanyField, the resolved company is missing a field this certification requires on record, named alongside the certification id in the message; and, for a certification Standards itself rejects, its error type verbatim — Unknown, PropertyDoesNotExistOnCertification or PropertyTypeMismatch. Only failed answers report DataPointNotFound, ValueTypeMismatch, InvalidListOption, UnitRequired, InvalidUnit and UnsupportedDataPointType. Only failed omissions report QuestionNotFound, the question id names no question — including one deleted while the request was being processed; and DuplicateOmissionRows, two omissions for the same company, question and reporting period, which does not fire for the same question omitted for two different companies. A v1 search, calculators upsert or company-mapping task resolves here with its result as a single unpaged file entry — pageSize and companyCount are -1 because per-page numbers do not apply, and the one entry's URL is the complete result. The remaining upserts likewise resolve with status and, on failure, the error. A correlation id belonging to a different profile than your API key's yields 401, not 404 — 404 means the id does not exist.

Request​

Responses​

The task's current status.