Introduction

This is the API reference for Viatel's API.

The reference provides a detailed explanation of all resources that are accessible through the Viatel API. Our API is designed around REST, has predictable resource-oriented URLs, and uses standard HTTP verbs and status codes. Authentication can be done by Basic Auth or token.

Message formats

Requests are sent as JSON, or in some cases form-encoded. String properties are encoded using UTF-8, and date properties are set as ISO 8601 strings, more detailed explanation below.

HTTP responses

Please use the following guidelines for http responses:

Accept any 2xx codes as success
Interpret any 4xx as an error
Interpret any 5xx as an error

Versioning

The API base URL contains a version identifier. The latest two versions are maintained. New properties and data models are continuously added. Fields that aren't listed in this reference may be present in response objects.

API Updates

We try to update our API in a backwards compatible way to avoid breaking existing integrations. Unfortunatly that's not always possible when we iterate on our API and release new products and features. Sometimes we need to make breaking changes which will result in a new version of the API.

Non-breaking changes

Below is a list of changes we don’t consider as breaking changes.

Addition of a response body when one didn't previously exist
Addition of optional or read-only fields/properties
Re-ordering of fields in the JSON
Addition of HTTP headers
Addition of new values to an enum

Errors

Viatel's API use HTTP status codes together with error fields to handle errors. When an API call fails, Viatel will respond with a 4xx or 5xx status code together with a response body containing an error field with the error code, details with an error message and also Viatel’s internal error code that can be helpful while investigating.

Common error codes

Error code	Error description	Reason

Error code	Error description	Reason
401	Unauthorized	Authentication failed. Make sure: The credentials are sent as Basic Auth The access token is sent in the request body The token is not expired
403	Forbidden	The API account does not have permission to make the request. Make sure the account has sufficient permissions.
405	Method Not Allowed	The method for the endpoint is not supported. Try to change to GET or POST and try again.
415	Unsupported Media Type	Information must be provided using JSON. Change from Text, XML, JavaScript, HTML or any other format to JSON.

Example of an error response

{
    "errorCode": "InvalidParameters",
    "errorCodeNumeric": 100,
    "internalErrorCode": "-101",
    "traceId": "80060ebb-0001-de00-b63f-84710c7967bb",
    "type": "https://tools.ietf.org/html/rfc7231#section-6.5.1",
    "title": "API error",
    "detail": "Invalid InboxId",
    "status": 400,
    "instance": null
}

Data Types

A coherent format is used across the API for phone numbers, currencies, amounts and dates.

Phone numbers

Phone numbers are expressed in E164 format; in international format excluding a plus sign.

JSON example

{
    "to": "46707123456"
}

Currency

Currrency uses the ISO 4217 standard for defining currencies. Examples are SEK, NOK, DKK and EUR.

JSON example

{
  "currency": "SEK"
}

Amount

Amounts are expressed in minor units according to the ISO 4217 standard, unless otherwise stated, which means the smallest unit of the currency is used when expressed.

Examples

Currency	Value	Represents

Currency	Value	Represents
SEK	100	1 kr
EUR	50	€ 0.50
GBP	500	£5
USD	1000	$10

JSON example

{
  "orderAmount": 1000
}

Strings

Strings may be up to 255 characters, unless otherwise noted in the field description.

Dates

Dates are expressed according to the ISO 8601 standard with combined date, time and timezone. The exception is dateOfBirth fields where values in the format YYYY-MM-DD are accepted.

Examples

Value	Representation

Value	Representation
2022-04-03T07:45:00Z	The 3rd of April 2022 at 07:45:00 and the UTC timezone.
2022-04-03T07:45:00.098Z	The 3th of April 2022 at 07:45:00, with factional seconds 98 (98 milliseconds) and the UTC timezone.

JSON example

{
  "sendDateTime": "2018-08-08T08:37:22Z",
  "dateOfBirth": "1981-09-06"
}

Locale and Country

Locales should be formatted as a language tag consisting of a two-letter language code combined with a two-letter country code according to RFC 1766. Examples are en-us for US English, en-gb for British English and sv-se for Swedish (in Sweden).

Countries are handled as two-letter country codes according to ISO 3166 alpha-2. Examples are us for the United States, gb for Great Britain and se for Sweden.

{
  "locale": "sv-se",
  "country": "se"
}

Encoding

All data sent to Viatel’s API should be UTF-8 encoded.

Caching

To increase performance, both credentials and permissions are cached in Viatel’s platform. If you change credentials or permissions on an API account, it may take up to ten minutes before it’s propagated.

Rate limits

To ensure service stability, the API validates request rate limits on an account basis. If you make an excessive amount of requests, you will receive an http response code of 429 Too Many Requests. If this occurs during expected use of the Viatel API, please contact Viatel Support to resolve the issue.

Authentication

You can authenticate to the API using either an Access Token or Basic Auth (username/password).

General Notes

Credentials are environment-specific (e.g., production vs. staging) and not interchangeable.
If credentials or tokens are missing, malformed, or invalid, the API will respond with: HTTP 401 Unauthorized

Token-Based Authentication (Recommended)

Access tokens provide better performance and are the preferred method for most API interactions.

How to Get a Token

To request an access token, you need an Auth token that you create through the customer portal as described in the Administration - Users.

Use this Auth token with the Auth API to obtain your access token. Set the Auth token as a string value in the request body, e.g. “xyz…“. Calls to the Auth API is made with no authentication method set ("No Auth"). For full instructions and request/response examples, see Viatel API Reference.

How to Use the Token

