API-Overview

The ClickSWITCH API Overview

Overview

Welcome! In this document, we will provide a high-level overview of what you can expect from this guide. We will go over what you need to get started, what you should expect to see in this guide, as well as the general flow of the ClickSWITCH process.

At the heart of the ClickSWITCH API is one main objective: Identifying targets (banks, employers, etc.) and helping customers “switch” the account information used to either deposit or withdraw money to/from these targets.

The Flow

Performing a switch is different based on who the target is, what the type of switch it is, and many other factors. However, the ClickSWITCH API strives to make this process as simple and streamlined as possible.

In order to begin the process, you’ll need to set up the customer in the ClickSWITCH API. Once the customer is set up you will ask the customer to identify the ‘target’ they want to switch to their new account (employer, social security or annuity payment, utility bill payments, etc).

Once you have this information and provide it to the ClickSWITCH API, we will then send you back a question or series of questions to ask the user based on what you’ve sent us. Because the process is different for each target and type, the data needed to successfully perform a switch will differ. The ClickSWITCH API becomes conversational at this point. We will send you what we need from the user, you will send it back, and then we will ask additional questions and expect additional responses until we have all the data we need. At this point, we will let you know we have all the information we need and allow you to review that information is correct and confirm you want to perform that switch with the information provided.

Real-World Example

In this guide, we will run through a real-world example of how the ClickSWITCH API might be used in a customer app to perform a direct deposit switch. We will break this process down into six steps:

  1. Setup
  2. Create a customer
  3. Select a type
  4. Select a target
  5. Create a switch
  6. Finalize the switch

Getting Started

Before getting started you will need to obtain a ClickSWITCH API key. You can do this by contacting ClickSWITCH directly and requesting a key. This API key should be sent in the header of each request with a key of api-key. If you do not pass up this API key in the header of each request, you will receive a 400 error from the server.

Additional Resources

Along with our real-world guide, detailed documentation for each of our API endpoints is available in our SwaggerHub so that you can take a more in-depth look at what is available through the ClickSWITCH API. Click on the “SwaggerHub” link in the sidebar on the left-hand side of your screen to see more.

Next Steps

Now that you have an API key you’re ready to start creating customers and switches! Click on the link below or the “Setup” link in the sidebar in order to start learning how this process might look in a real-world scenario.


Setup

At the heart of ClickSWITCH is the ability to create switches for customers. Here we will go over how a typical customer flow might go for creating a switch. This will include API calls as well as explanations of what the API calls should accomplish.

In order to make sure the process goes smoothly, however, we need to first make some API calls to set ourselves up for success. ClickSWITCH will be sending you lots of data via the API and will also expect you to send it some very specific data. This data includes statusesactions and targets.

Get Statuses

First you will want to get a list of statuses for switches. This will help you display to your users what status the switch is currently in correctly. Because ClickSWITCH changes statuses and their labels as needed, it’s a good idea to hit this API when beginning the process to ensure you’re showing your users the proper status labels for their switches.

In order to do this, just hit the following endpoint with a GET request and a list of statuses will come back similar to the “Example Response Object” below:

METHOD ENDPOINT
GET /types/statuses

Parameter Reference

This resource does not require any parameters.

Get Actions

Now that we know what statuses are possible for switches and how to display them to our users, let’s get a list of possible actions. Actions can be performed on switches, but only the actions returned in this API call are valid. Because the actions which can be performed also change at times, it is best practice to get the list of actions from this endpoint rather than hard coding them in your application.

Here is an example of how you would get this information from the ClickSWITCH API:

METHOD ENDPOINT
GET /types/actions

Parameter Reference

This resource does not require any parameters.

Get Targets

Now that you have all the supported statuses and actions for switches, let’s get a list of target types. Target types are the kinds of switches available to customers, such as “deposit” or “payment” switches.

Here is how you would get the list of available targets from the API:

METHOD ENDPOINT
GET /types/targets

Parameter Reference

This resource does not require any parameters.

