NAV
curl

← Home

Onboarding

Introduction

Disclaimer: This documentation is currently in Alpha and is subject to drastic change.

This is the official reference documentation for the SVB Onboarding APIs. Please see the authentication documentation for access information.


The SVB Onboarding API is a programmatic interface for onboarding a new customer to the bank. Using this API it’s possible for a company to begin a relationship with SVB and begin using a variety of banking products, including opening a bank account, getting issued a debit card, and more, all in a completely automated fashion.

Versioning

We expect this API to change quickly as we automate larger portions of the onboarding process. We will use the same versioning scheme, namely a URL path prefix indicating the major version number (e.g. /v1/). However this API will be versioned separately from our existing payments APIs.

Workflow

Onboarding a new customer to the bank requires a lot of information, more than fits in a single API request. This API defines a set of resources (company, address, person, login, parent_company, file, document, gov_ident) that together comprise all of the information needed to onboard a customer.

The relationships of these resources form a tree structure with company at the root. This company is the primary resource of the API and represents the corporate entity that will become a customer of the bank. When an API request is made to create a company, the entire related tree of resources that branch off of company is submitted together and the backend systems that process the onboarding begin.

API Resource Dependencies Tree

Whenever a resource relates to another, it has a field with a name of the form [resource]_id (or [resource]_ids, when a many-to-one relationship is expected). For example, the person resource has a field called address_id, which must be set to the ID of a valid address resource. If you’re familiar with relational databases, you can think of these related IDs as foreign keys.

Because many resources depend on a related resource, the records must be created in a particular order. For example, because a person requires a valid address_id and gov_ident_id, that address and gov_ident must be created prior to creating a person resource.

For any given onboarding, the final resource created will always be the company.

Company Status

Each company has a status field that reflects if the company has an open account or not. The company’s events field is an array of status updates, which you can use to track changes in status.

The company status will be one of the following values:

Status Definition
pending The company is either being prepared for submission, or is in review.
rejected The company has been rejected and the account has not been created.
conditionally_approved The company has been approved, but only a limited access account has been created.
approved The company has been approved, and account has been created.
blocked The company has not been approved and SVB is waiting on supporting documents.
suspended The company was approved, but the account is currently suspended.
terminated The company was approved, but the account has been closed.

Testing Company Status

The following company names are reserved for testing various onboarding company statuses. Creating a company with the specified name will result in a corresponding updated status, and if applicable, an account number.

Name Status
TEST APPROVED TEST approved
TEST REJECTED TEST rejected
TEST BLOCKED TEST blocked

Products and Roles

A product resource is set at the company level and can be activated by a person who meets particular requirements. The role requirements to enable products are as follows:

Product dda_account is added by default.

Product to enable Person role requirement Other requirement
dda_account none none
debit_card authorized_signer Cannot be in India
fx bank_account_administrator Have wires product
mobile_deposits bank_account_administrator Have a login_name
Must be physically in the US
web bank_account_administrator Have a login_name
wires bank_account_administrator and authorized_signer Have a login_name

Source of Funds

A company’s source_of_funds attribute will be one of the following values:

Source of funds Definition
existing Revenue, profits existing, or established entities
family Family
grant Grants/Donations-Non-Profit Clients Only
inheritance Inheritance
internal Internal Transfer
investor Non-VC investor
loan Loan Proceeds/Advance
personal Personal savings or investments
retirement Retirement or pension funds
vc Venture capital funding

Resources

Companies

The newly-created corporation to be onboarded.

Example:

