By: Jared Dellitt,

Understanding simplified customer onboarding through a better-formed API—pun absolutely intended.

If you have questions about this concept or incorporating Dwolla HAL forms, join the discussion.

At Dwolla, our API is our bread & butter, so we’re always trying to improve the usability and decrease the time it takes for our partners to go live. One way we accomplish this is by building our own products on top of the same APIs that we expect our partners to use. For example, the Dwolla Dashboard & Admin is built almost entirely using our API V2. From the very beginning, we knew we wanted to broaden the functionality of this dashboard—specifically, we knew we wanted our White Label partners to have the ability to edit customers within the dashboard.

When we first started adding the ‘edit’ functionality, we quickly realized we were going to be duplicating a lot of the logic that was already in our API to determine what fields needed to be submitted for all types and statuses of customers. We really wanted a way for the API to tell us the information we needed to show the user, based on the current state of the customer being edited.

To do so, we needed dynamic form definitions based on the state of the API resources. Since our API is hypermedia-driven and an implementation of the HAL spec, we wanted something that aligned with how our current responses are represented.

After some research, the obvious answer was to use the HAL-FORMS Media Type, but after some prototyping we quickly realized it wasn’t going to fit our needs as we’d hoped. Features we considered important for usability of the generated HTML were missing, such as: providing a set of accepted values for a dropdown, hints on the field type and custom validation rules. These limitations inspired us to take some of the best ideas of HAL-FORMS and expand upon them.

Dwolla HAL-Forms describes how we decided to represent forms in the API and it starts with the media type. Similar to our error responses, which we represent using vnd.error, the form responses don’t deviate much from HAL, so we’re including it as a profile link.

When this profile is provided in the Accept header of the request, the API knows that you’re looking for a form for the given resource. So how is a client expected to know if a form is available for a given resource? Links! This is a RESTful API after all. In order for the forms to be discoverable, we include links in the resources to the forms.

So when a customer is retrieved, an “edit-form” link is now included in the “_links” object of the response.

GET /customers/1bdcf411-4a81-4534-993b-9ba183a3b3dc HTTP/1.1
Accept: application/vnd.dwolla.v1.hal+json

Following that link and using the given type (with the form profile) as the Accept header returns the form that defines how and what can be updated for the customer. It describes where to post the form, how to build the request body, and what Content-Type header should be included.

GET /customers/1bdcf411-4a81-4534-993b-9ba183a3b3dc HTTP/1.1
Accept: application/vnd.dwolla.v1.hal+json; profile="https://github.com/dwolla/hal-forms"

This response then gets translated into a form for editing customers in Dashboard & Admin!

dwolla-dashboard-and-admin

If the customer gets put into the “document” or “retry” state while being verified, the form may change with just the fields that are needed to get the customer to a good state (e.g. address, DOB, SSN, etc.).

The dynamic nature of the forms also works for creating customers. If you make a request to “/customers” with the form profile, you’ll get a response that includes multiple forms you can choose from based on the type of customer you’re trying to create.

The benefits of this approach are numerous as developers won’t need to spend time interpreting Dwolla’s business rules and how to apply them based on the state of a given resource in order to generate a user interface. Simple validations, accepted values and input labels are all provided out of the box.

Currently forms are only returned for creating & editing customers, but we’re looking forward to expanding them across our existing and future endpoints.

Learn more about Dwolla’s ACH API here or view our developer documentation.

If you have questions about this concept or incorporating Dwolla HAL forms, join the discussion.

Get started with an ACH integration

We'll help you design your ideal payments experience.

Loading...

Thank you

A Dwolla representative will reach out to you within one business day.

Sorry

There was an error and your the form was not submitted.

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.