Now that you have a list of valid statusesactions and target types you are ready to create your customer!

Create a Customer

Let’s consider the following example. You have a customer in your app and you want to begin the process of creating a switch for that customer. You may show them a screen like the one below where the customer has chosen to begin the switch process.

At this point, you need to make sure this customer exists in the ClickSWITCH API. In order to do this, you need to send a PUT request to the customers endpoint and either update the existing customer or create the customer record if one does not already exist. Below is an outline of the customers endpoint and what data it expects.

API Endpoint

When you take the customer to this page you need to either create the customer or update the customer by hitting the following API resource:

METHOD ENDPOINT
PUT /customers/{customerKey}

Parameter Reference

PARAMETER DESCRIPTION
customerKey
string
A unique identifier for the customer. Can be any string between 1 and 64 characters. It is case sensitive.
email
string
The email for the customer you are creating or updating.
phoneNumber
string
The phone number for the customer you are creating or updating.
accountHolders
array
An array of account holder objects containing the following properties:

  • firstName (string): The account holders first name.
  • middleInitial (string): The account holders middle initial.
  • lastName (string): The account holders last name.
accounts
array
An array of account objects containing the following properties:

  • number (string): The account number for the given account.
  • routingNumber (string): The routing number for the given account.
  • type (string): The type of account (e.g. checking).
  • name (string): A name used to identify the account (e.g. Personal Checking).
addresses
array
An array of address objects containing the following properties:

  • line1 (string): The first line of the street address.
  • line2 (string): The second line of the street address.
  • line3 (string): The third line of the street address.
  • city (string): The name of the city.
  • zip (string): The zip code of the city.
  • state (string): The two digit state code.
  • country (string): The two digit country code.
metadata
object
An object containing any metadata you would like to add to the customer.
context
string
The context value to be returned in the response. This is supplied initially by your app and is returned from the API in the response so that responses can be correlated with requests in JSON-P and batch situations. (This is not required)
*Required field

Once you have created/updated the customer, you will be ready to go onto the next step which is helping the customer select the type.

Select a Type

Check for Pending Switches

Before we get started selecting the type of switch we need to first check the switches that have already been submitted or may be incomplete for the customer we just set up or updated in the previous step.

In order to do this we need to hit the following API resource:

API Endpoint: Switches

METHOD ENDPOINT
GET /customers/{customerKey}/switches

Selecting a Type

Now the user needs to determine if they are trying to perform a deposit switch or a payment switch. In the screenshot below, the “Get Started!” button at the bottom would indicate they want to proceed with a deposit switch. The reason the UI is weighted this way is because most institutions will want to help users bring more money into their new account first. However, if the users clicks on “Switch Payments” then you would start down the path for payments.

Selecting Additional Account Holders (Optional)

The only instance where you should need this is if your app does not have any context around the account holder(s) you are performing switches for. In this case you could get account holder data from the ClickSWITCH endpoint below:

METHOD ENDPOINT
GET /customers/{customerKey}

Parameter Reference

PARAMETER DESCRIPTION
customerKey*
string
A unique identifier for the customer. Can be any string between 1 and 64 characters. It is case sensitive.
context
string
The context value to be returned in the response. This is supplied initially by your app and is returned from the API in the response so that responses can be correlated with requests in JSON-P and batch situations. (This is not required)
*Required field

Now that you’ve selected the type of switch and determined which account holder the switch is for you can move on to the next step: selecting a target.

Select a Target

The goal of this step is to determine the target for the switch. There are 3 different types of targets. All of them require you to hit the same endpoint to generate a switch for, but you will send different data based on the type. Below are the types and a brief explanation of them:

TYPE DESCRIPTION
Known Target A known target is a target which ClickSWITCH already knows about (it exists in our system). This means that when you search against the “targets” API endpoint below the target the users chooses is in that list of targets verified by ClickSWITCH.
Location Target A location target is a target which was not returned from the targets API endpoint, but was returned from the “locations” API endpoint search. It is not a target that is verified by ClickSWITCH, but it is a target ClickSWITCH at least has some data on.
Unknown Target An unknown target is just as it sounds. This is a target which cannot be found in either the targets API endpoint or the locations API endpoints. It is a target that ClickSWITCH is not familiar with.