{
  "id": 123,
  "account_number": "1234567890",
  "accounts": [
    {
      "account_number": "1234567890",
      "currency": "USD"
    },
    {
      "account_number": "9876543210",
      "currency": "USD"
    }
  ],
  "description": "Widget Corp is the world leader in high quality widgets.",
  "document_ids": [331, 332, 333],
  "documents": [
    {
      "id": 331,
      "url": "https://api.svb.com/v1/documents/331"
    },
    {
      "id": 332,
      "url": "https://api.svb.com/v1/documents/332"
    },
    {
      "id": 333,
      "url": "https://api.svb.com/v1/documents/333"
    }
  ],
  "email_address": "founders@widgetcorp.example.com",
  "events": [
    {
      "updated_at": "2017-01-21T12:39:49.042Z",
      "previous": null,
      "data": {
        "status": "pending",
        "status_reason": null,
        "status_reason_category": null
      }
    },
    {
      "updated_at": "2017-01-21T13:24:16.002Z",
      "previous": {
        "status": "pending",
        "status_reason": null,
        "status_reason_category": null
      },
      "data": {
        "status": "approved",
        "status_reason": null,
        "status_reason_category": null
      }
    }
  ],
  "incorporation_address_id": 444,
  "incorporation_address": {
    "id": 444,
    "url": "https://api.svb.com/v1/addresses/444"
  },
  "mailing_address_id": 555,
  "mailing_address": {
    "id": 555,
    "url": "https://api.svb.com/v1/addresses/555"
  },
  "metadata": {"foo": "bar"},
  "mcc": 123,
  "name": "Widget Corp",
  "options": null,
  "parent_company_id": 666,
  "parent_company": {
    "id": 666,
    "url": "https://api.svb.com/v1/parent_companies/666"
  },
  "person_ids": [777, 778],
  "persons": [
    {
      "id": 777,
      "url": "https://api.svb.com/v1/persons/777"
    },
    {
      "id": 778,
      "url": "https://api.svb.com/v1/persons/778"
    }
  ],
  "phone_number": "+1-415-333-1234",
  "physical_address_id": 888,
  "physical_address": {
    "id": 888,
    "url": "https://api.svb.com/v1/addresses/888"
  },
  "product_description": "A photo sharing app; everyone loves those.",
  "products": [
    "dda_account",
    "fx",
    "web"
  ],
  "referral_source": "Hacker News",
  "risk_commentary": null,
  "source_of_funds": "vc",
  "state": "DE",
  "status": "approved",
  "type": "company",
  "url": "https://api.svb.com/v1/companies/123",
  "website_url": "https://www.example.com/widgets"
}

Create a company

Example request

POST /v1/companies

curl "https://api.svb.com/v1/addresses" \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H 'Content-Type: application/json' \
    -X POST \
    -d '{
          "data": {
            "document_ids": [20544, 20545],
            "phone_number": "415.555.1212",
            "description": "Banking as a Service",
            "physical_address_id": 16801,
            "source_of_funds": "family",
            "email_address": "apibanking@svb.com",
            "name": "Standard Bank",
            "person_ids": [13379],
            "parent_company_id": 10535,
            "risk_commentary": "Clearly a fake company",
            "state": "CA",
            "website_url": "https://developers.svb.com"
          }
        }'

Parameters:

Name Type Required? Description
description string Description of the company.
document_ids array[int] IDs of any document resources that should be associated with the company.
email_address string R The company’s email address.
incorporation_address_id int ID of address resource representing the company’s officially incorporated address, if different than the physical_address_id.
mailing_address_id int ID of address resource representing the company’s preferred mailing address, if different than the physical_address_id.
metadata object Metadata (same as other APIs).
mcc int Merchant category code, if known.
name string R The company’s legal name.
options object Additional domain specific options
parent_company_id int If the company has a corporate beneficial owner, the ID of the parent company resource.
person_ids array[int] If the company has personal beneficial owners, the IDs of the person resources.
phone_number string R The company’s phone number.
physical_address_id int R ID of address resource representing the company’s primary physical address.
product_description string Description of the product that the company sells.
products array[string] Banking products that the company has. Available products: dda_account (required), debit_card, fx, mobile_deposits, web, wires
referral_source string Source that referred the company.
risk_commentary string Any additional information SVB’s risk team should be aware of.
source_of_funds string The company’s source of funds.
state subdiv U.S. State where the company is incorporated. (abbreviation, e.g. DE = Delaware)
website_url string R The company’s web address (URL).

Response:

200 OK The new company resource.

Retrieve a company

Request:

GET /v1/companies/:id

Response:

200 OK The company resource.

Update a company

Request:

PATCH /v1/companies/:id

Parameters:

Note: Since this is a PATCH update, any parameters not passed will remain unchanged.

Name Type Required? Description
description string See parameters table above, under “Create a company”, for descriptions.
document_ids array[int]
email_address string
incorporation_address_id int
mailing_address_id int
mcc int
metadata object
name string
person_ids array[int]
phone_number string
physical_address_id int
product_description string
products array[string]
referral_source string
risk_commentary string
state subdiv
website_url string

Response:

200 OK The updated company resource.

Delete a company

Request:

DELETE /v1/companies/:id

Resources:

