# PII

Use this API to verify the Know Your Customer (KYC) status for an account.

Tilia ensures your payout transactions meet KYC requirements by gathering and verifying your customer's identity information and related documents.

Users wishing to receive [payouts](./invoicing/operation/requestPayout/) are required to submit KYC data, which must be validated and accepted by Tilia before funds can be released. Users submit KYC data via the [KYC flow](/web-uis/kyc-flow/), which may be called as a standalone or as part of the payout flow.

Whether or not your service should check KYC status depends on whether or not you are supporting payouts. If so, prior to initiating a payout request, you'll want to

1. Check your customer's KYC status, and

2. Send the customer through the [KYC flow](/web-uis/kyc-flow/), if necessary.

KYC verification occurs both synchronously and asynchronously, and users may need to submit their KYC details more than once.

KYC information can not be modified through this API. Any changes must be made through Tilia Customer Support.

Version: 1.0.0
License: Tilia, Inc.

## Servers

Production Environment
```
https://pii.tilia-inc.com
```

Staging Environment
```
https://pii.staging.tilia-inc.com
```

## Security

### tilia_auth

Type: oauth2

### user_context

When making an API request that is either returning personalized customer data or acting on behalf of a customer, the customer's consent is required.

Type: oauth2
Token URL: auth.tilia-inc.com/token
Scopes:
- `read_kyc`: Grants permission to read an account's KYC state
- `read_kycs`: Grants permission to read the KYC state of multiple accounts
- `verify_kyc`: Grants permission to create a KYC verification session for an account

## Download OpenAPI description

[PII](https://thunes-tilia-docs.redocly.app/_bundle/openapi/prod/pii/openapi.yaml)

## Other

### KYC state changed

 - [POST kyc_status](https://thunes-tilia-docs.redocly.app/openapi/prod/pii/openapi/webhooks/kycstatus.md): Webhook event notification request.


event_name value: kyc-webhook


| This request is sent to registered webhook event handlers after |
| :--- |
| A user updates their KYC information or their status changes during the KYC review process. |


The Request body described below is the message property in the event notification request data. For more information about event notification requests, visit Webhooks.

### KYB status change

 - [POST kyb_status_change](https://thunes-tilia-docs.redocly.app/openapi/prod/pii/openapi/webhooks/kybstatuschange.md): Webhook event notification request.


| This request is sent to registered webhook event handlers after |
| :--- |
| An entity's KYB status changes |


The Request body described below is the message property in the event notification request data. For more information about event notification requests, visit Webhooks.

### Check KYC status

 - [GET /v1/kyc/{account_id}](https://thunes-tilia-docs.redocly.app/openapi/prod/pii/openapi/other/getkycstatus.md): Retrieves the status of the latest KYC information submitted for the account and an array of matched account scores.

Each matched account score indicates how similar the KYC application data matches existing PII. A match score of 1.0 is a perfect match.

IMPORTANT: Accounts must have accepted KYC data on file in order to accrue a balance that may be paid out. If the KYC state is NODATA, DENY, or CANCEL, direct the user to resubmit KYC data using the KYC flow.

### Set Account KYC to State

 - [PUT /v2/kyc/account/{account_id}/state](https://thunes-tilia-docs.redocly.app/openapi/prod/pii/openapi/other/setaccountkycstate.md): [STAGING ONLY] Sets an Account KYC state to the state specified in the payload. Can optionally set the PII level and/or KYC requirements. This API is meant for integration testing purposes.

### Begin KYB application process

 - [POST /v1/entity/{account_id}/onboard](https://thunes-tilia-docs.redocly.app/openapi/prod/pii/openapi/other/kybentityonboard.md): Submits a request for a know your business (KYB) application