Requests

Build Switch REST API requests with the correct base URL, authentication, HTTP method, parameters, pagination, and response-shaping options.

Before you call resource APIs, configure Authentication, then use this page to format URLs, parameters, request bodies, pagination, search, sorting, and response field sets. If you are choosing where to start, see Getting Started.

Request URLs

Send Switch API requests to this base URL:

https://api.genability.com

Use this URL pattern for versioned Switch endpoints:

https://api.genability.com/rest/v1/{some resource path}

For example, these URLs retrieve all accounts, one account by Arcadia accountId, and one account by your providerAccountId:

https://api.genability.com/rest/v1/accounts
https://api.genability.com/rest/v1/accounts/genability-account-id-here
https://api.genability.com/rest/v1/accounts/pid/your-own-unique-id-here

Each resource type has a reference page that lists the URL pattern for that resource. For example, see Account Tariffs API.

Authentication

Each request must include credentials that identify your application. Switch uses HTTP Basic Authentication with your appId as the username and your appKey as the password. For details, see Authentication.

Data types

In addition to standard string and number inputs, Switch APIs use arrays and JSON payloads for some requests.

Array inputs

Some fields accept multiple values. Specify these values as a string array. For example, Tariff API parameters such as customerClasses and tariffTypes can accept multiple values.

You can pass arrays as comma-separated values or as repeated query parameters. These examples request only "DEFAULT" and "ALTERNATIVE" tariffs:

tariffTypes=DEFAULT,ALTERNATIVE
tariffTypes=DEFAULT&tariffTypes=ALTERNATIVE

JSON payloads

Switch API responses use JSON (JavaScript Object Notation). JSON is the only response format supported by the public REST APIs. JSON is a lightweight serialization format that works with most programming languages and integration technologies.

Use JSON request bodies when making HTTP POST and PUT calls that require a payload.

Switch does not currently support compression of REST request payloads. You can enable gzip compression for API responses; see Compressing Requests.

For more details on response formats, see Responses.

HTTP methods

Most API calls use HTTP GET because they retrieve one or more resources. Operations that create, update, or delete resources use other HTTP methods:

Some JavaScript libraries and other technologies do not have an easy way to submit PUT or DELETE requests, so Switch supports a POST overload. Include a method parameter with a value of PUT to update a resource or DELETE to remove one.

POST and PUT body

When submitting a POST or PUT request, include a request body when the endpoint requires one. You may need to specify these headers:

Pagination

Use pageStart and pageCount to control how many results a list request returns. Most endpoints that return one or more resources support pagination.

For example, fetch the first 100 results by setting pageStart to 0 and pageCount to 100. To fetch the second 100 results, set pageStart to 100 and pageCount to 100.

Use the count property in the response to see how many results matched your query. The count property is limited to a maximum of 100,000, so interpret 100000 as "100,000 or more." See Response payload for an example response.

Searching and sorting

Use search and sort parameters to filter text across one or more fields and order the returned results. All parameters in this table are optional:

Getting minimum, standard, and extended views

In object data definitions, the "Fields" column can be blank, contain E, or contain M. These values indicate whether a property is part of the standard field set, the extended field set, or the minimum field set.

Most requests accept a fields parameter that controls which fields are returned. Pass min to return a smaller subset of fields, or pass ext to return all available fields. If you omit fields, the API returns the standard view.

Use the minimum view for smaller payloads, such as drop-down lists or autocomplete inputs. Use the standard view for search results and common calculations. Use the extended view when you need less common fields.

Using SSL

Call all API methods over SSL. You must use SSL when working with non-public data such as customer accounts and usage profiles. Most REST-capable client languages and technologies support SSL.

Compressing responses

Switch supports gzip HTTP compression for API responses. Enable this feature in your client to reduce network traffic. The official Java client library supports gzip response compression out of the box.

HTTP response compression

To enable HTTP response compression, add this header to your requests:

Accept-Encoding: gzip

Next steps

1. Review Responses to handle standard response payloads and errors.
2. Review Dates & Times before sending date ranges or time-zone-aware values.
3. Use Testing & Debugging Overview to validate credentials, input formats, and error handling before calling resource APIs.