PII and IDV Documents

Personally Identifiable Information

Customers PII

To access the PII details of verified customers on the platform, you can either use the partner portal or API requests.

Customers PII in the Partner Portal

To access the customer PII information on the partner portal, first ensure the user has the "PII Read" role assigned to them. If the user doesn't have this permission, any team member with the "User Admin" role can add the "PII Read" role to that team member. Please review this guide on editing a user's role in the partner portal.

After logging into the partner portal, select the desired Bank from the drop-down menu below the Cybrid logo. Then, click on the Customers page from the vertical menu on the left side of the screen. Look up the specific customer using their GUID and click on the GUID hyperlink. On the subsequent page, go to the Details tab in the horizontal menu and review the customer's personal information, including name, address, date of birth, phone number, and email address.

Customers PII via API request

To retrieve the customer PII information via API, ensure you have included the customers:pii:read in your token's scope and have set the pii query parameter to the true, such as the following:

📘
GET /api/customers/customer_guid?include_pii=true

{
  // ...
  name": {
    "first": "string",
    "middle": "string",
    "last": "string",
    "full": "string"
  },
  "address": {
    "street": "string",
    "street2": null,
    "city": "string",
    "subdivision": "string",
    "postal_code": "string",
    "country_code": "US"
  },
  "aliases": null,
  "website": null,
  "date_of_birth": "string",
  "phone_number": "string",
  "email_address": "string",
  "identification_numbers": [
    {
      "type": "drivers_license",
      "issuing_country_code": "US",
      "identification_number": "string"
    }
  ]
}

Other PIIs

To retrieve the PII for other resources similar to customers, you will need to ensure you have included the <resource>:pii:read in your token's scope and have set the pii query parameter to the true. For example:

Counterparties PII via API request

📘
GET /api/counterparties/counterparty_guid?include_pii=true

External Bank Accounts PII via API request

📘
GET /api/external_bank_accounts/external_bank_account_guid?include_pii=true

Identity Verifications PII via API request

📘
GET /api/identity_verifications/identity_verification_guid?include_pii=true

Files PII via API request

Unlike other resources mentioned above, the /api/files endpoint doesn't have include_pii query params, but instead you will need to use include_download_url, which allows you to use download_url in the response body for downloading the file. Such as the following API request:

📘
GET /api/files/:file_guid?include_download_url=true

Identity Verification Documents

To retrieve the files associated with identity verification documents (such as a driver's license used during a KYC), first, you'll need to parse and extract the file GUIDs related to the underlying identity verification (IDV) using the following API request:

📘
GET /api/identity_verifications/:identity_verification_guid?include_pii=true

{
  // ...
  "created_at": "datetime",
  "updated_at": "datetime",
  "type": "kyc",
  "guid": "identity_verification_guid",
  "method": "id_and_selfie",
  "customer_guid": "customer_guid",
  "state": "completed",
  // ...
  "documents": [
    {
      "guid": "document_guid",
      "type": "drivers_license",
      "validated": true,
      "expiration_date": "date",
      "files": [
        {
          "created_at": "datetime",
          "updated_at": "datetime",
          "guid": "file_guid",
          "type": "drivers_license_front",
          "filename": "drivers_license_front.jpg",
          "content_type": "image/jpeg"
        },
        {
          "created_at": "datetime",
          "updated_at": "datetime",
          "guid": "file_guid",
          "type": "drivers_license_back",
          "filename": "drivers_license_back.jpg",
          "content_type": "image/jpeg"
        }
        // ...
      ]
    },
    // ...
  ]
}

💡
Make sure you are setting the include_pii to true and had included the identity_verifications:pii:read in the token scope.

Next, you will need to use the following API request to obtain a link for downloading the desired file:

📘
GET /api/files/:file_guid?include_download_url=true

{
  "created_at": "datetime",
  "updated_at": "datetime",
  "guid": "file_guid",
  "organization_guid": "organization_guid",
  "bank_guid": "bank_guid",
  "customer_guid": "customer_guid",
  "type": "drivers_license_front",
  "state": "completed",
  "filename": "drivers_license_front.jpg",
  "content_type": "image/jpeg",
  "failure_code": null,
  "download_url": "https:/download_url",
  "download_expires_at": "datetime"
}

💡
Make sure you are setting the include_download_url to true and had included the files:pii:read in the token scope.