---
title: "Add KYC2 Request – Creates a KYC2 gate request for a user."
method: POST
path: "/programs/{programCode}/users/{userIdentifier}/kycGates/kyc2"
tags: ["Kyc"]
---

# Add KYC2 Request – Creates a KYC2 gate request for a user.

`POST /programs/{programCode}/users/{userIdentifier}/kycGates/kyc2`

Creates a KYC2 gate request for a user, submitting SSN for verification. Returns pending KYC gate, status, and attempts remaining.

## Path parameters

- `userIdentifier` string, required
- `programCode` string, required

## Headers

- `X-GD-RequestId` string, required

## Request body

- CreateKyc2Request — Represents a request to create a KYC2 gate for a user. Used to submit SSN for KYC2 verification, supporting both plain and encrypted SSN for secure transmission. Includes a user identifier for internal correlation and tracking.
  - `ssn` string, nullable — The full SSN of the user. Used for identity verification in KYC2 flows.
  - `encryptedSsn` EncryptedData — Represents a container for encrypted data used in secure data transfer operations. Contains the encrypted payload and associated cryptographic metadata, including encryption version, ephemeral public key, and public key hash. Used to securely transmit sensitive information such as user data, ensuring confidentiality and integrity during transport.
    - `version` string, nullable — The version of the encryption algorithm used to encrypt the data (e.g., "v1", "v2").
    - `ephemeralPublicKey` string, nullable — The ephemeral public key used in the encryption process, typically for key exchange or session establishment.
    - `publicKeyHash` string, nullable — The hash of the public key used to verify the integrity and authenticity of the encryption key.
    - `data` string, nullable — The encrypted data payload, typically base64-encoded, containing the sensitive information.

## Response `201`

Created

- CreateKyc2Response — Represents the response returned after creating a KYC2 gate request. Contains the KYC2 gate details, including pending gate, status, attempts remaining, required properties, identity challenges, and encrypted challenge data. Used to communicate the next required verification step, current KYC progress, and any additional identity challenge questions for the user.
  - `kycGate` CreateKyc2 — Represents the KYC2 gate details returned after a KYC2 request. Contains pending KYC gate, status, attempts remaining, required properties, identity challenges, and encrypted challenge data. Used to communicate the next required verification step, current KYC progress, and any additional identity challenge questions for the user.
    - `pendingKycGate` string, nullable — The pending KYC gate value indicating the next verification step required for the user.
    - `kycGateAttemptsRemaining` integer — The number of KYC gate attempts remaining for the user. Used to track how many more attempts are allowed for the current KYC gate.
    - `kycGateStatus` string, nullable — The status of the current KYC gate (e.g., "Pending", "Passed", "Failed").
    - `requiredProperties` string[], nullable — The list of required properties for the KYC2 gate, such as additional fields or documents needed.
    - `identityChallenges` IdentityChallenge[], nullable — The list of identity challenge questions presented to the user for verification. Each challenge includes a question, possible answer choices, and metadata.
      - `questionId` integer — The unique identifier of the challenge question. Used to correlate the question with user responses and backend validation.
      - `questionText` string, nullable — The text of the challenge question presented to the user. Example: "Which of the following addresses have you lived at?"
      - `identityChallengeAnswerChoices` IdentityChallengeAnswerChoice[], nullable — The list of possible answer choices for the challenge question. Each answer choice includes an answer ID and display content.
        - `answerId` integer — The unique identifier of the answer choice. Used to correlate the user's selection with backend validation and scoring.
        - `content` string, nullable — The display content of the answer choice presented to the user. Example: an address, date, or other relevant information.
    - `encryptedIdentityChallenges` EncryptedData — Represents a container for encrypted data used in secure data transfer operations. Contains the encrypted payload and associated cryptographic metadata, including encryption version, ephemeral public key, and public key hash. Used to securely transmit sensitive information such as user data, ensuring confidentiality and integrity during transport.
      - `version` string, nullable — The version of the encryption algorithm used to encrypt the data (e.g., "v1", "v2").
      - `ephemeralPublicKey` string, nullable — The ephemeral public key used in the encryption process, typically for key exchange or session establishment.
      - `publicKeyHash` string, nullable — The hash of the public key used to verify the integrity and authenticity of the encryption key.
      - `data` string, nullable — The encrypted data payload, typically base64-encoded, containing the sensitive information.
  - `responseDetails` ResponseDetail[], nullable — Required: A list of response details providing status codes, descriptions, and additional information about the result of the operation.
    - `code` integer — The primary status or error code for the response (e.g., 200 for success, 400 for validation error).
    - `subCode` integer, nullable — An optional subcode providing more granular detail about the response or error.
    - `description` string, nullable — A human-readable description of the response, error, or status.
    - `url` string, nullable — A URL linking to documentation or a web page with more information about the response code.

## Other responses

- `401` — Unauthorized
- `403` — Forbidden
- `500` — Internal Server Error
- `503` — Service Unavailable

---

[API](https://skmtc.net/greendot/apis/baas-apis.md) · [All operations](https://skmtc.net/greendot/apis/baas-apis/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/greendot/baas-apis/revisions/666553766b78/schema)