Based on which of the above 3 target types you end up with after you go through the searching steps below, you will send different data to the switches endpoint when creating a switch. Please refer to the table below to see which property you will send to the switches endpoint depending on the target type:

TYPE PROPERTY
Known Target targetId – The ID returned by the ClickSWITCH API for the given target
Location Target locationId – The ID returned by the ClickSWITCH API for the given location
Unknown Target accountHolderIndex – This actually gets sent regardless of the type of target, but is also sent for unknown targets

Searching for a Target

You will now want to present the user with a screen similar to the one below. This screen allows the user to search for their target.

In order to perform a search based on what the user types into the search box you will want to hit the API resource below with the parameters outlined:

API Endpoint: Targets

METHOD ENDPOINT
GET /targets?type={TYPE}&name={SEARCH_TERM}

Parameter Reference

PARAMETER DESCRIPTION
customer*
string
A valid customerKey for the customer you are searching for.
type*
string
The type of target you are searching for (e.g. deposit, payment).
name*
string
A partial name of the company or government agency. (This would be the text the user entered into the search box in the screenshot above)
category
integer
A valid category key to filter results by.
context
string
The context value to be returned in the response. This is supplied initially by your app and is returned from the API in the response so that responses can be correlated with requests in JSON-P and batch situations. (This is not required)
*Required field

If results were found and the customer selects their target then you can skip ahead to the Create a Switch section.

Location Search for New Target

In the event that no results are returned or the user doesn’t find the target from the list you gave them, you can hit the following API resource to get a more comprehensive list of targets. Think of this endpoint like you would searching for a target on Google. We may know the target and a few details about them, but we may not know exactly how that target wants the switch to be performed as they aren’t in our system. You will still be able to create a switch request, but it will kick off a manual process internally at ClickSWITCH in order to try and discover how to perform the switch.

API Endpoint: Locations

METHOD ENDPOINT
GET /locations?name={SEARCH_TERM}

Parameter Reference

PARAMETER DESCRIPTION
customer*
string
A valid customerKey for the customer you are searching for.
name*
string
A partial name of the company or government agency. (This would be the text the user entered into the search box in the screenshot above)
context
string
The context value to be returned in the response. This is supplied initially by your app and is returned from the API in the response so that responses can be correlated with requests in JSON-P and batch situations. (This is not required)
*Required field

Once you have displayed this new list of options to the customer and they make a selection you’re ready for the next step: creating the switch!

Create a Switch

We now have all the data we need to create the switch request. We can now POST that data to the API resources for switches:

API Endpoint: Switches (Post)

METHOD ENDPOINT
POST /customers/{customerKey}/switches

Parameter Reference

PARAMETER DESCRIPTION
type
string
The type of switch you want to perform (e.g. deposit, payment).
accountHolderIndex
string
Index of which account holder this is for.
targetId
string
The ID of the target the customer chose.
locationId
string
The ID of the location the customer chose. (if no target was chosen)
values
object
An object containing information about the switch such as accounts and fields.

Once you have sent a POST request to the above endpoint with the switch information you should get a response letting you know the status of the switch, as well as what else you need to obtain from the user.

Submit Additional Information

Using the response from the section above you can build out a form to obtain the reamining information needed from the user in order to perform the switch. The response will tell you what fields you should show the user, what type of field it should be, and the data type supported. You may end up generating a form that looks similar to the one below:

Once the user fills out this form you will need to send a PUT request to the following API resource:

API Endpoint: Switches (Put)

METHOD ENDPOINT
PUT /customers/{customerKey}/switches/{switchIndex}

Parameter Reference

