API Design

The Railz API is organized around REST. Our API has predictable resource-oriented URLs, accepts form-encoded request bodies, returns JSON-encoded responses, and uses standard HTTP response codes, authentication, and verbs.

You can use the Railz API for free in Sandbox mode. This does not affect your data in Production mode, nor does it interact with any production instance from Accounting Service Providers (ASPs). It is an environment that offers limited functionality for testing.

Production mode offers you full, unlimited access to every feature of your selected plan, and begins processing live requests when in use.

🚧

The API key you use to authenticate requests will determine whether the request is in Sandbox or Production mode. API keys for the Sandbox and Production environments are obtained by signing up for a Railz account on the Railz Dashboard™.

API Protocol

The Railz API follows the REST standard taking advantage of HTTP methodologies defined by the RFC 2616 protocol. It uses GET/POST requests to communicate and HTTP response codes to indicate status and errors.

All responses come in standard JSON and all requests must include Content-Type: application/json header, and a valid JSON body when applicable.

The Railz API is served over HTTPS TLS v1.2 to ensure data privacy; HTTP or HTTPS with TLS equal 1.1 and below are not supported.

❗️

The API supports only secure communications over HTTPS TLS v1.2 to ensure data privacy. HTTP or HTTPS with TLS under v1.2 are not supported and will be rejected.

Host

The Railz API has two base URLs used for authentication and retrieving data.

Authentication Base URL

The authentication base URL is used for calling the getAccess endpoint to retrieve an access_token and generating a server-side widget session. See Authentication for more details.

All authentication endpoints in the reference documentation use the following base URL:

https://auth.railz.ai/

API Base URL

All non-authentication endpoints in the reference documentation use the following base URL:

https://api.railz.ai/

🚧

Use the Authentication URL first to authenticate your connection, then the Base URL for all subsequent API requests.