Create a beneficial owner #

This section details how to create a new beneficial owner. To create beneficial owners, you need to collect the beneficial owner's full name, ssn, date of birth, and permanent address. Optionally, passport information must be included for non-US persons that do not have a US issued SSN. Beneficial owners require additional information that will give Dwolla the ability to confirm the identity of the individual.

For more information on how to create a beneficial owner, reference our step by step guide.

HTTP request #

POST https://api.dwolla.com/customers/{id}/beneficial-owners

Request Parameters #

Parameter	Required	Type	Description
firstName	yes	string	The legal first name of the beneficial owner. Must be ≤ 50 characters and cannot contain special characters [<>="`!?%~${}\].
lastName	yes	string	The legal last name of the beneficial owner. Must be ≤ 50 characters and cannot contain special characters [<>="`!?%~${}\].
ssn	conditional	string	Full nine digits of the beneficial owner’s social security number. If SSN is omitted, passport is required.
dateOfBirth	yes	string	Beneficial owner’s date of birth in `YYYY-MM-DD` format. Must be between 18 to 125 years of age.
address	yes	object	An address JSON object. Full address of the beneficial owner's physical address.
passport	conditional	object	An optional passport JSON object. Required for non-US persons. Includes passport identification number and country. If passport is omitted, SSN is required.

Address JSON object #

Parameter	Required	Type	Description
address1	yes	string	First line of the street address of the Beneficial Owner's permanent residence. PO Boxes are not allowed. Must be ≤ 50 characters and contain no special characters [<>="`!?%~${}\].
address2	no	string	Second line of the street address. PO Boxes are not allowed. Must be ≤ 50 characters and contain no special characters [<>="`!?%~${}\].
address3	no	string	Third line of the street address. PO Boxes are not allowed. Must be ≤ 50 characters and contain no special characters [<>="`!?%~${}\].
city	yes	string	City of the Beneficial Owner's permanent residence. Must be ≤ 50 characters. Cannot contain numbers or special characters [<>="`!?%~${}\].
stateProvinceRegion	yes	string	US persons - Two-letter US state abbreviation of the Beneficial Owner's physical address. See the US Postal Service guide. Non-US persons - Two-letter state, province, or region ISO abbreviation. If no two-letter abbreviation exists, use the country’s ISO 2-letter abbreviation. Must be uppercase (e.g., `CA`).
country	yes	string	Country of the Beneficial Owner's permanent residence. Two-digit ISO country code (e.g., `US` for United States, `CA` for Canada). See the ISO country codes list.
postalCode	conditional	string	Postal code of the Beneficial Owner’s permanent residence. US persons must provide a 5-digit ZIP code (e.g., `50314`). Non-US persons - Optional, but may include alphanumeric postal codes where applicable.

Passport JSON object #

Parameter	Required	Type	Description
number	conditional	string	Required if Beneficial Owner resides outside of the United States and has no Social Security Number. Must be ≤ 255 characters and contain no special characters [<>="`!?%~${}\].
country	conditional	string	Country of issued passport. Two-digit ISO country code (e.g., `US` for United States, `CA` for Canada). Must be 2 characters (ISO standard).

Request and response #

Raw

POST https://api-sandbox.dwolla.com/customers/81696e5d-a593-45a6-8863-3c20ad634de5/beneficial-owners
Content-Type: application/vnd.dwolla.v1.hal+json
Accept: application/vnd.dwolla.v1.hal+json
Authorization: Bearer pBA9fVDBEyYZCEsLf/wKehyh1RTpzjUj5KzIRfDi0wKTii7DqY

{
  "firstName": "document",
  "lastName": "owner",
  "ssn": "123-46-7890",
  "dateOfBirth": "1960-11-30",
  "address": {
    "address1": "123 Main St.",
    "city": "New York",
    "stateProvinceRegion": "NY",
    "country": "US",
    "postalCode": "10005"
  }
}

HTTP/1.1 201 Created
Location: https://api.dwolla.com/beneficial-owners/FC451A7A-AE30-4404-AB95-E3553FCD733F

Overview

Retrieve a beneficial owner

Test in the Sandbox for free today.

Use sandbox environment to test API requests.

Get API Keys

Dwolla

Product

Developers

Financial institutions play an important role in our network.

All funds transfers made using the Dwolla Platform are performed by a financial institution partner, and any funds held in a Dwolla Balance are held by a financial institution partner. Learn more about our financial institution partners.