Introduction

Welcome to the Dwolla API documentation. This API will give you the ability to connect your software to banking infrastructure to move money, store funds, validate customer identities, and verify bank accounts.

Making requests

All requests should supply the Accept: application/vnd.dwolla.v1.hal+json header. POST requests must specify the Content-Type: application/vnd.dwolla.v1.hal+json header. Request and response bodies are JSON encoded.

Requests must be made over HTTPS. Any non-secure requests are met with a redirect (HTTP 302) to the HTTPS equivalent URI.

POST https://api.dwolla.com/customers
Content-Type: application/json
Accept: application/vnd.dwolla.v1.hal+json
Authorization: Bearer myOAuthAccessToken123

{
  "foo": "bar"
}

... or ...

GET https://api.dwolla.com/accounts/a84222d5-31d2-4290-9a96-089813ef96b3/transfers

Authorization

All requests require either an OAuth access token or a client_id and client_secret. OAuth access tokens are passed via the Authorization HTTP header:

Authorization: Bearer {access_token_here}

API Host

Production: https://api.dwolla.com

Sandbox: https://api-sandbox.dwolla.com

Idempotency key

To prevent an operation from being performed more than once, Dwolla supports passing in an Idempotency-Key header with a unique key as the value. Multiple POSTs with the same idempotency key and request body won’t result in multiple resources being created. It is recommended to use a random value for the idempotency key, like a UUID (i.e. - Idempotency-Key: d2adcbab-4e4e-430b-9181-ac9346be723a).

For example, if a request to initiate a transfer fails due to a network connection issue, you can reattempt the request with the same idempotency key to guarantee that only a single transfer is created.

If you reattempt a POST request with the same value for the Idempotency-Key, rather than creating new or potentially duplicate resources, you will receive a 201 Created, with the original response of the created resource. If the Dwolla server is still processing the original POST request, you will receive a 409 Conflict error response on the subsequent request. Multiple POSTs with the same idempotency key including an exact match request body won’t result in multiple resources being created. Idempotency keys are intended to prevent conflicts over a short period of time, therefore keys which are paired with a request body expire after 24 hours.

1. To prevent resources from being created more than once, we highly recommend making all requests idempotent.

Example transfer using an Idempotency Key

POST https://api-sandbox.dwolla.com/transfers
Accept: application/vnd.dwolla.v1.hal+json
Content-Type: application/vnd.dwolla.v1.hal+json
Authorization: Bearer pBA9fVDBEyYZCEsLf/wKehyh1RTpzjUj5KzIRfDi0wKTii7DqY
Idempotency-Key: 19051a62-3403-11e6-ac61-9e71128cae77

{
    "_links": {
        "destination": {
            "href": "https://api-sandbox.dwolla.com/funding-sources/04173e17-6398-4d36-a167-9d98c4b1f1c3"
        },
        "source": {
            "href": "http://api-sandbox.dwolla.com/funding-sources/707177c3-bf15-4e7e-b37c-55c3898d9bf4"
        }
    },
    "amount": {
        "currency": "USD",
        "value": "1337.00"
    }
}
...

HTTP/1.1 201 Created
Location: https://api-sandbox.dwolla.com/transfers/74c9129b-d14a-e511-80da-0aa34a9b2388

# Using DwollaV2 - https://github.com/Dwolla/dwolla-v2-ruby
headers = {
  "Idempotency-Key" => "19051a62-3403-11e6-ac61-9e71128cae77"
}

request_body = {
  :_links => {
    :source => {
      :href => "https://api-sandbox.dwolla.com/funding-sources/04173e17-6398-4d36-a167-9d98c4b1f1c3"
    },
    :destination => {
      :href => "https://api-sandbox.dwolla.com/funding-sources/707177c3-bf15-4e7e-b37c-55c3898d9bf4"
    }
  },
  :amount => {
    :currency => "USD",
    :value => "1.00"
  }
}

transfer = app_token.post "transfers", request_body, headers
transfer.response_headers[:location] # => "https://api.dwolla.com/transfers/74c9129b-d14a-e511-80da-0aa34a9b2388"

<?php
$transfersApi = new DwollaSwagger\TransfersApi($apiClient);

$transfer = $transfersApi->create([
  '_links' => [
    'source' => [
      'href' => 'https://api-sandbox.dwolla.com/funding-sources/04173e17-6398-4d36-a167-9d98c4b1f1c3',
    ],
    'destination' => [
      'href' => 'https://api-sandbox.dwolla.com/funding-sources/707177c3-bf15-4e7e-b37c-55c3898d9bf4'
    ]
  ],
  'amount' => [
    'currency' => 'USD',
    'value' => '1.00'
  ]
],
[
    'Idempotency-Key' => '19051a62-3403-11e6-ac61-9e71128cae77'
]);

$transfer; # => "https://api-sandbox.dwolla.com/transfers/74c9129b-d14a-e511-80da-0aa34a9b2388"
?>

# Using dwollav2 - https://github.com/Dwolla/dwolla-v2-python
headers = {
  'Idempotency-Key': '19051a62-3403-11e6-ac61-9e71128cae77'
}

request_body = {
  '_links': {
    'source': {
      'href': 'https://api-sandbox.dwolla.com/funding-sources/04173e17-6398-4d36-a167-9d98c4b1f1c3'
    },
    'destination': {
      'href': 'https://api-sandbox.dwolla.com/funding-sources/707177c3-bf15-4e7e-b37c-55c3898d9bf4'
    }
  },
  'amount': {
    'currency': 'USD',
    'value': '1.00'
  }
}

transfer = app_token.post('transfers', request_body, headers)
transfer.headers['location'] # => 'https://api.dwolla.com/transfers/74c9129b-d14a-e511-80da-0aa34a9b2388'

var headers = {
  'Idempotency-Key': '19051a62-3403-11e6-ac61-9e71128cae77'
}
var requestBody = {
  _links: {
    source: {
      href: 'https://api-sandbox.dwolla.com/funding-sources/04173e17-6398-4d36-a167-9d98c4b1f1c3'
    },
    destination: {
      href: 'https://api-sandbox.dwolla.com/funding-sources/707177c3-bf15-4e7e-b37c-55c3898d9bf4'
    }
  },
  amount: {
    currency: 'USD',
    value: '1.00'
  }
};

appToken
  .post('transfers', requestBody, headers)
  .then(res => res.headers.get('location')); // => 'https://api-sandbox.dwolla.com/transfers/74c9129b-d14a-e511-80da-0aa34a9b2388'

Errors

Error responses use HTTP status codes to indicate the type of error. The JSON response body will contain a top-level error code and a message with a detailed description of the error. Errors will contain their own media type and will closely align with this spec.

Example HTTP 401 error

{
  "code": "InvalidAccessToken",
  "message": "Invalid access token."
}

Common errors

The following errors are common across all API endpoints.

Validation errors

Responses with a top-level error code of ValidationError are returned when it’s possible to correct a specific problem with your request. The response will include a message: “Validation error(s) present. See embedded errors list for more details.” At least one, but possibly more, detailed error will be present in the list of embedded errors. Multiple errors are represented in a collection of embedded error objects.

_embedded JSON object

The path field is a JSON pointer to the specific field in the request that has a problem. The message is a human readable description of the problem. The code is a detailed error code that can have one of the following values:

• Required - {field name} is required. For example, null or empty string in required field.
• Invalid - {field name} invalid.
• InvalidFormat - {field name} is not in a valid format. For example, characters in the amount field.
• Duplicate - “A customer with the specified email already exists.”
• ReadOnly - this field is not allowed to be modified
• NotAllowed - value, while valid/exists, is not allowed to be used
• Restricted - account or customer restricted from this activity
• InsufficientFunds - used on source or destination fields of transfer endpoint
• RequiresFundingSource - used on destination field of transfer endpoint to indicate customer needs a bank
• FileTooLarge - used on document upload

Example HTTP 400 validation error

{
    "code": "ValidationError",
    "message": "Validation error(s) present. See embedded errors list for more details.",
    "_embedded": {
        "errors": [
            {
                "code": "Required",
                "message": "FirstName required.",
                "path": "/firstName",
                "_links": {}
            }
        ]
    }
}

Links

Relationships and available actions for a resource are represented with links. All resources have a _links attribute. At a minimum, all resources will have a self link which indicates the URL of the resource itself.

Some links, such as funding-sources, give you a URL which you can follow to access related resources. For example, the customer resource has a funding-sources link which, when followed, will list the customer’s available funding sources.

Responses which contain a collection of resources have pagination links, first, next, last, and prev.

{
  "_links": {
    "self": {
      "href": "https://api.dwolla.com/customers/132681FA-1B4D-4181-8FF2-619CA46235B1"
    },
    "funding-sources": {
      "href": "https://api.dwolla.com/customers/132681FA-1B4D-4181-8FF2-619CA46235B1/funding-sources"
    },
    "transfers": {
      "href": "https://api.dwolla.com/customers/132681FA-1B4D-4181-8FF2-619CA46235B1/transfers"
    },
    "retry-verification": {
      "href": "https://api.dwolla.com/customers/132681FA-1B4D-4181-8FF2-619CA46235B1"
    }
  },
  "id": "132681FA-1B4D-4181-8FF2-619CA46235B1",
  "firstName": "Jane",
  "lastName": "doe",
  "email": "jdoe@nomail.com",
  "type": "personal",
  "status": "retry",
  "created": "2015-09-29T19:47:28.920Z"
}

Tools

The following section will outline development tools you can take advantage of to assist in your integration with the Dwolla API. The available tools can help to improve your testing and development workflow, as well as aid in solving a difficult problem (e.g. UI generation) when integrating Dwolla into your application.

Dwolla Hal-Forms

Dwolla HAL-Forms is an extension of the HAL spec and was created to describe how Dwolla represents forms in the API. The extension starts with the media type. The media type should be used as a profile link as part of the Accept header of the request in conjunction with the Dwolla HAL style media type. By including these two media-type identifiers in the Accept header, the API knows that you’re looking for a form for the given resource.

Example Accept header value

application/vnd.dwolla.v1.hal+json; profile="https://github.com/dwolla/hal-forms"

