Skip to content
API References
/
/
Begin KYB application pro...

PII (1.0.0)

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 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, 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, 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.

Download OpenAPI description
openapi.json
openapi.yaml
Overview
URL
https://www.tilia-inc.com
Tilia, Inc.
tilia@lindenlab.com
License
Tilia, Inc.
Languages
Servers
Mock server
https://docs.tilia.io/_mock/openapi/prod/pii/openapi/
Production Environment
https://pii.tilia-inc.com/
Staging Environment
https://pii.staging.tilia-inc.com/

webhooks

Webhooks

Check KYC status

Request

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.

Security
tilia_auth
Path
account_idstring(AccountId)<= 36 charactersrequired

The account ID to retrieve.

Example: acct_2TiDFXHVFMlAuyy7ovvz3YPKv9b
curl -i -X GET \
  https://docs.tilia.io/_mock/openapi/prod/pii/openapi/v1/kyc/acct_2TiDFXHVFMlAuyy7ovvz3YPKv9b \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>'

Responses

Successfully retrieved KYC status.

Bodyapplication/json
statusstring

The status of the request, either Success or Failure.

Example: "Success"
messageArray of strings

An array of short, human-readable messages describing the failure. If the request was successful, this array will be empty.

Example: null
codesArray of strings

An array of failure reason codes. If the request was successful, this array will be empty.

Example: null
payloadobject(GetAccountKYC)
Response
application/json
{
  "status": "Success",
  "message": null,
  "codes": null,
  "payload": {
    "account_id": "acct_2TiDFXHVFMlAuyy7ovvz3YPKv9b",
    "kyc_id": "kyc_2V2VpXKr8kW6ukYe03VG1QBlnxd",
    "kyc_requirements": "FULL_KYC",
    "match_checks": [ … ],
    "pii_level": "BASIC",
    "state": "ACCEPT"
  }
}

Set Account KYC to State

Request

[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.

Security
tilia_auth
Path
account_idstring(AccountId)<= 36 charactersrequired

The account ID to set.

Example: acct_2TiDFXHVFMlAuyy7ovvz3YPKv9b
Bodyapplication/json
statestringrequired

The state to set this account to. Must be one of ACCEPT, MANUAL_REVIEW, DENY, CANCEL, NODATA

pii_levelstring

The PII level to set this account to. Must be one of BASIC, FULL, DEFAULT

kyc_requirementsstring

The KYC requirements to set this account to. Must be one of NONE, FULL_KYC, TAX_UPDATE. An empty value is allowed.

curl -i -X PUT \
  https://docs.tilia.io/_mock/openapi/prod/pii/openapi/v2/kyc/account/acct_2TiDFXHVFMlAuyy7ovvz3YPKv9b/state \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "state": "string",
    "pii_level": "string",
    "kyc_requirements": "string"
  }'

Responses

No response body

Begin KYB application process

Request

Submits a request for a know your business (KYB) application

Security
tilia_auth
Path
account_idstring(AccountId)<= 36 charactersrequired

Tilia account ID with which the business entity will be associated

Example: acct_2TiDFXHVFMlAuyy7ovvz3YPKv9b
Bodyapplication/jsonrequired

KYB Entity Onboard Request

user_emailstring

Email that will receive the link to the KYB application form

If left blank, the email associated with the account_id in the route will be used.

Example: "testing@tilia.com"
entity_namestringrequired

Entity's legal name

Example: "Tilia Entity"
custom_application_idstring
Example: "9a2beeb0-ed09-4c69-9627-786eb6d2df33"
jurisdictionstringrequired

Type of application being requested

Possible values:

  • domestic
  • international
Example: "domestic"
curl -i -X POST \
  https://docs.tilia.io/_mock/openapi/prod/pii/openapi/v1/entity/acct_2TiDFXHVFMlAuyy7ovvz3YPKv9b/onboard \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "user_email": "testing@tilia.com",
    "entity_name": "Tilia Entity",
    "custom_application_id": "9a2beeb0-ed09-4c69-9627-786eb6d2df33",
    "jurisdiction": "domestic"
  }'

Responses

A new KYB application process has begun

Bodyapplication/json
statusstring

The status of the request, either Success or Failure.

Example: "Success"
messageArray of strings

An array of short, human-readable messages describing the failure. If the request was successful, this array will be empty.

Example: null
codesArray of strings

An array of failure reason codes. If the request was successful, this array will be empty.

Example: null
payloadobject(KYBOnboardResponse)
Response
application/json
{
  "status": "Success",
  "message": null,
  "codes": null,
  "payload": {
    "entity_id": "ent_2V2RYOBpuscTtZmpDhlTWeJtJdw",
    "vendor_response": { … }
  }
}