Pull (purchase) process impacts by characterization method

Reveal impact values on a process by characterization-method id. Each id is a (method, process) pair — the same string the Library app sends when a user picks a method on the pull modal. Wraps the impacts/pull-multiple flow.

POST/public/processes/:id/impacts/pull

⚠

This endpoint is non-idempotent and billable. Each successful request debits credits per characterization method revealed.

⚠

Works for both aggregated and flow-based processes. Note: for flow-based processes the pulled values do not yet surface on GET /processes/:id (that read path is in progress) — the pull itself debits credits and is recorded correctly.

Impact values on a process are calculated through characterization methods (e.g. IPCC 2021, ReCiPe 2016) — pulling a method reveals every impact row attributable to it on the parent process. To browse the methods available across the library, see GET /impact-methods.

Send the id of a row from GET /impact-methods in characterizationFactorIds (the field keeps that name for parity with the underlying library data model). Each id, scoped to the process in the URL, reveals every impact row on that process under that method — one credit per method. You do not need to enumerate individual indicators.

ℹ

A bare method id ("methodId") is the simplest form. The canonical composite "methodId,processId" is also accepted and is what the endpoint echoes back in pulledCharacterizationFactorIds; when you send a bare id the process scope is taken from the URL.

Path parameters

Parameter	Type	Description
idrequired	string (uuid)	The process id the impacts belong to.

Request body

Parameter	Type	Description
characterizationFactorIds (characterization-method ids)required	string[]	1–500 characterization-method ids. Each entry is the `id` of a row from GET /impact-methods (a bare UUID), or the canonical `"methodId,processId"` composite — for a bare id the URL's :id is used as the process scope.

Response

200OK

{
  "processId": "340e4939-6d75-430c-b6c7-1e98d566afdd",
  "pulledCharacterizationFactorIds": [
    "dbc5a15e-e65f-4834-85a6-b9d9940f0a67,340e4939-6d75-430c-b6c7-1e98d566afdd",
    "d0cd0702-bcfa-4f9b-a2e3-4adfc93ccaff,340e4939-6d75-430c-b6c7-1e98d566afdd"
  ],
  "revealedImpactCount": 36
}

pulledCharacterizationFactorIds is always in the canonical "methodId,processId" form, even if you sent bare ids. revealedImpactCount is the number of impact rows newly revealed across all requested methods.

Errors

400Bad Request when characterizationFactorIds is empty or malformed. 404Not Foundwhen the process doesn't exist, a requested method id is unknown, or none of the requested methods have any impacts on this process. 403Forbidden when the team has insufficient credits. 409Conflict when every impact under the requested methods was already revealed.

Example

curl -s -X POST \
  'https://api.circa.ai/public/processes/340e4939-6d75-430c-b6c7-1e98d566afdd/impacts/pull' \
  -H 'x-api-key: circa_live_xxx' \
  -H 'x-team-id: TEAM_ID_FROM_OVERVIEW' \
  -H 'Circa-Version: 2026-05-11.arrakis' \
  -H 'Content-Type: application/json' \
  -d '{
    "characterizationFactorIds": [
      "dbc5a15e-e65f-4834-85a6-b9d9940f0a67,340e4939-6d75-430c-b6c7-1e98d566afdd",
      "d0cd0702-bcfa-4f9b-a2e3-4adfc93ccaff,340e4939-6d75-430c-b6c7-1e98d566afdd"
    ]
  }'

After pulling

The next GET /processes/:id for this team returns the revealed impact rows with revealed: true and the real numeric value. To browse the available methods, see GET /impact-methods.