The primary benefit is the ability to dynamically generate your UI based on the state of a particular resource. Your application can easily transition state without knowing Dwolla’s business rules and what information needs to included in the actual request to transition state. When an "edit-form" link relation is returned on the resource, then your application can follow the link by making a GET request to that resource, including the header shown above. The response will include a simple JSON response body that contains information on the HTTP method, message content-type, and the request parameters used when sending the request to the Dwolla API. Note: Currently, forms are only returned for creating & editing customers, but we’re looking forward to expanding them across our existing and future endpoints.

Reference the spec for more information on the properties that can be returned in the Dwolla HAL-FORMS response. Or read a blog post from one of our developers on building out this functionality.

SDK Support

The Dwolla API has officially maintained software packages to make it easier for developers to get started with making requests. This section is here to provide basic instructions on how to install these packages and get up and running with them. We recommend you use a POSIX-standardized shell on your development machine, and assume that you are already familiar and set-up with any tools required for your specific technical ecosystem.

Officially maintained SDKs are available for Ruby, Node.js, Python, and C#.

The PHP SDKs is autogenerated by swagger-codegen and are versioned in accordance with our API schema. Each endpoint grouping is assigned a class and then an operation which you can use to make a request. You can choose which environment to target (e.g production vs sandbox) by providing the SDK a different API host value. These libraries are not actively maintained, therefore we encourage community contribution.

Base URLs

Ruby

dwolla_v2 is available on RubyGems with source code available on our GitHub page. More information is available on the project’s README.

Installation

gem install dwolla_v2

Quickstart

Let’s list some Customer objects:

require 'dwolla_v2'

# Navigate to https://dashboard.dwolla.com/applications (production) or https://dashboard-sandbox.dwolla.com/applications (Sandbox) for your application key and secret.
app_key = "..."
app_secret = "..."
$dwolla = DwollaV2::Client.new(key: app_key, secret: app_secret) do |config|
  config.environment = :sandbox # optional - defaults to production
end

# create an application token
app_token = $dwolla.auths.client

customers = app_token.get "customers", limit: 10

Python

dwollav2 is available on PyPi with source code available on our GitHub page. More information is available on the project’s README.

Installation

pip install dwollav2

Quickstart

Let’s list some Customer objects:

import dwollav2

# Navigate to https://dashboard.dwolla.com/applications (production) or https://dashboard-sandbox.dwolla.com/applications (Sandbox) for your application key and secret.
app_key = '...'
app_secret = '...'
client = dwollav2.Client(key = app_key,
                         secret = app_secret,
                         environment = 'sandbox') # optional - defaults to production

app_token = client.Auth.client()

customers = app_token.get('customers', {'limit': 10})

PHP

dwolla-swagger-php is available on Packagist with source code available on our GitHub page. More information is available on the project’s README.

Installation

composer require dwolla/dwollaswagger
composer install

Quickstart

Let’s list some Customer objects:

<?php
require('../path/to/vendor/autoload.php');

DwollaSwagger\Configuration::$username = 'API_KEY';
DwollaSwagger\Configuration::$password = 'API_SECRET';

// For Sandbox
$apiClient = new DwollaSwagger\ApiClient("https://api-sandbox.dwolla.com");
// For production
// $apiClient = new DwollaSwagger\ApiClient("https://api.dwolla.com");

$tokensApi = new DwollaSwagger\TokensApi($apiClient);
$appToken = $tokensApi->token();

DwollaSwagger\Configuration::$access_token = $appToken->access_token;

$customersApi = new DwollaSwagger\CustomersApi($apiClient);
$myCusties = $customersApi->_list(10);

?>

C#

Dwolla.Client is available on Nuget with source code available on our GitHub page. More information is available on the project’s README.

Installation

Install-Package Dwolla.Client

Quickstart

Let’s list some Customer objects:

var client = DwollaClient.Create(isSandbox: true);

var tokenRes = await client.PostAuthAsync<AppTokenRequest, TokenResponse>(
    new Uri($"{client.AuthBaseAddress}/token"),
    new AppTokenRequest {Key = "...", Secret = "..."});

var headers = new Headers {{"Authorization", $"Bearer {tokenRes.Content.Token}"}};
var rootRes = (await client.GetAsync<RootResponse>(new Uri(client.ApiBaseAddress), headers)).Content;

var customers = await client.GetAsync<GetCustomersResponse>(rootRes.Links["customers"].Href, headers);

Kotlin

dwolla-v2-kotlin is an actively maintained client library for Java/Kotlin applications and is used to facilitate interactions with the Dwolla API. The source code is available on our GitHub page. More information is available on the project’s README. Note: The library is currently in preview mode for developers. Any feedback as well as community contribution is encouraged.

Installation

Maven

Add this to your project’s POM:

<repositories>
    <repository>
        <id>jitpack.io</id>
        <url>https://jitpack.io</url>
    </repository>
</repositories>

<dependency>
    <groupId>com.github.Dwolla</groupId>
    <artifactId>dwolla-v2-kotlin</artifactId>
    <version>0.1.1</version>
</dependency>

Gradle

Add this to your project’s build file:

repositories {
    // ...
    maven(url = "https://jitpack.io") {
        name = "jitpack"
    }
}

dependencies {
    implementation("com.github.Dwolla:dwolla-v2-kotlin:0.1.1")
}

Quickstart

Let’s set up a Dwolla client using our application key and secret:

Kotlin

import com.dwolla.Client
import com.dwolla.Environment

val dwolla = Client(
    key = "yourClientKey",       // see dashboard.dwolla.com
    secret = "yourClientSecret", // for your client credentials
    environment = Environment.SANDBOX
)

Java

import com.dwolla.Client;
import com.dwolla.Environment;

Client dwolla = new Client(
    "yourClientKey",    // see dashboard.dwolla.com
    "yourClientSecret", // for your client credentials
    Environment.SANDBOX
);

dwolla-swagger-java

dwolla-swagger-java is not actively maintained by Dwolla, however source code is available on our GitHub page and community contribution is encouraged. More information is available on the project’s README.

JavaScript

dwolla-v2 is available on NPM with source code available on our GitHub page. More information is available on the project’s README.

Installation

npm install dwolla-v2

Quickstart

Let’s fetch a page of customers:

const dwolla = require('dwolla-v2');

// Navigate to https://dashboard.dwolla.com/applications (production) or https://dashboard-sandbox.dwolla.com/applications (Sandbox) for your application key and secret.
const appKey = '...';
const appSecret = '...';
const client = new dwolla.Client({
  key: appKey,
  secret: appSecret,
  environment: 'sandbox' // optional - defaults to production
});

// create a token
client.auth.client()
  .then(appToken => appToken.get('customers', { limit: 10 }))
  .then(res => console.log(res.body));

Drop-in Components

Dwolla’s UI drop-in components library allows developers to leverage isolated functions or build connected flows in their web applications, which expedites the integration process with the Dwolla Platform. Each component within this library includes HTML, CSS and JavaScript that developers can drop-in and customize to fit the look and feel of their application.

Dwolla’s UI components library, dwolla-web.js, requires a unique client-side token that is generated using a server-side SDK. The client token contains granular permissions to perform a specific action on behalf of a Customer.

Client Token lifetime

Client-tokens are single-use tokens that are valid for up to 1 hour after being generated. More than one client token can be generated and valid at one time.

Create a client token

The client token API request requires an action as well as a link which points to the Customer that identifies the end-user performing the action within the drop-in component. The action is a string that contains a granular permission for the Customer performing the action within a drop-in component. Note: This endpoint requires application authorization.

Client token actions

HTTP request

POST https://api.dwolla.com/client-tokens

Request parameters

Request and response

POST https://api-sandbox.dwolla.com/client-tokens 
Accept: application/vnd.dwolla.v1.hal+json 
Content-Type: application/json
Authorization: Bearer {{token}}
{
"action": "customer.update”,
  "_links": {
    “customer”: {
        “href”: “https://api-sandbox.dwolla.com/customers/{{customerId}}” 
    }
  }
}

...

{
 "token": "4adF858jPeQ9RnojMHdqSD2KwsvmhO7Ti7cI5woOiBGCpH5krY"
}

# Using DwollaV2 - https://github.com/Dwolla/dwolla-v2-ruby
request_body = {
  :_links => {
    :customer => {
      :href => "https://api-sandbox.dwolla.com/customers/707177c3-bf15-4e7e-b37c-55c3898d9bf4"
    }
  },
  :action => "customer.update"
}

client_token = app_token.post "client-tokens", request_body
client_token.token # => "4adF858jPeQ9RnojMHdqSD2KwsvmhO7Ti7cI5woOiBGCpH5krY"

<?php
// Using dwollaswagger - https://github.com/Dwolla/dwolla-swagger-php
$request_body = array (
  '_links' =>
  array (
    'customer' =>
    array (
      'href' => 'https://api-sandbox.dwolla.com/customers/8779a1f7-7a98-4a86-921e-83539f6c895e',
    ),
  ),
  'action' => 'customer.update'
);
$clientTokensApi = new DwollaSwagger\TokensApi($apiClient);
$clientToken = $clientTokensApi->clientTokens($request_body);
?>

# Using dwollav2 - https://github.com/Dwolla/dwolla-v2-python
request_body = {
  '_links': {
    'customer': {
      'href': 'https://api-sandbox.dwolla.com/customers/707177c3-bf15-4e7e-b37c-55c3898d9bf4'
    }
  },
  'action': 'customer.update'
}

client_token = app_token.post('client-tokens', request_body)
client_token.body['token'] # => '4adF858jPeQ9RnojMHdqSD2KwsvmhO7Ti7cI5woOiBGCpH5krY'

// Using DwollaV2 - https://github.com/Dwolla/dwolla-v2-node
var requestBody = {
  _links: {
    customer: {
      href: 'https://api-sandbox.dwolla.com/customers/707177c3-bf15-4e7e-b37c-55c3898d9bf4'
    }
  },
  action: 'customer.update'
};

appToken
 .post("/client-tokens", requestBody)
 .then(res => res.body.token); // => '4adF858jPeQ9RnojMHdqSD2KwsvmhO7Ti7cI5woOiBGCpH5krY'

Authorization

