Dwolla Developers Logo
Back
API Reference
  • SDK Support
    Drop-in Components
    Authorization
    Root
    Accounts
    Customers
    OverviewCreate a customerRetrieve a customerList and search customersUpdate a customerList business classificationsRetrieve a business classification
    Knowledge-based Authentication (KBA)
    Beneficial Owners
    Documents
    Funding Sources
    Transfers
    Mass payments
    Labels
    Events
    Webhook subscriptions
    Webhooks
CommunityOpen in new tabChangelog
Get API Keys
CommunityOpen in new tabChangelog
JavaScript
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 StatusCodeDescription201CreatedCustomer 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 #

ParameterRequiredTypeDescriptionfirstNameyesstringCustomer'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)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
JavaScript
var requestBody = {
  firstName: "Jane",
  lastName: "Merchant",
  email: "jmerchant@nomail.net",
  type: "receive-only",
  businessName: "Jane Corp llc",
  ipAddress: "99.99.99.99",
};

dwolla
  .post("customers", requestBody)
  .then((res) => res.headers.get("location")); // => 'https://api-sandbox.dwolla.com/customers/fc451a7a-ae30-4404-aB95-e3553fcd733f'

Unverified Customer - Request parameters #

ParameterRequiredTypeDescriptionfirstNameyesstringCustomer'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)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
JavaScript
var requestBody = {
  firstName: "Jane",
  lastName: "Merchant",
  email: "jmerchant@nomail.net",
  ipAddress: "99.99.99.99",
};

dwolla
  .post("customers", requestBody)
  .then((res) => res.headers.get("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 resource article.

ParameterRequiredTypeDescriptionfirstNameyesstringAn 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
JavaScript
var requestBody = {
  firstName: "John",
  lastName: "Doe",
  email: "jdoe@nomail.net",
  type: "personal",
  address1: "99-99 33rd St",
  city: "Some City",
  state: "NY",
  postalCode: "11101",
  dateOfBirth: "1970-01-01",
  // For the first attempt, only the
  // last 4 digits of SSN required
  // If the entire SSN is provided,
  // it will still be accepted
  ssn: "1234",
};

dwolla
  .post("customers", requestBody)
  .then((res) => res.headers.get("location")); // => 'https://api-sandbox.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 resource article. Dwolla will verify the identity of both the Business Owner and the Business entity.

ParameterRequiredTypeDescriptionfirstNameyesstringThe 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: businessdateOfBirthyesstringThe 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.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 CustomerswebsitenostringBusiness’ website. e.g. https://www.domain.comphonenostringBusiness'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)
JavaScript
var requestBody = {
  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",
};

dwolla
  .post("customers", requestBody)
  .then((res) => res.headers.get("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 resource article. 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.

ParameterRequiredTypeDescriptionfirstNameyesstringThe 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: businessaddress1yesstringStreet 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.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.comphonenostringBusiness'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.

ParameterRequiredTypeDescriptionfirstNameyesStringThe 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 OfficerdateOfBirthyesStringThe 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
ParameterRequiredTypeDescriptionaddress1yesstringStreet 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.

ParameterRequiredTypeDescriptionnumberconditionalstringRequired 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)
JavaScript
var requestBody = {
  firstName: 'Account',
  lastName: 'Admin',
  email: 'accountAdmin@email.com',
  type: 'business',
  address1: '99-99 33rd St',
  city: 'Some City',
  state: 'NY',
  postalCode: '11101',
  controller: {
      firstName: 'John',
      lastName: 'Controller',
      title: 'CEO',
      dateOfBirth: '1980-01-31',
      ssn: '1234'
      address: {
        address1: '1749 18th st',
        address2: 'apt 12',
        city: 'Des Moines',
        stateProvinceRegion: 'IA',
        postalCode: '50266',
        country: 'US',
      }
  },
  businessClassification: '9ed38155-7d6f-11e3-83c3-5404a6144203',
  businessType: 'llc',
  businessName: 'Jane Corp',
  ein: '12-3456789'
};
dwolla
  .post('customers', requestBody)
  .then(res => res.headers.get('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
2021 All Rights Reserved

Dwolla

  • About
  • Blog
  • Pricing
  • Contact Sales
  • Terms of Service
  • Privacy Policy
Financial institutions play an important role in our network.

Dwolla, Inc. is the operator of a software platform that communicates user instructions for funds transfers to our financial institution partners.

Dwolla is an agent of Veridian Credit Union. All ACH and Wire transfers are performed by Veridian Credit Union. Your Dwolla Balance, if any, is held in one or more pooled holding accounts held by Veridian Credit Union. These funds may not be eligible for share insurance by the National Credit Union Share Insurance Fund.

Sponsorship and Settlement of Push-to-Debit payment services provided by MetaBank®, N.A.
Push-to-Debit payments are typically available within 30 minutes.

Real-Time Payments are performed by Cross River Bank, which holds funds on behalf of the Receiver of such transactions in one or more pooled custodial accounts. These funds are not subject to FDIC pass-through deposit insurance.