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

Update a customer #

This endpoint can be used to facilitate the following use cases: 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.

HTTP request #

POST https://api.dwolla.com/customers/{id}

Update a Customer's information #

A limited set of information can be updated on an existing created Customer. Note: A Customer's information cannot be updated when in a status of document or suspended.

Request parameters - unverified Customer and receive-only User

Parameter	Required	Type	Description
firstName	no	string	Customer's first name. Must be ≤ 50 characters and cannot contain special characters [<>="`!?%~${}\].
lastName	no	string	Customer's last name. Must be ≤ 50 characters and cannot contain special characters [<>="`!?%~${}\].
email	no	string	Customer's email address. Must be a valid email format, e.g., `example@domain.com`.
businessName	no	string	Customer's registered business name. Must be ≤ 255 characters and cannot contain special characters [<>="`!?%~${}\]. An empty string value will unset this field.

Request parameters - verified Customer

Parameter	Required	Type	Description
email	no	string	Customer's email address. Must be a valid email format, e.g., `example@domain.com`.
ipAddress	no	string	Customer's IP address.
address1	no	string	First line of the street address of the customer's permanent residence. Note: PO Boxes are not allowed. Must be ≤ 50 characters and cannot contain special characters [<>="`!?%~${}\].
address2	no	string	Second line of the street address of the customer's permanent residence. Note: PO Boxes are not allowed. Must be ≤ 50 characters and cannot contain special characters [<>="`!?%~${}\].
city	no	string	City of customer's permanent residence. Must be ≤ 50 characters and cannot contain special characters [<>="`!?%~${}\].
state	no	string	Two letter abbreviation of the state in which the customer resides. e.g. `NY`.
postalCode	no	string	Postal code of customer's permanent residence. Should be a five-digit postal code, e.g. `50314`.
phone	no	string	Customer's 10-digit phone number. No hyphens or other separators, e.g. `3334447777`. Must be 10 digits and cannot contain special characters [<>="`!?%~${}\].

Request parameters - verified Customer with type=business

In addition to the table above, business verified Customers can update the following fields.