Dwolla utilizes the OAuth 2 protocol to facilitate authorization. OAuth is an authorization framework that enables a third-party application to obtain access to protected resources (Transfers, Funding Sources, Customers etc.) in the Dwolla API. Access to the Dwolla API can be granted to an application either on behalf of a user or on behalf of the application itself. This section covers application auth which is meant for server-to-server applications using the Dwolla API.

Creating an application

Before you can get started with making OAuth requests, you’ll need to first register an application with Dwolla by logging in and navigating to the applications page. Once an application is registered you will obtain your client_id and client_secret (aka App Key and Secret), which will be used to identify your application when calling the Dwolla API. The Sandbox environment provides you with a created application once you have signed up for an account. Learn more in our getting started guide. Remember: Your client_secret should be kept a secret! Be sure to store your client credentials securely.

Token lifetime

Access tokens are short lived: 1 hour. To refresh authorization on an application access token, your application will simply exchange its client credentials for a new app access token. Any access tokens that have been previously initialized will not be invalidated with the creation of a new one; they will simply expire within an hour of the time of their creation.

Application authorization

The client credentials flow is the simplest OAuth 2 grant, with a server-to-server exchange of your application’s client_id, client_secret for an OAuth application access token. In order to execute this flow, your application will send a POST requests with the Authorization header that contains the word Basic followed by a space and a base64-encoded string client_id:client_secret.

Authorization: Basic Base64(client_id:client_secret)

HTTP request

Production: POST https://api.dwolla.com/token

Sandbox: POST https://api-sandbox.dwolla.com/token

Including the Content-Type: application/x-www-form-urlencoded header, the request is sent to the token endpoint with grant_type=client_credentials in the body of the request:

Request parameters

Response parameters

Request

POST https://api-sandbox.dwolla.com/token
Authorization: Basic YkVEMGJMaEFhb0pDamplbmFPVjNwMDZSeE9Eb2pyOUNFUzN1dldXcXUyeE9RYk9GeUE6WEZ0bmJIbXR3dXEwNVI1Yk91WmVOWHlqcW9RelNSc21zUU5qelFOZUFZUlRIbmhHRGw=
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials

# Using dwollav2 - https://github.com/Dwolla/dwolla-v2-python
# This example assumes you've already initialized the client. Reference the SDKs page for more information: https://developers.dwolla.com/pages/sdks.html
app_token = client.Auth.client()

// Using DwollaV2 - https://github.com/Dwolla/dwolla-v2-node
// This example assumes you've already initialized the client. Reference the SDKs page for more information: https://developers.dwolla.com/pages/sdks.html
client.auth.client()
  .then(function(appToken) {
    return appToken.get('/');
  })
  .then(function(res) {
    console.log(JSON.stringify(res.body));
  });

# Using DwollaV2 - https://github.com/Dwolla/dwolla-v2-ruby
# This example assumes you've already initialized the client. Reference the SDKs page for more information: https://developers.dwolla.com/pages/sdks.html
app_token = $dwolla.auths.client
# => #<DwollaV2::Token client=#<DwollaV2::Client id="..." secret="..." environment=:sandbox> access_token="..." expires_in=3600 scope="...">

<?php
// Using dwollaswagger - https://github.com/Dwolla/dwolla-swagger-php
// This example assumes you've already intialized the client. Reference the SDKs page for more information: https://developers.dwolla.com/pages/sdks.html
$tokensApi = new DwollaSwagger\TokensApi($apiClient);
$appToken = $tokensApi->token();

DwollaSwagger\Configuration::$access_token = $appToken->access_token;
?>

Successful response

{
  "access_token": "SF8Vxx6H644lekdVKAAHFnqRCFy8WGqltzitpii6w2MVaZp1Nw",
  "token_type": "bearer",
  "expires_in": 3600
}

Root

The “root” serves as an entry point to the API, providing your application with the ability to fetch and discover resources available based on the OAuth access_token provided in the request. If an application access token is provided in the request, the API will return links to resources that belong to the Dwolla application (i.e. “events” and “webhook-subscriptions”).

HTTP request

GET https://api.dwolla.com/

Request and response

GET https://api-sandbox.dwolla.com/
Accept: application/vnd.dwolla.v1.hal+json
Authorization: Bearer pBA9fVDBEyYZCEsLf/wKehyh1RTpzjUj5KzIRfDi0wKTii7DqY

...

{
  "_links": {
    "account": {
      "href": "https://api-sandbox.dwolla.com/accounts/ad5f2162-404a-4c4c-994e-6ab6c3a13254"
    },
    "customers": {
      "href": "https://api-sandbox.dwolla.com/customers"
    }
  }
}

root = app_token.get "/"
root._links.account.href # => "https://api-sandbox.dwolla.com/accounts/ad5f2162-404a-4c4c-994e-6ab6c3a13254"

<?php
$rootApi = new DwollaSwagger\RootApi($apiClient);

$root = $rootApi->root();
$accountUrl = $root->_links["account"]->href; # => "https://api-sandbox.dwolla.com/accounts/ad5f2162-404a-4c4c-994e-6ab6c3a13254"
?>

# Using dwollav2 - https://github.com/Dwolla/dwolla-v2-python
root = app_token.get('/')
root.body['_links']['account']['href'] # => 'https://api-sandbox.dwolla.com/accounts/ad5f2162-404a-4c4c-994e-6ab6c3a13254'

appToken
  .get('/')
  .then(res => res.body._links.account.href); // => 'https://api-sandbox.dwolla.com/accounts/ad5f2162-404a-4c4c-994e-6ab6c3a13254'

Accounts

An Account represents your Dwolla Master Account that was established on dwolla.com.

Account links

{
  "_links": {
    "self": {
      "href": "https://api-sandbox.dwolla.com/accounts/ca32853c-48fa-40be-ae75-77b37504581b"
    },
    "receive": {
      "href": "https://api-sandbox.dwolla.com/transfers"
    },
    "funding-sources": {
      "href": "https://api-sandbox.dwolla.com/accounts/ca32853c-48fa-40be-ae75-77b37504581b/funding-sources"
    },
    "transfers": {
      "href": "https://api-sandbox.dwolla.com/accounts/ca32853c-48fa-40be-ae75-77b37504581b/transfers"
    },
    "customers": {
      "href": "https://api-sandbox.dwolla.com/customers"
    },
    "send": {
      "href": "https://api-sandbox.dwolla.com/transfers"
    }
  },
  "id": "ca32853c-48fa-40be-ae75-77b37504581b",
  "name": "Jane Doe"
}

Retrieve account details

This section shows you how to retrieve basic account information belonging to the authorized Dwolla Master Account.

To retrieve your Account ID, you will need to call the root of the API.

HTTP request

GET https://api.dwolla.com/accounts/{id}

Request parameters

HTTP status and error codes

Request and response

GET https://api-sandbox.dwolla.com/accounts/ca32853c-48fa-40be-ae75-77b37504581b
Accept: application/vnd.dwolla.v1.hal+json
Authorization: Bearer pBA9fVDBEyYZCEsLf/wKehyh1RTpzjUj5KzIRfDi0wKTii7DqY

{
  "_links": {
    "self": {
      "href": "https://api-sandbox.dwolla.com/accounts/ca32853c-48fa-40be-ae75-77b37504581b"
    },
    "receive": {
      "href": "https://api-sandbox.dwolla.com/transfers"
    },
    "funding-sources": {
      "href": "https://api-sandbox.dwolla.com/accounts/ca32853c-48fa-40be-ae75-77b37504581b/funding-sources"
    },
    "transfers": {
      "href": "https://api-sandbox.dwolla.com/accounts/ca32853c-48fa-40be-ae75-77b37504581b/transfers"
    },
    "customers": {
      "href": "https://api-sandbox.dwolla.com/customers"
    },
    "send": {
      "href": "https://api-sandbox.dwolla.com/transfers"
    }
  },
  "id": "ca32853c-48fa-40be-ae75-77b37504581b",
  "name": "Jane Doe"
}

# Using DwollaV2 - https://github.com/Dwolla/dwolla-v2-ruby
account_url = 'https://api-sandbox.dwolla.com/accounts/ca32853c-48fa-40be-ae75-77b37504581b'

account = app_token.get account_url
account.name # => "Jane Doe"

<?php
$accountUrl = 'https://api-sandbox.dwolla.com/accounts/ca32853c-48fa-40be-ae75-77b37504581b';

$accountsApi = new DwollaSwagger\AccountsApi($apiClient);

$account = $accountsApi->id($accountUrl);
print($account->name); # => "Jane Doe"
?>

# Using dwollav2 - https://github.com/Dwolla/dwolla-v2-python
account_url = 'https://api-sandbox.dwolla.com/accounts/ca32853c-48fa-40be-ae75-77b37504581b'

account = app_token.get(account_url)
account.body['name']

var accountUrl = 'https://api-sandbox.dwolla.com/accounts/ca32853c-48fa-40be-ae75-77b37504581b';

appToken
  .get(accountUrl)
  .then(res => res.body.name); // => 'Jane Doe'

Create a funding source for an account

This section details how to add a bank account to a Dwolla Master Account. The bank account will have a status of unverified upon creation. Before a Dwolla Master Account is eligible to transfer money from their bank or credit union account they need to verify ownership of the account via micro-deposit verification.

For more information on micro-deposit verification, reference the funding source verification resource article.

HTTP request

POST https://api.dwolla.com/funding-sources

Request parameters

HTTP status and error codes

Request and response

POST https://api-sandbox.dwolla.com/funding-sources
Content-Type: application/vnd.dwolla.v1.hal+json
Accept: application/vnd.dwolla.v1.hal+json
Authorization: Bearer pBA9fVDBEyYZCEsLf/wKehyh1RTpzjUj5KzIRfDi0wKTii7DqY
{
    "routingNumber": "222222226",
    "accountNumber": "123456789",
    "bankAccountType": "checking",
    "name": "My Bank"
}

...

HTTP/1.1 201 Created
Location: https://api-sandbox.dwolla.com/funding-sources/04173e17-6398-4d36-a167-9d98c4b1f1c3

<?php
$fundingApi = new DwollaSwagger\FundingsourcesApi($apiClient);

