# Create a KYC request

Creates a KYC request.

The customer is redirected to the `kycGatherer` link.
After the customer completes the KYC process,
they are redirected back to the `redirectUrl` link.

Corresponding webhooks, such as: KYC document accepted and KYC document rejected,
are sent to the subscribers.

When the complete list of documents is received and accepted,
the KYC request fulfilled webhook is sent to subscribers.

If a `credit-file-proof` request is successful,
it returns a `decision` value of `single-source` or `dual-source`.
The corresponding `identity-proof` and `address-proof` documents are not requested.

Endpoint: POST /kyc-requests
Version: latest
Security: SecretApiKey, JWT

## Request fields

- `customerId` (string, required)
  ID of the customer resource.
  Example: cus_0YV7DDSDD1C8DA64KHH2W33CPF
- `documents` (array, required)
  Documents to request from the customer.
- `documents.type` (string, required)
  Enum: "identity-proof", "address-proof", "funds-proof", "purchase-proof", "credit-file-proof"
- `documents.subtypes` (array | null)
  Permitted document subtype.
- `documents.maxAttempts` (integer)
  Total number of allowed document upload attempts. Use `0` to allow unlimited upload attempts.
- `documents.faceProofRequired` (boolean)
  Specifies if the customer must upload a photo of their face (selfie) that matches a provided KYC document.
