# Request KYC documents using the Rebilly API

This topic describes how to request Know Your Customer (KYC) documents from customers using the Rebilly API. The KYC process compares customer data against data in documents to verify a match. For information on KYC and how to use it in the Rebilly UI, see [KYC](/docs/kyc-and-aml/kyc).

To use this features, you must activate the Rebilly KYC add-on. For more information, see [KYC & AML](/docs/kyc-and-aml).

## Prerequisites

To complete this guide, you need customer data. To obtain customer data, see [Retrieve a customer](/docs/dev-docs/api/customers/getcustomer) or [Upsert a customer](/docs/dev-docs/api/customers/putcustomer).

## Gathering docs


```mermaid
sequenceDiagram
    participant Your app
    participant Customer
    participant Rebilly
    Customer->>Your app: Press to "KYC"
    Your app->>Rebilly: Create a "KYC Request"
    alt status is fulfilled due to credit file success
      Rebilly-->>Your app: Status fulfilled
    else status is not fulfilled
      Rebilly-->>Your app: Response with KYC gatherer link
      Your app-->>Customer: Redirect to KYC gatherer
      loop For each document...
        Customer->>Rebilly: Provide file (KYC document)
        Rebilly-->>Customer: File token reference
        Customer->>Rebilly: Analyze document by reference token
        alt is rejected
          Rebilly-->>Customer: Document rejected, correction suggestion (...)
        else is good
          Rebilly-->>Customer: All good
        end
      end
      Customer-->>Your app: Redirect
    end
```

1. Create a [PostKycRequest](/docs/dev-docs/api/kyc-documents/postkycrequest).
The following is a sample request body.

```json
{
  "documents": [
    {
      "type": "identity-proof",
      "faceProofRequired": true
    }
  ],
  "redirectUrl": "http://example.com",
  "customerId": "abc123"
}
```
The following is a sample response body.

```json
{
  "id": "4f6cf35x-2c4y-483z-a0a9-158621f77a21",
  "documents": [
    {
      "type": "identity-proof",
      "maxAttempts": 3,
      "faceProofRequired": true
    }
  ],
  "status": "pending",
  "redirectUrl": "http://example.com",
  "expirationTime": "2022-08-24T14:15:22Z",
  "createdTime": "2022-08-24T14:15:22Z",
  "updatedTime": "2022-08-24T14:15:22Z",
  "customerId": "abc123",
  "reason": "",
  "matchLevel": 2,
  "_links": [
    {
      "rel": "self",
      "href": "https://example.rebilly.com"
    },
    {
      "rel": "kycGatherer",
      "href": "https://verification.comply.services/?token=123"
    }
  ]
}
```
If the response `status` is `fulfilled` the process is complete, which might happen with an instant process such as a credit file lookup.
The response includes a related link `kycGatherer` resource in the `_links` collection.
Use the corresponding `href` value in the next step.
2. Redirect the customer to the `href` value of that `kycGatherer` link.
When the customer completes the process, they return to the `redirectUrl` with an `info` query parameter appended to the URL.


## Webhooks

Use webhooks to stay updated about the status of KYC documents. Subscribe to these events:

- [KYC request fulfilled](/docs/dev-docs/api/kyc-documents/kyc-request-fulfilled/)
- [KYC document modified](/docs/dev-docs/api/kyc-documents/kyc-document-modified/)
- [KYC document reviewed](/docs/dev-docs/api/kyc-documents/kyc-document-reviewed/)
- [KYC document accepted](/docs/dev-docs/api/kyc-documents/kyc-document-accepted/)
- [KYC document rejected](/docs/dev-docs/api/kyc-documents/kyc-document-rejected/)


![kyc-webhooks-setup](/assets/kyc-webhooks.0a92c9614294440a4fda28c9d65720f9b499e35121f1d87b4b87753c9a9cafca.a8224ebd.png)

[Learn more about webhooks](/docs/dev-docs/webhooks-configuration)