$fundingSource = $fundingApi->createFundingSource([
  "routingNumber" => "222222226",
  "accountNumber" => "123456789",
  "bankAccountType" => "checking",
  "name" => "My Bank"
]);
$fundingSource; # => "https://api-sandbox.dwolla.com/funding-sources/04173e17-6398-4d36-a167-9d98c4b1f1c3"
?>

# Using DwollaV2 - https://github.com/Dwolla/dwolla-v2-ruby
request_body = {
  routingNumber: '222222226',
  accountNumber: '123456789',
  bankAccountType: 'checking',
  name: 'My Bank'
}

funding_source = app_token.post "funding-sources", request_body
funding_source.response_headers[:location] # => "https://api-sandbox.dwolla.com/funding-sources/04173e17-6398-4d36-a167-9d98c4b1f1c3"

# Using dwollav2 - https://github.com/Dwolla/dwolla-v2-python
request_body = {
  'routingNumber': '222222226',
  'accountNumber': '123456789',
  'bankAccountType': 'checking',
  'name': 'My Bank'
}

funding_source = app_token.post('funding-sources', request_body)
funding_source.headers['location'] # => 'https://api-sandbox.dwolla.com/funding-sources/04173e17-6398-4d36-a167-9d98c4b1f1c3'

var requestBody = {
  'routingNumber': '222222226',
  'accountNumber': '123456789',
  'bankAccountType': 'checking',
  'name': 'My Bank'
};

appToken
  .post(`funding-sources`, requestBody)
  .then(res => res.headers.get('location')); // => 'https://api-sandbox.dwolla.com/funding-sources/04173e17-6398-4d36-a167-9d98c4b1f1c3'

List funding sources for an account

Retrieve a list of funding sources that belong to an Account. By default, all funding sources are returned unless the removed querystring parameter is set to false in the request.

HTTP request

GET https://api.dwolla.com/accounts/{id}/funding-sources

Request parameters

HTTP status and error codes

Request and response

GET https://api.dwolla.com/accounts/ca32853c-48fa-40be-ae75-77b37504581b/funding-sources
Accept: application/vnd.dwolla.v1.hal+json
Authorization: Bearer pBA9fVDBEyYZCEsLf/wKehyh1RTpzjUj5KzIRfDi0wKTii7DqY

...
{
    "_links": {
        "self": {
            "href": "https://api-sandbox.dwolla.com/accounts/ca32853c-48fa-40be-ae75-77b37504581b/funding-sources",
            "resource-type": "funding-source"
        }
    },
    "_embedded": {
        "funding-sources": [
            {
                "_links": {
                    "self": {
                        "href": "https://api-sandbox.dwolla.com/funding-sources/04173e17-6398-4d36-a167-9d98c4b1f1c3",
                        "type": "application/vnd.dwolla.v1.hal+json",
                        "resource-type": "funding-source"
                    },
                    "account": {
                        "href": "https://api-sandbox.dwolla.com/accounts/ca32853c-48fa-40be-ae75-77b37504581b",
                        "type": "application/vnd.dwolla.v1.hal+json",
                        "resource-type": "account"
                    }
                },
                "id": "04173e17-6398-4d36-a167-9d98c4b1f1c3",
                "status": "verified",
                "type": "bank",
                "bankAccountType": "checking",
                "name": "My Account - Checking",
                "created": "2017-09-25T20:03:41.000Z",
                "removed": false,
                "channels": [
                    "ach"
                ],
                "bankName": "First Midwestern Bank"
            },
            {
                "_links": {
                    "self": {
                        "href": "https://api-sandbox.dwolla.com/funding-sources/b268f6b9-db3b-4ecc-83a2-8823a53ec8b7",
                    },
                    "account": {
                        "href": "https://api-sandbox.dwolla.com/accounts/ca32853c-48fa-40be-ae75-77b37504581b",
                    },
                    "with-available-balance": {
                        "href": "https://api-sandbox.dwolla.com/funding-sources/b268f6b9-db3b-4ecc-83a2-8823a53ec8b7",
                    },
                    "balance": {
                        "href": "https://api-sandbox.dwolla.com/funding-sources/b268f6b9-db3b-4ecc-83a2-8823a53ec8b7/balance",
                    }
                },
                "id": "b268f6b9-db3b-4ecc-83a2-8823a53ec8b7",
                "status": "verified",
                "type": "balance",
                "name": "Balance",
                "created": "2017-08-22T18:21:51.000Z",
                "removed": false,
                "channels": []
            }
        ]
    }
}

# Using DwollaV2 - https://github.com/Dwolla/dwolla-v2-ruby
account_url = 'https://api.dwolla.com/accounts/ca32853c-48fa-40be-ae75-77b37504581b'

funding_sources = app_token.get "#{account_url}/funding-sources"
funding_sources._embedded['funding-sources'][0].name # => "Jane Doe's Checking"

<?php
$accountUrl = 'https://api.dwolla.com/accounts/ca32853c-48fa-40be-ae75-77b37504581b';

$fsApi = new DwollaSwagger\FundingsourcesApi($apiClient);

$fundingSources = $fsApi->getAccountFundingSources($accountUrl);
$fundingSources->_embedded->{'funding-sources'}[0]->name; # => "Jane Doe’s Checking"
?>

# Using dwollav2 - https://github.com/Dwolla/dwolla-v2-python
account_url = 'https://api.dwolla.com/accounts/ca32853c-48fa-40be-ae75-77b37504581b'

funding_sources = app_token.get('%s/funding-sources' % account_url)
funding_sources.body['_embedded']['funding-sources'][0]['name'] # => 'Jane Doe’s Checking'

var accountUrl = 'https://api-sandbox.dwolla.com/accounts/ca32853c-48fa-40be-ae75-77b37504581b';

appToken
  .get(`${accountUrl}/funding-sources`)
  .then(res => res.body._embedded['funding-sources'][0].name); // => 'ABC Bank Checking'

List and search transfers for an account

This section covers how to retrieve an Account’s list of transfers. Transaction search is supported by passing in optional query string parameters such as: search which represents a term to search on, correlationId, startAmount, endAmount, startDate, endDate, and status.

HTTP request

GET https://api.dwolla.com/accounts/{id}/transfers

Request parameters

HTTP status and error codes

Request and response

GET https://api.dwolla.com/accounts/62e88a41-f5d0-4a79-90b3-188cf11a3966/transfers
Accept: application/vnd.dwolla.v1.hal+json
Authorization: Bearer pBA9fVDBEyYZCEsLf/wKehyh1RTpzjUj5KzIRfDi0wKTii7DqY

...

{
  "_links": {
    "self": {
      "href": "https://api-sandbox.dwolla.com/accounts/62e88a41-f5d0-4a79-90b3-188cf11a3966/transfers",
      "type": "application/vnd.dwolla.v1.hal+json",
      "resource-type": "transfer"
    },
    "first": {
      "href": "https://api-sandbox.dwolla.com/accounts/62e88a41-f5d0-4a79-90b3-188cf11a3966/transfers?&limit=25&offset=0",
      "type": "application/vnd.dwolla.v1.hal+json",
      "resource-type": "transfer"
    },
    "last": {
      "href": "https://api-sandbox.dwolla.com/accounts/62e88a41-f5d0-4a79-90b3-188cf11a3966/transfers?&limit=25&offset=0",
      "type": "application/vnd.dwolla.v1.hal+json",
      "resource-type": "transfer"
    }
  },
  "_embedded": {
    "transfers": [{
      "_links": {
        "cancel": {
          "href": "https://api-sandbox.dwolla.com/transfers/14c6bcce-46f7-e811-8112-e8dd3bececa8",
          "type": "application/vnd.dwolla.v1.hal+json",
          "resource-type": "transfer"
        },
        "source": {
          "href": "https://api-sandbox.dwolla.com/funding-sources/12a0eaf9-9561-468d-bdeb-186b536aa2ed",
          "type": "application/vnd.dwolla.v1.hal+json",
          "resource-type": "funding-source"
        },
        "self": {
          "href": "https://api-sandbox.dwolla.com/transfers/14c6bcce-46f7-e811-8112-e8dd3bececa8",
          "type": "application/vnd.dwolla.v1.hal+json",
          "resource-type": "transfer"
        },
        "funded-transfer": {
          "href": "https://api-sandbox.dwolla.com/transfers/15c6bcce-46f7-e811-8112-e8dd3bececa8",
          "type": "application/vnd.dwolla.v1.hal+json",
          "resource-type": "transfer"
        },
        "destination": {
          "href": "https://api-sandbox.dwolla.com/funding-sources/84c77e52-d1df-4a33-a444-51911a9623e9",
          "type": "application/vnd.dwolla.v1.hal+json",
          "resource-type": "account"
        }
      },
      "id": "14c6bcce-46f7-e811-8112-e8dd3bececa8",
      "status": "pending",
      "amount": {
        "value": "42.00",
        "currency": "USD"
      },
      "created": "2018-12-03T22:00:22.980Z",
      "clearing": {
        "source": "standard"
      },
      "individualAchId": "IDOWBKVE"
    }, {
      "_links": {
        "cancel": {
          "href": "https://api-sandbox.dwolla.com/transfers/15c6bcce-46f7-e811-8112-e8dd3bececa8",
          "type": "application/vnd.dwolla.v1.hal+json",
          "resource-type": "transfer"
        },
        "self": {
          "href": "https://api-sandbox.dwolla.com/transfers/15c6bcce-46f7-e811-8112-e8dd3bececa8",
          "type": "application/vnd.dwolla.v1.hal+json",
          "resource-type": "transfer"
        },
        "source": {
          "href": "https://api-sandbox.dwolla.com/accounts/62e88a41-f5d0-4a79-90b3-188cf11a3966",
          "type": "application/vnd.dwolla.v1.hal+json",
          "resource-type": "account"
        },
        "source-funding-source": {
          "href": "https://api-sandbox.dwolla.com/funding-sources/12a0eaf9-9561-468d-bdeb-186b536aa2ed",
          "type": "application/vnd.dwolla.v1.hal+json",
          "resource-type": "funding-source"
        },
        "funding-transfer": {
          "href": "https://api-sandbox.dwolla.com/transfers/14c6bcce-46f7-e811-8112-e8dd3bececa8",
          "type": "application/vnd.dwolla.v1.hal+json",
          "resource-type": "transfer"
        },
        "destination": {
          "href": "https://api-sandbox.dwolla.com/customers/d295106b-ca20-41ad-9774-286e34fd3c2d",
          "type": "application/vnd.dwolla.v1.hal+json",
          "resource-type": "customer"
        },
        "destination-funding-source": {
          "href": "https://api-sandbox.dwolla.com/funding-sources/500f8e0e-dfd5-431b-83e0-cd6632e63fcb",
          "type": "application/vnd.dwolla.v1.hal+json",
          "resource-type": "funding-source"
        }
      },
      "id": "15c6bcce-46f7-e811-8112-e8dd3bececa8",
      "status": "pending",
      "amount": {
        "value": "42.00",
        "currency": "USD"
      },
      "created": "2018-12-03T22:00:22.970Z",
      "clearing": {
        "source": "standard"
      }
    }]
  },
  "total": 2
}

