Create a KYC request

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.

Security
SecretApiKey or JWT
Bodyapplication/jsonrequired
KYC request resource.
customerIdstring, <= 50 characters(CustomerId)required
ID of the customer resource.
Example:"cus_0YV7DDSDD1C8DA64KHH2W33CPF"
documentsArray of objects, non-empty(KycRequestDocument)required
Documents to request from the customer.
redirectUrlstring or null, (uri)

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.

reasonstring or null
Reason for uploading.
Example:"spend limit"
matchLevelinteger(KycDocumentMatchLevels)
Document verification level.
Default:2
Enum ValueDescription
1
Moderate verification requirements. This option is used for sale transactions.
2
Strict verification requirements. This option is used for credit transactions.
3
Basic verification requirements. This option is used when a high level of verification is not required.
expirationTimestring, (date-time)
Date and time when the request expires. The default value is one hour in the future.
In the sandbox environment, to mark a `credit-file-proof` KYC document as `accepted`, pass the customer's first name to the `accept` field. If an incorrect first name is passed, the document is rejected.
curl -i -X POST \
  https://www.rebilly.com/_mock/catalog/all/kyc-requests \
  -H 'Content-Type: application/json' \
  -H 'REB-APIKEY: YOUR_API_KEY_HERE' \
  -d '{
    "customerId": "123_456789",
    "redirectUrl": "https://example.com/return-here/",
    "documents": [
      {
        "type": "credit-file-proof",
        "maxAttempts": 1
      },
      {
        "type": "identity-proof"
      },
      {
        "type": "address-proof"
      }
    ],
    "reason": "registration"
  }'

Responses

KYC request created.
Headers
Locationstring, (uri)
Location of the related resource.
Example:"https://api.rebilly.com/example"
Rate-Limit-Limitinteger

Maximum number of requests available at one time for this rate limit. For more information, see Rate limits.

Example:500
Rate-Limit-Remaininginteger

Number of requests still available for this rate limit. For more information, see Rate limits.

Example:499
Bodyapplication/json
idstring, <= 50 charactersread-only
ID of the KYC request.
Example:"kyc_req_0YV7JMJ3DBCGRBR7K9D4HVGPP5"
customerIdstring, <= 50 characters(CustomerId)required
ID of the customer resource.
Example:"cus_0YV7DDSDD1C8DA64KHH2W33CPF"
documentsArray of objects, non-empty(KycRequestDocument)required
Documents to request from the customer.
statusstringread-only
Status of the request.
Enum ValueDescription
gathering
No documents have been provided yet. This is a temporary state.
attempted

At least one document has been provided but none were assigned the accepted status. This is a temporary state.

partial

At least one requested document has the accepted status, but not all requested documents have been assigned the accepted status. This is a temporary state.

pending-review

At least one requested document has the pending status, and no requested documents have been assigned the accepted status. This is a temporary state, until the document is reviewed, or another accepted document is provided.

fulfilled

All requested documents are provided and have been assigned the accepted status. This is a permanent state.

failed

At least one requested document has exhausted all attempts, and has not been assigned a accepted, pending, or in-progress status. This is a permanent state.

abandoned
One or more documents provided but the request expired. This is a permanent state.
expired
No documents were provided and the request expired. This is a permanent state.
redirectUrlstring or null, (uri)

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.

reasonstring or null
Reason for uploading.
Example:"spend limit"
matchLevelinteger(KycDocumentMatchLevels)
Document verification level.
Default:2
Enum ValueDescription
1
Moderate verification requirements. This option is used for sale transactions.
2
Strict verification requirements. This option is used for credit transactions.
3
Basic verification requirements. This option is used when a high level of verification is not required.
revisionintegerread-only
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.
expirationTimestring, (date-time)
Date and time when the request expires. The default value is one hour in the future.
createdTimestring, (date-time)(CreatedTime)read-only
Date and time when the resource is created. This value is set automatically when the resource is created.
updatedTimestring, (date-time)(UpdatedTime)read-only
Date and time when the resource is updated. This value is set automatically when the resource is updated.
_linksArray of objectsread-only
Related links.
_embeddedobjectread-only

Embedded objects that are requested by the expand query parameter.

Response
{
  "id": "kyc_req_0YV7JMJ3DBCGRBR7K9D4HVGPP5",
  "customerId": "cus_0YV7DDSDD1C8DA64KHH2W33CPF",
  "documents": [
    { … }
  ],
  "status": "gathering",
  "redirectUrl": "http://example.com",
  "reason": "spend limit",
  "matchLevel": 1,
  "revision": 0,
  "expirationTime": "2019-08-24T14:15:22Z",
  "createdTime": "2019-08-24T14:15:22Z",
  "updatedTime": "2019-08-24T14:15:22Z",
  "_links": [
    { … }
  ],
  "_embedded": {
    "documents": []
  }
}