{
  "openapi": "3.0.1",
  "info": {
    "title": "PII",
    "description": "Use this API to verify the Know Your Customer (KYC) status for an account.\n\nTilia ensures your payout transactions meet KYC requirements by gathering and verifying your customer's identity information and related documents.\n\nUsers 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.\n\nWhether 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\n\n1. Check your customer's KYC status, and\n\n2. Send the customer through the [KYC flow](/web-uis/kyc-flow/), if necessary.\n\nKYC verification occurs both synchronously and asynchronously, and users may need to submit their KYC details more than once.\n\nKYC information can not be modified through this API. Any changes must be made through Tilia Customer Support.",
    "contact": {
      "name": "Tilia, Inc.",
      "url": "https://www.tilia-inc.com",
      "email": "tilia@lindenlab.com"
    },
    "version": "1.0.0",
    "license": {
      "name": "Tilia, Inc.",
      "url": "https://www.tilia-inc.com/contact/"
    }
  },
  "servers": [
    {
      "url": "https://pii.tilia-inc.com",
      "description": "Production Environment"
    },
    {
      "url": "https://pii.staging.tilia-inc.com",
      "description": "Staging Environment"
    }
  ],
  "paths": {
    "/v1/kyc/{account_id}": {
      "get": {
        "summary": "Check KYC status",
        "description": "Retrieves the status of the latest KYC information submitted for the account and an array of matched account scores.\n\nEach matched account score indicates how similar the KYC application data matches existing PII. A match score of 1.0 is a perfect match.\n\nIMPORTANT: 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.",
        "parameters": [
          {
            "name": "account_id",
            "in": "path",
            "description": "The account ID to retrieve.",
            "required": true,
            "schema": {
              "$ref": "#/components/schemas/AccountId"
            }
          }
        ],
        "operationId": "GetKYCStatus",
        "responses": {
          "200": {
            "$ref": "#/components/responses/kycStatus"
          },
          "400": {
            "$ref": "#/components/responses/invalid"
          },
          "401": {
            "$ref": "#/components/responses/unauthorized"
          },
          "500": {
            "$ref": "#/components/responses/serverError"
          }
        },
        "security": [
          {
            "tilia_auth": [
              "read_kycs"
            ]
          }
        ]
      }
    },
    "/v2/kyc/account/{account_id}/state": {
      "put": {
        "summary": "Set Account KYC to State",
        "description": "[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.",
        "operationId": "SetAccountKYCState",
        "parameters": [
          {
            "name": "account_id",
            "in": "path",
            "description": "The account ID to set.",
            "required": true,
            "schema": {
              "$ref": "#/components/schemas/AccountId"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "required": [
                  "state"
                ],
                "type": "object",
                "properties": {
                  "state": {
                    "type": "string",
                    "description": "The state to set this account to. Must be one of ACCEPT, MANUAL_REVIEW, DENY, CANCEL, NODATA"
                  },
                  "pii_level": {
                    "type": "string",
                    "description": "The PII level to set this account to. Must be one of BASIC, FULL, DEFAULT"
                  },
                  "kyc_requirements": {
                    "type": "string",
                    "description": "The KYC requirements to set this account to. Must be one of NONE, FULL_KYC, TAX_UPDATE. An empty value is allowed."
                  }
                }
              }
            }
          },
          "required": false
        },
        "responses": {
          "200": {
            "description": "No response body"
          },
          "401": {
            "$ref": "#/components/responses/unauthorized"
          },
          "500": {
            "$ref": "#/components/responses/serverError"
          }
        },
        "security": [
          {
            "tilia_auth": [
              "write_kycs"
            ]
          }
        ]
      }
    },
    "/v1/entity/{account_id}/onboard": {
      "post": {
        "summary": "Begin KYB application process",
        "operationId": "KYBEntityOnboard",
        "description": "Submits a request for a know your business (KYB) application",
        "parameters": [
          {
            "name": "account_id",
            "in": "path",
            "description": "Tilia account ID with which the business entity will be associated",
            "required": true,
            "schema": {
              "$ref": "#/components/schemas/AccountId"
            }
          }
        ],
        "requestBody": {
          "description": "KYB Entity Onboard Request",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/KYBOnboardRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "description": "A new KYB application process has begun",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/BaseSuccess"
                    },
                    {
                      "type": "object",
                      "properties": {
                        "payload": {
                          "$ref": "#/components/schemas/KYBOnboardResponse"
                        }
                      }
                    }
                  ]
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/invalid"
          },
          "401": {
            "$ref": "#/components/responses/unauthorized"
          },
          "500": {
            "$ref": "#/components/responses/serverError"
          }
        },
        "security": [
          {
            "tilia_auth": [
              "write_entities"
            ]
          }
        ]
      }
    }
  },
  "x-webhooks": {
    "kyc_status": {
      "post": {
        "summary": "KYC state changed",
        "description": "Webhook event notification request.\n\n\n**`event_name` value:** `kyc-webhook`\n\n\n| This request is sent to registered webhook event handlers after |\n| :--- |\n| A user updates their KYC information or their status changes during the KYC review process. |\n\n\nThe Request body described below is the `message` property in the event notification request data. For more information about event notification requests, visit [Webhooks](/webhooks/#develop-a-webhook-event-handler).",
        "operationId": "kycStatus",
        "requestBody": {
          "$ref": "#/components/requestBodies/KYCStatus"
        },
        "responses": {
          "2XX": {
            "description": "Return a 2XX status to indicate that the data was received successfully"
          }
        },
        "security": [
          {
            "tilia_auth": []
          }
        ]
      }
    },
    "kyb_status_change": {
      "post": {
        "summary": "KYB status change",
        "description": "Webhook event notification request.\n\n\n| This request is sent to registered webhook event handlers after |\n| :--- |\n| An entity's KYB status changes |\n\n\nThe Request body described below is the `message` property in the event notification request data. For more information about event notification requests, visit [Webhooks](/webhooks/#develop-a-webhook-event-handler).",
        "operationId": "kybStatusChange",
        "requestBody": {
          "$ref": "#/components/requestBodies/KYBStatusChange"
        },
        "responses": {
          "2XX": {
            "description": "Return a 2XX status to indicate that the data was received successfully"
          }
        },
        "security": [
          {
            "tilia_auth": []
          }
        ]
      }
    }
  },
  "components": {
    "securitySchemes": {
      "tilia_auth": {
        "type": "oauth2",
        "flows": {
          "clientCredentials": {
            "tokenUrl": "https://auth.staging.tilia-inc.com/token",
            "scopes": {}
          }
        }
      },
      "user_context": {
        "type": "oauth2",
        "x-internal": true,
        "description": "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.",
        "flows": {
          "password": {
            "tokenUrl": "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"
            }
          }
        }
      }
    },
    "schemas": {
      "BaseSuccess": {
        "type": "object",
        "properties": {
          "status": {
            "type": "string",
            "description": "The status of the request, either `Success` or `Failure`.",
            "example": "Success"
          },
          "message": {
            "type": "array",
            "description": "An array of short, human-readable messages describing the failure. If the request was successful, this array will be empty.",
            "items": {
              "type": "string"
            },
            "example": null
          },
          "codes": {
            "type": "array",
            "description": "An array of failure reason codes. If the request was successful, this array will be empty.",
            "items": {
              "type": "string"
            },
            "example": null
          }
        }
      },
      "AccountId": {
        "type": "string",
        "maxLength": 36,
        "example": "acct_2TiDFXHVFMlAuyy7ovvz3YPKv9b"
      },
      "KYCId": {
        "type": "string",
        "maxLength": 36,
        "example": "kyc_2V2VpXKr8kW6ukYe03VG1QBlnxd"
      },
      "AccountKYC": {
        "type": "object",
        "properties": {
          "account_id": {
            "allOf": [
              {
                "description": "The account ID that this KYC data belongs to",
                "x-go-name": "AccountID"
              },
              {
                "$ref": "#/components/schemas/AccountId"
              }
            ]
          },
          "city": {
            "type": "string",
            "example": "Hollywood",
            "x-go-name": "City"
          },
          "country": {
            "type": "string",
            "example": "US",
            "x-go-name": "Country"
          },
          "created": {
            "type": "string",
            "description": "When this check occurred",
            "example": "2022-02-22 22:22:22.222222",
            "x-go-name": "Created"
          },
          "data_source": {
            "type": "string",
            "description": "This field denotes the system responsible for acquiring the data",
            "example": "idmind",
            "x-go-name": "DataSource"
          },
          "date_of_birth": {
            "type": "string",
            "example": "1948-03-02",
            "x-go-name": "DOB"
          },
          "document_back": {
            "type": "string",
            "example": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAADIAAAABCAYAAACc0f2yAAAAEElEQVR42mP8z8AAREMfAACNFAIAcYQyygAAAABJRU5ErkJggg==",
            "x-go-name": "DocBackFile"
          },
          "document_back_id": {
            "type": "string",
            "example": "doc_2Crgdd4GQ8CVapZH2YQRD9cobIR",
            "x-go-name": "DocBackID"
          },
          "document_country": {
            "type": "string",
            "example": "US",
            "x-go-name": "DocCountry"
          },
          "document_front": {
            "type": "string",
            "example": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAADIAAAABCAYAAACc0f2yAAAAEElEQVR42mP8z8AAREMfAACNFAIAcYQyygAAAABJRU5ErkJggg==",
            "x-go-name": "DocFrontFile"
          },
          "document_front_id": {
            "type": "string",
            "example": "doc_2CrgdcCZOoRrXKhzT4qjMGDGp0a",
            "x-go-name": "DocFrontID"
          },
          "document_type": {
            "type": "string",
            "example": "DL",
            "x-go-name": "DocType"
          },
          "extra_files": {
            "type": "array",
            "items": {
              "type": "string",
              "example": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAADIAAAABCAYAAACc0f2yAAAAEElEQVR42mP8z8AAREMfAACNFAIAcYQyygAAAABJRU5ErkJggg=="
            },
            "x-go-name": "ExtraFiles"
          },
          "first": {
            "type": "string",
            "example": "Cynthia",
            "x-go-name": "First"
          },
          "form_id": {
            "type": "string",
            "example": "59b517834ec7258258bt940ec615f77842ecb70d",
            "description": "The specific IDMind form that the user filled out to get this state",
            "x-go-name": "FormID"
          },
          "initiator": {
            "type": "string",
            "description": "KYC checks are initiated by compliance or the user",
            "example": "integrator",
            "x-go-name": "Initiator"
          },
          "integrator": {
            "type": "string",
            "description": "The integrator this KYC data belongs to",
            "example": "cool-company",
            "x-go-name": "Integrator"
          },
          "kyc_id": {
            "allOf": [
              {
                "description": "This ID begins as the nonce ID in a collect PII flow, and gets used\nas the idmind.Tid (transaction id) to identify the instance of the KYC collection",
                "x-go-name": "KYCID"
              },
              {
                "$ref": "#/components/schemas/KYCId"
              }
            ]
          },
          "last": {
            "type": "string",
            "example": "Ramos",
            "x-go-name": "Last"
          },
          "note": {
            "type": "string",
            "description": "An optional note provided when compliance initiated the KYC check",
            "example": "Canadian citizen",
            "x-go-name": "Note"
          },
          "phone_code": {
            "type": "string",
            "example": "+1",
            "x-go-name": "PhoneCode"
          },
          "phone_number": {
            "type": "string",
            "example": "888-888-8888",
            "x-go-name": "Phone"
          },
          "ssn_last4": {
            "type": "string",
            "example": "9999",
            "x-go-name": "SSNLast4"
          },
          "state": {
            "type": "string",
            "example": "CA",
            "description": "The most recent KYC state of this account",
            "x-go-name": "State"
          },
          "street": {
            "type": "string",
            "example": "1750 El Cerrito PL",
            "x-go-name": "Street"
          },
          "street2": {
            "type": "string",
            "example": "UNIT A",
            "x-go-name": "Street2"
          },
          "middle": {
            "type": "string",
            "example": "Anne Marie",
            "x-go-name": "Middle"
          },
          "signature": {
            "type": "string",
            "example": "Cynthia A M Ramos",
            "x-go-name": "Signature"
          },
          "document_address_mismatch": {
            "type": "boolean",
            "example": false,
            "x-go-name": "DocAddressMismatch"
          },
          "use_1099": {
            "type": "boolean",
            "example": true,
            "x-go-name": "Use1099"
          },
          "zip": {
            "type": "string",
            "example": "90028",
            "x-go-name": "Zip"
          },
          "updated": {
            "type": "string",
            "description": "Last time this check was updated",
            "example": "2022-02-22 22:22:22.222222",
            "x-go-name": "Updated"
          },
          "vendor_reference_id": {
            "type": "string",
            "description": "This is the unique ID in the vendor's (idmind) system for the txn that created this data",
            "example": "59b517834ec7258258c6940ec6143f77842ecb70d",
            "x-go-name": "VendorReferenceID"
          },
          "rules": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "example": [
              "dv:0",
              "ed:1"
            ]
          }
        },
        "x-go-package": "github.com/lindenlab/extraction-pii/lib/controllers"
      },
      "V2RegisterValidationErrors": {
        "type": "object",
        "properties": {
          "email": {
            "type": "string",
            "description": "Indicates a problem with the email address.",
            "x-go-name": "Email"
          },
          "password": {
            "type": "string",
            "description": "Indicates a problem with the password.",
            "x-go-name": "Password"
          },
          "tracking_id": {
            "type": "string",
            "description": "Indicates a problem with the tracking ID.",
            "x-go-name": "TrackingId"
          },
          "username": {
            "type": "string",
            "description": "Indicates a problem with the username.",
            "example": "USERNAME_ALREADY_TAKEN",
            "x-go-name": "Username"
          }
        },
        "x-go-package": "github.com/lindenlab/extraction-registration/client/pb"
      },
      "Basic400Response": {
        "type": "object",
        "description": "The response payload.",
        "properties": {
          "errors": {
            "$ref": "#/components/schemas/V2RegisterValidationErrors"
          }
        },
        "x-go-package": "github.com/lindenlab/extraction-registration/client/pb"
      },
      "KYCCheckResponse": {
        "type": "object",
        "properties": {
          "account_id": {
            "allOf": [
              {
                "description": "The account ID that this KYC data belongs to",
                "x-go-name": "AccountID"
              },
              {
                "$ref": "#/components/schemas/AccountId"
              }
            ]
          },
          "city": {
            "type": "string",
            "x-go-name": "City"
          },
          "country": {
            "type": "string",
            "x-go-name": "Country"
          },
          "created": {
            "type": "string",
            "description": "When this check occurred",
            "x-go-name": "Created"
          },
          "data_source": {
            "type": "string",
            "description": "This field denotes the system responsible for acquiring the data",
            "x-go-name": "DataSource"
          },
          "date_of_birth": {
            "type": "string",
            "x-go-name": "DOB"
          },
          "document_back": {
            "type": "string",
            "x-go-name": "DocBackFile"
          },
          "document_back_id": {
            "type": "string",
            "x-go-name": "DocBackID"
          },
          "document_country": {
            "type": "string",
            "x-go-name": "DocCountry"
          },
          "document_front": {
            "type": "string",
            "x-go-name": "DocFrontFile"
          },
          "document_front_id": {
            "type": "string",
            "x-go-name": "DocFrontID"
          },
          "document_type": {
            "type": "string",
            "x-go-name": "DocType"
          },
          "extra_files": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "x-go-name": "ExtraFiles"
          },
          "first": {
            "type": "string",
            "x-go-name": "First"
          },
          "form_id": {
            "type": "string",
            "description": "The specific IDMind form that the user filled out to get this state",
            "x-go-name": "FormID"
          },
          "initiator": {
            "type": "string",
            "description": "KYC checks are initated by compliance or the user",
            "x-go-name": "Initiator"
          },
          "integrator": {
            "type": "string",
            "description": "The integrator this kyc data belongs to",
            "x-go-name": "Integrator"
          },
          "kyc_id": {
            "allOf": [
              {
                "description": "This ID begins as the nonce ID in a collect PII flow, and gets used\nas the idmind.Tid (transaction id) to identify the instance of the KYC collection",
                "x-go-name": "KYCID"
              },
              {
                "$ref": "#/components/schemas/KYCId"
              }
            ]
          },
          "last": {
            "type": "string",
            "x-go-name": "Last"
          },
          "note": {
            "type": "string",
            "description": "An optional note provided when compliance initiated the KYC check",
            "x-go-name": "Note"
          },
          "phone_code": {
            "type": "string",
            "x-go-name": "PhoneCode"
          },
          "phone_number": {
            "type": "string",
            "x-go-name": "Phone"
          },
          "pii_collection_uri": {
            "type": "string",
            "description": "This URI is the location to redirect the customer so they can fill out the KYC form\nIt only exists if `state` is not an accept state.",
            "x-go-name": "PIICollectionURI"
          },
          "ssn_last4": {
            "type": "string",
            "x-go-name": "SSNLast4"
          },
          "state": {
            "type": "string",
            "description": "The most recent KYC state of this account",
            "x-go-name": "State"
          },
          "street": {
            "type": "string",
            "x-go-name": "Street"
          },
          "updated": {
            "type": "string",
            "description": "Last time this check was updated",
            "x-go-name": "Updated"
          },
          "vendor_reference_id": {
            "type": "string",
            "description": "This is the unique ID in the vendor's (idmind) system for the txn that created this data",
            "x-go-name": "VendorReferenceID"
          },
          "zip": {
            "type": "string",
            "x-go-name": "Zip"
          }
        },
        "x-go-package": "github.com/lindenlab/extraction-pii/lib/controllers"
      },
      "SearchResponse": {
        "type": "object",
        "properties": {
          "applications": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/AccountKYC"
            },
            "x-go-name": "Applications"
          },
          "record_count": {
            "type": "integer",
            "format": "int64",
            "x-go-name": "RecordCount"
          }
        },
        "description": "SearchResponse is the response payload from POST /kyc/search",
        "x-go-package": "github.com/lindenlab/extraction-pii/lib/controllers"
      },
      "KYCMatchCheck": {
        "type": "object",
        "properties": {
          "kyc_match_check_id": {
            "type": "string",
            "description": "KYC match check ID",
            "example": "kycmc_2E5Osjju8K0KpDAXWknVJ7My1wL",
            "x-go-name": "KYCMatchCheckID"
          },
          "matched_account_id": {
            "allOf": [
              {
                "description": "Tilia account ID of the account that matched the PII",
                "x-go-name": "MatchedAccountID"
              },
              {
                "$ref": "#/components/schemas/AccountId"
              }
            ]
          },
          "matched_kyc_id": {
            "allOf": [
              {
                "description": "KYC ID of the matching PII",
                "x-go-name": "MatchedKYCID"
              },
              {
                "$ref": "#/components/schemas/KYCId"
              }
            ]
          },
          "match_score": {
            "type": "number",
            "description": "Score (between 0.0 and 1.0) of the match",
            "example": 0.99,
            "x-go-name": "MatchScore"
          }
        }
      },
      "GetAccountKYC": {
        "type": "object",
        "properties": {
          "account_id": {
            "allOf": [
              {
                "description": "The Tilia account ID.",
                "x-go-name": "AccountID"
              },
              {
                "$ref": "#/components/schemas/AccountId"
              }
            ]
          },
          "kyc_id": {
            "allOf": [
              {
                "description": "KYC application ID",
                "x-go-name": "KYCID"
              },
              {
                "$ref": "#/components/schemas/KYCId"
              }
            ]
          },
          "kyc_requirements": {
            "type": "string",
            "description": "Describes an account's KYC requirements.\n\nPossible values are listed in the following table.\n\n| Value | Description |\n| :-----| :-------|\n| `FULL_KYC`   | The account must go through KYC in order to accrue a stored value balance and receive payouts.|\n| `NONE`  | The account does not have additional PII verification requirements.|\n| `TAX_UPDATE`   | The account must update their information on file for tax purposes.|",
            "example": "FULL_KYC",
            "x-go-name": "KYCRequirements"
          },
          "match_checks": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/KYCMatchCheck"
            }
          },
          "pii_level": {
            "type": "string",
            "description": "Describes the state of PII associated with an account.\n\nPossible values are listed in the following table.\n\n| Value | Description |\n| :-----| :-------|\n| `BASIC`   | The account's PII exists and can be used for tax purposes, but is not verified.|\n| `NONE`  | The account has no associated PII.|\n| `FULL`   | The account's PII exists and its KYC state is ACCEPT.|",
            "example": "BASIC",
            "x-go-name": "PIILevel"
          },
          "state": {
            "type": "string",
            "description": "Identity verification (KYC or KYB) state of this account.\n\nPossible values are listed in the following table. \n\n| Value | Description |\n| :----- | :-------|\n| `ACCEPT`   | KYC (or KYB) data has been accepted.|\n| `CANCEL` | Tilia's Compliance Team reached out to the user for more info and never received a response. The user can submit a new KYC application.|\n| `DENY`   | KYC data has been rejected. New KYC data may be submitted.|\n| `MANUAL_REVIEW`  | The account's KYC data is under manual review by the Tilia Compliance Team.|\n| `NODATA`   | \tNo information has been collected for the account|\n| `NONE`   | Information has been successfully collected for tax purposes, KYC has not been run.| \n| `PROCESSING`   | KYC data is being actively processed.|\n| `REVERIFY`  | (Legacy) User needs to resubmit a new KYC application.|\n| `SYSTEM-CANCELLED` | Application canceled by the system due to incorrect or incomplete information provided. The user can submit a new KYC application.|",
            "example": "ACCEPT",
            "x-go-name": "State"
          }
        }
      },
      "KYBEntityId": {
        "type": "string",
        "maxLength": 36,
        "example": "ent_2V2RYOBpuscTtZmpDhlTWeJtJdw"
      },
      "KYBEntityAgentId": {
        "type": "string",
        "maxLength": 36,
        "example": "agt_2V2Sp6EOWcEuqaQpV4MlrHAI3ss"
      },
      "KYBEntityDocumentId": {
        "type": "string",
        "maxLength": 36,
        "example": "doc_2V2TeCaZzRKrie8xcqMcdnFRmP5"
      },
      "KYBEntityDocument": {
        "type": "object",
        "properties": {
          "entity_document_id": {
            "allOf": [
              {
                "description": "The TUID of the entity document.",
                "x-go-name": "EntityDocumentID"
              },
              {
                "$ref": "#/components/schemas/KYBEntityDocumentId"
              }
            ]
          },
          "entity_id": {
            "allOf": [
              {
                "description": "The TUID of the entity the document is associated with.",
                "x-go-name": "EntityID"
              },
              {
                "$ref": "#/components/schemas/KYBEntityId"
              }
            ]
          },
          "entity_agent_id": {
            "allOf": [
              {
                "description": "The ID of the agent this document is associated with. If empty, document is for the whole entity.",
                "x-go-name": "EntityAgentID"
              },
              {
                "$ref": "#/components/schemas/KYBEntityAgentId"
              }
            ]
          },
          "pii_document_name": {
            "type": "string",
            "description": "Name of the document",
            "x-go-name": "PIIDocumentName"
          },
          "pii_document_id": {
            "type": "string",
            "description": "PII ID for the document",
            "x-go-name": "PIIDocumentID"
          },
          "file": {
            "type": "string",
            "description": "base64 encoded file",
            "x-go-name": "file",
            "example": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAADIAAAABCAYAAACc0f2yAAAAEElEQVR42mP8z8AAREMfAACNFAIAcYQyygAAAABJRU5ErkJggg=="
          },
          "mime_type": {
            "type": "string",
            "description": "mime type of file",
            "x-go-name": "mime_type",
            "example": "image/png"
          },
          "created": {
            "type": "string",
            "description": "Date the document was created",
            "x-go-name": "Created"
          },
          "updated": {
            "type": "string",
            "description": "The last date the document was updated",
            "x-go-name": "Updated"
          }
        },
        "x-go-package": "github.com/lindenlab/extraction-pii/lib/models"
      },
      "KYBEntityAgent": {
        "type": "object",
        "properties": {
          "entity_agent_id": {
            "allOf": [
              {
                "description": "The TUID of the entity agent.",
                "x-go-name": "EntityAgentID"
              },
              {
                "$ref": "#/components/schemas/KYBEntityAgentId"
              }
            ]
          },
          "entity_id": {
            "allOf": [
              {
                "description": "The TUID of the entity the agent is associated with.",
                "x-go-name": "EntityID"
              },
              {
                "$ref": "#/components/schemas/KYBEntityId"
              }
            ]
          },
          "agent_name": {
            "type": "string",
            "description": "The agent's full name.",
            "x-go-name": "AgentName"
          },
          "account_id": {
            "allOf": [
              {
                "description": "The agent's account ID.",
                "x-go-name": "AccountID"
              },
              {
                "$ref": "#/components/schemas/AccountId"
              }
            ]
          },
          "status": {
            "type": "string",
            "description": "ACCEPT, PROCESSING, INCOMPLETE, CANCEL, DENY, INACTIVE.",
            "x-go-name": "Status"
          },
          "kyc_status": {
            "type": "string",
            "description": "The KYC status for the agent.",
            "x-go-name": "KYCStatus"
          },
          "created": {
            "type": "string",
            "description": "Date the agent was created",
            "x-go-name": "Created"
          },
          "updated": {
            "type": "string",
            "description": "The last date the agent was updated",
            "x-go-name": "Updated"
          },
          "roles": {
            "type": "array",
            "items": {
              "type": "string",
              "description": "The agent's role."
            },
            "x-go-name": "Roles"
          },
          "documents": {
            "type": "array",
            "items": {
              "allOf": [
                {
                  "$ref": "#/components/schemas/KYBEntityDocument"
                }
              ]
            }
          }
        },
        "x-go-package": "github.com/lindenlab/extraction-pii/lib/models"
      },
      "KYBEntity": {
        "type": "object",
        "properties": {
          "entity_id": {
            "allOf": [
              {
                "description": "The TUID of the entity.",
                "x-go-name": "EntityID"
              },
              {
                "$ref": "#/components/schemas/KYBEntityId"
              }
            ]
          },
          "entity_name": {
            "type": "string",
            "description": "The name of the entity",
            "x-go-name": "EntityName"
          },
          "tax_id": {
            "type": "string",
            "description": "US EIN or tax id",
            "x-go-name": "TaxID"
          },
          "naics_numbers": {
            "type": "string",
            "description": "Comma-separated list of 6-digit North American Industry Classificaiton System (NAICS) codes.",
            "x-go-name": "NAICSNumbers"
          },
          "duns_numbers": {
            "type": "string",
            "description": "Comma-separated list of 9-digit Dun & Bradstreet (DUNS) numbers.",
            "x-go-name": "DUNSNumbers"
          },
          "account_id": {
            "allOf": [
              {
                "description": "ID of the Tilia account used to create the entity",
                "x-go-name": "AccountID"
              },
              {
                "$ref": "#/components/schemas/AccountId"
              }
            ]
          },
          "entity_type": {
            "type": "string",
            "description": "Type of entity.",
            "x-go-name": "EntityType"
          },
          "status": {
            "type": "string",
            "description": "ACCEPT, PROCESSING, INCOMPLETE, CANCEL, DENY, INACTIVE.",
            "x-go-name": "Status"
          },
          "created": {
            "type": "string",
            "description": "Date the entity was created.",
            "x-go-name": "Created"
          },
          "updated": {
            "type": "string",
            "description": "The last date the entity was updated.",
            "x-go-name": "Updated"
          },
          "agents": {
            "type": "array",
            "items": {
              "allOf": [
                {
                  "$ref": "#/components/schemas/KYBEntityAgent"
                }
              ]
            }
          },
          "documents": {
            "type": "array",
            "items": {
              "allOf": [
                {
                  "$ref": "#/components/schemas/KYBEntityDocument"
                }
              ]
            }
          }
        },
        "x-go-package": "github.com/lindenlab/extraction-pii/lib/models"
      },
      "BasicResponse": {
        "type": "object",
        "properties": {
          "status": {
            "type": "string",
            "description": "The status of the request, either `Success` or `Failure`.",
            "example": "Success",
            "x-go-name": "Status"
          },
          "message": {
            "type": "array",
            "description": "An array of short, human-readable messages describing the failure. If the request was successful, this array will be empty.",
            "items": {
              "type": "string"
            },
            "example": [],
            "x-go-name": "Message"
          },
          "codes": {
            "type": "array",
            "description": "An array of failure reason codes. If the request was successful, this array will be empty.",
            "items": {
              "type": "string"
            },
            "example": [],
            "x-go-name": "Codes"
          },
          "payload": {
            "type": "object",
            "properties": {},
            "description": "The response payload.",
            "x-go-name": "Payload"
          }
        }
      },
      "AccountKYCWithMatchCheck": {
        "type": "object",
        "properties": {
          "account_id": {
            "allOf": [
              {
                "description": "Account ID to which this KYC data belongs",
                "x-go-name": "AccountID"
              },
              {
                "$ref": "#/components/schemas/AccountId"
              }
            ]
          },
          "city": {
            "type": "string",
            "example": "Hollywood",
            "x-go-name": "City"
          },
          "country": {
            "type": "string",
            "example": "US",
            "x-go-name": "Country"
          },
          "created": {
            "type": "string",
            "description": "Date when the check occurred in `YYYY-MM-DD HH:MM:SS.ssssss` format",
            "example": "2022-02-22 22:22:22.222222",
            "x-go-name": "Created"
          },
          "data_source": {
            "type": "string",
            "description": "Denotes the system responsible for acquiring the data",
            "example": "idmind",
            "x-go-name": "DataSource"
          },
          "date_of_birth": {
            "type": "string",
            "example": "1948-03-02",
            "x-go-name": "DOB"
          },
          "document_back": {
            "type": "string",
            "example": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAADIAAAABCAYAAACc0f2yAAAAEElEQVR42mP8z8AAREMfAACNFAIAcYQyygAAAABJRU5ErkJggg==",
            "x-go-name": "DocBackFile"
          },
          "document_back_id": {
            "type": "string",
            "example": "doc_2Crgdd4GQ8CVapZH2YQRD9cobIR",
            "x-go-name": "DocBackID"
          },
          "document_country": {
            "type": "string",
            "example": "US",
            "x-go-name": "DocCountry"
          },
          "document_front": {
            "type": "string",
            "example": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAADIAAAABCAYAAACc0f2yAAAAEElEQVR42mP8z8AAREMfAACNFAIAcYQyygAAAABJRU5ErkJggg==",
            "x-go-name": "DocFrontFile"
          },
          "document_front_id": {
            "type": "string",
            "example": "doc_2CrgdcCZOoRrXKhzT4qjMGDGp0a",
            "x-go-name": "DocFrontID"
          },
          "document_type": {
            "type": "string",
            "example": "DL",
            "x-go-name": "DocType"
          },
          "extra_files": {
            "type": "array",
            "items": {
              "type": "string",
              "example": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAADIAAAABCAYAAACc0f2yAAAAEElEQVR42mP8z8AAREMfAACNFAIAcYQyygAAAABJRU5ErkJggg=="
            },
            "x-go-name": "ExtraFiles"
          },
          "first": {
            "type": "string",
            "example": "Cynthia",
            "x-go-name": "First"
          },
          "form_id": {
            "type": "string",
            "example": "59b517834ec7258258bt940ec615f77842ecb70d",
            "description": "Specific IDMind form that the user filled out to get this state",
            "x-go-name": "FormID"
          },
          "initiator": {
            "type": "string",
            "description": "Indicates who starts the KYC checks",
            "example": "integrator",
            "x-go-name": "Initiator"
          },
          "integrator": {
            "type": "string",
            "description": "Integrator to which this KYC data belongs",
            "example": "cool-company",
            "x-go-name": "Integrator"
          },
          "kyc_id": {
            "allOf": [
              {
                "description": "This ID begins as the nonce ID in a collect PII flow, and gets used\nas the idmind.Tid (transaction id) to identify the instance of the KYC collection",
                "x-go-name": "KYCID"
              },
              {
                "$ref": "#/components/schemas/KYCId"
              }
            ]
          },
          "last": {
            "type": "string",
            "example": "Ramos",
            "x-go-name": "Last"
          },
          "note": {
            "type": "string",
            "description": "Optional note provided when the compliance team has initiated the KYC check",
            "example": "Canadian citizen",
            "x-go-name": "Note"
          },
          "phone_code": {
            "type": "string",
            "example": "+1",
            "x-go-name": "PhoneCode"
          },
          "phone_number": {
            "type": "string",
            "example": "888-888-8888",
            "x-go-name": "Phone"
          },
          "ssn_last4": {
            "type": "string",
            "example": "9999",
            "x-go-name": "SSNLast4"
          },
          "state": {
            "type": "string",
            "example": "CA",
            "description": "Most recent KYC state of this account",
            "x-go-name": "State"
          },
          "street": {
            "type": "string",
            "example": "1750 El Cerrito PL",
            "x-go-name": "Street"
          },
          "street2": {
            "type": "string",
            "example": "UNIT A",
            "x-go-name": "Street2"
          },
          "middle": {
            "type": "string",
            "example": "Anne Marie",
            "x-go-name": "Middle"
          },
          "signature": {
            "type": "string",
            "example": "Cynthia A M Ramos",
            "x-go-name": "Signature"
          },
          "document_address_mismatch": {
            "type": "boolean",
            "example": false,
            "x-go-name": "DocAddressMismatch"
          },
          "use_1099": {
            "type": "boolean",
            "example": true,
            "x-go-name": "Use1099"
          },
          "zip": {
            "type": "string",
            "example": "90028",
            "x-go-name": "Zip"
          },
          "updated": {
            "type": "string",
            "description": "Date when the most recent update to this check occurred in `YYYY-MM-DD HH:MM:SS.ssssss` format",
            "example": "2022-02-22 22:22:22.222222",
            "x-go-name": "Updated"
          },
          "vendor_reference_id": {
            "type": "string",
            "description": "Unique ID in the vendor's (IDMind) system for the transaction that created this data",
            "example": "59b517834ec7258258c6940ec6143f77842ecb70d",
            "x-go-name": "VendorReferenceID"
          },
          "rules_bitch": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "example": [
              "dv:0",
              "ed:1"
            ]
          },
          "match_checks": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/KYCMatchCheck"
            }
          }
        },
        "x-go-package": "github.com/lindenlab/extraction-pii/lib/controllers"
      },
      "FileUpload": {
        "type": "object",
        "properties": {
          "file_contents": {
            "type": "array",
            "description": "base64 encoded file",
            "example": "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mNk+A8AAQUBAScY42YAAAAASUVORK5CYII",
            "x-go-name": "FileContents"
          },
          "file_name": {
            "type": "string",
            "description": "The name of the file",
            "example": "my_bill",
            "x-go-name": "FileName"
          },
          "file_ext": {
            "type": "string",
            "description": "The extension of the file",
            "example": ".pdf",
            "x-go-name": "FileExt"
          },
          "file_mime_type": {
            "type": "string",
            "description": "Media Type of the file",
            "example": "application/pdf",
            "x-go-name": "FileMimeType"
          }
        },
        "x-go-package": "github.com/lindenlab/extraction-pii/lib/models"
      },
      "AccountKYCRequest": {
        "type": "object",
        "properties": {
          "city": {
            "type": "string",
            "example": "Hollywood",
            "x-go-name": "City"
          },
          "country": {
            "type": "string",
            "example": "US",
            "x-go-name": "Country"
          },
          "date_of_birth": {
            "type": "string",
            "example": "1948-03-02",
            "x-go-name": "DOB"
          },
          "document_back": {
            "type": "string",
            "example": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAADIAAAABCAYAAACc0f2yAAAAEElEQVR42mP8z8AAREMfAACNFAIAcYQyygAAAABJRU5ErkJggg==",
            "x-go-name": "DocBackFile"
          },
          "document_country": {
            "type": "string",
            "example": "US",
            "x-go-name": "DocCountry"
          },
          "document_front": {
            "type": "string",
            "example": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAADIAAAABCAYAAACc0f2yAAAAEElEQVR42mP8z8AAREMfAACNFAIAcYQyygAAAABJRU5ErkJggg==",
            "x-go-name": "DocFrontFile"
          },
          "document_type": {
            "type": "string",
            "example": "DL",
            "x-go-name": "DocType"
          },
          "first": {
            "type": "string",
            "example": "Cynthia",
            "x-go-name": "First"
          },
          "last": {
            "type": "string",
            "example": "Ramos",
            "x-go-name": "Last"
          },
          "note": {
            "type": "string",
            "description": "An optional note provided when compliance initiated the KYC check",
            "example": "Canadian citizen",
            "x-go-name": "Note"
          },
          "phone_code": {
            "type": "string",
            "example": "+1",
            "x-go-name": "PhoneCode"
          },
          "phone_number": {
            "type": "string",
            "example": "888-888-8888",
            "x-go-name": "Phone"
          },
          "state": {
            "type": "string",
            "description": "The most recent KYC state of this account",
            "example": "CA",
            "x-go-name": "State"
          },
          "street": {
            "type": "string",
            "example": "1750 El Cerrito PL",
            "x-go-name": "Street"
          },
          "street2": {
            "type": "string",
            "example": "UNIT A",
            "x-go-name": "Street2"
          },
          "middle": {
            "type": "string",
            "example": "Anne Marie",
            "x-go-name": "Middle"
          },
          "signature": {
            "type": "string",
            "example": "Cynthia A M Ramos",
            "x-go-name": "Signature"
          },
          "document_address_mismatch": {
            "type": "boolean",
            "example": false,
            "x-go-name": "DocAddressMismatch"
          },
          "use_1099": {
            "type": "boolean",
            "example": true,
            "x-go-name": "Use1099"
          },
          "zip": {
            "type": "string",
            "example": "90028",
            "x-go-name": "Zip"
          },
          "ssn": {
            "type": "string",
            "example": "999-99-9999",
            "x-go-name": "SSN"
          },
          "extra_files": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/FileUpload"
            }
          }
        },
        "x-go-package": "github.com/lindenlab/extraction-pii/lib/controllers"
      },
      "CustomApplicationID": {
        "type": "string",
        "example": "9a2beeb0-ed09-4c69-9627-786eb6d2df33",
        "description": "Custom publisher ID used to track the application in the publisher's system"
      },
      "KYBOnboardRequest": {
        "type": "object",
        "required": [
          "entity_name",
          "jurisdiction"
        ],
        "properties": {
          "user_email": {
            "type": "string",
            "example": "testing@tilia.com",
            "description": "Email that will receive the link to the KYB application form\n\nIf left blank, the email associated with the `account_id` in the route will be used."
          },
          "entity_name": {
            "type": "string",
            "example": "Tilia Entity",
            "description": "Entity's legal name"
          },
          "custom_application_id": {
            "allOf": [
              {
                "$ref": "#/components/schemas/CustomApplicationID"
              }
            ]
          },
          "jurisdiction": {
            "type": "string",
            "example": "domestic",
            "description": "Type of application being requested\n\n**Possible values**:\n\n- `domestic`\n- `international`"
          }
        },
        "x-go-package": "github.com/lindenlab/extraction-pii/lib/controllers"
      },
      "VendorApplicationID": {
        "type": "string",
        "example": "12345",
        "description": "Application ID used to track your application through Tilia's underwriting service system"
      },
      "KYBOnboardResponse": {
        "type": "object",
        "properties": {
          "entity_id": {
            "allOf": [
              {
                "description": "Unique Tilia ID for your entity"
              },
              {
                "$ref": "#/components/schemas/KYBEntityId"
              }
            ]
          },
          "vendor_response": {
            "type": "object",
            "properties": {
              "vendor_application_id": {
                "allOf": [
                  {
                    "$ref": "#/components/schemas/VendorApplicationID"
                  }
                ]
              },
              "application_url": {
                "type": "string",
                "example": "www.claim-kyb-application.com/12345",
                "description": "URL used to complete the application"
              },
              "custom_application_id": {
                "allOf": [
                  {
                    "$ref": "#/components/schemas/CustomApplicationID"
                  }
                ]
              }
            }
          }
        },
        "x-go-package": "github.com/lindenlab/extraction-pii/lib/controllers"
      },
      "KYBStatusChangeBody": {
        "type": "object",
        "properties": {
          "account_id": {
            "allOf": [
              {
                "description": "Tilia account ID with which the business entity will be associated"
              },
              {
                "$ref": "#/components/schemas/AccountId"
              }
            ]
          },
          "custom_application_id": {
            "allOf": [
              {
                "$ref": "#/components/schemas/CustomApplicationID"
              }
            ]
          },
          "entity_id": {
            "allOf": [
              {
                "description": "Unique Tilia ID for your entity"
              },
              {
                "$ref": "#/components/schemas/KYBEntityId"
              }
            ]
          },
          "entity_status": {
            "type": "string",
            "description": "Status of the KYB entity\n\nPossible values are listed in the following table.\n\n| Value | Description |\n| :-----| :-------|\n| `ACCEPT`   | KYB data has been accepted. |\n| `CANCEL`   | The application process is halted due to no response from user. |\n| `DENY`   | KYB data has been rejected. |\n| `INACTIVE`   | The entity no longer exists. |\n| `INCOMPLETE`   | Application not yet submitted by applicant. |\n| `PROCESSING`  | This KYB application is being reviewed by Tilia. |",
            "example": "ACCEPT"
          },
          "vendor_application_id": {
            "allOf": [
              {
                "$ref": "#/components/schemas/VendorApplicationID"
              }
            ]
          }
        }
      }
    },
    "responses": {
      "invalid": {
        "description": "Invalid input.",
        "content": {
          "application/json": {
            "schema": {
              "type": "object",
              "properties": {
                "status": {
                  "type": "string",
                  "description": "The status of the request, either `Success` or `Failure`."
                },
                "message": {
                  "type": "array",
                  "description": "An array of short, human-readable messages describing the failure. If the request was successful, this array will be empty.",
                  "items": {
                    "type": "string"
                  }
                },
                "codes": {
                  "type": "array",
                  "description": "An array of failure reason codes. If the request was successful, this array will be empty.",
                  "items": {
                    "type": "string"
                  }
                },
                "payload": {
                  "$ref": "#/components/schemas/Basic400Response"
                }
              }
            }
          }
        }
      },
      "serverError": {
        "description": "Service unavailable or server error."
      },
      "unauthorized": {
        "description": "Unauthorized access."
      },
      "kycStatus": {
        "description": "Successfully retrieved KYC status.",
        "content": {
          "application/json": {
            "schema": {
              "allOf": [
                {
                  "$ref": "#/components/schemas/BaseSuccess"
                },
                {
                  "type": "object",
                  "properties": {
                    "payload": {
                      "$ref": "#/components/schemas/GetAccountKYC"
                    }
                  }
                }
              ]
            }
          }
        }
      },
      "notFound": {
        "description": "Resource not found.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/BasicResponse"
            },
            "example": {
              "status": "Failure",
              "message": [
                "failed to get account"
              ],
              "codes": [
                "ACCOUNT_GET_ERROR"
              ],
              "payload": null
            }
          }
        }
      }
    },
    "requestBodies": {
      "KYCStatus": {
        "content": {
          "application/json": {
            "schema": {
              "allOf": [
                {
                  "$ref": "#/components/schemas/GetAccountKYC"
                },
                {
                  "type": "object",
                  "properties": {
                    "kyc_id": {
                      "allOf": [
                        {
                          "description": "A unique identifier for the KYC collection record."
                        },
                        {
                          "$ref": "#/components/schemas/KYCId"
                        }
                      ]
                    }
                  }
                }
              ]
            }
          }
        }
      },
      "KYBStatusChange": {
        "content": {
          "application/json": {
            "schema": {
              "allOf": [
                {
                  "$ref": "#/components/schemas/KYBStatusChangeBody"
                }
              ]
            }
          }
        }
      }
    }
  }
}