# Using DwollaV2 - https://github.com/Dwolla/dwolla-v2-ruby
account_url = 'https://api-sandbox.dwolla.com/accounts/62e88a41-f5d0-4a79-90b3-188cf11a3966'

transfers = app_token.get "#{account_url}/transfers"
transfers._embedded['transfers'][0].status # => "processed"

<?php
$accountUrl = 'https://api-sandbox.dwolla.com/accounts/62e88a41-f5d0-4a79-90b3-188cf11a3966';

$transfersApi = new DwollaSwagger\TransfersApi($apiClient);

$transfers = $transfersApi->getAccountTransfers($accountUrl);
$transfers->_embedded->{'transfers'}[0]->status; # => "processed"
?>

# Using dwollav2 - https://github.com/Dwolla/dwolla-v2-python
account_url = 'https://api-sandbox.dwolla.com/accounts/62e88a41-f5d0-4a79-90b3-188cf11a3966'

transfers = app_token.get('%s/transfers' % account_url)
transfers.body['_embedded']['transfers'][0]['status'] # => "processed"

var accountUrl = 'https://api-sandbox.dwolla.com/accounts/62e88a41-f5d0-4a79-90b3-188cf11a3966';

appToken
  .get(`${accountUrl}/transfers`)
  .then(res => res.body._embedded['transfers'][0].status); // => 'processed'

List mass payments for an account

This section covers how to retrieve an Account’s list of previously created mass payments. Mass payments are returned ordered by date created, with most recent mass payments appearing first.

HTTP request

GET https://api.dwolla.com/accounts/{id}/mass-payments

Request parameters

HTTP status and error codes

Request and response

GET https://api-sandbox.dwolla.com/accounts/ca32853c-48fa-40be-ae75-77b37504581b/mass-payments
Accept: application/vnd.dwolla.v1.hal+json
Authorization: Bearer pBA9fVDBEyYZCEsLf/wKehyh1RTpzjUj5KzIRfDi0wKTii7DqY

....

{
  "_links": {
    "self": {
      "href": "https://api-sandbox.dwolla.com/accounts/ca32853c-48fa-40be-ae75-77b37504581b/mass-payments"
    },
    "first": {
      "href": "https://api-sandbox.dwolla.com/accounts/ca32853c-48fa-40be-ae75-77b37504581b/mass-payments?limit=25&offset=0"
    },
    "last": {
      "href": "https://api-sandbox.dwolla.com/accounts/ca32853c-48fa-40be-ae75-77b37504581b/mass-payments?limit=25&offset=0"
    }
  },
  "_embedded": {
    "mass-payments": [
      {
        "_links": {
          "self": {
            "href": "https://api-sandbox.dwolla.com/mass-payments/b4b5a699-5278-4727-9f81-a50800ea9abc"
          },
          "source": {
            "href": "https://api-sandbox.dwolla.com/funding-sources/84c77e52-d1df-4a33-a444-51911a9623e9"
          },
          "items": {
            "href": "https://api-sandbox.dwolla.com/mass-payments/b4b5a699-5278-4727-9f81-a50800ea9abc/items"
          }
        },
        "id": "b4b5a699-5278-4727-9f81-a50800ea9abc",
        "status": "complete",
        "created": "2015-09-03T14:14:10.000Z",
        "metadata": {
          "UserJobId": "some ID"
        },
        "correlationId": "8a2cdc8d-629d-4a24-98ac-40b735229fe2"
      }
    ]
  },
  "total": 1
}

# Using DwollaV2 - https://github.com/Dwolla/dwolla-v2-ruby
account_url = 'https://api-sandbox.dwolla.com/accounts/ca32853c-48fa-40be-ae75-77b37504581b'

mass_payments = account_token.get "#{account_url}/mass-payments", limit: 10
mass_payments._embedded['mass-payments'][0].status # => "complete"

<?php
$accountUrl = 'https://api-sandbox.dwolla.com/accounts/a84222d5-31d2-4290-9a96-089813ef96b3';

$masspaymentsApi = new DwollaSwagger\MasspaymentsApi($apiClient);

$masspayments = $masspaymentsApi->getByAccount($accountUrl, 10, 0);
$masspayments->_embedded->{'mass-payments'}[0]->status; # => "complete"
?>

# Using dwollav2 - https://github.com/Dwolla/dwolla-v2-python
account_url = 'https://api-sandbox.dwolla.com/accounts/ca32853c-48fa-40be-ae75-77b37504581b'

transfers = app_token.get('%s/mass-payments' % account_url, limit = 10)
transfers.body['_embedded']['mass-payments'][0]['status'] # => "complete"

var accountUrl = 'https://api-sandbox.dwolla.com/accounts/ca32853c-48fa-40be-ae75-77b37504581b';

appToken
  .get(`${accountUrl}/mass-payments`)
  .then(res => res.body._embedded['mass-payments'][0].status); // => 'complete'

Customers

A Customer represents an individual or business with whom you intend to transact with and is programmatically created and managed by a Dwolla Master account via the API. In order for a Dwolla Account to create and manage Customers, an application must obtain permission from Dwolla before being enabled in production. Note: Customers can only be US persons. Business Verified Customers may have non-US Controllers or Beneficial Owners.

Customer types

With a transfer of money, at least one party must complete the identity verification process, either the sender or the receiver. This can be either the Dwolla Master Account itself or a verified Customer type. Based on your business model and funds flow, it’s your decision about which party completes this process– you may even want to have both parties complete the identity verification process. A brief description of each Customer type is below, but for a more in-depth overview of each Customer type and what their capabilities are, check out our developer resource article.

Receive-only Users

Receive-only users are restricted to a “payouts only” funds flow. A receive-only user maintains limited functionality in the API and is only eligible to receive transfers to an attached bank account. This Customer type can only interact with verified Customers and a Dwolla Master Account.

Unverified Customers

Unverified Customers have a default sending transaction limit of $5,000 per week. A week is defined as Monday to Sunday UTC time. As this Customer is not identity verified, they will only be able to transact with verified Customers or your Dwolla Master Account.

Verified Customers

Verified Customers are defined by their ability to both send and receive money, thus, being able to fit all funds flows. They can also interact with any Customer type and hold a balance funding source within the Dwolla network. Think of the Dwolla balance as a “wallet” which a Customer can send, receive, or hold funds to within the Dwolla network. With no weekly transfer limits, this Customer type is flexible for high transaction volumes.

A verified Customer can be created as a type of either Personal or Business.

Customer links

Customer resource

Customer statuses