204 No Content

List all companies

Request:

GET /v1/companies

Response:

200 OK List of company resources.

Persons

A human person, who is a beneficial owner of the company being onboarded.

Resource:

{
  "id": 123,
  "address_id": 456,
  "address": {
    "id": 456,
    "url": "https://api.svb.com/v1/addresses/456"
  },
  "date_of_birth": "1985-10-21",
  "email_address": "john.smith@gmail.md",
  "gov_ident_ids": [789],
  "gov_idents": [{
    "id": 789,
    "url": "https://api.svb.com/v1/gov_idents/789"
  }],
  "first_name": "John",
  "last_name": "Smith",
  "login_id": 1011,
  "middle_name": null,
  "metadata": {"foo": "bar"},
  "percent_ownership": 50,
  "phone_number": "+373 123 456 7890",
  "risk_commentary": null,
  "roles": [
    "bank_account_administrator"
  ],
  "ssn": "333224444",
  "title": "Co-Founder, CTO",
  "type": "person",
  "url": "https://api.svb.com/v1/persons/123"
}

Create a person

Example request

POST /v1/persons

curl "https://api.svb.com/v1/persons" \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H 'Content-Type: application/json' \
    -X POST \
    -d '{
          "data": {
            "address_id": 16801,
            "date_of_birth": "1980-03-04",
            "email_address": "kim@damerling.com",
            "first_name": "Kim",
            "gov_ident_ids": [13775],
            "last_name": "Damerling",
            "login_id": 3357,
            "percent_ownership": 100,
            "phone_number": "415.555.1212",
            "roles": ["bank_account_administrator"],
            "ssn": "333224444",
            "title": "Founder"
          }
        }'

Parameters:

Name Type Required? Description
address_id int R ID of the address resource associated with this person.
date_of_birth date R Date of birth.
email_address string R Email address.
first_name string R First name.
gov_ident_ids array[int] R IDs of the gov-ident resources associated with this person.
last_name string R Last name.
login_id int ID of the login resource associated with this person.
metadata object Metadata (same as other APIs).
middle_name string Middle name, if applicable.
percent_ownership number R Percentage ownership of the company; must be 0 < n <= 100.
phone_number string R Phone number.
risk_commentary string Any additional information SVB’s risk team should be aware of.
roles array[string] List of roles. One or more of authorized_signer, bank_account_administrator, beneficial_owner, incorporator, primary_representative, secretary
ssn string Social security number, if applicable.
title string R Title within the company.

Response:

200 OK The new person resource.

Retrieve a person

Request:

GET /v1/persons/:id

Response:

200 OK The person resource.

Update a person

Request:

PATCH /v1/persons/:id

Parameters:

Note: Since this is a PATCH update, any parameters not passed will remain unchanged.

Name Type Required? Description
address_id int See parameters table above, under “Create a person”, for descriptions.
date_of_birth date
email_address string
first_name string
gov_ident_ids array[int]
last_name string
login_id int
metadata object
middle_name string
percent_ownership number
phone_number string
risk_commentary string
roles array[string]
ssn string
title string

Response:

200 OK The updated person resource.

Delete a person

Request:

DELETE /v1/persons/:id

Response:

204 No Content

List all persons

Request:

GET /v1/persons

Response:

200 OK List of person resources.

Logins

Reserve a login name (the user name) to the online banking system.

Resource:

Name Description Type
login_name The login name string
reservation_expires When the login name expires, if it is not used date
{
  "id": 123,
  "login_name": "adalovelace",
  "reservation_expires": "2017-09-20"
}

Create a login

Reserve a login name in the online banking system.

Example request

curl "https://api.svb.com/v1/persons" \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H 'Content-Type: application/json' \
    -X POST \
    -d '{
          "data": {
            "login_name": "api473789"
          }
        }'

POST /v1/logins

Parameters:

Name Type Required? Description
login_name string R The login name

Response:

200 OK The new login resource.

Retrieve a login

Request:

GET /v1/logins/:id

Response:

200 OK The login resource.

Delete a login

Request:

DELETE /v1/logins/:id

Response:

204 No Content

List all logins

Request:

GET /v1/logins

Response:

200 OK List of login resources.

Parent Companies

A corporation who is a beneficial owner of the company being onboarded.

Resource:

