Retrieve a KYC request

Retrieve a KYC request with specified ID.

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

Resource identifier string.

query Parameters
expand
string

Expands a request to include embedded objects within the _embedded property of the response. This field accepts a comma-separated list of objects.

For more information, see Expand to include embedded objects.

Responses
200

KYC request was retrieved.

Response Schema: application/json
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)

Allowed 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 whether 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. Temporary state.

attempted

At least one document has been provided but is not accepted. Temporary state.

partial

At least one requested document has the accepted status, but not all of them. Temporary state.

pending-review

At least one document type has a document with the pending status and no documents with the accepted status. Temporary state (until reviewed or another accepted document is provided).

fulfilled

All requested documents are provided and accepted. Permanent state.

failed

At least one requested document exhausted all attempts and does not have the status accepted, pending or in-progress. Permanent state.

abandoned

Request expired and has at least one document provided. Permanent state.

expired

Request expired without any document uploaded. Permanent state.

redirectUrl
string <uri>

The URL to redirect the customer when an upload is completed. When the customer is redirected, Rebilly will append an info query parameter which may have one of the following values (example: https://example.com?info=success):

  • back - The customer clicked the back to website link;
  • token_expired - The customer's token expired;
  • success - The customer uploaded docs that were successfully analyzed;
  • manual - The customer uploaded docs that will require manual review because the analyzer rejected them or couldn't process them;
  • partial - The customer had success with some doc type but not with other (for example, successful proof of address but skipped proof of id).
expirationTime
string <date-time>

Expiration date-time. Default value is one hour in the future.

createdTime
string <date-time>

Creation date-time.

updatedTime
string <date-time> (UpdatedTime)

Read-only timestamp. This value updates when the resource is updated.

Array of Self (object) or KycDocumentsLink (object) non-empty

Related resource links.

Array (non-empty)
Any of:
href
required
string

Link URL.

rel
required
string

Type of link.

Value: "self"
object

Embedded objects that are requested by the expand query parameter..

Array of any (StorefrontKycDocument)
Array
documentType
required
string

Document type submitted for validation, only identity-proof type is analyzed in an automated manner.

status
required
string

Status of the validation.

Enum: Description
pending

Waiting to be reviewed or analyzed

in-progress

Being analyzed by Rebilly's AI

accepted

Accepted by AI or a human

rejected

Rejected by AI or a human

archived

Archived by Rebilly's AI

id
string <= 50 characters

Unique resource ID. Defaults to UUID v4.

fileId
string <= 50 characters
Deprecated

Linked file object id.

fileIds
Array of strings

Linked file object id's.

Files uploaded for identity-proof must have following corresponding tags attached ['kyc', 'id-front'], ['kyc', 'id-back'], ['kyc', 'face-proof'] in order to be properly recognized as identity-proof files.

documentSubtype
string

Document subtype submitted for validation.

Enum: "passport" "id-card" "driver-license" "birth-certificate" "utility-bill" "rental-receipt" "lease-agreement" "copy-credit-card" "credit-card-statement" "bank-statement" … 16 more
object (KycDocumentRejection)
requestId
string or null <= 50 characters

KYC request identifier string.

createdTime
string <date-time>

Creation date/time.

updatedTime
string <date-time> (UpdatedTime)

Read-only timestamp. This value updates when the resource is updated.

processedTime
string <date-time>

Processing date/time.

object
Array of Self (object) non-empty

Related resource links.

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",
  • "documents": [
    ],
  • "status": "gathering",
  • "redirectUrl": "http://example.com",
  • "expirationTime": "2019-08-24T14:15:22Z",
  • "createdTime": "2019-08-24T14:15:22Z",
  • "updatedTime": "2019-08-24T14:15:22Z",
  • "_links": [
    ],
  • "_embedded": {
    }
}