{
  "_links": {
    "self": {
      "href": "https://api-sandbox.dwolla.com/customers/9da3aa7c-2524-430b-a751-6dc722735fce",
      "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/9da3aa7c-2524-430b-a751-6dc722735fce",
      "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/9da3aa7c-2524-430b-a751-6dc722735fce",
      "type": "application/vnd.dwolla.v1.hal+json",
      "resource-type": "customer"
    },
    "funding-sources": {
      "href": "https://api-sandbox.dwolla.com/customers/9da3aa7c-2524-430b-a751-6dc722735fce/funding-sources",
      "type": "application/vnd.dwolla.v1.hal+json",
      "resource-type": "funding-source"
    },
    "transfers": {
      "href": "https://api-sandbox.dwolla.com/customers/9da3aa7c-2524-430b-a751-6dc722735fce/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": "9da3aa7c-2524-430b-a751-6dc722735fce",
  "firstName": "Jane",
  "lastName": "Doe",
  "email": "janedoe@email.com",
  "type": "personal",
  "status": "verified",
  "created": "2016-08-17T18:58:47.630Z",
  "address1": "99-99 33rd St",
  "address2": "Apt 8",
  "city": "Some City",
  "state": "NY",
  "postalCode": "11101",
  "phone": "5554321234"
}

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

Request parameters - receive-only User

Request and response - receive-only User

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

# Using DwollaV2 - https://github.com/Dwolla/dwolla-v2-ruby
request_body = {
  :firstName => 'Jane',
  :lastName => 'Merchant',
  :email => 'jmerchant@nomail.net',
  :type => 'receive-only',
  :businessName => 'Jane Corp llc',
  :ipAddress => '99.99.99.99'
}

customer = app_token.post "customers", request_body
customer.response_headers[:location] # => "https://api-sandbox.dwolla.com/customers/fc451a7a-ae30-4404-aB95-e3553fcd733f"

<?php
$customersApi = new DwollaSwagger\CustomersApi($apiClient);

$customer = $customersApi->create([
  'firstName' => 'Jane',
  'lastName' => 'Merchant',
  'email' => 'jmerchant@nomail.net',
  'type' => 'receive-only',
  'businessName' => 'Jane Corp llc',
  'ipAddress' => '99.99.99.99'
]);
$customer; # => "https://api-sandbox.dwolla.com/customers/fc451a7a-ae30-4404-aB95-e3553fcd733f"
?>

# Using dwollav2 - https://github.com/Dwolla/dwolla-v2-python
request_body = {
  'firstName': 'Jane',
  'lastName': 'Merchant',
  'email': 'jmerchant@nomail.net',
  'type': 'receive-only',
  'businessName': 'Jane Corp llc',
  'ipAddress': '99.99.99.99'
}

customer = app_token.post('customers', request_body)
customer.headers['location'] # => 'https://api-sandbox.dwolla.com/customers/fc451a7a-ae30-4404-aB95-e3553fcd733f'

var requestBody = {
  firstName: 'Jane',
  lastName: 'Merchant',
  email: 'jmerchant@nomail.net',
  type: 'receive-only',
  businessName: 'Jane Corp llc',
  ipAddress: '99.99.99.99'
};

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

Request parameters - unverified Customer

Request and response - unverified Customer

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

# Using DwollaV2 - https://github.com/Dwolla/dwolla-v2-ruby
request_body = {
  :firstName => 'Jane',
  :lastName => 'Merchant',
  :email => 'jmerchant@nomail.net',
  :ipAddress => '99.99.99.99'
}

customer = app_token.post "customers", request_body
customer.headers[:location] # => "https://api-sandbox.dwolla.com/customers/fc451a7a-ae30-4404-aB95-e3553fcd733f"

<?php
$customersApi = new DwollaSwagger\CustomersApi($apiClient);

$customer = $customersApi->create([
  'firstName' => 'Jane',
  'lastName' => 'Merchant',
  'email' => 'jmerchant@nomail.net',
  'ipAddress' => '99.99.99.99'
]);

$customer; # => "https://api-sandbox.dwolla.com/customers/fc451a7a-ae30-4404-aB95-e3553fcd733f"
?>

# Using dwollav2 - https://github.com/Dwolla/dwolla-v2-python
request_body = {
  'firstName': 'Jane',
  'lastName': 'Merchant',
  'email': 'jmerchant@nomail.net',
  'ipAddress': '99.99.99.99'
}

customer = app_token.post('customers', request_body)
customer.headers['location'] # => 'https://api-sandbox.dwolla.com/customers/fc451a7a-ae30-4404-aB95-e3553fcd733f'

var requestBody = {
  firstName: 'Jane',
  lastName: 'Merchant',
  email: 'jmerchant@nomail.net',
  ipAddress: '99.99.99.99'
};

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

Request parameters - verified personal Customer

For an in-depth look at personal verified Customers creation and status handling, refer to our developer resource article.

Request and response - verified personal Customer

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

<?php
$customersApi = new DwollaSwagger\CustomersApi($apiClient);

$customer = $customersApi->create([
  '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'
]);

$customer; # => "https://api-sandbox.dwolla.com/customers/fc451a7a-ae30-4404-aB95-e3553fcd733f"
?>

# Using DwollaV2 - https://github.com/Dwolla/dwolla-v2-ruby
request_body = {
  :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'
}

customer = app_token.post "customers", request_body
customer.response_headers[:location] # => "https://api-sandbox.dwolla.com/customers/fc451a7a-ae30-4404-aB95-e3553fcd733f"

# Using dwollav2 - https://github.com/Dwolla/dwolla-v2-python
request_body = {
  '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'
}

customer = app_token.post('customers', request_body)
customer.headers['location'] # => 'https://api-sandbox.dwolla.com/customers/fc451a7a-ae30-4404-aB95-e3553fcd733f'

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'
};

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

Request parameters - verified business Customer (sole proprietorship only)

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.

Request and response - verified business Customer (sole proprietorship only)

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

<?php
$customersApi = new DwollaSwagger\CustomersApi($apiClient);
$new_customer = $customersApi->create([
    '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']);

?>

# Using DwollaV2 - https://github.com/Dwolla/dwolla-v2-ruby (Recommended)
request_body = {
    :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'
}

customer = app_token.post "customers", request_body
customer.response_headers[:location] # => "https://api-sandbox.dwolla.com/customers/62c3aa1b-3a1b-46d0-ae90-17304d60c3d5"

# Using dwollav2 - https://github.com/Dwolla/dwolla-v2-python (Recommended)
request_body = {
  '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'
}

customer = app_token.post('customers', request_body)
customer.headers['location'] # => 'https://api-sandbox.dwolla.com/customers/62c3aa1b-3a1b-46d0-ae90-17304d60c3d5'

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',
};

appToken
  .post('customers', requestBody)
  .then(res => res.headers.get('location')); // => 'https://api-sandbox.dwolla.com/customers/62c3aa1b-3a1b-46d0-ae90-17304d60c3d5'

Request parameters - verified business Customer (businessType=llc, corporation or partnership)

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.

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.

Controller address JSON object

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.

Verified Business Customer (businessType= llc, corporation or partnership)

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

<?php
$customersApi = new DwollaSwagger\CustomersApi($apiClient);
$new_customer = $customersApi->create([
  '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' => '1990-10-10',
      'ssn' => '1234',
      'address' =>
      [
          'address1' => '18749 18th st',
          'address2' => 'apt 12',
          'city' => 'Des Moines',
          'stateProvinceRegion' => 'IA',
          'postalCode' => '50265',
          'country' => 'US'
      ],
  ],
  'phone' => '5554321234',
  'businessClassification' => '9ed3f670-7d6f-11e3-b1ce-5404a6144203',
  'businessType' => 'llc',
  'businessName' => 'Jane Corp',
  'ein' => '00-0000000']);

?>

# Using DwollaV2 - https://github.com/Dwolla/dwolla-v2-ruby (Recommended)
request_body = {
  :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'
}

customer = app_token.post "customers", request_body
customer.response_headers[:location] # => "https://api-sandbox.dwolla.com/customers/62c3aa1b-3a1b-46d0-ae90-17304d60c3d5"

# Using dwollav2 - https://github.com/Dwolla/dwolla-v2-python (Recommended)
request_body = {
  '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': 'apt12',
        'city': 'Des Moines',
        'stateProvinceRegion': 'IA',
        'postalCode': '50266',
        'country': 'US'
      }
  },
  'businessClassification': '9ed38155-7d6f-11e3-83c3-5404a6144203',
  'businessType': 'llc',
  'businessName': 'Jane Corp',
  'ein': '12-3456789'
}
customer = app_token.post('customers', request_body)
customer.headers['location'] # => 'https://api-sandbox.dwolla.com/customers/62c3aa1b-3a1b-46d0-ae90-17304d60c3d5'

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'
};
appToken
  .post('customers', requestBody)
  .then(res => res.headers.get('location')); // => 'https://api-sandbox.dwolla.com/customers/62c3aa1b-3a1b-46d0-ae90-17304d60c3d5'

Retrieve a customer

This section shows you how to retrieve a Customer belonging to the authorized Dwolla Master Account. Each Customer id is a part of its location resource. You can pass either an id or the entire location resource to make this request.

HTTP request

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

Request parameters

HTTP status and error codes

Request and response

GET https://api-sandbox.dwolla.com/customers/07d59716-ef22-4fe6-98e8-f3190233dfb8
Accept: application/vnd.dwolla.v1.hal+json
Authorization: Bearer pBA9fVDBEyYZCEsLf/wKehyh1RTpzjUj5KzIRfDi0wKTii7DqY

{
  "_links": {
    "self": {
      "href": "https://api-sandbox.dwolla.com/customers/07d59716-ef22-4fe6-98e8-f3190233dfb8"
    }
  },
  "id": "07d59716-ef22-4fe6-98e8-f3190233dfb8",
  "firstName": "Jane",
  "lastName": "Doe",
  "email": "janedoe@nomail.com",
  "type": "unverified",
  "status": "unverified",
  "created": "2015-09-03T23:56:10.023Z"
}

# Using DwollaV2 - https://github.com/Dwolla/dwolla-v2-ruby
customer_url = 'https://api-sandbox.dwolla.com/customers/07d59716-ef22-4fe6-98e8-f3190233dfb8'

customer = app_token.get customer_url
customer.firstName # => "Jane"

<?php
$customerUrl = 'https://api-sandbox.dwolla.com/customers/07d59716-ef22-4fe6-98e8-f3190233dfb8';

$customersApi = new DwollaSwagger\CustomersApi($apiClient);

$customer = $customersApi->getCustomer($customerUrl);
$customer->firstName; # => "Jane"
?>

# Using dwollav2 - https://github.com/Dwolla/dwolla-v2-python
customer_url = 'https://api-sandbox.dwolla.com/customers/07d59716-ef22-4fe6-98e8-f3190233dfb8'

customer = app_token.get(customer_url)
customer.body['firstName']

var customerUrl = 'https://api-sandbox.dwolla.com/customers/07d59716-ef22-4fe6-98e8-f3190233dfb8';

appToken
  .get(customerUrl)
  .then(res => res.body.firstName); // => 'Jane'

List and search customers

This section outlines how to retrieve your list of created Customers. This endpoint contains optional query string parameters allowing you to filter by email and status, as well as search on key fields such as firstName, lastName, and businessName.

HTTP Request

GET https://api.dwolla.com/customers

Pagination

By default, an embedded list of 25 customers are returned and are sorted by created timestamp. To page through the remaining list, you’ll specify a combination of limit and offset as query string parameters. Limit can have a max value of 200 customer objects. It is recommended to use the _links object in the response which includes the following relational links for paging. Check out the Links section for more information.

• next includes the URL to list the next set of Customers as defined by Limit
• prev includes the URL to list the previous set of Customers as defined by Limit
• first includes the URL to list the first set of Customers as defined by Limit
• last includes the URL to list the last set of Customers as defined by Limit
• self link indicates the URL of the resource itself

Example HTTP Request

GET https://api.dwolla.com/customers?limit=5&offset=25

Searching and filtering Customers

The search query string parameter contains a fuzzy search query across firstName, lastName, businessName, and email fields. Scoring is performed on the search term which looks for approximate spellings that match the entered search string and results are returned accordingly in an embedded customers array. Note: For exact match on email string value, the email filter should be used.

The email query string parameter is a filter that returns an embedded customers array based on an exact match of the filter value. For example, if you would like to search for a Customer with the email address “jane@email.com”, you can append the additional parameter email to the request URL as shown in the example HTTP request below. Note: The email filter string value must be URL-encoded.

The status query string parameter can be used to list an embedded customers array based on the status field. For example, if you would like to list all Customers that are in document status, you can append the additional parameter status to the request URL with the value “document”. Check out all possible values listed in the table below.