{
  "id": 123,
  "address_id": 456,
  "address": {
    "id": 456,
    "url": "https://api.svb.com/v1/addresses/456"
  },
  "country": "FR",
  "description": "A very large and international corporation.",
  "name": "La Société Internationale",
  "metadata": {"foo": "bar"},
  "percent_ownership": 100,
  "source_of_funds": "inheritance",
  "type": "parent_company",
  "url": "https://api.svb.com/v1/parent_companies/123"
}

Create a parent company

Example request

curl "https://api.svb.com/v1/parent_companies" \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H 'Content-Type: application/json' \
    -X POST \
    -d '{
          "data": {
            "country": "US",
            "address_id": 16801,
            "percent_ownership": 100,
            "description": "Wir machen die beste Produckten.",
            "name": "Die Super Gesellschaft"
          }
        }'

POST /v1/parent_companies

Parameters:

Name Type Required? Description
address_id int R ID of the address resource associated with this parent company.
country country R Country where the parent company is incorporated.
description string Description of the parent company.
name string R The parent company’s name.
metadata object Metadata (same as other APIs).
percent_ownership number R Percentage ownership of the company; must be 0 < n <= 100.
source_of_funds string The parent company’s source of funds.

Response:

200 OK The new parent company resource.

Retrieve a parent company

Request:

GET /v1/parent_companies/:id

Response:

200 OK The parent company resource.

Update a parent company

Request:

PATCH /v1/parent_companies/:id

Parameters:

Note: Since this is a PATCH update, any parameters not passed will remain unchanged.

Name Type Required? Description
address_id int See parameters table above, under “Create a parent company”, for descriptions.
country country
description string
name string
metadata object
percent_ownership number
source_of_funds string

Response:

200 OK The updated parent company resource.

Delete a parent company

Request:

DELETE /v1/parent_company/:id

Response:

204 No Content

List all parent companies

Request:

GET /v1/parent_companies

Response:

200 OK List of parent company resources.

Addresses

An address on Earth.

Example address object

{
  "id": 123,
  "street_line1": "123 Fake St",
  "street_line2": "Suite 45",
  "street_line3": null,
  "city": "San Francisco",
  "state": "CA",
  "postal_code": "94104",
  "country": "US",
  "type": "address",
  "url": "https://api.svb.com/v1/addresses/123"
}

Create an address

Example request

curl "https://api.svb.com/v1/addresses" \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H 'Content-Type: application/json' \
    -X POST \
    -d '{
          "data": {
            "city": "San Francisco",
            "street_line2": "Suite 200",
            "street_line1": "555 Mission St.",
            "country": "US",
            "state": "CA",
            "postal_code": "94105"
          }
        }'

POST /v1/addresses

Arguments

Name Type Required? Description
street_line1 string R Street address.
street_line2 string Street address, continued if necessary.
street_line3 string Street address, continued if necessary.
city string R Address city.
state subdiv US state abbreviation, if applicable.
postal_code string Address postal code, if applicable.
country country R Address country.

Response:

200 OK The new address resource.

Retrieve an address

Request:

GET /v1/addresses/:id

Response:

200 OK The address resource.

Update an address

Request:

PATCH /v1/addresses/:id

Parameters:

Note: Since this is a PATCH update, any parameters not passed will remain unchanged.

Name Type Required? Description
street_line1 string R See parameters table above, under “Create an address”, for descriptions.
street_line2 string
street_line3 string
city string R
state subdiv
postal_code string
country country R

Response:

200 OK The updated address resource.

Delete an address

Request:

DELETE /v1/addresses/:id

Response:

204 No Content

List all addresses

Request:

GET /v1/addresses

Response:

200 OK List of address resources.

Files

An uploaded file, either a pdf document, or a scanned jpg or png image of a document. Note that the resource itself is a JSON object containing file metadata. Because these files often contain sensitive personal information, the binary file data itself will be write-only. This binary file, once uploaded, will not be served back to the client, only its metadata.

Resource:

{
  "id": 123,
  "media_type": "image/png",
  "media_size": 123456,
  "metadata": {"foo": "bar"},
  "type": "file",
  "url": "https://api.svb.com/v1/files/123"
}

Create a file

Uploads a new file.

Example request

curl "https://api.svb.com/v1/files" \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -X POST \
    -F "file=@./articles-of-inc.pdf;type=application/pdf"

POST /v1/files

This endpoint differs from the others as it does not accept a JSON body, but rather binary form data (a file) with Content-Type: multipart/form-data. The MIME type of the file itself can be any of the following:

