In this topic:

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 provided by goTransverse]
Content-Type application/json

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

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

Request Syntax

Format a request with query parameters in the following way:

1 Endpoint
2 Query parameter name
3 Query 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.

Top