메인 콘텐츠로 건너뛰기

​
Projection이 필요한 이유

기본적으로 Webhook과 GET/Submission 응답은 제출자가 입력하거나 Argos에서 생성한 모든 필드를 포함합니다. 제출 데이터가 많아질수록 네트워크 비용, 고객사의 PII 보관 부담, 데이터 관리 복잡도가 함께 증가합니다. Projection은 특정 필드만 제외하는 정책을 프로젝트 단위로 저장해, 고객사가 필요한 정보만 수신하도록 돕는 데이터 최소화 도구입니다.
Projection 정책은 대시보드가 아니라 전용 API (POST /projection)로만 생성·관리합니다.

​
적용 범위와 제약

  • Projection은 현재 Liveform을 통해 생성된 Submission에만 적용됩니다.
  • Projection이 적용된 Submission과 연결된 Webhook 이벤트(submission.submit, submission.approved, submission.rejected) 및 GET/Submission 응답에 동일하게 반영됩니다.
  • GET/Submission은 Submission 생성 시점에 지정된 Projection을 기준으로 데이터를 반환합니다. 정책을 바꿔도 기존 Submission에는 소급 적용되지 않습니다.
프로젝트당 최대 10개의 Projection 정책만 저장할 수 있습니다. 11번째 생성을 시도하면 409 Projection count limit exceeded 오류가 발생합니다.

​
Projection 정책 구성 요소

구성 요소설명고려 사항
name정책 식별자소문자, 숫자, 언더스코어만 허용되며 프로젝트 내에서 unique 해야 합니다.
mode필드 처리 방식현재는 exclude만 지원합니다.
fields제외 대상 필드 배열first_name, address_formatted, cf1 등 POST/Projection 문서의 허용 목록 중에서만 선택할 수 있습니다.
projection_id시스템이 발급하는 고유 IDLiveform URL, Webhook 로그, GET/Submission 응답에서 정책 적용 여부를 판별할 때 사용합니다.
이름에 버전(_v1, _v2)이나 용도(_aml_only)를 명시하면 여러 정책을 병행 운영할 때 혼선을 줄일 수 있습니다.

​
동작 개요 및 예시

  1. POST /projection으로 제외 정책을 만들면 Argos가 projection_id를 반환합니다.
  2. Liveform URL 또는 토큰에 projectionId(또는 projectionName)를 암호화해 전달합니다.
  3. 제출이 완료되면 해당 Projection이 Webhook과 GET/Submission의 응답 구조를 제어합니다.
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
      }
    }
  ]
}
identityNumber와 같이 제외된 필드는 Webhook/GET/Submission 응답에서 누락되거나 null 처리되며, Argos 저장소에는 그대로 남아 있더라도 고객 서버에는 전달되지 않습니다.

​
Projection 사용 절차

1

Projection 정책 생성

POST /projection에서 제외할 필드 목록을 정의합니다. 정책은 즉시 활성화됩니다.
응답에 "message": "Create projection success"와 projection_id가 포함되어야 합니다.
2

Liveform 제출에 Projection 연결

Liveform URL 또는 토큰의 암호화 영역에 projectionId를 포함합니다. 예시:
https://form.argosidentity.com?pid=proj_x1yz&encrypted={'projectionId':'proj_123abc'}
projectionId와 projectionName은 동시에 사용할 수 없으며, 두 값 모두 반드시 암호화해야 합니다. 자세한 암호화 규칙은 쿼리 스트링 및 토큰 가이드를 참고하세요.
3

Webhook 및 Get Submission으로 결과 확인

Projection이 적용된 제출은 Webhook payload와 GET/Submission 응답에 projection.projectionId가 포함됩니다. 전달받은 데이터가 기대한 필드만 남았는지 검증하세요.
Webhook 로그에서 projection.projectionId가 기대값과 일치하는지 확인하면 잘못된 정책 연결을 빠르게 파악할 수 있습니다.
4

정책 모니터링 및 폐기

GET /projection과 GET /projection/{projectionId}로 정책 현황을 점검합니다. 더 이상 필요하지 않은 정책은 DELETE /projection/{projectionId}로 제거하세요.

​
Projection 관련 API 빠른 링크

POST/Projection

새로운 Projection 정책을 생성하고 제외 필드를 정의하는 방법

GET/Projection

프로젝트에 저장된 모든 Projection 정책 목록 조회

GET/Projection/{projectionId}

단일 Projection 정책의 세부 정보를 확인하고 변경 추적

DELETE/Projection

사용이 끝난 Projection을 삭제해 데이터 재노출을 허용하거나 슬롯을 확보

​
운영 모범 사례

  • Projection 도입 전, 팀별로 필요한 필드 목록을 정의하고 승인 절차를 문서화하세요.
  • GET/Submission 응답에서 projectionId를 로그에 남기면 감사 추적과 역추적이 쉬워집니다.
  • 새 Projection을 만들기 전에 기존 정책을 재사용할 수 있는지 확인해 10개 제한을 효율적으로 사용하세요.
  • Webhook 소비 애플리케이션에서 Projection별 스키마를 명시적으로 선언하면 누락 필드로 인한 NullPointer 오류를 예방할 수 있습니다.
QA 환경에 동일한 Projection 이름을 복제할 때는 접두사(예: dev_, stg_)를 붙이면 운영 정책과 혼동되지 않습니다.

​
Troubleshooting

  • Liveform URL의 encrypted 파라미터가 실제로 암호화되었는지 확인하세요.
  • projectionId 대신 projectionName을 넣었다면 이름 철자를 소문자·언더스코어 규칙에 맞게 작성했는지 검증하세요.
  • GET /projection으로 정책이 존재하는지, created_at이 최신인지 비교해 잘못된 ID를 사용하는지 확인하세요.
Projection이 적용된 Submission에서도 필드는 Argos에 저장되어 있습니다. 다만 동일 Projection이 계속 연결되어 있으면 Webhook 및 GET/Submission에서 재노출되지 않습니다. projectionId로 DELETE /projection/{projectionId}를 호출해 정책을 제거한 뒤, Liveform을 다시 호출하면 이후 제출부터 전체 데이터가 전달됩니다.
프로젝트당 10개 제한 때문에 새 정책을 만들 수 없다면, GET /projection으로 사용 현황을 살펴보고 더 이상 참조되지 않는 정책을 삭제하거나, 필드 조합을 통합하는 새 버전을 설계하세요.