Result files

A bulk search does not return its data in an API response. The finished task points at files — one per page of the result — and you download them. These pages describe what is in those files: the envelope the task hands you, the conventions every file follows, and one page per file shape with every field.

The example workflows show the files in the context of a job; this section is the complete description, and where the two differ, this section is authoritative.

From task to file

Poll GET /api/v2/bulk/tasks/{correlationId} until the task reaches a terminal state. On Success or PartialSuccess its result lists the pages:

{
  "correlationId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "createdAtUtc": "2026-08-20T08:12:44.9Z",
  "updatedAtUtc": "2026-08-20T08:14:52.03Z",
  "status": "Success",
  "requestType": "BulkGetStandardHolders",
  "result": {
    "pageSize": 100000,
    "pageCount": 1,
    "pages": [
      {
        "url": "https://exports.because.eco/…/page-0001.json?sv=…",
        "companyCount": 6321
      }
    ]
  },
  "error": null
}

Field	Meaning
result.pageSize	The page size the task ran with — the request's pageSize, or the endpoint's default when omitted. -1 marks a single-file result.
result.pageCount	How many pages there are; equals pages.length.
result.pages[]	In page order. The last page is usually short.
result.pages[].url	The file. See Downloading.
result.pages[].companyCount	How many top-level entries the file holds — companies for the company-shaped exports, standards for the standards export. -1 on a single-file result.

result is null until the task finishes, and stays null for task types that return no file — the remaining imports report through status and error alone.

Which task produces which file

Submitted to	requestType on the task	File
POST /api/v2/bulk/framework-answers/search	BulkGetFrameworkAnswers	Framework answers page
POST /api/v2/bulk/companies/search	BulkGetCompanies	Companies page
POST /api/v2/bulk/standards/holders/search	BulkGetStandardHolders	Standard holders page
POST /api/v2/bulk/standards/search	BulkGetStandards	Standards page
POST /api/v2/bulk/calculators/search	BulkGetCompanyCalculators	Calculators page
POST /api/v1/bulk/calculators/upsert	BulkUpsertCalculators	Calculators upsert result — single file
POST /api/v1/bulk/company-mappings	BulkMapCompanies	Company mapping result — single CSV file

The remaining bulk endpoints — the framework-answers, companies, standard-holders and custom-property-values upserts — produce no file. Their task reports status, and on failure error names what went wrong, row by row where the endpoint supports it. The full row-level record of an upsert, successes included, is available to the owning company in the BeCause app under Company manager → Import & export → API → API usage, as a downloadable report per request.

Downloading

Each url is a self-contained link: GET it directly, with no Authorization header. It is valid for thirty days from when the task finished, after which it stops working — download promptly rather than bookmarking it. Page links are served from exports.because.eco.

Page files are gzip-compressed JSON served as application/json with Content-Encoding: gzip. Most HTTP clients — Postman, a browser, Python requests, axios, .NET HttpClient with automatic decompression — decompress transparently and hand you plain JSON. A client that does not honour Content-Encoding receives the gzip bytes unchanged; bare curl is the common case, and --compressed fixes it:

curl --compressed "https://exports.because.eco/…/page-0001.json?sv=…" > page-1.json

Single-file results are not compressed.

Conventions every page file follows

• Every page is a complete document on its own. Anything referenced by id inside a page — datapoints, custom properties, standards, validators, calculator variables — is declared in a catalog at the top of that same page. Pages can be processed independently and in parallel; nothing requires reading page one before page two.
• camelCase property names, as in the rest of the API.
• A field with nothing to say is absent, not null. Optional lists are absent when empty, optional values are absent when unknown. Read with a parser that tolerates missing keys.
• Enumerations are strings carrying the value's name — "Yearly", "Certified", "January" — never its number.
• Dates and times are ISO 8601 in UTC — "2026-01-01T00:00:00Z". Treat every timestamp as UTC whether or not it carries the Z designator. Date-only values are ISO 8601 calendar dates, "2026-01-01".
• Identifiers are the same ids the rest of the API uses. A company id in one export joins directly against the same company in another export, in a company mapping, or in an import's identifiedBy.companyId.
• Catalogs repeat across pages. A standard referenced on page 1 and page 2 is declared on both, identically; a consumer merging pages keeps either copy and deduplicates by id.
• How widely a catalog is drawn depends on the catalog. The datapoint, standard, validator and calculator-variable catalogs are narrowed to what the page's own entries reference. customProperties is never narrowed to the page: the companies and standard-holders exports draw it from the values across the whole export, the framework-answers and calculators exports from the requested properties your profile owns. Either way it is identical on every page, so a property that only a later page's companies hold is still named on page 1, and a given property carries the same name in every export that returns it.

Single-file results

The calculators upsert and the company mapping are older endpoints that write their whole result to one file. The task reports them through the same result envelope with the sentinel -1 in place of the per-page numbers:

{
  "result": {
    "pageSize": -1,
    "pageCount": 1,
    "pages": [
      { "url": "https://…/bulk-export-result.json?sv=…", "companyCount": -1 }
    ]
  }
}

The file behind that URL is uncompressed. The calculators upsert writes JSON that — unlike the page files — emits null for fields without a value; the company mapping writes CSV. Their shapes are on the calculators upsert result and company mapping result pages.