- `documents.faceLivenessRequired` (boolean)
  Specifies if the customer must use the face liveness feature when uploading a selfie. For more information, see [Facial recognition and identity verification](https://www.rebilly.com/docs/kyc-and-aml/kyc#facial-recognition-identity-verification).
- `redirectUrl` (string | null)
  URL where the customer is redirected when a KYC document upload is complete. When the customer is redirected, Rebilly appends an `info` query parameter that has one of the following values: - `back`: Customer clicked the `back to website` link. - `token_expired`: Customer's token expired. - `success`: Customer uploaded KYC documents that have been analyzed. - `manual`: Customer uploaded KYC documents that require a manual review. This is because the analyzer rejected the documents or could not process them. - `partial`: Some of the customer's KYC documents have been analyzed, but other documents have not. For example, this may occur when a proof of address document is analyzed but proof of ID is not. Example: `https://example.com?info=success`.
- `reason` (string | null)
  Reason for uploading.
  Example: spend limit
- `matchLevel` (integer)
  Document verification level.
  Enum: 1, 2, 3
- `subtypeRestrictions` (object)
  Document subtypes that are prohibited for `identityProof`, `addressProof`, `fundsProof`, and `purchaseProof`. This object does not include `credit-file-proof` because it has no subtypes.
  Example: {"identityProof":["driver-license","public-health-card"]}
- `subtypeRestrictions.identityProof` (array)
  Prohibited subtypes of proof of identity.
- `subtypeRestrictions.addressProof` (array)
  Prohibited subtypes of proof of address.
- `subtypeRestrictions.fundsProof` (array)
  Prohibited subtypes of proof of funds.
- `subtypeRestrictions.purchaseProof` (array)
  Prohibited subtypes of proof of purchase.
- `expirationTime` (string)
  Date and time when the request expires. The default value is one hour in the future.

## Response 201 fields

- `id` (string)
  ID of the KYC request.
  Example: kyc_req_0YV7JMJ3DBCGRBR7K9D4HVGPP5
- `customerId` (string, required)
  ID of the customer resource.
  Example: cus_0YV7DDSDD1C8DA64KHH2W33CPF
- `documents` (array, required)
  Documents to request from the customer.
- `documents.type` (string, required)
  Enum: "identity-proof", "address-proof", "funds-proof", "purchase-proof", "credit-file-proof"
- `documents.subtypes` (array | null)
  Permitted document subtype.
- `documents.maxAttempts` (integer)
  Total number of allowed document upload attempts. Use `0` to allow unlimited upload attempts.
- `documents.faceProofRequired` (boolean)
  Specifies if the customer must upload a photo of their face (selfie) that matches a provided KYC document.
- `documents.faceLivenessRequired` (boolean)
  Specifies if the customer must use the face liveness feature when uploading a selfie. For more information, see [Facial recognition and identity verification](https://www.rebilly.com/docs/kyc-and-aml/kyc#facial-recognition-identity-verification).
- `status` (string)
  Status of the request.
  Enum: "gathering", "attempted", "partial", "pending-review", "fulfilled", "failed", "abandoned", "expired"
- `redirectUrl` (string | null)
  URL where the customer is redirected when a KYC document upload is complete. When the customer is redirected, Rebilly appends an `info` query parameter that has one of the following values: - `back`: Customer clicked the `back to website` link. - `token_expired`: Customer's token expired. - `success`: Customer uploaded KYC documents that have been analyzed. - `manual`: Customer uploaded KYC documents that require a manual review. This is because the analyzer rejected the documents or could not process them. - `partial`: Some of the customer's KYC documents have been analyzed, but other documents have not. For example, this may occur when a proof of address document is analyzed but proof of ID is not. Example: `https://example.com?info=success`.
- `reason` (string | null)
  Reason for uploading.
  Example: spend limit
- `matchLevel` (integer)
  Document verification level.
  Enum: 1, 2, 3
- `revision` (integer)
  Number of times the KYC request data has been modified. Use this value when analyzing webhook data to determine if a change must take precedence over the current representation.
- `subtypeRestrictions` (object)
  Document subtypes that are prohibited for `identityProof`, `addressProof`, `fundsProof`, and `purchaseProof`. This object does not include `credit-file-proof` because it has no subtypes.
  Example: {"identityProof":["driver-license","public-health-card"]}
- `subtypeRestrictions.identityProof` (array)
  Prohibited subtypes of proof of identity.
- `subtypeRestrictions.addressProof` (array)
  Prohibited subtypes of proof of address.
- `subtypeRestrictions.fundsProof` (array)
  Prohibited subtypes of proof of funds.
- `subtypeRestrictions.purchaseProof` (array)
  Prohibited subtypes of proof of purchase.
- `subtypeRestrictionUiEnabled` (boolean)
  Specifies if the KYC document gatherer displays guidance about prohibited document subtypes.
- `expirationTime` (string)
  Date and time when the request expires. The default value is one hour in the future.
- `createdTime` (string)
  Date and time when the resource is created. This value is set automatically when the resource is created.
- `updatedTime` (string)
  Date and time when the resource is updated. This value is set automatically when the resource is updated.
- `_links` (array)
  Related links.
- `_links.href` (string)
  Link URL.
- `_links.rel` (string)
  Type of link.
  Enum: "self", "documents", "gatherer"
- `_embedded` (object)
  Embedded objects that are requested by the `expand` query parameter.
- `_embedded.documents` (array)

## Response 401 fields

- `status` (integer)
  HTTP status code.
- `type` (string)
  Problem type in the form of a [URI](https://tools.ietf.org/html/rfc3986) reference. It should provide human-readable documentation for the problem type. When this member is not present, its value is assumed to be "about:blank".
- `title` (string)
  Short, human-readable summary of the problem type. Other than for the purposes of localization, this should not change from occurrence to occurrence of the problem.
- `detail` (string)
  Human-readable explanation that is specific to this occurrence of the problem.
- `instance` (string)
  URI reference that identifies the specific occurrence of the problem. It may or may not yield further information if dereferenced.

## Response 403 fields

- `status` (integer)
  HTTP status code.
- `error` (string)
  Message that describes why the request is forbidden. Most responses use a descriptive message, such as `Not allowed to change security settings`. If the organization requires multi-factor authentication (MFA) and MFA verification has not been completed for the session, this value is `mfa_required`. If MFA verification has not been completed for the session and the operation requires a confirmed session, this value is `mfa_required_for_caller`. This includes turning on `requireMfa` and resetting MFA for a user. If the organization restricts access to a list of IP addresses and the request comes from an IP address that is not in the list, this value is `ip_not_allowed`.
- `organizationId` (string)
  Unique organization identifier. An organization is an entity that represents a company. For more information, see [Obtain an organization ID](https://www.rebilly.com/docs/settings/organizations-and-websites/#obtain-your-organization-id-and-website-id).
  Example: org_0YVDM8RC7GDADADSBSMW124JA8
- `type` (string)
  Problem type in the form of a [URI](https://tools.ietf.org/html/rfc3986) reference. It should provide human-readable documentation for the problem type. When this member is not present, its value is assumed to be "about:blank".
- `title` (string)
  Short, human-readable summary of the problem type. Other than for the purposes of localization, this should not change from occurrence to occurrence of the problem.
- `detail` (string)
  Human-readable explanation that is specific to this occurrence of the problem.
- `instance` (string)
  URI reference that identifies the specific occurrence of the problem. It may or may not yield further information if dereferenced.

## Response 422 fields

- `status` (integer)
  HTTP status code.
- `type` (string)
  Problem type in the form of a [URI](https://tools.ietf.org/html/rfc3986) reference. It should provide human-readable documentation for the problem type. When this member is not present, its value is assumed to be "about:blank".
- `title` (string)
  Short, human-readable summary of the problem type. Other than for the purposes of localization, this should not change from occurrence to occurrence of the problem.
- `detail` (string)
  Human-readable explanation that is specific to this occurrence of the problem.
- `instance` (string)
  URI reference that identifies the specific occurrence of the problem. It may or may not yield further information if dereferenced.
- `invalidFields` (array)
  Invalid field details.
  Example: [{"field":"field1","message":"field1 is invalid"},{"field":"subObject.field2","message":"field2 is invalid"},{"field":"subObject.field2","message":"another error in the field2"}]
- `invalidFields.field` (string)
  Name of the field. Dot notation is used for nested object field names.
- `invalidFields.message` (string)
  Message field.

## Response 429 fields

- `type` (string)
  Problem type in the form of a [URI](https://tools.ietf.org/html/rfc3986) reference. It should provide human-readable documentation for the problem type. When this member is not present, its value is assumed to be "about:blank".
  Example: about:blank
- `title` (string)
  Short, human-readable summary of the problem type. Other than for the purposes of localization, this should not change from occurrence to occurrence of the problem.
  Example: Rate Limit Exceeded
- `status` (integer)
  HTTP status code.
- `detail` (string)
  Human-readable explanation that is specific to this occurrence of the problem.
  Example: A request cannot be executed because the user has sent too many requests within a certain period of time
- `instance` (string)
  URI reference that identifies the specific occurrence of the problem. It may or may not yield further information if dereferenced.