Language

Access API principles

Developers migrating from v1 should familiarize themselves with new design and patterns used in the Access API. The Access API is a hypermedia API that adopts the HAL spec, which provides a set of conventions for using hyperlinks (URLs) for “discoverability”. One key benefit is its self-documenting nature and the ability to consume the API with no prior knowledge. The idea is to follow links to suggested resources and actions based on the current OAuth context, instead of referencing resources by their Id.

Resources

A resource is a JSON object (e.g. a Transfer object) that contains: properties that represent the current state of the resource, _links pointing to relevant resources, and an optional _embedded property which is a collection of related child resources. At a minimum, a resource will have at least a _links property containing a self link.

Links

_links is an object that simply contains links to related resources. A key in a _links object is the name of the link, and it describes the link relation(rel). e.g. “send”, “funding-sources”, “initiate-micro-deposits”, etc.

Example of an Access API response

{
  "_links": {
    "self": {
      "href": "https://api-uat.dwolla.com/accounts/ad5f2162-404a-4c4c-994e-6ab6c3a13254",
      "type": "account"
    },
    "receive": {
      "href": "https://api-uat.dwolla.com/transfers",
      "type": "transfer"
    },
    "funding-sources": {
      "href": "https://api-uat.dwolla.com/accounts/ad5f2162-404a-4c4c-994e-6ab6c3a13254/funding-sources",
      "type": "funding-source"
    },
    "transfers": {
      "href": "https://api-uat.dwolla.com/accounts/ad5f2162-404a-4c4c-994e-6ab6c3a13254/transfers",
      "type": "transfer"
    },
    "customers": {
      "href": "https://api-uat.dwolla.com/customers",
      "type": "customer"
    },
    "send": {
      "href": "https://api-uat.dwolla.com/transfers",
      "type": "transfer"
    }
  },
  "id": "ad5f2162-404a-4c4c-994e-6ab6c3a13254",
  "name": "Jane Doe"
}

HTTP status codes and errors

If you’re interacting with Dwolla’s v1 API, then you may know that it relies primarily on returning an HTTP 200 status code. A major improvement we made with the Access API is returning meaningful HTTP status codes. These status codes can be leveraged by a client to easily handle responses without having to parse the entire response body.

In addition to meaningful status codes, error responses that are HTTP 4xx/5xx level return a well formed JSON response body that contains a unique top-level error code and a message with a detailed description of the error.

v1 error response
HTTP 200

{
  "Success": false,
  "Message": "Please enter a valid 9-digit routing number.",
  "Response": null,
  "_links": null
}
Access API error response
HTTP 400

{
  "code": "ValidationError",
  "message": "Validation error(s) present. See embedded errors list for more details.",
  "_embedded": {
    "errors": [
      {
        "code": "InvalidFormat",
        "message": "Routing number must be 9 characters.",
        "path": "/routingNumber"
      }
    ]
  }
}

Financial institutions play an important role in the Dwolla network.

Dwolla, Inc. is an agent of Veridian Credit Union and Compass Bank and all funds associated with your account in the Dwolla network are held in pooled accounts at Veridian Credit Union and Compass Bank. These funds are not eligible for individual insurance, including FDIC insurance and may not be eligible for share insurance by the National Credit Union Share Insurance Fund. Dwolla, Inc. is the operator of a software platform that communicates user instructions for funds transfers to Veridian Credit Union and Compass Bank.