RocketKOR

Getting Started Guides

Get Started: Verify a Customer (IDV)

Authenticate your customers using Identity Verification (IDV). For example, Customers may need to be verified before they can be issued a bank account.

You can verify Individual and Business Customers. If you verify a Business Customer, any Beneficial Owners attached to the Customer will also be verified as part of the IDV process.

In this guide, you’ll learn how to:

  1. Determine which IDV profile to use to verify a Customer Account.
  2. Ensure the Customer Account contains the required information for IDV.
  3. Ensure any Beneficial Owners for the Customer Account contain the required information for IDV.
  4. Upload identity documents for the Customer and any Beneficial Owners.
  5. Submit an IDV application for the Customer.
  6. Monitor the IDV application status.

Before You Start

Sandbox Account: Sign up for a RocketKOR sandbox account. When your sandbox account is created, one or more Service Accounts will be created for your Business Account. A Service Account is a non-human user of a Business Account that performs functions (such as creating transactions) via the RocketKOR APIs on behalf of the Business Account.

Authentication: Before you can call the APIs, you must authenticate a Service Account by exchanging the account’s API key and secret for an access token.

Customer Account: Ensure the Business Customer or Individual Customer has an active Customer Account.

Beneficial Owners: For Business Customers, add any Beneficial Owners to the Customer Account.

Step 1: Choose an IDV Profile

List the available IDV profiles for the Business Account and determine which profile to use for the Customer. For example, a Business Customer will need a different profile than an Individual Customer. In addition, some profiles may perform basic checks while others may perform more extensive checks.

In the request, use the identityAccountTypes query parameter to list profiles for Business Customers (BUSINESS_CUSTOMER) or Individual Customers (INDIVIDUAL_CUSTOMER).

API Reference

List Identity Verification Profiles

Endpoint

GET /v1/identity-verification-profiles

Response Example

Returns a list of Identity Verification Profile objects. Review the response and determine which IDV profile is most appropriate for the Customer Account you want to verify.

Once you’ve selected an IDV profile, make a note of the profile requirements. In the next steps, you’ll check the Customer Account and Beneficial Owners to ensure they contain this information. These requirements include:

  • Customer Account status (allowedAccountStatuses)
  • Customer Account information and identity documents (minimumInformationRequired)
  • Beneficial Owner information and identity documents (beneficiary)

Also make a note of the profile ID (id). You’ll need this ID in step 5 when you submit an IDV application for the Customer.

The following example shows an IDV profile to verify a Business Customer and their Beneficial Owners.

				
					{
  "id": "kyb-profile-1",
  "name": "Business and Beneficiary check",
  "allowedAccountTypes": [
    "BUSINESS_CUSTOMER"
  ],
  "allowedAccountStatuses": [
    "ACTIVE"
  ],
  "minimumInformationRequired": {
    "business": {
      "info": [
        "TAX_ID",
        "PRIMARY_EMAIL_ADDRESS",
        "PRIMARY_PHONE_NUMBER"
      ],
      "name": [
        "BUSINESS_LEGAL_NAME"
      ],
      "documents": {
        "formation": []
      },
      "physicalAddress": [
        "LINE1",
        "CITY",
        "STATE",
        "POSTAL_CODE",
        "COUNTRY"
      ]
    },
    "beneficiary": {
      "info": [
        "DATE_OF_BIRTH",
        "SSN",
        "PRIMARY_EMAIL_ADDRESS",
        "PRIMARY_PHONE_NUMBER"
      ],
      "name": [
        "FIRST",
        "LAST"
      ],
      "documents": {
        "passport": [
          "ISSUING_COUNTRY",
          "EXPIRY_DATE"
        ],
        "drivingLicense": [
          "ISSUING_COUNTRY",
          "EXPIRY_DATE"
        ]
      },
      "physicalAddress": [
        "LINE1",
        "CITY",
        "STATE",
        "POSTAL_CODE",
        "COUNTRY"
      ]
    }
  }
}

Step 2: Capture Identifying Information for the Customer

Retrieve the Customer Account and ensure it has the required status and information listed in the IDV profile you selected in step 1.

API Reference

Retrieve a Customer

Endpoint

GET /v1/customers/{customerId}

In the request, pass the Customer Account ID to the customerId parameter.

Response Example

Returns the Business Customer or Individual Customer object. These objects contain the Customer Account details.

Check the response to ensure the required fields are present. If necessary, use the Update a Business Customer or Update an Individual Customer API to add any missing information to the Customer Account.

