Getting Started with the Gotransverse API

The Gotransverse API is a RESTful API that uses JSON formatting for payloads and responses.

The API consists of a collection of microservices that are maintained and versioned separately for ease of development. The vast majority of core Gotransverse operations are available in the Billing microservice. Billing is a great place to get started with understanding the Gotransverse API.

Other specialized microservices include Usage Processing Pipeline and Usage Processing Pipeline Webhook for handling usage processing. You can use the Tax Essentials microservice to set up taxation requirements and the Stored Value Service microservice to manage a stored value service with prepaid registers.

To get started with the Gotransverse API, we recommend using a tool like Postman to test out example requests. Postman is a HTTP client that allows users to test Web services.

Authentication and the Header

The following are the most common header values:

X-API-Key [a secret API key generated through the UI 1.0 User Management page]
Content-Type application/json

Gotransverse microservices use an x-api-key in the request header for authentication. If using a tool like Postman, set the Authorization Type to No Auth, as the header provides authorization.

In UI 1.0, you can generate API keys for the necessary GTV API 2.0 sets that include Billing, Dunning, Revenue Management, Configure Price Quote, Currex, Job Scheduler, Stored Value Service, Tax Essentials, and Usage Processing.

Content type in the header is almost always application/json. One exception is the Download invoice or usage request, where content type is application/pdf for an invoice and text/csv for a usage file.

Endpoints and Requests

An endpoint is a URI that specifies where a resource is available for your application to interact with Gotransverse microservices. You combine an endpoint with a method to create a request.

Request Syntax

Format a basic request with the following syntax:
syntax for HTTP request

1 The HTTP method
2 Environment, either sandbox or production
3 Specific microservice
4 Microservice version number
5 Endpoint

Request Body

The body of a request is formatted in JSON. For GET requests, the body is empty. For other methods, the body contains one or more objects or entities. Objects or entities represent resources in Gotransverse.

The following body example contains the CreateBillingAccount object to create a billing account.


{
  "external_account_num": "902322329",
  "start_date": "2018-01-01T06:00:00.000Z",
  "responsible_party": {
    "party_type": "organization",
    "organization_name": "yahoo",
    "addresses": [{
      "address_type": "email",
      "purpose": "PRIMARY",
      "email": "example@gotransverse.com"
      }, {
      "address_type": "postal",
      "purpose": "BILLING",
      "country": "USA",
      "city": "AUSTIN",
      "region_or_state": "TX",
      "postal_code": "78701",
      "line1": "620 CONGRESS AVE SUITE 200"
      }]
    },
  "bill_cycle": {
    "id": "80",
    "bill_cycle_type": "daily"
    },
  "bill_type": "EMAIL",
  "billing_account_category": {
    "id": "52"
  }
}
		

HTTP Methods

Gotransverse microservices use the following HTTP methods:

  • GET - Queries objects, collections of objects, or specific parameters within objects
  • POST - Creates new instances of objects or performs actions like status changes on objects
  • PUT - Updates existing instances of objects
  • DELETE - Removes objects

Query Parameters

Query parameters filter query results from a GET request. They are also known as query keys, and they are often used in Gotransverse to retrieve information that can then be used in a request. Query keys are specific to requests within each endpoint, and they are listed in API reference documentation with the label query.

query

To filter query results, add one or more query parameters at the end of the request URI after a question mark (?). Query parameters and their values are name-value pairs, which are separated with an equals sign (=). Each name-value pair is separated by an ampersand (&).

Filtering

Filtering provides options to customize the data in the response based on the selected criteria. You can filter the data displayed in API responses using Gotransverse API Query Language. The syntax of the API query language is similar to SQL. The criteria are expressed in the form of predicates in the following format:
“<query parameter> <comparison operator> ‘<constant>’”

1The name of the available query parameter. For example, billing_account_id or bill_cycle_type.
2The comparison operator such as EQ (equals) or GT (greater than).
3The constant value in single quotes ('sample'). Parentheses are used to group predicates in complex clauses. For example: (start_date GT '2021-01-24T23:33:07+00:00').

To create the desired query, combine query parameters available for the endpoint with the comparison and logical operators.

