Ask AI or search...
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 StatusCodeDescription
201CreatedCustomer created.
400BadRequestThe request body contains bad syntax or is incomplete.
400ValidationErrorReference the errors section for list of possible _embedded validation errors.
403ForbiddenNot authorized to create customers.
404NotFoundCustomer not found.

Receive-only User - Request parameters #

ParameterRequiredTypeDescription
firstNameyesstringCustomer's first name. Must be less than or equal to 50 characters and contain no special characters.
lastNameyesstringCustomer's last name. Must be less than or equal to 50 characters and contain no special characters.
emailyesstringCustomer's email address.
typeyesstringValue of receive-only.
businessNamenostringCustomer'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.)
ipAddressnostringCustomer's IP address.
correlationIdnostringA 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 #

ParameterRequiredTypeDescription
firstNameyesstringCustomer's first name. Must be less than or equal to 50 characters and contain no special characters.
lastNameyesstringCustomer's last name. Must be less than or equal to 50 characters and contain no special characters.
emailyesstringCustomer's email address.
businessNamenostringCustomer'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.)
ipAddressnostringCustomer's IP address.
correlationIdnostringA 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.

ParameterRequiredTypeDescription
firstNameyesstringAn individual Customer's first name. Must be less than or equal to 50 characters and contain no special characters.
lastNameyesstringAn individual Customer's last name. Must be less than or equal to 50 characters and contain no special characters.
emailyesstringCustomer's email address.
ipAddressnostringCustomer's IP address.
typeyesstringThe Verified Customer type. Set to personal if creating a verified personal Customer.
address1yesstringFirst 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.
address2nostringSecond 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.
cityyesstringCity of Customer's permanent residence.
stateyesstringTwo letter abbreviation of the state in which the Customer resides, e.g. CA.
postalCodeyesstringPostal code of Customer's permanent residence. US five-digit ZIP or ZIP + 4 code. e.g. 50314.
dateOfBirthyesstringCustomer's date of birth in YYYY-MM-DD format. Must be between 18 to 125 years of age.
ssnyesstringLast four or full 9 digits of the Customer's Social Security Number.
phonenostringCustomer's 10 digit phone number. No hyphens or other separators, e.g. 3334447777.
correlationIdnostringA 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.

ParameterRequiredTypeDescription
firstNameyesstringThe legal first name of the business owner. Must be less than or equal to 50 characters and contain no special characters.
lastNameyesstringThe legal last name of the business owner. Must be less than or equal to 50 characters and contain no special characters.
emailyesstringemail address of the business owner.
ipAddressnostringipAddress of registering user is recommended.
typeyesstringValue of: business
dateOfBirthyesstringThe date of birth of the business owner. Formatted in YYYY-MM-DD format. Must be between 18 to 125 years of age.
ssnyesstringLast four or full 9 digits of the business owner's Social Security Number.
address1yesstringStreet number, street name of business’ physical address. Must be less than or equal to 50 characters and contain no special characters.
address2nostringApartment, floor, suite, bldg. # of business’ physical address Must be less than or equal to 50 characters and contain no special characters.
cityyesstringCity of business’ physical address.
stateyesstringTwo-letter US state or territory abbreviation code of business’ physical address. For two-letter abbreviation reference, check out the US Postal Service guide.
postalCodeyesstringBusiness’ US five-digit ZIP or ZIP + 4 code.
businessNameyesstringRegistered business name. Name must be 255 characters or fewer, and cannot include any special characters.
doingBusinessAsnostringPreferred business name -- also known as fictitious name, or assumed name.
businessTypeyesstringBusiness structure. Value of soleProprietorship.
businessClassificationyesstringThe industry classification Id that corresponds to Customer’s business. Reference the Business Classifications section to learn how to generate this Id.
einnostringEmployer Identification Number. Optional for soleProprietorship business Customers
websitenostringBusiness’ website. e.g. https://www.domain.com
phonenostringBusiness's 10 digit phone number. No hyphens or other separators, e.g. 3334447777.
correlationIdnostringA 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.

ParameterRequiredTypeDescription
firstNameyesstringThe 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.
lastNameyesstringThe 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.
emailyesstringemail address of individual creating and managing the Customer account.
ipAddressnostringipAddress of registering user is recommended.
typeyesstringValue of: business
address1yesstringStreet number, street name of business’ physical address. Must be less than or equal to 50 characters and contain no special characters.
address2nostringApartment, floor, suite, bldg. # of business’ physical address. Must be less than or equal to 50 characters and contain no special characters.
cityyesstringCity of business’ physical address.
stateyesstringTwo-letter US state or territory abbreviation code of business’ physical address. For two-letter abbreviation reference, check out the US Postal Service guide.
postalCodeyesstringBusiness’ US five-digit ZIP or ZIP + 4 code.
businessNameyesstringRegistered business name. Name must be 255 characters or fewer, and cannot include any special characters.
doingBusinessAsnostringPreferred business name – also known as fictitious name, or assumed name.
businessTypeyesstringBusiness structure. Possible values are corporation, llc, partnership.
businessClassificationyesstringThe industry classification Id that corresponds to Customer’s business. Reference the Business Classifications section to learn how to generate this Id.
einyesstringEmployer Identification Number.
websitenostringBusiness’ website. e.g. https://www.domain.com
phonenostringBusiness's 10 digit phone number. No hyphens or other separators, e.g. 3334447777.
controllerconditionalobjectA controller JSON object.
correlationIdnostringA 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.

ParameterRequiredTypeDescription
firstNameyesStringThe legal first name of the controller.
lastNameyesStringThe legal last name of the controller.
titleyesStringJob title of the business verified Customer’s controller. IE - Chief Financial Officer
dateOfBirthyesStringThe date of birth of the controller. Formatted in YYYY-MM-DD format. Must be between 18 to 125 years of age.
ssnconditionalStringLast four or full 9 digits of controller’s Social Security Number. Required for US persons. If SSN is omitted, passport is required.
addressyesobjectAn address JSON object. Full address of the controller's physical address.
passportconditionalobjectAn 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 #

ParameterRequiredTypeDescription
address1yesstringStreet number, street name of controller’s physical address. Note: PO Boxes are not allowed.
address2nostringApartment, floor, suite, bldg. # of controller’s physical address. Note: PO Boxes are not allowed.
address3nostringThird line of the street address of the controller's physical address. Note: PO Boxes are not allowed.
cityyesstringCity of controller’s physical address.
stateProvinceRegionyesstringUS 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.
postalCodeconditionalstringController’s’ US five-digit ZIP or ZIP + 4 code. Optional if controller is a non-US person.
countryyesstringCountry 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.

ParameterRequiredTypeDescription
numberconditionalstringRequired if controller is a non-US person and has no Social Security Number.
countryconditionalstringCountry 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
Test in the Sandbox for free today.
Use sandbox environment to test API requests.
Get API Keys
2024 All Rights Reserved
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.