Parameter	Required	Type	Description
doingBusinessAs	no	string	Name that is different from the officially registered name of Customer’s business. Must be ≤ 255 characters and cannot contain special characters [<>="`!?%~${}\].
website	no	string	Must be a valid URL format with protocol, subdomain, domain, and top-level domain. e.g. `https://www.domain.com`.

Upgrade an unverified Customer to verified Customer #

An unverified Customer can be upgraded to a verified Customer by supplying the necessary information required to create a verified Customer. Reference the create customer section for required information.

Suspend a Customer #

Unverified and Verified Customers can be suspended by specifying a status of suspended in your request. You'll need to contact Dwolla to unsuspend a Customer.

Request parameters

Parameter	Required	Type	Description
status	yes	string	Value of `suspended`.

Deactivate a Customer #

Customers can be deactivated by specifying a status of deactivated in your request. A Customer cannot be deactivated if the Customer has a suspended verification status. Customers can be systematically deactivated by Dwolla if certain ACH return codes are triggered on bank transfer failures.

Request parameters

Parameter	Required	Type	Description
status	yes	string	Value of `deactivated`.

Reactivate a Customer #

Customers can be reactivated by specifying a status of reactivated in your request. Reactivated Customers will be moved to the status they were in prior to being deactivated.

Request parameters

Parameter	Required	Type	Description
status	yes	string	Value of `reactivated`.

Retry verification #

If the verified Customer has a status of retry, some information may have been miskeyed. You have one more opportunity to correct any mistakes using this endpoint. This time, you’ll need to provide the Customer’s full SSN. If the additional attempt fails, the resulting status will be either document or suspended.

Customer must be in the retry state:

bash

{
    "_links": {
        "deactivate": {
            "href": "https://api-sandbox.dwolla.com/customers/53863b11-1758-47c8-821f-00e6a126f97f",
            "type": "application/vnd.dwolla.v1.hal+json",
            "resource-type": "customer"
        },
        "self": {
            "href": "https://api-sandbox.dwolla.com/customers/53863b11-1758-47c8-821f-00e6a126f97f",
            "type": "application/vnd.dwolla.v1.hal+json",
            "resource-type": "customer"
        },
        "edit-form": {
            "href": "https://api-sandbox.dwolla.com/customers/53863b11-1758-47c8-821f-00e6a126f97f",
            "type": "application/vnd.dwolla.v1.hal+json; profile=\"https://github.com/dwolla/hal-forms\"",
            "resource-type": "customer"
        },
        "edit": {
            "href": "https://api-sandbox.dwolla.com/customers/53863b11-1758-47c8-821f-00e6a126f97f",
            "type": "application/vnd.dwolla.v1.hal+json",
            "resource-type": "customer"
        },
        "funding-sources": {
            "href": "https://api-sandbox.dwolla.com/customers/53863b11-1758-47c8-821f-00e6a126f97f/funding-sources",
            "type": "application/vnd.dwolla.v1.hal+json",
            "resource-type": "funding-source"
        },
        "retry-verification": {
            "href": "https://api-sandbox.dwolla.com/customers/53863b11-1758-47c8-821f-00e6a126f97f",
            "type": "application/vnd.dwolla.v1.hal+json",
            "resource-type": "customer"
        },
        "transfers": {
            "href": "https://api-sandbox.dwolla.com/customers/53863b11-1758-47c8-821f-00e6a126f97f/transfers",
            "type": "application/vnd.dwolla.v1.hal+json",
            "resource-type": "transfer"
        }
    },
    "id": "53863b11-1758-47c8-821f-00e6a126f97f",
    "firstName": "retry",
    "lastName": "doe",
    "email": "jdoe@nomail.com",
    "type": "personal",
    "status": "retry",
    "created": "2017-11-06T20:11:13.430Z",
    "address1": "99-99 33rd St",
    "city": "Some City",
    "state": "NY",
    "postalCode": "11101"
}

Request and response #

This example goes through retry verification for a Personal Verified Customer.

Raw

POST https://api-sandbox.dwolla.com/customers/53863b11-1758-47c8-821f-00e6a126f97f
Content-Type: application/vnd.dwolla.v1.hal+json
Accept: application/vnd.dwolla.v1.hal+json
Authorization: Bearer pBA9fVDBEyYZCEsLf/wKehyh1RTpzjUj5KzIRfDi0wKTii7DqY

{
  "firstName": "John",
  "lastName": "Doe",
  "email": "jdoe@nomail.com",
  "ipAddress": "10.10.10.10",
  "type": "personal",
  "address1": "221 Corrected Address St.",
  "address2": "Apt 201",
  "city": "San Francisco",
  "state": "CA",
  "postalCode": "94104",
  "dateOfBirth": "1970-07-11",
  "ssn": "123-45-6789"
}

...

{
    "_links": {
        "deactivate": {
            "href": "https://api-sandbox.dwolla.com/customers/53863b11-1758-47c8-821f-00e6a126f97f",
            "type": "application/vnd.dwolla.v1.hal+json",
            "resource-type": "customer"
        },
        "self": {
            "href": "https://api-sandbox.dwolla.com/customers/53863b11-1758-47c8-821f-00e6a126f97f",
            "type": "application/vnd.dwolla.v1.hal+json",
            "resource-type": "customer"
        },
        "receive": {
            "href": "https://api-sandbox.dwolla.com/transfers",
            "type": "application/vnd.dwolla.v1.hal+json",
            "resource-type": "transfer"
        },
        "edit-form": {
            "href": "https://api-sandbox.dwolla.com/customers/53863b11-1758-47c8-821f-00e6a126f97f",
            "type": "application/vnd.dwolla.v1.hal+json; profile=\"https://github.com/dwolla/hal-forms\"",
            "resource-type": "customer"
        },
        "edit": {
            "href": "https://api-sandbox.dwolla.com/customers/53863b11-1758-47c8-821f-00e6a126f97f",
            "type": "application/vnd.dwolla.v1.hal+json",
            "resource-type": "customer"
        },
        "funding-sources": {
            "href": "https://api-sandbox.dwolla.com/customers/53863b11-1758-47c8-821f-00e6a126f97f/funding-sources",
            "type": "application/vnd.dwolla.v1.hal+json",
            "resource-type": "funding-source"
        },
        "transfers": {
            "href": "https://api-sandbox.dwolla.com/customers/53863b11-1758-47c8-821f-00e6a126f97f/transfers",
            "type": "application/vnd.dwolla.v1.hal+json",
            "resource-type": "transfer"
        },
        "send": {
            "href": "https://api-sandbox.dwolla.com/transfers",
            "type": "application/vnd.dwolla.v1.hal+json",
            "resource-type": "transfer"
        }
    },
    "id": "53863b11-1758-47c8-821f-00e6a126f97f",
    "firstName": "John",
    "lastName": "Doe",
    "email": "jdoe@nomail.com",
    "type": "personal",
    "status": "verified",
    "created": "2017-11-06T20:11:13.430Z",
    "address1": "221 Corrected Address St.",
    "address2": "Apt 201",
    "city": "San Francisco",
    "state": "CA",
    "postalCode": "94104"
}

If you try more than once, or Customer is not in retry state:

bash

{
  "code": "InvalidResourceState",
  "message": "Resource cannot be modified."
}

Request parameters - retry verified personal Customer #

Parameter	Required	Type	Description
firstName	yes	string	Customer's first name. Must be ≤ 50 characters and cannot contain special characters [<>="`!?%~${}\].
lastName	yes	string	Customer's last name. Must be ≤ 50 characters and cannot contain 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	Either `personal` or `business`. If business, see above for additional required information.
address1	yes	string	First line of the street address of the Customer's permanent residence. Note: PO Boxes are not allowed. Must be ≤ 50 characters and cannot contain special characters [<>="`!?%~${}\].
address2	no	string	Second line of the street address of the Customer's permanent residence. Note: PO Boxes are not allowed. Must be ≤ 50 characters and cannot contain special characters [<>="`!?%~${}\].
city	yes	string	City of Customer's permanent residence. Must be ≤ 50 characters and cannot contain special characters [<>="`!?%~${}\].
state	yes	string	Two letter abbreviation of the state in which the customer resides, e.g. `CA`. Must be uppercase.
postalCode	yes	string	Postal code of Customer's permanent residence. Should be a five digit postal 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	Customer's full Social Security Number. Must contain only numbers (e.g., `123456789`).
phone	no	string	Customer's 10 digit phone number. No hyphens or other separators, e.g. `3334447777`.

HTTP status and error codes #

HTTP Status	Message
400	Duplicate customer or validation error.
403	Not authorized to create customers.

List and search customers

List business classifications

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.