Docs

Ask AI or search...

Select Language

Get API Keys

Select Product

Select Category

Home

API Reference

API Fundamentals
SDK Support
Drop-in Components
Authorization
Root
Accounts
Customers
Overview Create a customer Retrieve a customer List and search customers Update a customer List business classifications Retrieve a business classification
Knowledge-based Authentication (KBA)
Beneficial Owners
Documents
Exchanges
Open Banking
Funding Sources
Transfers
Labels
Mass payments
Events
Webhook subscriptions
Webhooks

Get API Keys

Create a customer #

This section details how to create a new Customer. It is important to prompt your users to provide their full name as it appears on a US government issued identification card. This will help ensure a straight-through processing approach. If errors occur in name or date of birth, where you may be prompted for such information, additional manual steps are required, which may add processing time that impedes their experience or may even result in additional cost to you.

To create Receive-only Users, you'll provide the customer's full name and email address, type with the value of receive-only, and businessName if applicable. Must be a US person.

To create Unverified Customers, you will only need to provide the customer's full name and email address, as well as a businessName if applicable. Must be a US person.

To create Verified Customers, Dwolla will require additional information to confirm the identity of the individual or business. Must be a US person. Verified Customers can include type business or personal. For businesses, Dwolla will need to verify information about both the business and the controller for that business. Dwolla does not identity verify the Account Admin. The controller may be a non-US person.

HTTP request #

POST https://api.dwolla.com/customers

HTTP status and error codes #

HTTP Status	Code	Description
201	Created	Customer created.
400	BadRequest	The request body contains bad syntax or is incomplete.
400	ValidationError	Reference the errors section for list of possible _embedded validation errors.
403	Forbidden	Not authorized to create customers.
404	NotFound	Customer not found.

Receive-only User - Request parameters #

Parameter	Required	Type	Description
firstName	yes	string	Customer's first name. Must be ≤ 50 characters and contain no special characters [<>="`!?%~${}\].
lastName	yes	string	Customer's last name. Must be ≤ 50 characters and contain no special characters [<>="`!?%~${}\].
email	yes	string	Customer's email address. Must be a valid email format (e.g., `example@domain.com`).
type	yes	string	Value of `receive-only`.
businessName	no	string	Customer's registered business name. (Optional if not a business entity, though if a business name is supplied, it must be ≤ 255 characters and cannot include special characters [<>="`!?%~${}\].)
ipAddress	no	string	Customer's IP address.
correlationId	no	string	A unique string value attached to a customer which can be used for traceability between Dwolla and your application. Must be ≤ 255 characters and contain no spaces. Acceptable characters: `a-z`, `0-9`, `-`, `.`, and `_`. Note: Do not use sensitive Personal Identifying Information (PII). Uniqueness is enforced across Customers.

Request and response - receive-only User

Raw

POST https://api-sandbox.dwolla.com/customers
Content-Type: application/vnd.dwolla.v1.hal+json
Accept: application/vnd.dwolla.v1.hal+json
Authorization: Bearer pBA9fVDBEyYZCEsLf/wKehyh1RTpzjUj5KzIRfDi0wKTii7DqY

{
  "firstName": "Jane",
  "lastName": "Merchant",
  "email": "jmerchant@nomail.net",
  "type": "receive-only",
  "businessName": "Jane Corp llc",
  "ipAddress": "99.99.99.99"
}

HTTP/1.1 201 Created
Location: https://api.dwolla.com/customers/fc451a7a-ae30-4404-aB95-e3553fcd733f

Unverified Customer - Request parameters #

Parameter	Required	Type	Description
firstName	yes	string	Customer's first name. Must be ≤ 50 characters and contain no special characters [<>="`!?%~${}\].
lastName	yes	string	Customer's last name. Must be ≤ 50 characters and contain no special characters [<>="`!?%~${}\].
email	yes	string	Customer's email address. Must be a valid email format (e.g., `example@domain.com`).
businessName	no	string	Customer's registered business name. (Optional if not a business entity, though if a business name is supplied, it must be ≤ 255 characters and cannot include special characters [<>="`!?%~${}\].)
ipAddress	no	string	Customer's IP address.
correlationId	no	string	A unique string value attached to a customer which can be used for traceability between Dwolla and your application. Must be ≤ 255 characters and contain no spaces. Acceptable characters: `a-z`, `0-9`, `-`, `.`, and `_`. Note: Do not use sensitive Personal Identifying Information (PII). Uniqueness is enforced across Customers.