Parameters:

Name Type Required? Description
file binary R Binary file data.
metadata object Metadata (same as other APIs).

Response:

200 OK The new file resource.

Retrieve a file

Retrives the file resource with id :id.

Request:

GET /v1/files/:id

Response:

200 OK The file resource.

Delete a file

Request:

DELETE /v1/files/:id

Response:

204 No Content

List all files

Request:

GET /v1/files

Response:

200 OK List of file resources.

Documents

A signed legal document. This resource contains metadata and a link to a file containing the scanned document itself.

EIN number format should be XX-XXXXXXX.

Resource:

{
  "id": 123,
  "document_type": "ein",
  "file_id": 456,
  "file": {
    "id": 456,
    "url": "https://api.svb.com/v1/files/456"
  },
  "metadata": {},
  "number": "12-3456789",
  "type": "document",
  "url": "https://api.svb.com/v1/documents/123"
}

Create a document

Example request

curl "https://api.svb.com/v1/documents" \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H 'Content-Type: application/json' \
    -X POST \
    -d '{
          "data": {
            "document_type": "inc",
            "file_id": 24674
          }
        }'

POST /v1/documents

Parameters:

Name Type Required? Description
document_type string R One of: bda (“Bank Depository Agreement”), inc (“Certificate of Incorporation”), obe (“Online Banking Enrollment”), ein (“Employer Identification Number”), fai (“Filed Articles of Incorporation”).
file_id int R ID of a file resource (see above) containing a scanned copy of the executed document.
metadata object Metadata (same as other APIs).
number string The actual document number. Required for document_type ein

Response:

200 OK A new document resource.

Retrieve a document

Request:

GET /v1/documents/:id

Response:

200 OK The document resource with id :id.

Delete a document

Request:

DELETE /v1/documents/:id

Response:

204 No Content

List all documents

Request:

GET /v1/documents

Response:

200 OK List of document resources.

Government IDs

A special variety of document; this is a government-issued document establishing the identity of the holder. In the United States, this could be a driver’s license or a passport.

Due to United States government sanctions, persons from certain prohibited countries will require a valid passport for onboarding.

Resource:

{
  "id": 123,
  "country": "US",
  "document_type": "driving_license",
  "expires_on": "2020-08-31",
  "file_id": 456,
  "file": {
    "id": 456,
    "url": "https://api.svb.com/v1/files/456"
  },
  "first_name": "John",
  "middle_name": null,
  "last_name": "Boyd",
  "number": "F7720121",
  "url": "https://api.svb.com/v1/gov_idents/123"
}

Create a government ID

Example request

curl "https://api.svb.com/v1/gov_idents" \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H 'Content-Type: application/json' \
    -X POST \
    -d '{
          "data": {
            "first_name": "Dale",
            "last_name": "Cooper",
            "country": "US",
            "number": "1234567890",
            "file_id": 24673,
            "document_type": "passport",
            "expires_on": "2020-08-31"
          }
        }'

POST /v1/gov_idents

Parameters:

Name Type Required? Description
country country R Country of issuance (two-letter country code).
document_type string R One of: ‘passport’, 'driving_license’, 'id_card’, 'other’.
expires_on date Date of expiry, required if applicable and available (YYYY-MM-DD)
file_id int R ID of a file resource (see above) containing a scanned copy of this government ID.
first_name string R The listed first name of the holder, if available.
last_name string R The listed last name of the holder, if available.
middle_name string The listed middle name of the holder, if applicable and available.
number string R The actual ID number, i.e. for a driver’s license this would be the person’s “driver’s license number.”

Response:

200 OK A new government ID resource.

Retrieve a government ID

Request:

GET /v1/gov_idents/:id

Response:

200 OK The government ID resource with id :id.

Update a government ID

Request:

PATCH /v1/gov_idents/:id

Parameters:

Note: Since this is a PATCH update, any parameters not passed will remain unchanged.

Name Type Required? Description
country country R See parameters table above, under “Create a government ID”.
document_type string R
expires_on date
file_id int R
first_name string R
last_name string R
middle_name string
number string R

Response:

200 OK The updated government resource.

Delete a government ID

Request:

DELETE /v1/gov_idents/:id

Response:

204 No Content

List all government IDs

Request:

GET /v1/gov_idents

Response:

200 OK List of government ID resources.