Skip to main content

​
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.
Projection policies are created and managed exclusively through the POST /projection API rather than the dashboard.

​
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.
Each project can store up to 10 Projection policies. Creating an 11th policy returns 409 Projection count limit exceeded.

​
Policy components

ComponentDescriptionKey considerations
nameHuman-readable identifierLowercase letters, digits, and underscores only; unique per project.
modeHow data is handledOnly the exclude option is available today.
fieldsArray of fields to hideMust use values from the allowlist in POST /projection.
projection_idSystem-generated IDReferenced by Liveform URLs, webhook logs, and GET/Submission payloads to confirm which policy was applied.
Include intent or versioning in the name field (for example, aml_minimal_v1) so teams can reuse policies confidently.

​
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.
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"]
  }'

{
  "data": [
    {
      "submissionId": "subm_8zg6kp9",
      "status": "approved",
      "projection": {
        "projectionId": "proj_123abc",
        "projectionName": "kyc_minimal_v1"
      },
      "data": {
        "first_name": "Minty",
        "nationality": "KOR",
        "identityNumber": null
      }
    }
  ]
}
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

1

Create the policy

Use POST /projection to define the exclusion list. Policies become active immediately.
The response must contain "message": "Create projection success" and a projection_id.
2

Attach the policy to Liveform

Add the encrypted projectionId to the Liveform URL or token payload, for example:
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 for encryption details.
3

Validate via webhooks or Get Submission

Webhook payloads and GET/Submission responses include projection.projectionId. Confirm that the payload now only surfaces the intended fields.
Log projection.projectionId in your downstream services to trace which policy shaped each payload.
4

Monitor and retire policies

GET /projection and GET /projection/{projectionId} help you review active policies. Delete unused entries via DELETE /projection/{projectionId} to free up slots or re-expose data.

POST/Projection

Create new policies and define the exclusion set.

GET/Projection

Retrieve every Projection configured for the project.

GET/Projection/{projectionId}

Inspect a single policy, including fields and creation timestamp.

DELETE/Projection

Remove obsolete policies to re-expose fields or stay within the 10-slot limit.

​
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.
Prefix policy names by environment (for example, dev_payment_v1) to avoid confusing staging and production policies.

​
Troubleshooting

  • 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.
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} and trigger a new submission to receive full payloads again.
If you reach the 10-policy limit, audit the current list via GET /projection. Remove unused policies or consolidate field combinations into a smaller shared set before creating new ones.