PARAMETER DESCRIPTION
context
string
The context value to be returned in the response. This is supplied initially by your app and is returned from the API in the response so that responses can be correlated with requests in JSON-P and batch situations. (This is not required)
type
string
The type of switch you want to perform (e.g. deposit, payment).
accountHolderIndex
string
Index of which account holder this is for.
targetId*
string
The ID of the target the customer chose.
values
object
An object containing information about the switch such as accounts and fields.

The response from the API will differ depending on the switch type. You will either receive a response with additional information you need to obtain, or you will receive a response with a status of Ready. Repeat this step until you recieve a Ready status from the API, or the customer decides to perform one of the actions returned in the state portion of the above API call. Please see the next section for details on submitting actions.

Submitting Actions

As you can see in the above example response, the API returned the 3 actions: HTTP-PUTCancel and Submit. What this means is at this point in the process the user can “Save” the switch they’ve partially completed (HTTP-PUT), “Cancel” the incomplete switch (Cancel) or Submit the switch. At any point in the above workflow you can send any of these actions based on what the user would like to do. Just send the action to the endpoint below and ClickSWITCH will handle the rest:

API Endpoint: Switches Action

METHOD ENDPOINT
PUT /customers/{customerKey}/switches/{switchIndex}/action

Parameter Reference

PARAMETER DESCRIPTION
context
string
The context value to be returned in the response. This is supplied initially by your app and is returned from the API in the response so that responses can be correlated with requests in JSON-P and batch situations. (This is not required)

Once you have received the Ready status you can move to the final step: Finalizing the Switch.

Finalize the Switch

The final step is to confirm the switch by calling the action endpoint for a given switch and sending the “Submit” action. You will likely want to show the customer a screen such as the one below so they can confirm everything looks correct.

Submitting the Action

When the customer taps on submit then you should hit the following API resource and pass the “Submit” action which was returned in the list of actions from the API response when creating/updating the switch in the last step:

API Endpoint: Switches Action

METHOD ENDPOINT
PUT /customers/{customerKey}/switches/{switchIndex}/action

Parameter Reference

PARAMETER DESCRIPTION
context
string
The context value to be returned in the response. This is supplied initially by your app and is returned from the API in the response so that responses can be correlated with requests in JSON-P and batch situations. (This is not required)
index
integer
The switchIndex for the given switch.
action
string
The action you want to perform. (e.g. Submit)

Congratulations! You’ve just helped a customer successfully submit a switch request. You should now see a response from the API outlining the details of the switch you just created and it’s current status.

Edit a Switch

There may be a time when your user doesn’t have all the information they need at the time they are first performing a switch, or perhaps they run out of time in the middle. At any point in the process, you can save a partially completed switch to be completed later. In this document, we will cover just how to do this.

First, you will need to get a list of switches and present it to the user so that they can pick which switch they would like to edit. Here is the API call which will return this information:

API Endpoint: Switches

METHOD ENDPOINT
GET /customers/{customerKey}/switches

Now that you have a list of switches to present to the customer, you may want to show them a screen like the one below:

If your user sees a switch in the list above which they want to continue to work on or edit, then you will need to make the following API call in order to get the details of that switch and continue to gather information for that switch:

METHOD ENDPOINT
GET /customers/{customerKey}/switches/{switchIndex}

Parameter Reference

PARAMETER DESCRIPTION
context
string
The context value to be returned in the response. This is supplied initially by your app and is returned from the API in the response so that responses can be correlated with requests in JSON-P and batch situations. (This is not required)
customerKey
string
A valid customerKey for the customer you are searching for.
switchIndex
string
The index of the switch (unique within a customer).

Now you need to continue to continue gathering and submitting information for the switch. What you do now will depend on where the customer left off. Based on the data that comes back from the call above you will know where to continue from. It will be one of the steps in the “Creating a Switch” guide in this documentation. Please refer to the “Creating a Switch” guide for more information on how to tell which step you should take the user to and what UI to present them with.


Swaggerhub API Documentation

Interested in taking a deeper dive into the full API documentation? You can check out our SwaggerHub for the full public PartnerAPI.