The following example shows a response for a Business Customer Account.

				
					{
  "id": "69248436-39f5-4074-9823-76d2580c82a6",
  "status": "ACTIVE",
  "addresses": [
    {
      "type": "PHYSICAL",
      "streetLine1": "200 King St",
      "streetLine2": "Suite 310",
      "cityName": "Greenville",
      "stateCode": "MO",
      "countryCode": "USA",
      "zipCode": "63368",
      "primary": true
    }
  ],
  "type": "BUSINESS",
  "businessName": "ACME",
  "contacts": [
    {
      "firstName": "Jack",
      "lastName": "Smith",
      "primary": true,
      "primaryPhoneNumber": {
        "number": "+14151234",
        "type": "WORK",
      },
      "primaryEmail": {
        "value": "jsmith@acme.com",
      }
    }
  ],
  "legalName": "ACME Corporation",
  "primaryPhone": "+14151234",
  "website": "https://www.acme.com",
  "dateOfFormation": "2010-01-31",
  "legalEntityType": "CORP",
  "taxIdCountryCode": "USA",
  "taxId": "12-3456789",
  ...
}

Step 3: Capture Identifying Information for Beneficial Owners

If you’re verifying a Business Customer Account, retrieve any Beneficial Owners and ensure they have the required information listed in the IDV profile you selected in step 1.

API Reference

Retrieve a Beneficial Owner

Endpoint

GET /v1/customers/{customerId}/beneficiaries/{beneficiaryId}

In the request:

  • Pass the Customer Account id to the customerId parameter.
  • Pass the Beneficial Owner id to the beneficiaryId parameter.

Response Example

Returns the Beneficial Owner object.

Check the response to ensure the required fields are present. If necessary, use the Update a Beneficial Owner API to add any missing information to the Beneficial Owner.

				
					{
  "parentId": "69248436-39f5-4074-9823-76d2580c82a6",
  "id": "997dec9d-afcb-4843-a9e3-5333b6228229",
  "firstName": "Natalie",
  "lastName": "Smith",
  "sex": "FEMALE",
  "primaryPhoneNumber": {
    "number": "+17512312345",
    "type": "MOBILE",
  },
  "primaryEmail": {
    "value": "nsmith@example.com",
  },
  "dateOfBirth": "1981-05-11",
  "socialId": "123-45-6789",
  "addresses": [
    {
      "type": "PHYSICAL",
      "streetLine1": "400 Richmond St",
      "cityName": "New York",
      "stateCode": "NY",
      "countryCode": "USA",
      "zipCode": "10001",
      "primary": true
    }
  ],
  ...
}

Step 4: Upload Identity Documents for the Customer and Beneficial Owners

Some IDV profiles require that identity documents exist for the Customer Account and any Beneficial Owners.

Check the IDV profile you selected in step 1 to see if there are any required documents. If so, use the List All Documents API to see if these documents have already been uploaded.

If an identity document is missing from a Customer or Beneficial Owner, you’ll need to add the document.

To do this, you’ll need the Customer Account ID or Beneficial Owner ID. You’ll also need to provide the following information about the document. After sending a request with this information, you’ll upload the document by calling the content URL provided in the response.

Parameter

Description

holderId

Customer Account ID or Beneficial Owner ID.

holderType

Type of account holder. Value must be CUSTOMER or BENEFICIARY.

documentType

Type of document. The following values are supported:

  • driving-license  Driver’s license. Can be added for Individual Customers and Beneficial Owners.
  • passport  Passport. Can be added for Individual Customers and Beneficial Owners.
  • formation  Formation document. Can be added for Business Customers.
  • tax  Tax document. Can be added for Business Customers.
  • ownership  Ownership document. Can be added for Business Customers.
  • other  Other type of document. Can be added for Individual Customers, Business Customers, and Beneficial Owners.

name

Name of the document.

description

Description of the document. Required if documentType is formation, tax, ownership, or other.

extension

Document file extension (JPG, JPEG, PNG, or PDF).

contentLength

File content size in bytes.

number

Document number. Required if documentType is driving-license or passport.

issuingCountryCode

Country code where the document was issued. Required if documentType is driving-license or passport.

issuingStateCode

State or province code where the document was issued. Required if documentType is driving-license.

expiryDate

Expiry date for the document. Required if documentType is driving-license or passport.

API Reference

Create a Document

Endpoint

POST /v1/documents