Example Request URL using email filter

GET https://api.dwolla.com/customers?email=jane%40email.com

Example Request URL using search

GET https://api.dwolla.com/customers?search=Jane

Example Request URL using status filter

GET https://api.dwolla.com/customers?status=document

Request parameters

Request and response

GET https://api-sandbox.dwolla.com/customers
Accept: application/vnd.dwolla.v1.hal+json
Authorization: Bearer pBA9fVDBEyYZCEsLf/wKehyh1RTpzjUj5KzIRfDi0wKTii7DqY

{
  "_links": {
    "first": {
      "href": "https://api-sandbox.dwolla.com/customers?limit=25&offset=0"
    },
    "last": {
      "href": "https://api-sandbox.dwolla.com/customers?limit=25&offset=0"
    },
    "self": {
      "href": "https://api-sandbox.dwolla.com/customers?limit=25&offset=0"
    }
  },
  "_embedded": {
    "customers": [
      {
        "_links": {
          "self": {
            "href": "https://api-sandbox.dwolla.com/customers/07d59716-ef22-4fe6-98e8-f3190233dfb8"
          }
        },
        "id": "07d59716-ef22-4fe6-98e8-f3190233dfb8",
        "firstName": "Jane",
        "lastName": "Doe",
        "email": "janedoe@nomail.com",
        "type": "unverified",
        "status": "unverified",
        "created": "2015-09-03T23:56:10.023Z"
      }
    ]
  },
  "total": 1
}

# Using DwollaV2 - https://github.com/Dwolla/dwolla-v2-ruby
customers = app_token.get "customers", limit: 10
customers._embedded.['customers'][0].firstName # => "Jane"

<?php
$customersApi = new DwollaSwagger\CustomersApi($apiClient);

$customers = $customersApi->_list(10, 0);
$customers->_embedded->{'customers'}[0]->firstName; # => "Jane"
?>

# Using dwollav2 - https://github.com/Dwolla/dwolla-v2-python
customer = app_token.get('customers', limit = 10)
customer.body['_embedded']['customers'][0]['firstName'] # => 'Jane'

appToken
  .get('customers', { limit: 10 })
  .then(res => res.body._embedded['customers'][0].firstName); // => 'Jane'

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

Request parameters - verified Customer

Request parameters - verified Customer with type=business

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

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 this table 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

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

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

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:

{
    "_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. For a Business Verified Customer in retry status, all fields that were required in the initial Customer creation attempt will be required in the retry attempt, along with the full 9-digit SSN. To learn more about retry for business verified Customers and view further code examples, refer to our business verified Customer developer resource article.

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"
}

<?php
$customersApi = new DwollaSwagger\CustomersApi($apiClient);

$customerUrl = 'https://api.dwolla.com/customers/53863b11-1758-47c8-821f-00e6a126f97f';
$customer = $customersApi->updateCustomer(array (
  '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',
), $customerUrl);

$customer->id; # => "53863b11-1758-47c8-821f-00e6a126f97f"
?>

# Using DwollaV2 - https://github.com/Dwolla/dwolla-v2-ruby
customer_url = 'https://api-sandbox.dwolla.com/customers/53863b11-1758-47c8-821f-00e6a126f97f'
request_body = {
      "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"
}

customer = app_token.post customer_url, request_body
customer.id # => "53863b11-1758-47c8-821f-00e6a126f97f"

# Using dwollav2 - https://github.com/Dwolla/dwolla-v2-python
customer_url = 'https://api-sandbox.dwolla.com/customers/53863b11-1758-47c8-821f-00e6a126f97f'
request_body = {
  "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"
}

customer = app_token.post(customer_url, request_body)
customer.body.id # => '53863b11-1758-47c8-821f-00e6a126f97f'

var customerUrl = 'https://api-sandbox.dwolla.com/customers/53863b11-1758-47c8-821f-00e6a126f97f';
var requestBody = {
  firstName: "John",
  lastName: "Doe",
  email: "johndoe@dwolla.com",
  ipAddress: "10.10.10.10",
  type: "personal",
  address1: "221 Corrected Address St.",
  address2: "Fl 8",
  city: "Ridgewood",
  state: "NY",
  postalCode: "11385",
  dateOfBirth: "1990-07-11",
  ssn: "202-99-1516"
};

appToken
  .post(customerUrl, requestBody)
  .then(res => res.body.id); // => '53863b11-1758-47c8-821f-00e6a126f97f'

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

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

Request parameters - retry verified personal Customer

HTTP status and error codes

List business classifications

Retrieve an _embedded list of business classifications that contains an _embedded list of industry classifications. The appropriate Id from the list of industry classifications must be passed in the businessClassification parameter when creating a Business Verified Customer. The industry classification is used to identify the Customer’s business and is required by Dwolla when verifying a business in order to better analyze the nature of a business.

HTTP request

GET https://api.dwolla.com/business-classifications

Request and response

GET https://api-sandbox.dwolla.com/business-classifications
Accept: application/vnd.dwolla.v1.hal+json
Authorization: Bearer pBA9fVDBEyYZCEsLf/wKehyh1RTpzjUj5KzIRfDi0wKTii7DqY

{
  "_links": {},
  "_embedded": {
    "business-classifications": [
      {
        "_links": {
          "self": {
            "href": "https://api-sandbox.dwolla.com/business-classifications/9ed3f669-7d6f-11e3-b545-5404a6144203"
          }
        },
        "_embedded": {
          "industry-classifications": [
            {
              "id": "9ed3f671-7d6f-11e3-803c-5404a6144203",
              "name": "Gourmet foods"
            },
            {
              "id": "9ed3f66c-7d6f-11e3-86ae-5404a6144203",
              "name": "Distilleries"
            },
            {
              ...........
            }
          ]
        },
        "id": "9ed3f669-7d6f-11e3-b545-5404a6144203",
        "name": "Food retail and service"
      }
      ...........
    ]
  },
  "total": 27
}

# Using DwollaV2 - https://github.com/Dwolla/dwolla-v2-ruby
business_classifications = app_token.get "business-classifications"
business_classifications._embedded['business-classifications'][0].name # => "Food retail and service"

<?php
$businessClassificationsApi = new DwollaSwagger\BusinessclassificationsApi($apiClient);

$busClassifications = $businessClassificationsApi->_list();
$busClassifications->_embedded->{'business-classifications'}[0]->name; # => "Food retail and service"
?>

# Using dwollav2 - https://github.com/Dwolla/dwolla-v2-python
business_classifications = app_token.get('business-classifications')
business_classifications.body['_embedded']['business-classifications'][0]['name'] # => 'Food retail and service'

appToken
  .get('business-classifications')
  .then(res => res.body._embedded['business-classifications'][0].name); // => 'Food retail and service'

Retrieve a business classification

This section shows you how to retrieve an Id from a list of industry classifications to be passed in the businessClassification parameter when creating a Business Verified Customer.

HTTP request

GET https://api.dwolla.com/business-classifications/{id}

Request parameters

Request and response

GET https://api-sandbox.dwolla.com/business-classifications/9ed3a866-7d6f-11e3-a0ce-5404a6144203
Accept: application/vnd.dwolla.v1.hal+json
Authorization: Bearer pBA9fVDBEyYZCEsLf/wKehyh1RTpzjUj5KzIRfDi0wKTii7DqY

{
  "_links": {
    "self": {
      "href": "https://api-sandbox.dwolla.com/business-classifications/9ed3a866-7d6f-11e3-a0ce-5404a6144203"
    }
  },
  "_embedded": {
    "industry-classifications": [
      {
        "id": "9ed3cf58-7d6f-11e3-81a4-5404a6144203",
        "name": "Toys and games"
      },
      {
        "id": "9ed3cf50-7d6f-11e3-8ae8-5404a6144203",
        "name": "Music"
      },
      {
        ...........
      }
    ]
  },
  "id": "9ed3a866-7d6f-11e3-a0ce-5404a6144203",
  "name": "Entertainment and media"
}

# Using DwollaV2 - https://github.com/Dwolla/dwolla-v2-ruby
business_classification_url = 'https://api-sandbox.dwolla.com/business-classifications/9ed3a866-7d6f-11e3-a0ce-5404a6144203'

business_classification = app_token.get business_classification_url
business_classification.name # => "Entertainment and media"

<?php
$businessClassificationUrl = 'https://api-sandbox.dwolla.com/business-classifications/9ed3a866-7d6f-11e3-a0ce-5404a6144203';

$businessClassificationsApi = new DwollaSwagger\BusinessclassificationsApi($apiClient);

$busClassifications = $businessClassificationsApi->getBusinessClassification($businessClassificationUrl);
$busClassifications->name; # => "Entertainment and media"
?>

# Using dwollav2 - https://github.com/Dwolla/dwolla-v2-python
business_classification_url = 'https://api-sandbox.dwolla.com/business-classifications/9ed3a866-7d6f-11e3-a0ce-5404a6144203'

busClassification = app_token.get(business_classification_url)
busClassification.body['name']

var businessClassificationUrl = 'https://api-sandbox.dwolla.com/business-classifications/9ed3a866-7d6f-11e3-a0ce-5404a6144203';

appToken
  .get(businessClassificationUrl)
  .then(res => res.body.name); // => 'Entertainment and media'

Knowledge-based Authentication (KBA)

Knowledge-based authentication, commonly referred to as KBA, is a method of authentication which seeks to prove the identity of an individual. KBA requires the knowledge of private information of the individual to prove that the person providing the identity information is the owner of the identity. Questions are compiled from public and private data such as marketing data, credit reports or transaction history.

Note: KBA as a method of verifying an identity is only available to Personal Verified Customers at this time.

1. This section outlines a premium feature for the Dwolla API. To learn more about pricing and enabling this functionality, please contact Sales.

KBA Links

Initiate KBA Session

This section covers how to generate a new KBA identifier which is used to represent the session for the user created as a personal Verified Customer record.

HTTP Request

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

Request parameters

Example request and response

POST https://api.dwolla.com/customers/33aa88b1-97df-424a-9043-d5f85809858b/kba
Authorization: Bearer cRahPzURfaIrTKL18tmslWPqKdzkLeYJm0oB1hGJ1vMPArft1v
Content-Type: application/json
Accept: application/vnd.dwolla.v1.hal+json

