Retrieve a KYC request

Retrieves a KYC request with a specified ID.

SecuritySecretApiKey or JWT
Request
path Parameters
id
required
string <= 50 characters ^[@~\-\.\w]+$

ID of the resource.

Responses
200

KYC request retrieved.

Response Schema: application/json
customerId
required
string (CustomerId) <= 50 characters

Customer resource ID.

required
Array of objects (KycRequestDocuments)

Documents to request from the customer.

Array
type
required
string

Type of document to request from the customer.

Enum: "identity-proof" "address-proof" "funds-proof" "purchase-proof" "credit-file-proof"
subtypes
Array of strings or null (KycDocumentSubtypes)

Permitted document subtype.

Enum: "passport" "id-card" "driver-license" "birth-certificate" "utility-bill" "rental-receipt" "lease-agreement" "copy-credit-card" "credit-card-statement" "bank-statement" … 16 more
maxAttempts
integer [ 0 .. 100 ]
Default: 3

Total number of allowed document upload attempts. Use 0 to allow unlimited upload attempts.

faceProofRequired
boolean

Specifies if the customer must upload a photo of their face (selfie) that matches a provided KYC document.

id
string <= 50 characters

Unique resource ID. Defaults to UUID v4.

status
string

Status of the request.

Enum: Description
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.

redirectUrl
string <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.

reason
string

Reason for uploading.

matchLevel
integer [ 1 .. 2 ]
Default: 2

Tolerance level setting for document matches. The value of 1 is more tolerant and 2 is strict.

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.

expirationTime
string <date-time>

Date and time when the request expires. The default value is one hour in the future.

createdTime
string <date-time> (CreatedTime)

Date and time which is set automatically when the resource is created.

updatedTime
string <date-time> (UpdatedTime)

Date and time which updates automatically when the resource is updated.

Array of objects

Related links.

Array
href
string

Link URL.

rel
string

Type of link.

Enum: "self" "documents" "gatherer"
object

Embedded objects that are requested by the expand query parameter.

documents
Array of arrays
401

Unauthorized access. Invalid credentials used.

403

Access forbidden.

404

Resource not found.

get/kyc-requests/{id}
Request samples
Response samples
application/json
{
  • "id": "4f6cf35x-2c4y-483z-a0a9-158621f77a21",
  • "customerId": "cus_0YV7DDSDD1C8DA64KHH2W33CPF",
  • "documents": [
    ],
  • "status": "gathering",
  • "redirectUrl": "http://example.com",
  • "reason": "spend limit",
  • "matchLevel": 2,
  • "revision": 0,
  • "expirationTime": "2019-08-24T14:15:22Z",
  • "createdTime": "2019-08-24T14:15:22Z",
  • "updatedTime": "2019-08-24T14:15:22Z",
  • "_links": [
    ],
  • "_embedded": {
    }
}