Once you have obtained an access token, include it in the Authorization header of all API requests using the Bearer scheme:

Authorization: Bearer <access_token>

This token must be included with every request to authenticate the caller.

Token Expiry

Access tokens are valid for 60 minutes from the time they are created. The expiration time is not extended when the token is used. The remaining validity duration of the access token is included in the response from the Auth API. When the access token expires, a new access token must be requested. If an expired access token is used, an HTTP 401 status code is returned.

API Credentials (Basic Auth)

Alternatively, you can authenticate directly using your API credentials via HTTP Basic Auth.

Credentials

Field	Description

Field	Description
Username	The name of the API account (e.g mycompany-client-api)
Password	A secret associated with your account used to authorize API access

For details on managing API users and setting passwords, see Administration - Users .

How to Use the Credentials

Include your credentials in the Authorization header using Basic Auth.

Authorization: Basic <base64(username:password)>

API Specification

Auth API

The Auth API is used to generate an access token.

Technical specification

Production	Viatel Auth API documentation
Stage	Viatel Auth API documentation (stage)

SMS API

The SMS API is used to send text messages.

Technical specification

Production	Viatel SMS API documentation
Stage	Viatel SMS API documentation (stage)

Set a phone number to generate an expected error

By setting a given phone number in the To-field a given error is generated.

To	Expected response

To	Expected response
46780000000	Unknown
46780000100	InvalidParameters
46780000200	GetFailed
46780000650	OutOfCredits
46780000800	Exception

Notifications via HTTP

For information about receiving notifications via HTTP for SMS related events see SMS Service - HTTP Notifications. For example events such as Incoming SMS, SMS Delivery Reports or Charge Reports.

SMS Box API

The SMS Box API is used to get inboxes and messages.
Utilizing the SMS API requires an SMS Account configured for the API user, see Administration - Users .

Technical specification

Production	Viatel SMS Box API documentation
Stage	Viatel SMS Box API documentation (stage)

RCS API

The RCS API enables businesses to initiate Rich Business Messaging (RBM) conversations, leveraging Rich Communication Services (RCS) technology. It supports starting new customer interactions with rich, interactive content.

Technical specification

Production	Viatel RCS API documentation
Stage	Viatel RCS API documentation (stage)

CallRouterAx API

The CallRouter API is used to manage a CallRouterAx service.

Technical specification

Production	Viatel CallRouterAx API documentation
Stage	Viatel CallRouterAx API documentation (stage)

Charity API

The Charity API is used by charity organizations and fundraisers to get information in relation to their charity campaigns.

counterString is an identifier and can be configured to be unique for each phone number or participation. The value is in lower case. counterString can be used to decode if the participation was done via sms, call or another channel. If the counterString is configured to be unique per phone number, the first/oldest participation will be decoded as channel.

Converted means that the participant has completed the registration. Viatel's service will then not send any further reminders.

Technical specification

Production	Viatel Charity API documentation
Stage	Viatel Charity API documentation (stage)

Carrier Billing API

The Carrier Billing API is used by operators to fetch billing data.

Technical specification

Production	Viatel CarrierBilling API documentation
Stage	Viatel CarrierBilling API documentation (stage)

AgentLine API

The AgentLine API is used by manage the service.

Technical specification

Production	Viatel AgentLine API documentation
Stage	Viatel AgentLine API documentation (stage)

Campaigns API

The Campaigns API is used to create a campaign on a premium rate number or geographical number. This API is used for clients with a related service.

Technical specification

Production	Viatel Campaigns API documentation
Stage	Viatel Campaigns API documentation (stage)

Checkout API

The Checkout API is used to manage payments made by cards and invoices.

Technical specification

Production	Viatel Checkout API documentation
Stage	Viatel Checkout API documentation (stage)

Address API

The Address API is used to lookup addresses and personal data based on phone number or social security number.
Utilizing the Address API requires a Match Account configured for the API user, see Administration - Users .

Technical specification

Production	Viatel Address API documentation
Stage	Viatel Address API documentation (stage)

1 Introduction
- 1.1 Message formats
- 1.2 HTTP responses
- 1.3 Versioning
- 1.4 Errors
- 1.5 Data Types
- 1.6 Caching
- 1.7 Rate limits
2 Authentication
3 API Specification
- 3.1 Auth API
- 3.2 SMS API
- 3.3 SMS Box API
- 3.4 RCS API
- 3.5 CallRouterAx API
- 3.6 Charity API
- 3.7 Carrier Billing API
- 3.8 AgentLine API
- 3.9 Campaigns API
- 3.10 Checkout API
- 3.11 Address API

Viatel API Reference

Introduction

Message formats

HTTP responses

Versioning

API Updates

Non-breaking changes

Errors

Common error codes

Example of an error response

Data Types

Phone numbers

JSON example

Currency

JSON example

Amount

Examples

JSON example

Strings

Dates

Examples

JSON example

Locale and Country

Encoding

Caching

Rate limits

Authentication

General Notes

Token-Based Authentication (Recommended)

How to Get a Token

How to Use the Token

Token Expiry

API Credentials (Basic Auth)

Credentials

How to Use the Credentials

API Specification

Auth API

Technical specification

SMS API

Technical specification

Set a phone number to generate an expected error

Notifications via HTTP

SMS Box API

Technical specification

RCS API

Technical specification

CallRouterAx API

Technical specification

Charity API

Technical specification

Carrier Billing API

Technical specification

AgentLine API

Technical specification

Campaigns API

Technical specification

Checkout API

Technical specification

Address API

Technical specification

Table of Contents