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 unkown 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 returend 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 unkown 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.

Create Customer

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
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)
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.

Example Response Object

{
  "apiVersion": "3.0.1",
  "context": "testing",
  "id": "1",
  "data": {
    "kind": "target",
    "currentItemCount": 2,
    "items": [
      {
        "targetId": 678313,
        "name": "Acme Inc.",
        "type": "deposit"
      },
      {
        "targetId": 678313,
        "name": "Acme Pensions",
        "type": "deposit"
      }
    ]
  }
}

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.

Create Customer

API Endpoint: Locations

METHOD ENDPOINT
GET /locations?name={SEARCH_TERM}

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)
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)

Example Response Object

{
  "apiVersion": "3.0.1",
  "context": "testing",
  "id": "1",
  "data": {
    "kind": "location",
    "currentItemCount": 2,
    "items": [
      {
        "locationId": "ChIJpRgrYs9OVEARZ90yrEnehfE",
        "name": "Acme Car Wash",
        "address": "129 Main St., Metropolis, DE 37484"
      },
      {
        "locationId": "ChIJO716Q4Uys1IRAxSiNinOHJ4",
        "name": "Acme Drive Thru",
        "address": "400 S. Main St., Metropolis, DE 37486"
      }
    ]
  }
}

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!