Request Example

				
					{
  "holderId": "69248436-39f5-4074-9823-76d2580c82a6",
  "holderType": "CUSTOMER",
  "documentType": "formation",
  "name": "Company Formation Document",
  "description": "Articles of Incorporation",
  "extension": "PDF",
  "contentLength": 81169,
  "number": "123-456-789",
  "issuingCountryCode": "US",
  "issuingStateCode": "NY",
  "expiryDate": "2030-02-03"
}

Response Example

Returns the Document object which includes a content url.

You can now upload the document by calling the url with an HTTP PUT request.

				
					{
  "id": "b175994b-fd5b-46d6-aba9-73638902f4a0",
  "businessAccountId": "733df8ac-5d93-4e5a-b665-36a1525353d8",
  "holderId": "69248436-39f5-4074-9823-76d2580c82a6",
  "holderType": "CUSTOMER",
  "documentType": "formation",
  "name": "Company Formation Document",
  "description": "Articles of Incorporation",
  "number": "123-456-789",
  "issuingCountryCode": "US",
  "issuingStateCode": "NY",
  "extension": "PNG",
  "contentLength": 81169,
  "expiryDate": "2030-02-03",
  "url": {
    "value": "https://documents.rocketkor.net/7260554c5",
    "allowed": "PUT",
    "expiresIn": 600
  }
  ...
}

Step 5: Submit an IDV Application for the Customer

Now that the account information and identity document updates are complete, the next step is to submit an IDV application for the Customer. This application will be sent to a trusted third-party IDV provider for processing. If the Customer has any Beneficial Owners, the Beneficial Owners will be automatically included in the verification process.

To submit an IDV application, you’ll need:

  • accountId  Customer Account ID.
  • identityVerificationProfileId  ID of the profile that will be used to process the application. You can obtain this ID from the response in step 1.

API Reference

Submit an IDV Application

Endpoint

POST /v1/identity-verifications

Request Example

				
					{
  "accountId": "69248436-39f5-4074-9823-76d2580c82a6",
  "identityVerificationProfileId": "kyb-profile-1"
}

Response Example

Returns the URI of the newly created IDV application in the Location header.

				
					{
  201 Identity verification application created successfully. Application resource URI is returned in the Location header.
}

Step 6: Monitor the IDV Application Status

Check the current status of the IDV application.

You can search for the application based on the filters such as the Customer Account ID (accountId), the Customer Account type (BUSINESS_CUSTOMER, INDIVIDUAL_CUSTOMER), the IDV profile used for the application (identityVerificationProfileId), and the date the application was created (createdDateFrom, createdDateTo).

Note  You can also use IDV watchlist events to receive notifications when an update is made to an IDV application’s status.

API Reference

List IDV Applications

Endpoint

GET /v1/identity-verifications

Response Example

Returns an array of Identity Verification Application objects, based on the request filters.

This object contains the IDV application details such as the current application status (latestStatus) and final application outcome (outcome). It also contains details for the Customer Account and any Beneficial Owners that were verified for the Customer Account (entities).

The following example shows a response for a Business Customer Account with a Beneficial Owner.

				
					{
  "id": "56de0668-7ae5-4706-8591-cd674c512267",
  "businessAccountId": "733df8ac-5d93-4e5a-b665-36a1525353d8",
  "accountId": "69248436-39f5-4074-9823-76d2580c82a6",
  "identityVerificationProfileId": "kyb-profile-1",
  "latestStatus": "COMPLETED",
  "outcome": "Approved",
  "legalName": "ACME Corporation",
  "accountType": "BUSINESS_CUSTOMER",
  "statusHistory": [ ... ],
  ...
  "entities": [
    {
      "status": "COMPLETED",
      "outcome": "Approved",
      "accountId": "69248436-39f5-4074-9823-76d2580c82a6",
      "entityType": "BUSINESS_CUSTOMER",
      "statusHistory": [ ... ],
      ...
    },
    {
      "status": "COMPLETED",
      "outcome": "Approved",
      "accountId": "997dec9d-afcb-4843-a9e3-5333b6228229",
      "entityType": "BENEFICIARY",
      "statusHistory": [ ... ],
      ...
    }
  ]
}
ON THIS PAGE
RocketKOR

Step into the future of Finance with RocketKOR! Simplify payments, banking, lending, and data analytics using our versatile KOR Platform.

A Rocket Financial Inc. company

@ 2024 RocketKOR, Inc. All rights reserved.

PCI DSS Compliant
Terms of Use     |     Privacy Policy