Docs

Select Language

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 less than or equal to 50 characters and contain no special characters.
lastName	yes	string	Customer's last name. Must be less than or equal to 50 characters and contain no special characters.
email	yes	string	Customer's email address.
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 or fewer, and cannot include any 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. Note: A correlationId is not a replacement for an idempotency-key. Must be less than or equal to 255 characters and contain no spaces. Acceptable characters are: `a-Z`, `0-9`, `-`, `.`, and `_`. Note: Sensitive Personal Identifying Information (PII) should not be used in this field and it is recommended to use a random value for correlationId, like a UUID. Uniqueness is enforced on correlationId 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 less than or equal to 50 characters and contain no special characters.
lastName	yes	string	Customer's last name. Must be less than or equal to 50 characters and contain no special characters.
email	yes	string	Customer's email address.
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 or fewer, and cannot include any 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 less than or equal to 255 characters and contain no spaces. Acceptable characters are: `a-Z`, `0-9`, `-`, `.`, and `_`. Note: Sensitive Personal Identifying Information (PII) should not be used in this field and it is recommended to use a random value for correlationId, like a UUID. Uniqueness is enforced on correlationId 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 less than or equal to 50 characters and contain no special characters.
lastName	yes	string	An individual Customer's last name. Must be less than or equal to 50 characters and contain no special characters.
email	yes	string	Customer's email address.
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 less than or equal to 50 characters and contain no special characters. Note: PO Boxes are not allowed.
address2	no	string	Second line of the street address of the Customer's permanent residence. Must be less than or equal to 50 characters and contain no special characters. Note: PO Boxes are not allowed.
city	yes	string	City of Customer's permanent residence.
state	yes	string	Two letter abbreviation of the state in which the Customer resides, e.g. `CA`.
postalCode	yes	string	Postal code of Customer's permanent residence. US five-digit ZIP or ZIP + 4 code. e.g. `50314`.
dateOfBirth	yes	string	Customer's date of birth in `YYYY-MM-DD` format. Must be between 18 to 125 years of age.
ssn	yes	string	Last four or full 9 digits of the Customer's Social Security Number.
phone	no	string	Customer's 10 digit phone number. No hyphens or other 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 less than or equal to 255 characters and contain no spaces. Acceptable characters are: `a-Z`, `0-9`, `-`, `.`, and `_`. Note: Sensitive Personal Identifying Information (PII) should not be used in this field and it is recommended to use a random value for correlationId, like a UUID. Uniqueness is enforced on correlationId 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 less than or equal to 50 characters and contain no special characters.
lastName	yes	string	The legal last name of the business owner. Must be less than or equal to 50 characters and contain no special characters.
email	yes	string	email address of the business owner.
ipAddress	no	string	ipAddress of registering user is recommended.
type	yes	string	Value of: `business`
dateOfBirth	yes	string	The date of birth of the business owner. Formatted in `YYYY-MM-DD` format. Must be between 18 to 125 years of age.
ssn	yes	string	Last four or full 9 digits of the business owner's Social Security Number.
address1	yes	string	Street number, street name of business’ physical address. Must be less than or equal to 50 characters and contain no special characters.
address2	no	string	Apartment, floor, suite, bldg. # of business’ physical address Must be less than or equal to 50 characters and contain no special characters.
city	yes	string	City of business’ physical address.
state	yes	string	Two-letter US state or territory abbreviation code of business’ physical address. For two-letter abbreviation reference, check out the US Postal Service guide.
postalCode	yes	string	Business’ US five-digit ZIP or ZIP + 4 code.
businessName	yes	string	Registered business name. Name must be 255 characters or fewer, and cannot include any 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 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. No hyphens or other 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 less than or equal to 255 characters and contain no spaces. Acceptable characters are: `a-Z`, `0-9`, `-`, `.`, and `_`. Note: Sensitive Personal Identifying Information (PII) should not be used in this field and it is recommended to use a random value for correlationId, like a UUID. Uniqueness is enforced on correlationId 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 less than or equal to 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 less than or equal to 50 characters and contain no special characters.
email	yes	string	email address of individual creating and managing the Customer account.
ipAddress	no	string	ipAddress of registering user is recommended.
type	yes	string	Value of: `business`
address1	yes	string	Street number, street name of business’ physical address. Must be less than or equal to 50 characters and contain no special characters.
address2	no	string	Apartment, floor, suite, bldg. # of business’ physical address. Must be less than or equal to 50 characters and contain no special characters.
city	yes	string	City of business’ physical address.
state	yes	string	Two-letter US state or territory abbreviation code of business’ physical address. For two-letter abbreviation reference, check out the US Postal Service guide.
postalCode	yes	string	Business’ US five-digit ZIP or ZIP + 4 code.
businessName	yes	string	Registered business name. Name must be 255 characters or fewer, and cannot include any special characters.
doingBusinessAs	no	string	Preferred business name – also known as fictitious name, or assumed name.
businessType	yes	string	Business structure. Possible values are `corporation`, `llc`, `partnership`.
businessClassification	yes	string	The industry classification Id that corresponds to Customer’s business. Reference the Business Classifications section to learn how to generate this Id.
ein	yes	string	Employer Identification Number.
website	no	string	Business’ website. e.g. `https://www.domain.com`
phone	no	string	Business's 10 digit phone number. No hyphens or other separators, e.g. `3334447777`.
controller	conditional	object	A controller JSON object.
correlationId	no	string	A unique string value attached to a customer which can be used for traceability between Dwolla and your application. Must be less than or equal to 255 characters and contain no spaces. Acceptable characters are: `a-Z`, `0-9`, `-`, `.`, and `_`. Note: Sensitive Personal Identifying Information (PII) should not be used in this field and it is recommended to use a random value for correlationId, like a UUID. Uniqueness is enforced on correlationId 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.
lastName	yes	String	The legal last name of the controller.
title	yes	String	Job title of the business verified Customer’s controller. IE - Chief Financial Officer
dateOfBirth	yes	String	The date of birth of the controller. Formatted in YYYY-MM-DD format. Must be between 18 to 125 years of age.
ssn	conditional	String	Last four or full 9 digits of controller’s Social Security Number. Required for US persons. If SSN is omitted, passport is required.
address	yes	object	An address JSON object. Full address of the controller'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.

Controller address JSON object #

Parameter	Required	Type	Description
address1	yes	string	Street number, street name of controller’s physical address. Note: PO Boxes are not allowed.
address2	no	string	Apartment, floor, suite, bldg. # of controller’s physical address. Note: PO Boxes are not allowed.
address3	no	string	Third line of the street address of the controller's physical address. Note: PO Boxes are not allowed.
city	yes	string	City of controller’s physical address.
stateProvinceRegion	yes	string	US persons - Two-letter US state abbreviation code of controller’s physical address. For two-letter US state abbreviation reference, check out the US Postal Service guide. Non-US persons - Two-letter state, province, or region ISO abbreviation code of controller's physical address. For two-letter ISO abbreviation reference, check out the ISO guide.
postalCode	conditional	string	Controller’s’ US five-digit ZIP or ZIP + 4 code. Optional if controller is a non-US person.
country	yes	string	Country of controller’s physical address. Two digit ISO code, e.g. `US`.

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 controller is a non-US person and has no Social Security Number.
country	conditional	string	Country of issued passport.

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.