Comparison operators are used to filter the response data by evaluating it against the specified filter criteria. For example, you can obtain only billing accounts with USD set as the default currency by using the currency_code query parameter followed by the EQ (equals) comparison operator and the ‘USD’ filter value: GET /billing-accounts?filter=currency_code EQ 'USD'. See Use Cases for more examples.

Gotransverse API Query Language supports the following comparison operators:

  • NEQ—Not Equal.
  • EQ—Equals.
  • LT—Less Than.
  • LTE—Less Than or Equal.
  • GT—Greater Than.
  • GTE—Greater Than or Equal.
  • IS NULL—Is set to NULL.
  • IS NOT NULL—Is not set to NULL.
  • LIKE—Matches the pattern specified by the following wildcard characters:
    • %—Any number of characters, including no characters.
    • _—Exactly one character.

Note: The LIKE operator only applies to parameters of the string type.

Logical operators like OR are used to connect two or more filter expressions in order to customize the response data based on multiple conditions. For example, with logical operators, you can select either Suspended or Active bill cycles in one request: GET /bill-cycles?filter=(status EQ 'SUSPENDED') OR (status EQ 'ACTIVE'). See Use Cases for more examples.

Gotransverse API Query Language supports the following logical operators:

  • AND—Conjunction
  • OR—Disjunction
  • NOT—Negation

Use Cases

  1. The following API request filters bill cycles against the following criteria:
    • Bill cycle type must be Monthly.
    • Bill cycle name must start with ‘Bill’ OR the bill cycle ID must be less than 9809.
    • GET /bill-cycles?filter=bill_cycle_type EQ 'monthly' AND (name LIKE 'Bill %' OR id LT '9809')
  2. The following API request filters billing accounts against the following criteria:
    • Billing account number must be greater than 7.
    • Billing Account currency must be USD.
    • Billing account status must be Active.
    • Associated bill cycle ID must be less than 555 OR the bill type must not be None.
    • GET /billing-accounts?filter=account_num GT '7' AND currency_code EQ 'USD' AND status EQ 'ACTIVE' AND
      (bill_cycle_id LT '555' OR bill_type NEQ 'NONE')

Sorting

Sorting enables data to be sorted in ascending or descending order for the specified query parameters. By default, query results are sorted in the ascending order for the ID property.

Ascending order means the smallest numbers or values first in the order display first. These are the examples of how different types of values are sorted in the ascending order:

  • Numbers or amounts are sorted from the smallest to largest.
  • Letters or words are sorted alphabetically from A to Z.
  • Dates are sorted from oldest (earliest) to most recent.
  • For data with numbers and letters such as address lines, numbers (from smallest to largest) are sorted first, then followed by A-Z.

Descending order means the largest numbers or values last in the order display first. These are the examples of how different types of values are sorted in the ascending order:

  • Numbers or amounts are sorted from largest to smallest.
  • Letters or words are sorted alphabetically from Z to A.
  • Dates are sorted from most recent to oldest (earliest).
  • For data with numbers and letters such as address lines, Z to A is sorted first, then followed by numbers (largest to smallest).

To sort the response data:

  • In the ascending order, no prefix is required. For example, id sorts results in ascending order by the ID query parameter: GET /billing-accounts?sort=id. Billing accounts with smaller ID values display first.
  • In the descending order, insert “-” in front of the query parameter name. For example,
    -category_name
    value sorts the results in the descending order by the category_name query parameter: GET /billing-account-categories?sort=-category_name. Billing account categories display in the reverse alphabetical order.

Note: The supported query parameters are indicated with (sortable) in descriptions.

Request Syntax

Format a request with query parameters in the following way:

1Endpoint
2Query parameter name
3Query parameter value

In the response, you receive the data filtered according to the query parameters that you specified. In the above example, you receive data for all billing accounts with active status and the billing type set to email.

Path Parameters

Path parameters limit a request to one individual resource. They help you to retrieve, update, or delete information about a specific entity. A path parameter is a variable part of the URI, in curly braces ({…}). In the Gotransverse JSON REST API, path parameters usually denote various types of ID. They are listed in API reference documentation with the label path.

To use a path parameter, replace the path parameter’s name and curly braces with the necessary value. For example, to get the data about a certain billing account using the endpoint /billing-accounts/{id}, format a request with a path parameter in the following way:
GET https://example-tract-api.com/billing/2/billing-accounts/1234567

Note: If using a tool like Postman to test out API requests, you can set path parameters as variables.