Create, retrieve, update, list and search Dwolla Customers — the account holders you onboard to send or receive money. Supports Unverified, Receive-Only, Personal Verified and Business Verified customer types with the identity-verification (KYC/CIP) fields the U.S. banking system requires, plus business classification lookups used during business-customer onboarding.
openapi: 3.1.0
info:
title: Dwolla API - Customers
description: Dwolla API Documentation
contact:
name: Dwolla Developer Relations Team
url: https://developers.dwolla.com
email: api@dwolla.com
version: '2.0'
termsOfService: https://www.dwolla.com/legal/tos/
license:
name: MIT
url: https://github.com/Dwolla/dwolla-openapi/blob/master/LICENSE
jsonSchemaDialect: https://spec.openapis.org/oas/3.1/dialect/base
servers:
- url: https://api.dwolla.com
description: Production server
- url: https://api-sandbox.dwolla.com
description: Sandbox server
security:
- clientCredentials: []
tags:
- name: customers
description: Operations related to Customers
paths:
/customers:
get:
tags:
- customers
summary: List and search customers
description: Returns a paginated list of customers sorted by creation date. Supports fuzzy search
across customer names, business names, and email addresses, plus exact filtering by email and
verification status. Default limit is 25 customers per page, maximum 200.
operationId: listAndSearchCustomers
x-speakeasy-name-override: list
parameters:
- name: limit
in: query
description: How many results to return
required: false
schema:
type: integer
- name: offset
in: query
description: How many results to skip
required: false
schema:
type: integer
- name: search
in: query
description: Searches on certain fields
required: false
schema:
type: string
- name: status
in: query
description: Filter by customer status
required: false
schema:
type: string
- $ref: '#/components/parameters/Accept'
responses:
'200':
description: successful operation
headers: {}
content:
application/vnd.dwolla.v1.hal+json:
schema:
$ref: '#/components/schemas/Customers'
'403':
description: Forbidden
headers: {}
content:
application/vnd.dwolla.v1.hal+json:
schema:
$ref: '#/components/schemas/ForbiddenError'
post:
tags:
- customers
summary: Create a customer
description: Creates a new customer with different verification levels and capabilities. Supports
personal verified customers (individuals), business verified customers (businesses), unverified
customers, and receive-only users. Customer type determines transaction limits, verification requirements,
and available features.
operationId: createCustomer
x-speakeasy-name-override: create
parameters:
- $ref: '#/components/parameters/Accept'
requestBody:
required: true
description: Parameters for customer to be created
content:
application/vnd.dwolla.v1.hal+json:
schema:
oneOf:
- $ref: '#/components/schemas/CreateReceiveOnlyUser'
- $ref: '#/components/schemas/CreateUnverifiedCustomer'
- $ref: '#/components/schemas/CreateVerifiedPersonalCustomer'
- $ref: '#/components/schemas/CreateVerifiedSolePropCustomer'
- $ref: '#/components/schemas/CreateVerifiedBusinessCustomerWithController'
- $ref: '#/components/schemas/CreateVerifiedBusinessCustomerWithInternationalController'
responses:
'201':
description: successful operation
headers:
Location:
$ref: '#/components/headers/Location'
'400':
description: Bad Request
headers: {}
content:
application/vnd.dwolla.v1.hal+json:
schema:
$ref: '#/components/schemas/BadRequestError'
'403':
description: forbidden
headers: {}
content:
application/vnd.dwolla.v1.hal+json:
schema:
type: object
properties:
code:
type: string
example: forbidden
message:
type: string
example: Not authorized to create customers.
'404':
description: not found
headers: {}
content:
application/vnd.dwolla.v1.hal+json:
schema:
type: object
properties:
code:
type: string
example: notFound
message:
type: string
example: not found.
/customers/{id}:
get:
tags:
- customers
summary: Retrieve a customer
description: Retrieve identifying information for a specific customer. The returned data varies
by customer type - verified customers include contact details, address information, and verification
status, while unverified customers and receive-only users contain basic contact information only.
operationId: getCustomer
x-speakeasy-name-override: get
x-codeSamples:
- lang: bash
source: 'GET https://api-sandbox.dwolla.com/customers/FC451A7A-AE30-4404-AB95-E3553FCD733F
Accept: application/vnd.dwolla.v1.hal+json
Authorization: Bearer pBA9fVDBEyYZCEsLf/wKehyh1RTpzjUj5KzIRfDi0wKTii7DqY
'
- lang: javascript
source: "// Using dwolla-v2 - https://github.com/Dwolla/dwolla-v2-node\ndwolla\n .get(\"customers/FC451A7A-AE30-4404-AB95-E3553FCD733F\"\
)\n .then((res) => res.body);\n"
- lang: python
source: '# Using dwollav2 - https://github.com/Dwolla/dwolla-v2-python
customer = app_token.get(''customers/FC451A7A-AE30-4404-AB95-E3553FCD733F'')
customer.body
'
- lang: php
source: '<?php
// Using dwollaswagger - https://github.com/Dwolla/dwolla-swagger-php
$customersApi = new DwollaSwagger\CustomersApi($apiClient);
$customer = $customersApi->getCustomer("FC451A7A-AE30-4404-AB95-E3553FCD733F");
?>
'
- lang: ruby
source: '# Using dwolla_v2 - https://github.com/Dwolla/dwolla-v2-ruby
customer = app_token.get "customers/FC451A7A-AE30-4404-AB95-E3553FCD733F"
'
parameters:
- name: id
in: path
description: Customer unique identifier
required: true
schema:
type: string
- $ref: '#/components/parameters/Accept'
responses:
'200':
description: successful operation
headers: {}
content:
application/vnd.dwolla.v1.hal+json:
schema:
oneOf:
- $ref: '#/components/schemas/UnverifiedCustomer'
- $ref: '#/components/schemas/ReceiveOnlyCustomer'
- $ref: '#/components/schemas/VerifiedPersonalCustomer'
- $ref: '#/components/schemas/VerifiedSolePropCustomer'
- $ref: '#/components/schemas/VerifiedBusinessCustomer'
'403':
description: forbidden
headers: {}
content:
application/vnd.dwolla.v1.hal+json:
schema:
type: object
properties:
code:
type: string
example: forbidden
message:
type: string
example: Not authorized to get a customer by id.
'404':
description: not found
headers: {}
content:
application/vnd.dwolla.v1.hal+json:
schema:
type: object
properties:
code:
type: string
example: notFound
message:
type: string
example: Customer not found.
post:
tags:
- customers
summary: Update a customer
description: Update Customer information, upgrade an unverified Customer to a verified Customer,
suspend a Customer, deactivate a Customer, reactivate a Customer, and update a verified Customer's
information to retry verification.
operationId: update
x-codeSamples:
- lang: bash
source: "POST https://api-sandbox.dwolla.com/customers/FC451A7A-AE30-4404-AB95-E3553FCD733F\n\
Content-Type: application/json\nAccept: application/vnd.dwolla.v1.hal+json\nAuthorization: Bearer\
\ pBA9fVDBEyYZCEsLf/wKehyh1RTpzjUj5KzIRfDi0wKTii7DqY\n\n{\n \"firstName\": \"John\",\n \"\
lastName\": \"Doe\",\n \"email\": \"johndoe@example.com\"\n}\n"
- lang: javascript
source: "// Using dwolla-v2 - https://github.com/Dwolla/dwolla-v2-node\ndwolla\n .post(\"customers/FC451A7A-AE30-4404-AB95-E3553FCD733F\"\
, {\n firstName: \"John\",\n lastName: \"Doe\",\n email: \"johndoe@example.com\"\n\
\ })\n .then((res) => res.body);\n"
- lang: python
source: "# Using dwollav2 - https://github.com/Dwolla/dwolla-v2-python\ncustomer = app_token.post('customers/FC451A7A-AE30-4404-AB95-E3553FCD733F',\
\ {\n 'firstName': 'John',\n 'lastName': 'Doe',\n 'email': 'johndoe@example.com'\n\
})\ncustomer.body\n"
- lang: php
source: "<?php\n// Using dwollaswagger - https://github.com/Dwolla/dwolla-swagger-php\n$customersApi\
\ = new DwollaSwagger\\CustomersApi($apiClient);\n$customer = $customersApi->updateCustomer(\"\
FC451A7A-AE30-4404-AB95-E3553FCD733F\", [\n 'firstName' => 'John',\n 'lastName' => 'Doe',\n\
\ 'email' => 'johndoe@example.com'\n]);\n?>\n"
- lang: ruby
source: "# Using dwolla_v2 - https://github.com/Dwolla/dwolla-v2-ruby\ncustomer = app_token.post\
\ \"customers/FC451A7A-AE30-4404-AB95-E3553FCD733F\", {\n firstName: \"John\",\n lastName:\
\ \"Doe\",\n email: \"johndoe@example.com\"\n}\n"
parameters:
- name: id
in: path
description: Customer unique identifier
required: true
schema:
type: string
- $ref: '#/components/parameters/Accept'
requestBody:
required: true
description: Parameters for updating a Customer
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/DeactivateCustomer'
- $ref: '#/components/schemas/ReactivateCustomer'
- $ref: '#/components/schemas/SuspendCustomer'
- $ref: '#/components/schemas/UpdateUnverifiedAndReceiveOnly'
- $ref: '#/components/schemas/UpdateVerifiedPersonal'
- $ref: '#/components/schemas/UpdateVerifiedBusiness'
- $ref: '#/components/schemas/UpgradeToUnverified'
- $ref: '#/components/schemas/UpgradeToVerifiedPersonal'
- $ref: '#/components/schemas/UpgradeToVerifiedBusiness'
- $ref: '#/components/schemas/UpgradeToVerifiedSoleProp'
- $ref: '#/components/schemas/RetryVerifiedPersonal'
- $ref: '#/components/schemas/RetryVerifiedBusinessNoController'
- $ref: '#/components/schemas/RetryVerifiedBusinessWithController'
- $ref: '#/components/schemas/RetryVerifiedBusinessWithInternationalController'
- $ref: '#/components/schemas/RetryVerifiedSoleProp'
responses:
'200':
description: successful operation
headers: {}
content:
application/vnd.dwolla.v1.hal+json:
schema:
oneOf:
- $ref: '#/components/schemas/UnverifiedCustomer'
- $ref: '#/components/schemas/ReceiveOnlyCustomer'
- $ref: '#/components/schemas/VerifiedPersonalCustomer'
- $ref: '#/components/schemas/VerifiedSolePropCustomer'
- $ref: '#/components/schemas/VerifiedBusinessCustomer'
'400':
description: bad request
headers: {}
content:
application/vnd.dwolla.v1.hal+json:
schema:
type: object
properties:
code:
type: string
example: badRequest
message:
type: string
example: Duplicate customer or validation error.
'403':
description: forbidden
headers: {}
content:
application/vnd.dwolla.v1.hal+json:
schema:
type: object
properties:
code:
type: string
example: forbidden
message:
type: string
example: Not authorized to update a customer.
/business-classifications:
get:
tags:
- customers
summary: List business classifications
description: Returns a directory of business and industry classifications required for creating
business verified customers. Each business classification contains multiple industry classifications.
The industry classification ID must be provided in the businessClassification parameter during
business customer creation for verification.
operationId: listBusinessClassifications
x-speakeasy-group: businessClassifications
x-speakeasy-name-override: list
x-codeSamples:
- lang: bash
source: 'GET https://api-sandbox.dwolla.com/business-classifications
Accept: application/vnd.dwolla.v1.hal+json
Authorization: Bearer pBA9fVDBEyYZCEsLf/wKehyh1RTpzjUj5KzIRfDi0wKTii7DqY
'
- lang: javascript
source: "// Using dwolla-v2 - https://github.com/Dwolla/dwolla-v2-node\ndwolla\n .get(\"business-classifications\"\
)\n .then((res) => res.body._embedded[\"business-classifications\"][0].name); // => 'Accommodation\
\ and Food Services'\n"
- lang: python
source: '# Using dwollav2 - https://github.com/Dwolla/dwolla-v2-python
classifications = app_token.get(''business-classifications'')
classifications.body[''_embedded''][''business-classifications''][0][''name''] # => ''Accommodation
and Food Services''
'
- lang: php
source: '<?php
// Using dwollaswagger - https://github.com/Dwolla/dwolla-swagger-php
$businessClassificationsApi = new DwollaSwagger\BusinessClassificationsApi($apiClient);
$classifications = $businessClassificationsApi->_list();
$classifications->_embedded->{''business-classifications''}[0]->name; # => "Accommodation and
Food Services"
?>
'
- lang: ruby
source: '# Using dwolla_v2 - https://github.com/Dwolla/dwolla-v2-ruby
classifications = app_token.get "business-classifications"
classifications._embedded.[''business-classifications''][0].name # => "Accommodation and Food
Services"
'
parameters:
- $ref: '#/components/parameters/Accept'
responses:
'200':
description: successful operation
headers: {}
content:
application/vnd.dwolla.v1.hal+json:
schema:
$ref: '#/components/schemas/BusinessClassifications'
'403':
description: Forbidden
headers: {}
content:
application/vnd.dwolla.v1.hal+json:
schema:
$ref: '#/components/schemas/ForbiddenError'
'404':
description: Not Found
headers: {}
content:
application/vnd.dwolla.v1.hal+json:
schema:
$ref: '#/components/schemas/NotFoundError'
/business-classifications/{id}:
get:
tags:
- customers
summary: Retrieve a business classification
description: Returns a specific business classification with its embedded industry classifications.
Use this endpoint to browse available industry options within a business category and obtain the
industry classification ID required for the businessClassification parameter when creating business
verified customers.
operationId: retrieveBusinessClassification
x-speakeasy-group: businessClassifications
x-speakeasy-name-override: get
x-codeSamples:
- lang: bash
source: 'GET https://api-sandbox.dwolla.com/business-classifications/9ed3f670-7d6f-11e3-b1ce-5404a6144203
Accept: application/vnd.dwolla.v1.hal+json
Authorization: Bearer pBA9fVDBEyYZCEsLf/wKehyh1RTpzjUj5KzIRfDi0wKTii7DqY
'
- lang: javascript
source: "// Using dwolla-v2 - https://github.com/Dwolla/dwolla-v2-node\ndwolla\n .get(\"business-classifications/9ed3f670-7d6f-11e3-b1ce-5404a6144203\"\
)\n .then((res) => res.body.name); // => 'Accommodation and Food Services'\n"
- lang: python
source: '# Using dwollav2 - https://github.com/Dwolla/dwolla-v2-python
classification = app_token.get(''business-classifications/9ed3f670-7d6f-11e3-b1ce-5404a6144203'')
classification.body[''name''] # => ''Accommodation and Food Services''
'
- lang: php
source: '<?php
// Using dwollaswagger - https://github.com/Dwolla/dwolla-swagger-php
$businessClassificationsApi = new DwollaSwagger\BusinessClassificationsApi($apiClient);
$classification = $businessClassificationsApi->getBusinessClassification("9ed3f670-7d6f-11e3-b1ce-5404a6144203");
$classification->name; # => "Accommodation and Food Services"
?>
'
- lang: ruby
source: '# Using dwolla_v2 - https://github.com/Dwolla/dwolla-v2-ruby
classification = app_token.get "business-classifications/9ed3f670-7d6f-11e3-b1ce-5404a6144203"
classification.name # => "Accommodation and Food Services"
'
parameters:
- name: id
in: path
description: business classification unique identifier
required: true
schema:
type: string
- $ref: '#/components/parameters/Accept'
responses:
'200':
description: successful operation
headers: {}
content:
application/vnd.dwolla.v1.hal+json:
schema:
$ref: '#/components/schemas/BusinessClassification'
'404':
description: not found
headers: {}
content:
application/vnd.dwolla.v1.hal+json:
schema:
type: object
properties:
code:
type: string
example: not_found
message:
type: string
example: not found.
components:
schemas:
VerifiedSolePropCustomer:
title: VerifiedSolePropCustomer
description: Verified sole proprietorship customer - distinguished from VerifiedBusinessCustomer
by businessType=soleProprietorship
allOf:
- $ref: '#/components/schemas/BaseCustomer'
- type: object
required:
- type
- status
- address1
- city
- state
- postalCode
- businessName
- businessType
- businessClassification
properties:
type:
type: string
enum:
- business
example: business
status:
type: string
enum:
- verified
- suspended
- deactivated
- document
- retry
example: verified
address1:
type: string
example: 123 Main Street
address2:
type: string
example: Ste 123
city:
type: string
example: Des Moines
state:
type: string
example: IA
postalCode:
type: string
example: '50309'
businessName:
type: string
example: Jane Corp
businessType:
type: string
enum:
- soleProprietorship
example: soleProprietorship
businessClassification:
type: string
example: 9ed3f670-7d6f-11e3-b1ce-5404a6144203
CreateVerifiedPersonalCustomer:
title: CreateVerifiedPersonalCustomer
description: Create a Verified Personal customer
type: object
required:
- firstName
- lastName
- email
- address1
- city
- state
- postalCode
- dateOfBirth
- type
- ssn
properties:
firstName:
type: string
example: Account
lastName:
type: string
example: Admin
email:
type: string
example: accountAdmin@email.com
ipAddress:
type: string
example: 143.156.7.8
phone:
type: string
example: '5555555555'
correlationId:
type: string
example: fc451a7a-ae30-4404-aB95-e3553fcd733
type:
type: string
const: personal
address1:
type: string
example: 99-99 33rd St
address2:
type: string
example: 99-99 33rd St
city:
type: string
example: Some City
state:
type: string
example: NY
postalCode:
type: string
example: '11101'
ssn:
type: string
example: '1234'
dateOfBirth:
type: string
example: '1980-09-12'
NotFoundError:
title: NotFoundError
description: Error response schema for 404 NotFound
type: object
required:
- code
- message
properties:
code:
type: string
example: NotFound
message:
type: string
example: The requested resource was not found.
RetryVerifiedSoleProp:
title: RetryVerifiedSoleProp
description: Retry Verification for Verified Business Customer (Sole Proprietorship)
type: object
required:
- firstName
- lastName
- email
- type
- dateOfBirth
- ssn
- address1
- city
- state
- postalCode
- businessClassification
- businessType
- businessName
- ein
properties:
firstName:
type: string
example: Business
lastName:
type: string
example: Owner
email:
type: string
example: solePropBusiness@email.com
ipAddress:
type: string
example: 143.156.7.8
type:
type: string
example: business
dateOfBirth:
type: string
example: '1980-01-31'
ssn:
type: string
example: '6789'
address1:
type: string
example: 99-99 33rd St
city:
type: string
example: Some City
state:
type: string
example: NY
postalCode:
type: string
example: '11101'
businessClassification:
type: string
example: 9ed3f670-7d6f-11e3-b1ce-5404a6144203
businessType:
type: string
example: soleProprietorship
businessName:
type: string
example: Jane Corp
ein:
type: string
example: 00-0000000
Passport:
title: Passport
type: object
required:
- number
- country
properties:
number:
type: string
country:
type: string
BadRequestError:
title: BadRequestError
description: Error response schema for 400 Bad Request
type: object
required:
- code
- message
properties:
code:
type: string
example: BadRequest
message:
type: string
example: The request body contains bad syntax or is incomplete.
InternationalAddress:
title: InternationalAddress
type: object
required:
- address1
- city
- country
- stateProvinceRegion
properties:
address1:
type: string
example: 462 Main Street
address2:
type: string
example: Suite 123
address3:
type: string
example: Unit 123
city:
type: string
example: Des Moines
postalCode:
type: string
example: '50309'
country:
type: string
example: USA
stateProvinceRegion:
type: string
example: IA
UpgradeToUnverified:
title: UpgradeToUnverified
description: Upgrade Receive Only User to Unverified Customer
type: object
required:
- type
properties:
type:
type: string
example: unverified
HalLink:
title: HalLink
type: object
properties:
href:
type: string
example: https://api.dwolla.com
type:
type: string
example: application/vnd.dwolla.v1.hal+json
resource-type:
type: string
example: resource-type
BusinessClassifications:
title: BusinessClassifications
type: object
properties:
_links:
additionalProperties:
$ref: '#/components/schemas/HalLink'
_embedded:
type: object
properties:
business-classifications:
type: array
items:
$ref: '#/components/schemas/BusinessClassification'
total:
type: integer
format: int32
example: 3
BaseCustomer:
title: BaseCustomer
description: Base schema containing common fields for all customer types
type: object
required:
- _links
- id
- firstName
- lastName
- email
- created
properties:
_links:
additionalProperties:
$ref: '#/components/schemas/HalLink'
id:
type: string
example: c41125c5-99c4-4303-a9f6-d066d28a61e3
firstName:
type: string
example: Jane
lastName:
type: string
example: Doe
email:
type: string
example: janedoe@mail.com
correlationId:
type: string
example: CID-abe2bb3d-d2ff-433b-95a3-0debd960ed25
created:
type: string
format: date-time
example: '2022-10-07T16:46:13.023Z'
UpgradeToVerifiedSoleProp:
title: UpgradeToVerifiedSoleProp
description: Upgrade Unverified Customer to Verified Business Customer (Sole Proprietorship)
type: object
required:
- firstName
- lastName
- email
- type
- dateOfBirth
- ssn
- address1
- city
- state
- postalCode
- businessClassification
- businessType
- businessName
- ein
properties:
firstName:
type: string
example: Business
lastName:
type: string
example: Owner
email:
type: string
example: solePropBusiness@email.com
ipAddress:
type: string
example: 143.156.7.8
type:
type: string
example: business
dateOfBirth:
type: string
example: '1980-01-31'
ssn:
type: string
example: '6789'
address1:
type: string
example: 99-99 33rd St
city:
type: string
example: Some City
state:
type: string
example: NY
postalCode:
type: string
example: '11101'
businessClassification:
type: string
example: 9ed3f670-7d6f-11e3-b1ce-5404a6144203
businessType:
type: string
example: soleProprietorship
businessName:
type: string
example: Jane Corp
ein:
type: string
example: 00-0000000
UpgradeToVerifiedBusiness:
title: UpgradeToVerifiedBusiness
description: Upgrade Unverified Customer to Verified Business Customer
type: object
required:
- firstName
- lastName
- email
- type
- address1
- city
- state
- postalCode
- controller
- businessClassification
- businessType
- businessName
- ein
properties:
firstName:
type: string
example: Account
lastName:
type: string
example: Admin
email:
type: string
example: accountAdmin@email.com
ipAddress:
type: string
example: 143.156.7.8
type:
type: string
example: business
address1:
type: string
example: 99-99 33rd St
city:
type: string
example: Some City
state:
type: string
example: NY
postalCode:
type: string
example: '11101'
controller:
type: object
required:
- firstName
- lastName
- title
- dateOfBirth
- address
properties:
firstName:
type: string
example: John
lastName:
type: string
example: Controller
title:
type: string
example: CEO
ssn:
type: string
example: '6789'
dateOfBirth:
type: string
example: '1980-01-31'
address:
type: object
required:
- address1
- city
- stateProvinceRegion
- postalCode
- country
properties:
address1:
type: string
example: 1749 18th st
address2:
type: string
example: apt 12
city:
type: string
example: Des Moines
stateProvinceRegion:
type: string
example: IA
postalCode:
type: string
example: '50266'
country:
type: string
example: US
businessClassification:
type: string
example: 9ed3f670-7d6f-11e3-b1ce-5404a6144203
businessType:
type: string
example: llc
businessName:
type: string
example: Jane Corp
ein:
type: string
example: 00-0000000
UpdateUnverifiedAndReceiveOnly:
title: UpdateUnverifiedAndReceiveOnly
description: Update Unverified Customer or Receive Only User Information
type: object
properties:
firstName:
type: string
example: John
lastName:
type: string
example: Doe
email:
type: string
example: accountAdmin@email.com
businessName:
type: string
example: Jane Corp
CreateReceiveOnlyUser:
title: CreateReceiveOnlyUser
description: Create a Receive Only User
type: object
required:
- firstName
- lastName
- email
- type
properties:
firstName:
type: string
example: Account
lastName:
type: string
example: Admin
email:
type: string
example: accountAdmin@email.com
type:
type: string
const: receive-only
ipAddress:
type: string
example: 143.156.7.8
phone:
type: string
example: '5555555555'
correlationId:
type: string
# --- truncated at 32 KB (59 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/dwolla/refs/heads/main/openapi/dwolla-customers-openapi.yml