...

HTTP/1.1 201 Created\
Location: https://api.dwolla.com/kba/33aa88b1-97df-424a-9043-d5f85809858b

customer_url = 'https://api-sandbox.dwolla.com/customers/ca22d192-48f1-4b72-b29d-681e9e20795d'

kba = app_token.post "#{customer_url}/kba"
kba.response_headers[:location] # => "https://api-sandbox.dwolla.com/kba/70b0e9cc-020d-4de2-9a82-a2281afa4c31"

<?php
$customersApi = new DwollaSwagger\CustomersApi($apiClient);

$customerUrl = "https://api.dwolla.com/customers/ca22d192-48f1-4b72-b29d-681e9e20795d"

$kba = $customersApi->initiateKba($customer_url);
$kba; # => "https://api-sandbox.dwolla.com/kba/70b0e9cc-020d-4de2-9a82-a2281afa4c31"
?>

customer_url = 'https://api-sandbox.dwolla.com/customers/61a74e62-e27d-46f1-9fa6-a8e57226bb3e'

kba = app_token.post('%s/kba' % customer_url)
kba.headers['location'] # => "https://api-sandbox.dwolla.com/kba/70b0e9cc-020d-4de2-9a82-a2281afa4c31"

var customerUrl = 'https://api-sandbox.dwolla.com/customers/61a74e62-e27d-46f1-9fa6-a8e57226bb3e';

appToken
  .post(`${customerUrl}/kba`)
  .then(res => res.headers.get('location')); // => 'https://api-sandbox.dwolla.com/kba/70b0e9cc-020d-4de2-9a82-a2281afa4c31'

HTTP Status and Error Codes

Retrieve KBA Questions

On KBA question creation, Dwolla will return a 201 HTTP statusCode and a link to the KBA session from which to retrieve questions. This section covers how to retrieve KBA questions after you have created the KBA session.

HTTP Request

GET https://api.dwolla.com/kba/{id}

Request parameters

Example request and response

GET https://api.dwolla.com/kba/33aa88b1-97df-424a-9043-d5f85809858b
Accept: application/vnd.dwolla.v1.hal+json
Authorization: Bearer cRahPzURfaIrTewKL18tmslWPqKdzkLeYJm0oB1hGJ1vMPArft1v

...

{
    "_links": {
        "answer": {
            "href": "https://api-sandbox.dwolla.com/kba/33aa88b1-97df-424a-9043-d5f85809858b",
            "type": "application/vnd.dwolla.v1.hal+json",
            "resource-type": "kba"
        }
    },
    "id": "33aa88b1-97df-424a-9043-d5f85809858b",
    "questions": [
        {
            "id": "2355953375",
            "text": "In what county do you currently live?",
            "answers": [
                {
                    "id": "2687969295",
                    "text": "Pulaski"
                },
                {
                    "id": "2687969305",
                    "text": "St. Joseph"
                },
                {
                    "id": "2687969315",
                    "text": "Daviess"
                },
                {
                    "id": "2687969325",
                    "text": "Jackson"
                },
                {
                    "id": "2687969335",
                    "text": "None of the above"
                }
            ]
        },
        {
            "id": "2355953385",
            "text": "Which team nickname is associated with a college you attended?",
            "answers": [
                {
                    "id": "2687969345",
                    "text": "Colts"
                },
                {
                    "id": "2687969355",
                    "text": "Eagles"
                },
                {
                    "id": "2687969365",
                    "text": "Gator"
                },
                {
                    "id": "2687969375",
                    "text": "Sentinels"
                },
                {
                    "id": "2687969385",
                    "text": "None of the above"
                }
            ]
        },
        {
            "id": "2355953395",
            "text": "What kind of IA license plate has been on your 1996 Acura TL?",
            "answers": [
                {
                    "id": "2687969395",
                    "text": "Antique"
                },
                {
                    "id": "2687969405",
                    "text": "Disabled Veteran"
                },
                {
                    "id": "2687969415",
                    "text": "Educational Affiliation"
                },
                {
                    "id": "2687969425",
                    "text": "Military Honor"
                },
                {
                    "id": "2687969435",
                    "text": "I have never been associated with this vehicle"
                }
            ]
        }
    ]
}

kba_url = 'https://api-sandbox.dwolla.com/kba/70b0e9cc-020d-4de2-9a82-a2281afa4c31'

kba_questions = app_token.get kba_url
kba_questions.id # => "70b0e9cc-020d-4de2-9a82-a2281afa4c31"

<?php
$kbaApi = new DwollaSwagger\KbaApi($apiClient);

kba_url = "https://api-sandbox.dwolla.com/kba/70b0e9cc-020d-4de2-9a82-a2281afa4c31";

$kbaQuestions = $kbaApi->getKbaQuestions($kbaUrl);
print $kbaQuestions->id; # => "70b0e9cc-020d-4de2-9a82-a2281afa4c31"
?>

kba_url = 'https://api-sandbox.dwolla.com/kba/70b0e9cc-020d-4de2-9a82-a2281afa4c31'

kba_questions = app_token.get(kba_url)
kba_questions.id # => '70b0e9cc-020d-4de2-9a82-a2281afa4c31'

var kbaUrl = 'https://api-sandbox.dwolla.com/kba/70b0e9cc-020d-4de2-9a82-a2281afa4c31';

appToken
  .get(kbaUrl)
  .then(res => res.body.id); // => '70b0e9cc-020d-4de2-9a82-a2281afa4c31'

HTTP Status and Error Codes

Verify KBA Questions

This section covers how to verify the KBA questions for Customer verification.

HTTP Request

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

Request parameters

answers JSON object

Example request and response

POST https://api.dwolla.com/kba/33aa88b1-97df-424a-9043-d5f85809858b
Accept: application/vnd.dwolla.v1.hal+json
Authorization: Bearer cRahPzURfaIrTewKL18tmslWPqKdzkLeYJm0oB1hGJ1vMPArft1v

...

{
    "answers": [
        {
            "questionId": "2355953375",
            "answerId": "2687969335"
        },
        {
            "questionId": "2355953385",
            "answerId": "2687969385"
        },
        {
            "questionId": "2355953395",
            "answerId": "2687969435"
        },
        {
            "questionId": "2355953405",
            "answerId": "2687969485"
        }
    ]
}

kba_url = 'https://api-sandbox.dwolla.com/kba/70b0e9cc-020d-4de2-9a82-a2281afa4c31'

request_body = {
    :answers => [
        {
            :questionId => "2355953375",
            :answerId => "2687969335"
        },
        {
            :questionId => "2355953385",
            :answerId => "2687969385"
        },
        {
            :questionId => "2355953395",
            :answerId => "2687969435"
        },
        {
            :questionId => "2355953405",
            :answerId => "2687969485"
        }
    ]
}

kba_answers = app_token.post kba_url, request_body

<?php
$kbaApi = new DwollaSwagger\KbaApi($apiClient);

$kbaUrl = "https://api-sandbox.dwolla.com/kba/70b0e9cc-020d-4de2-9a82-a2281afa4c31";

$kbaAnswers = $kbaApi->answerKbaQuestions([
    "answers" => [
         [
             "questionId" => "2355953375",
             "answerId" => "2687969335"
         ],
         [
             "questionId" => "2355953385",
             "answerId" => "2687969385"
         ],
         [
             "questionId" => "2355953395",
             "answerId" => "2687969435"
         ],
         [
             "questionId" => "2355953405",
             "answerId" => "2687969485"
         ]
    ]
  ], $kbaUrl);
?>

kba_url = 'https://api-sandbox.dwolla.com/kba/70b0e9cc-020d-4de2-9a82-a2281afa4c31'

request_body = {
    'answers' : [
        {
            'questionId': "2355953375",
            'answerId': "2687969335"
        },
        {
            'questionId': "2355953385",
            'answerId': "2687969385"
        },
        {
            'questionId': "2355953395",
            'answerId':"2687969435"
        },
        {
            'questionId': "2355953405",
            'answerId': "2687969485"
        }
    ]
}

kba_answers = app_token.post (kba_url, request_body)

var kbaUrl = 'https://api.dwolla.com/kba/70b0e9cc-020d-4de2-9a82-a2281afa4c31';
var requestBody = {
  answers : [
        {
            questionId: '2355953375',
            answerId: '2687969335'
        },
        {
            questionId: '2355953385',
            answerId: '2687969385'
        },
        {
            questionId: '2355953395',
            answerId:'2687969435'
        },
        {
            questionId: '2355953405',
            answerId: '2687969485'
        }
    ]
};

appToken
  .post(kbaUrl, requestBody)

HTTP Status and Error Codes

Beneficial owners

Verified Customers of type business are required to verify the identity of beneficial owners in addition to the controller of the business if they are one of the following business types:

• Corporation
• LLC
• Partnership

For more information on how to add beneficial owners, or to learn more on whether certain business types are exempt, check out our beneficial owner developer resource article.

Beneficial owners resource

{
    "_links": {
        "self": {
            "href": "https://api-sandbox.dwolla.com/beneficial-owners/caa81a5f-ec1e-4559-8b32-d90655bfd03c",
            "type": "application/vnd.dwolla.v1.hal+json",
            "resource-type": "beneficial-owner"
        }
    },
    "id": "caa81a5f-ec1e-4559-8b32-d90655bfd03c",
    "firstName": "Joe",
    "lastName": "owner",
    "address": {
        "address1": "12345 18th st",
        "address2": "Apt 12",
        "address3": "",
        "city": "Des Moines",
        "stateProvinceRegion": "IA",
        "country": "US",
        "postalCode": "50265"
    },
    "verificationStatus": "verified"
}

Create a beneficial owner

This section details how to create a new beneficial owner. To create beneficial owners, you need to collect the beneficial owner’s full name, ssn, date of birth, and permanent address. Optionally, passport information must be included for non-US persons that do not have a US issued SSN. Beneficial owners require additional information that will give Dwolla the ability to confirm the identity of the individual.

For more information on how to create a beneficial owner, refer to our developer resource article.

HTTP request

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

Request Parameters