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 example screenshots from a customers perspective, the API calls that should run in association with those screens, as well as explanations of what those 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 statuses, actions 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.

Example Response Object

{
  "apiVersion": "3.0.1",
  "context": "testing",
  "id": "1",
  "data": {
    "kind": "type#switch#status",
    "lang": "en-US",
    "currentItemCount": 9,
    "items": [
      {
        "id": "ready",
        "label": "Ready",
        "help": "The switch is ready to submit for processing."
      },
      {
        "id": "incomplete",
        "label": "Incomplete",
        "help": "The switch is missing information required for processing."
      },
      {
        "id": "canceled",
        "label": "Canceled",
        "help": "The switch has been canceled."
      },
      {
        "id": "submitted",
        "label": "Submitted",
        "help": "The switch has been submitted for processing."
      },
      {
        "id": "printed",
        "label": "Printed",
        "help": "The switch has been printed for signature and/or in-person delivery."
      },
      {
        "id": "processing",
        "label": "In Process",
        "help": "The switch is currently being processed by our fulfillment team."
      },
      {
        "id": "sent",
        "label": "Sent",
        "help": "The switch has been sent to the company or govt. agency for action."
      },
      {
        "id": "complete",
        "label": "Complete",
        "help": "The company or govt. agency has acknowledged that the change has been completed."
      },
      {
        "id": "unabletoprocess",
        "label": "Unable To Process",
        "help": "The switch is unable to be processed."
      }
    ]
  }
}

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.

Example Response Object

{
  "apiVersion": "3.0.1",
  "context": "testing",
  "id": "1",
  "data": {
    "kind": "type#switch#action",
    "lang": "en-US",
    "currentItemCount": 8,
    "items": [
      {
        "id": "save",
        "label": "Save",
        "help": "Saves a switch."
      },
      {
        "id": "submit",
        "label": "Submit",
        "help": "Submit the switch for processing."
      },
      {
        "id": "cancel",
        "label": "Cancel",
        "help": "Cancel the switch"
      },
      {
        "id": "complete",
        "label": "Complete",
        "help": "You've taken the steps to make this change online or in person so mark it complete."
      },
      {
        "id": "print",
        "label": "Print",
        "help": "Print the switch to sign or deliver in person."
      },
      {
        "id": "uncancel",
        "label": "Un-Cancel",
        "help": "Returns a canceled switch back to a state where it can be edited."
      },
      {
        "id": "delete",
        "label": "Delete",
        "help": "Deletes a switch that has been canceled."
      },
      {
        "id": "reject",
        "label": "Reject",
        "help": "Reject the switch."
      }
    ]
  }
}

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.

Example Response Object

{
  "apiVersion": "3.0.1",
  "context": "testing",
  "id": "1",
  "data": {
    "kind": "type#target",
    "lang": "en-US",
    "currentItemCount": 3,
    "items": [
      {
        "id": "deposit",
        "label": "Direct Deposit",
        "plural": "Direct Deposits",
        "recipient": "Depositor",
        "help": "Instructions to a company/govt. agency to change future direct deposits to your account."
      },
      {
        "id": "payment",
        "label": "Automatic Payment",
        "plural": "Automatic Payments",
        "recipient": "Payee",
        "help": "Instructions to a company/govt. agency to change future automatic payments from your account."
      }
    ]
  }
}

Now that you have a list of valid statuses, actions and target types you are ready to start creating switches for your customers!