PII and IDV Documents

Personally Identifiable Information

Customers PII

To access PII details of verified customers, use the partner portal or API requests.

Customers PII in the Partner Portal

To access customer PII in the partner portal, ensure the user has the "PII Read" role assigned to them. If the user lacks this permission, any team member with the "User Admin" role can add the "PII Read" role. See editing a user's roles for details.

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 customer PII via API, include customers:pii:read in your token's scope and set the include_pii query parameter to true:

ℹ️
API reference
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"
    }
  ]
}

identification_numbers can be an empty array even when the customer's identity verification completed. This happens when the document number was not captured during automated document extraction. Contact Cybrid support with the customer GUID if you need the identification number populated.

Other PIIs

To retrieve PII for other resources, include <resource>:pii:read in your token's scope and set the include_pii query parameter to true. transfer_details on GET /api/transfers/{transfer_guid} requires transfers:pii:read. For example:

Counterparties PII via API request

ℹ️
API reference
GET /api/counterparties/counterparty_guid?include_pii=true

External Bank Accounts PII via API request

ℹ️
API reference
GET /api/external_bank_accounts/external_bank_account_guid?include_pii=true

In sandbox, a Plaid-connected external bank account may return no account or routing details, even with include_pii=true. Sandbox data is simulated and some production integrations are bypassed. To test code that reads these fields, mock the production response shape in your application.

Identity Verifications PII via API request

ℹ️
API reference
GET /api/identity_verifications/identity_verification_guid?include_pii=true

Files PII via API request

Unlike the other resources above, the /api/files endpoint does not have an include_pii query parameter. Instead, use include_download_url, which returns a download_url in the response body for downloading the file:

ℹ️
API reference
GET /api/files/:file_guid?include_download_url=true

Identity Verification Documents

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

ℹ️
API reference
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"
        }
        // ...
      ]
    },
    // ...
  ]
}

ℹ️
Token scope
Set include_pii to true and include identity_verifications:pii:read in the token scope.

Next, use the following API request to obtain a download link for the desired file:

ℹ️
API reference
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"
}

ℹ️
Token scope
Set include_download_url to true and include files:pii:read in the token scope.