Request and response - unverified Customer

Raw

POST https://api-sandbox.dwolla.com/customers
Content-Type: application/vnd.dwolla.v1.hal+json
Accept: application/vnd.dwolla.v1.hal+json
Authorization: Bearer pBA9fVDBEyYZCEsLf/wKehyh1RTpzjUj5KzIRfDi0wKTii7DqY

{
  "firstName": "Jane",
  "lastName": "Merchant",
  "email": "jmerchant@nomail.net",
  "ipAddress": "99.99.99.99",
  "businessName": "Jane Merchant's Business"
}

HTTP/1.1 201 Created
Location: https://api-sandbox.dwolla.com/customers/fc451a7a-ae30-4404-aB95-e3553fcd733f

Verified personal Customer - Request parameters #

For an in-depth look at personal verified Customers creation and status handling, refer to our developer guide.

Parameter	Required	Type	Description
firstName	yes	string	An individual Customer's first name. Must be ≤ 50 characters and contain no special characters [<>="`!?%~${}\].
lastName	yes	string	An individual Customer's last name. Must be ≤ 50 characters and contain no special characters [<>="`!?%~${}\].
email	yes	string	Customer's email address. Must be a valid email format (e.g., `example@domain.com`).
ipAddress	no	string	Customer's IP address.
type	yes	string	The Verified Customer type. Set to `personal` if creating a verified personal Customer.
address1	yes	string	First line of the street address of the Customer's permanent residence. Must be ≤ 50 characters, contain no special characters [<>="`!?%~${}\], and cannot be a PO Box.
address2	no	string	Second line of the street address of the Customer's permanent residence. Must be ≤ 50 characters, contain no special characters [<>="`!?%~${}\], and cannot be a PO Box.
city	yes	string	City of Customer's permanent residence. Must be ≤ 50 characters and cannot contain numbers or special characters [<>="`!?%~${}\].
state	yes	string	Two-letter abbreviation of the state in which the Customer resides, e.g., `CA`. Must be a valid U.S. state.
postalCode	yes	string	Postal code of Customer's permanent residence. Must be a US 5-digit ZIP code (e.g., `50314`) or ZIP+4 (e.g., `50314-1234`).
dateOfBirth	yes	string	Customer's date of birth in `YYYY-MM-DD` format. Must be between 18 to 125 years old at the time of submission.
ssn	yes	string	Last four or full 9 digits of the Customer's Social Security Number. Must contain only numbers (e.g., `1234` or `123456789`).
phone	no	string	Customer's 10-digit phone number. Must contain only numbers, no hyphens, spaces, or separators (e.g., `3334447777`).
correlationId	no	string	A unique string value attached to a customer which can be used for traceability between Dwolla and your application. Must be ≤ 255 characters and contain no spaces. Acceptable characters: `a-z`, `0-9`, `-`, `.`, and `_`. Note: Do not use sensitive Personal Identifying Information (PII). Uniqueness is enforced across Customers.

Request and response - verified personal Customer

Raw

POST https://api-sandbox.dwolla.com/customers
Content-Type: application/vnd.dwolla.v1.hal+json
Accept: application/vnd.dwolla.v1.hal+json
Authorization: Bearer pBA9fVDBEyYZCEsLf/wKehyh1RTpzjUj5KzIRfDi0wKTii7DqY

{
  "firstName": "John",
  "lastName": "Doe",
  "email": "johndoe@nomail.net",
  "ipAddress": "10.10.10.10",
  "type": "personal",
  "address1": "99-99 33rd St",
  "city": "Some City",
  "state": "NY",
  "postalCode": "11101",
  "dateOfBirth": "1970-01-01",
  "ssn": "1234"
}

