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.

Example Response Object

{
  "apiVersion": "3.0.1",
  "context": "testing",
  "id": 1290,
  "data": {
    "kind": "switch",
    "item": {
      "index": 1,
      "type": "deposit",
      "targetId": 678313,
      "name": "Acme Inc.",
      "accountholderIndex": 0,
      "values": {
        "accounts": [
          {
            "index": 0
          }
        ],
        "fields": {}
      },
      "ux": {
        "accounts": {
          "limit": 1,
          "maxChecking": 1,
          "maxSavings": 1,
          "choices": [
            {
              "index": "0",
              "label": "Checking *3904"
            },
            {
              "index": "1",
              "label": "Savings *3289"
            }
          ],
          "fields": []
        },
        "fields": [
          {
            "key": "Custom_Net or Amount (in dollars)",
            "label": "Net or Amount (in dollars)",
            "type": "textbox",
            "required": false
          },
          {
            "key": "Custom_or Percentage of Pay (1 - 100)",
            "label": "Percentage of Pay (1 - 100)",
            "type": "textbox",
            "required": false
          },
          {
            "key": "Custom_Depositor's Full Mailing Address",
            "label": "Depositor's Full Mailing Address",
            "type": "textbox",
            "required": true
          },
          {
            "key": "Custom_Employee ID",
            "label": "Employee ID",
            "type": "textbox",
            "required": false
          },
          {
            "key": "Custom_Last 4 of SSN",
            "label": "Last 4 of SSN",
            "type": "textbox",
            "required": true
          }
        ]
      },
      "metadata": {
        "employee_id": "jsmith",
        "branch": "21"
      },
      "state": {
        "status": "Incomplete",
        "validation": {
          "accounts": [],
          "fields": [
            "Custom_Last 4 of SSN is required",
            "Custom_Depositor's Full Mailing Address is required"
          ],
          "overall": []
        },
        "actions": [
          "HTTP-PUT",
          "Cancel"
        ]
      }
    }
  }
}

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:

Create Customer

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.

Example Response Object

{
  "apiVersion": "3.0.1",
  "context": "testing",
  "id": 1290,
  "data": {
    "kind": "switch",
    "item": {
      "index": 1,
      "type": "deposit",
      "targetId": 678313,
      "name": "Acme Inc.",
      "accountholderIndex": 0,
      "values": {
        "accounts": [
          {
            "index": 0
          }
        ],
        "fields": {
          "Custom_Net or Amount (in dollars)": "500",
          "Custom_or Percentage of Pay (1 - 100)": "50",
          "Custom_Depositor's Full Mailing Address": "123 Main Street",
          "Custom_Employee ID": "123",
          "Custom_Last 4 of SSN": "1234"
        }
      },
      "ux": {
        "accounts": {
          "limit": 1,
          "maxChecking": 1,
          "maxSavings": 1,
          "choices": [
            {
              "index": "0",
              "label": "Checking *3904"
            },
            {
              "index": "1",
              "label": "Savings *3289"
            }
          ],
          "fields": []
        },
        "fields": [
          {
            "key": "Custom_Net or Amount (in dollars)",
            "label": "Net or Amount (in dollars)",
            "type": "textbox",
            "required": false
          },
          {
            "key": "Custom_or Percentage of Pay (1 - 100)",
            "label": "Percentage of Pay (1 - 100)",
            "type": "textbox",
            "required": false
          },
          {
            "key": "Custom_Depositor's Full Mailing Address",
            "label": "Depositor's Full Mailing Address",
            "type": "textbox",
            "required": true
          },
          {
            "key": "Custom_Employee ID",
            "label": "Employee ID",
            "type": "textbox",
            "required": false
          },
          {
            "key": "Custom_Last 4 of SSN",
            "label": "Last 4 of SSN",
            "type": "textbox",
            "required": true
          }
        ]
      },
      "metadata": {
        "employee_id": "jsmith",
        "branch": "21"
      },
      "state": {
        "status": "Ready",
        "validation": {
          "accounts": [],
          "fields": {},
          "overall": []
        },
        "actions": [
          "HTTP-PUT",
          "Cancel",
          "Submit"
        ]
      }
    }
  }
}

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-PUT, Cancel 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)
index
integer
The switchIndex for the given switch.
action
string
The action you want to perform. (e.g. Submit)

Example Response Object

{
  "apiVersion": "3.0.1",
  "context": "testing",
  "id": 1290,
  "data": {
    "kind": "switch",
    "item": {
      "index": 1,
      "type": "deposit",
      "targetId": 678313,
      "name": "Acme Inc.",
      "accountholderIndex": 0,
      "values": {
        "accounts": [
          {
            "index": 0
          }
        ],
        "fields": {}
      },
      "ux": {
        "accounts": {
          "limit": 1,
          "maxChecking": 1,
          "maxSavings": 1,
          "choices": [
            {
              "index": "0",
              "label": "Checking *3904"
            },
            {
              "index": "1",
              "label": "Savings *3289"
            }
          ],
          "fields": []
        },
        "fields": [
          {
            "key": "Custom_Net or Amount (in dollars)",
            "label": "Net or Amount (in dollars)",
            "type": "textbox",
            "required": false
          },
          {
            "key": "Custom_or Percentage of Pay (1 - 100)",
            "label": "Percentage of Pay (1 - 100)",
            "type": "textbox",
            "required": false
          },
          {
            "key": "Custom_Depositor's Full Mailing Address",
            "label": "Depositor's Full Mailing Address",
            "type": "textbox",
            "required": true
          },
          {
            "key": "Custom_Employee ID",
            "label": "Employee ID",
            "type": "textbox",
            "required": false
          },
          {
            "key": "Custom_Last 4 of SSN",
            "label": "Last 4 of SSN",
            "type": "textbox",
            "required": true
          }
        ]
      },
      "metadata": {
        "employee_id": "jsmith",
        "branch": "21"
      },
      "state": {
        "status": "Incomplete",
        "validation": {
          "accounts": [],
          "fields": [
            "Custom_Last 4 of SSN is required",
            "Custom_Depositor's Full Mailing Address is required"
          ],
          "overall": []
        },
        "actions": [
          "HTTP-PUT",
          "Cancel"
        ]
      }
    }
  }
}

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