> ## Documentation Index
> Fetch the complete documentation index at: https://developers.argosidentity.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Projection overview

> Design Projection policies so webhooks and Get Submission responses deliver only the data your system needs

## Why Projection matters

Webhook and `GET/Submission` responses include every field that the applicant entered or Argos generated during processing. As submissions grow, payload size, PII storage obligations, and data management complexity scale together.

Projection lets you persist exclusion policies per project so your applications only receive the slices of data they care about—enabling least-privilege data flows without modifying core workflows.

<Info>
  Projection policies are created and managed exclusively through the `POST /projection` API rather than the dashboard.
</Info>

## Scope and constraints

* Projection currently applies only to submissions created via Liveform.
* The policy affects webhook events linked to those submissions (`submission.submit`, `submission.approved`, `submission.rejected`) and the `GET/Submission` API alike.
* `GET/Submission` returns data based on the Projection assigned at submission time. Editing a policy later does not retroactively change existing submissions.

<Warning>
  Each project can store up to 10 Projection policies. Creating an 11th policy returns `409 Projection count limit exceeded`.
</Warning>

## Policy components

| Component       | Description               | Key considerations                                                                                                         |
| --------------- | ------------------------- | -------------------------------------------------------------------------------------------------------------------------- |
| `name`          | Human-readable identifier | Lowercase letters, digits, and underscores only; unique per project.                                                       |
| `mode`          | How data is handled       | Only the `exclude` option is available today.                                                                              |
| `fields`        | Array of fields to hide   | Must use values from the allowlist in [`POST /projection`](/en/idcheck/api-reference/api-reference-guide/post-projection). |
| `projection_id` | System-generated ID       | Referenced by Liveform URLs, webhook logs, and `GET/Submission` payloads to confirm which policy was applied.              |

<Tip>
  Include intent or versioning in the `name` field (for example, `aml_minimal_v1`) so teams can reuse policies confidently.
</Tip>

## How the flow works

1. Call `POST /projection` to define the exclusion set and receive a `projection_id`.
2. Encrypt that `projectionId` (or `projectionName`) inside the Liveform URL or token payload.
3. Once the user finishes the submission, webhooks and `GET/Submission` emit responses already filtered by the chosen Projection.

<RequestExample>
  ```bash cURL theme={null}
  curl --location 'https://rest-api.argosidentity.com/v3/projection' \
    --header 'Content-Type: application/json' \
    --header 'x-api-key: spearmint_project_key' \
    --data-raw '{
      "name": "kyc_minimal_v1",
      "mode": "exclude",
      "fields": ["date_of_birth","address_formatted","cf3"]
    }'
  ```
</RequestExample>

<ResponseExample>
  ```json GetSubmission excerpt theme={null}
  {
    "data": [
      {
        "submissionId": "subm_8zg6kp9",
        "status": "approved",
        "projection": {
          "projectionId": "proj_123abc",
          "projectionName": "kyc_minimal_v1"
        },
        "data": {
          "first_name": "Minty",
          "nationality": "KOR",
          "identityNumber": null
        }
      }
    ]
  }
  ```
</ResponseExample>

Fields listed in `fields`—such as `identityNumber` here—are omitted or set to `null` in both webhook payloads and `GET/Submission` responses, even though Argos still retains the underlying values.

## Projection workflow

<Steps>
  <Step title="Create the policy">
    Use [`POST /projection`](/en/idcheck/api-reference/api-reference-guide/post-projection) to define the exclusion list. Policies become active immediately.

    <Check>
      The response must contain `"message": "Create projection success"` and a `projection_id`.
    </Check>
  </Step>

  <Step title="Attach the policy to Liveform">
    Add the encrypted `projectionId` to the Liveform URL or token payload, for example:

    ```bash theme={null}
    https://form.argosidentity.com?pid=proj_x1yz&encrypted={'projectionId':'proj_123abc'}
    ```

    `projectionId` and `projectionName` are mutually exclusive, and both must be encrypted. See the [query string and token guide](/en/idcheck/getting-started/liveform-url/querystring-and-token-guide) for encryption details.
  </Step>

  <Step title="Validate via webhooks or Get Submission">
    Webhook payloads and [`GET/Submission`](/en/idcheck/api-reference/api-reference-guide/get-submission) responses include `projection.projectionId`. Confirm that the payload now only surfaces the intended fields.

    <Check>
      Log `projection.projectionId` in your downstream services to trace which policy shaped each payload.
    </Check>
  </Step>

  <Step title="Monitor and retire policies">
    [`GET /projection`](/en/idcheck/api-reference/api-reference-guide/get-projection) and [`GET /projection/{projectionId}`](/en/idcheck/api-reference/api-reference-guide/get-projection/projectionId) help you review active policies. Delete unused entries via [`DELETE /projection/{projectionId}`](/en/idcheck/api-reference/api-reference-guide/delete-projection) to free up slots or re-expose data.
  </Step>
</Steps>

## Projection API quick links

<CardGroup cols={2}>
  <Card title="POST/Projection" icon="plus" href="/en/idcheck/api-reference/api-reference-guide/post-projection">
    Create new policies and define the exclusion set.
  </Card>

  <Card title="GET/Projection" icon="list" href="/en/idcheck/api-reference/api-reference-guide/get-projection">
    Retrieve every Projection configured for the project.
  </Card>

  <Card title="GET/Projection/{projectionId}" icon="search" href="/en/idcheck/api-reference/api-reference-guide/get-projection/projectionId">
    Inspect a single policy, including fields and creation timestamp.
  </Card>

  <Card title="DELETE/Projection" icon="trash" href="/en/idcheck/api-reference/api-reference-guide/delete-projection">
    Remove obsolete policies to re-expose fields or stay within the 10-slot limit.
  </Card>
</CardGroup>

## Operational best practices

* Gather required-field lists from each consumer team before rolling out Projection and document the approvals.
* Store `projectionId` alongside webhook payloads or analytics logs to simplify audits and troubleshooting.
* Reuse existing policies when possible so you do not hit the 10-policy ceiling unnecessarily.
* Define explicit schemas per Projection in downstream services to avoid null-pointer exceptions when fields disappear.

<Tip>
  Prefix policy names by environment (for example, `dev_payment_v1`) to avoid confusing staging and production policies.
</Tip>

## Troubleshooting

<AccordionGroup>
  <Accordion title="Projection seems ignored">
    * Confirm the Liveform `encrypted` payload is actually encrypted; plaintext values are rejected.
    * When using `projectionName`, verify the spelling follows the lowercase-and-underscore rule.
    * Call `GET /projection` to ensure the referenced ID still exists and the timestamp matches your expectations.
  </Accordion>

  <Accordion title="Need to review excluded fields again">
    Argos still stores the full submission. However, as long as the Projection is attached, webhooks and `GET/Submission` will keep hiding those fields. Delete the policy with [`DELETE /projection/{projectionId}`](/en/idcheck/api-reference/api-reference-guide/delete-projection) and trigger a new submission to receive full payloads again.
  </Accordion>

  <Accordion title="Policy quota exceeded">
    If you reach the 10-policy limit, audit the current list via [`GET /projection`](/en/idcheck/api-reference/api-reference-guide/get-projection). Remove unused policies or consolidate field combinations into a smaller shared set before creating new ones.
  </Accordion>
</AccordionGroup>