HTTP/1.1 201 Created
Location: https://api.dwolla.com/customers/fc451a7a-ae30-4404-aB95-e3553fcd733f

Verified business Customer (sole proprietorship only) - Request parameters #

For an in-depth look at business verified Customers creation and status handling, refer to our developer guide. Dwolla will verify the identity of both the Business Owner and the Business entity.

Parameter	Required	Type	Description
firstName	yes	string	The legal first name of the business owner. Must be ≤ 50 characters and contain no special characters [<>="`!?%~${}\].
lastName	yes	string	The legal last name of the business owner. Must be ≤ 50 characters and contain no special characters [<>="`!?%~${}\].
email	yes	string	Email address of the business owner. Must be a valid email format (e.g., `example@domain.com`).
ipAddress	no	string	IP address of the registering user is recommended.
type	yes	string	Value of: `business`.
dateOfBirth	yes	string	The date of birth of the business owner. Must be in `YYYY-MM-DD` format and be between 18 to 125 years old.
ssn	yes	string	Last four or full 9 digits of the business owner's Social Security Number. Must contain only numbers (e.g., `1234` or `123456789`).
address1	yes	string	Street number, street name of business’ physical address. Must be ≤ 50 characters, contain no special characters [<>="`!?%~${}\], and cannot be a PO Box.
address2	no	string	Apartment, floor, suite, bldg. # of business’ physical address. Must be ≤ 50 characters and contain no special characters [<>="`!?%~${}\].
city	yes	string	City of business’ physical address. Must be ≤ 50 characters and cannot contain numbers or special characters [<>="`!?%~${}\].
state	yes	string	Two-letter US state or territory abbreviation code of business’ physical address. Must be uppercase (e.g., `CA`). Must be a valid U.S. state or territory abbreviation. For two-letter abbreviation reference, check out the US Postal Service guide.
postalCode	yes	string	Business’ US 5-digit ZIP code (e.g., `50314`) or ZIP+4 (e.g., `50314-1234`).
businessName	yes	string	Registered business name. Must be ≤ 255 characters and cannot include special characters [<>="`!?%~${}\].
doingBusinessAs	no	string	Preferred business name -- also known as fictitious name, or assumed name.
businessType	yes	string	Business structure. Value of `soleProprietorship`.
businessClassification	yes	string	The industry classification Id that corresponds to the Customer’s business. Reference the Business Classifications section to learn how to generate this Id.
ein	no	string	Employer Identification Number (optional for `soleProprietorship` business Customers).
website	no	string	Business’ website. e.g. `https://www.domain.com`
phone	no	string	Business's 10-digit phone number. Must contain only numbers, no hyphens, spaces, or separators (e.g., `3334447777`).
correlationId	no	string	A unique string value attached to a customer which can be used for traceability between Dwolla and your application, like a UUID. Must be ≤ 255 characters and contain no spaces. Acceptable characters: `a-z`, `0-9`, `-`, `.`, and `_`. Note: Do not use sensitive Personal Identifying Information (PII). Uniqueness is enforced across Customers.

Request and response - verified business Customer (sole proprietorship only)

Raw

POST https://api-sandbox.dwolla.com/customers
Content-Type: application/vnd.dwolla.v1.hal+json
Accept: application/vnd.dwolla.v1.hal+json
Authorization: Bearer 0Sn0W6kzNic+oWhDbQcVSKLRUpGjIdl/YyrHqrDDoRnQwE7Q

{
    "firstName": "Business",
    "lastName": "Owner",
    "email": "solePropBusiness@email.com",
    "ipAddress": "143.156.7.8",
    "type": "business",
    "dateOfBirth": "1980-01-31",
    "ssn": "6789",
    "address1": "99-99 33rd St",
    "city": "Some City",
    "state": "NY",
    "postalCode": "11101",
    "businessClassification": "9ed3f670-7d6f-11e3-b1ce-5404a6144203",
    "businessType": "soleProprietorship",
    "businessName":"Jane Corp",
    "ein":"00-0000000"
}

HTTP/1.1 201 Created
Location: https://api-sandbox.dwolla.com/customers/62c3aa1b-3a1b-46d0-ae90-17304d60c3d5

Verified business Customer (businessType=llc, corporation or partnership) - Request parameters #

For an in-depth look at business verified Customers creation and status handling, refer to our developer guide. A verified business Customer must input information on the controller and the Business entity for Dwolla. Dwolla will verify the identity of both the Controller and the Business Entity.

Parameter	Required	Type	Description
firstName	yes	string	The legal first name of the Account Admin or business owner signing up the business verified Customer. Must be ≤ 50 characters and contain no special characters [<>="`!?%~${}\].
lastName	yes	string	The legal last name of the Account Admin or individual signing up the business verified Customer. Must be ≤ 50 characters and contain no special characters [<>="`!?%~${}\].
email	yes	string	Email address of the individual creating and managing the Customer account. Must be a valid email format (e.g., `example@domain.com`).
ipAddress	no	string	IP address of the registering user is recommended.
type	yes	string	Value of: `business`.
address1	yes	string	Street number, street name of business’ physical address. Must be ≤ 50 characters, contain no special characters [<>="`!?%~${}\], and cannot be a PO Box.
address2	no	string	Apartment, floor, suite, bldg. # of business’ physical address. Must be ≤ 50 characters and contain no special characters [<>="`!?%~${}\].
city	yes	string	City of business’ physical address. Must be ≤ 50 characters and cannot contain numbers or special characters [<>="`!?%~${}\].
state	yes	string	Two-letter US state or territory abbreviation code of business’ physical address. Must be uppercase (e.g., `CA`). Must be a valid U.S. state or territory abbreviation. For two-letter abbreviation reference, check out the US Postal Service guide.
postalCode	yes	string	Business’ US 5-digit ZIP code (e.g., `50314`) or ZIP+4 (e.g., `50314-1234`).
businessName	yes	string	Registered business name. Must be ≤ 255 characters and cannot include special characters [<>="`!?%~${}\].
doingBusinessAs	no	string	Preferred business name – also known as fictitious name, or assumed name. Must be ≤ 255 characters and cannot include special characters [<>="`!?%~${}\].
businessType	yes	string	Business structure. Must be one of the following values: `corporation`, `llc`, or `partnership`.
businessClassification	yes	string	The industry classification Id that corresponds to the Customer’s business. Reference the Business Classifications section to learn how to generate this Id.
ein	yes	string	Employer Identification Number (EIN). Must contain only numbers and be 9 digits long (e.g., `123456789`).
website	no	string	Business’ website. e.g., `https://www.domain.com`. Must be a valid URL format.
phone	no	string	Business's 10-digit phone number. Must contain only numbers, no hyphens, spaces, or separators (e.g., `3334447777`).
controller	conditional	object	A controller JSON object. Required for businesses that are not sole proprietorships.
correlationId	no	string	A unique string value attached to a customer which can be used for traceability between Dwolla and your application, like a UUID. Must be ≤ 255 characters and contain no spaces. Acceptable characters: `a-z`, `0-9`, `-`, `.`, and `_`. Note: Do not use sensitive Personal Identifying Information (PII). Uniqueness is enforced across Customers.

Controller JSON object #

A controller is any natural individual who holds significant responsibilities to control, manage, or direct a company or other corporate entity (i.e. CEO, CFO, General Partner, President, etc). A company may have more than one controller, but only one controller’s information must be collected. A controller may be a non-US person.

Parameter	Required	Type	Description
firstName	yes	string	The legal first name of the controller. Must be ≤ 50 characters and contain no special characters [<>="`!?%~${}\].
lastName	yes	string	The legal last name of the controller. Must be ≤ 50 characters and contain no special characters [<>="`!?%~${}\].
title	yes	string	Job title of the business verified Customer’s controller (e.g., `Chief Financial Officer`). Must be ≤ 100 characters and cannot contain special characters [<>="`!?%~${}\].
dateOfBirth	yes	string	The date of birth of the controller. Must be formatted as `YYYY-MM-DD` and correspond to an individual between 18 and 125 years old.
ssn	conditional	string	Last four or full 9 digits of the controller’s Social Security Number (SSN). Required for U.S. persons. If SSN is omitted, a passport JSON object must be provided.
address	yes	object	A full address JSON object. Must be a valid U.S. or international physical address.
passport	conditional	object	A passport JSON object. Required for non-U.S. persons. Must include Passport Identification Number and Country. If omitted, an SSN is required.

Controller address JSON object #

Parameter	Required	Type	Description
address1	yes	string	Street number, street name of the controller’s physical address. Note: PO Boxes are not allowed. Must be ≤ 50 characters and contain no special characters [<>="`!?%~${}\].
address2	no	string	Apartment, floor, suite, bldg. # of the controller’s physical address. Note: PO Boxes are not allowed. Must be ≤ 50 characters and contain no special characters [<>="`!?%~${}\].
address3	no	string	Third line of the street address of the controller's physical address. Note: PO Boxes are not allowed. Must be ≤ 50 characters and contain no special characters [<>="`!?%~${}\].
city	yes	string	City of the controller’s physical address. Must be ≤ 50 characters and cannot contain numbers or special characters [<>="`!?%~${}\].
stateProvinceRegion	yes	string	US persons - Two-letter US state abbreviation code of the controller’s physical address. See the US Postal Service guide. Non-US persons - Two-letter state, province, or region ISO abbreviation of the controller’s address. See the ISO guide. Note: If a country does not have a two-letter abbreviation for a state/province, use two-letter ISO country code instead. Must be uppercase (e.g., `CA`).
postalCode	conditional	string	US persons - Must provide a 5-digit ZIP code (e.g., `12345`) or ZIP+4 (e.g., `12345-6789`). Non-US persons - Optional. Can include alphanumeric postal codes where applicable.
country	yes	string	Country of the controller’s physical address. Must be a two-letter ISO country code (e.g., `US` for United States, `CA` for Canada). Reference the ISO country codes list.

Controller passport JSON object #

A controller will only need to input passport information if they are non-US persons and do not have a Social Security Number.

Parameter	Required	Type	Description
number	conditional	string	Required if the controller is a non-US person and does not have a Social Security Number (SSN). Must be ≤ 255 characters.
country	conditional	string	Country where the passport was issued. Must be a two-letter ISO country code (e.g., `GB` for United Kingdom, `IN` for India).

Request and response - Verified Business Customer (businessType= llc, corporation or partnership)

Raw

POST https://api-sandbox.dwolla.com/customers
Content-Type: application/vnd.dwolla.v1.hal+json
Accept: application/vnd.dwolla.v1.hal+json
Authorization: Bearer 0Sn0W6kzNic+oWhDbQcVSKLRUpGjIdl/YyrHqrDDoRnQwE7Q

{
    "firstName": "Account",
    "lastName": "Admin",
    "email": "accountAdmin@email.com",
    "ipAddress": "143.156.7.8",
    "type": "business",
    "address1": "99-99 33rd St",
    "city": "Some City",
    "state": "NY",
    "postalCode": "11101",
    "controller": {
        "firstName": "John",
        "lastName": "Controller",
        "title": "CEO",
        "ssn": "6789",
        "dateOfBirth": "1980-01-31",
        "address": {
            "address1": "1749 18th st",
            "address2": "apt 12",
            "city": "Des Moines",
            "stateProvinceRegion": "IA",
            "postalCode": "50266",
            "country": "US"
        }
    },
    "businessClassification": "9ed3f670-7d6f-11e3-b1ce-5404a6144203",
    "businessType": "llc",
    "businessName":"Jane Corp",
    "ein":"00-0000000"
}

HTTP/1.1 201 Created
Location: https://api-sandbox.dwolla.com/customers/62c3aa1b-3a1b-46d0-ae90-17304d60c3d5

Overview

Retrieve a customer

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.