API docs by Redocly

Relatel API (2.1.2)

Download OpenAPI specification:

General

This API allows a developer to access data from a Relatel account and to extend Relatel with new functionality.

All phone numbers include the country calling code, without 00 or + prefix. E.g. a Danish number would be: 4571999999.

Product restrictions

Relatel supplies two types of products, a virtual switchboard and mobile subscriptions.

Different features and parts of the API depends on the user and/or company having the right features.

Switch

The switch product is our virtual switchboard. It has three different company/customer wide subscription plans, Professional, Contact Center and Unlimited. Also, each employee (except the first free) needs a subscription to enable access to the features in the selected plan.

Mobile subscriptions

Just a normal sim-card based mobile subscription, but with great love on top. All mobile subscriptions have the same API features.

Switch and mobile

Some features require both Switch and Mobile, thees will be marked.

Authentication

The Relatel v2 REST API can be accessed via OAuth 2.0 or with a one-off Access Token which you can create on https://app.relatel.dk/account/authorized_applications. This helps us track the usage of your application as well as providing the best possible security and safety to our users' data. OAuth 2.0 is a modern standard used by most providers, large and small.

To use the Relatel v2 REST API with oAuth 2.0 you need to first register your application. Given that each application is tied to it's own URL you might want to register one for development and one for production.

Please note that a user may at any time destroy their access tokens. You might want to take this into account when you're building your application.

Obtaining an Access Token

Every request to a user's data is authenticated by an access token. To get one the user must accept that they want to use your app. They do this on our domain. Start by redirecting your user to the following address:

https://app.relatel.dk/api/v2/authorize?client_id=YOUR_APPLICATIONS_ID&response_type=code&redirect_uri=YOUR_APPLICATIONS_REDIRECT_URI

Users will be prompted to login (if they aren't already) and then asked if they want to grant you access to their account. If they agree, they are taken to your redirect_uri with a request token as a parameter.

http://example.com/callback?code=REQUEST_TOKEN

Your app then makes a POST request like this:

https://app.relatel.dk/api/v2/token?client_id=YOUR_APPLICATIONS_ID&client_secret=YOUR_APPLICATIONS_SECRET&grant_type=authorization_code&redirect_uri=YOUR_APPLICATIONS_REDIRECT_URI&code=REQUEST_TOKEN

The response will be JSON:

{ "access_token": "ACCESS_TOKEN" }

Chat

Chat conversations and messages

getChats

Authorizations:
bearerAuth

Responses

Response samples

Content type
application/json
{
  • "chats": [
    ]
}

getChat

path Parameters
uuid
required
string

Responses

Response samples

Content type
application/json
{
  • "chat": {
    }
}

Order

Inspect recent orders

Get a list of orders (recent only)

Authorizations:
bearerAuth

Responses

Response samples

Content type
application/json
{
  • "orders": [
    ]
}

Get a specific order

Authorizations:
bearerAuth
path Parameters
id
required
integer

Order ID

Responses

Response samples

Content type
application/json
{
  • "id": 1234,
  • "type": "Order::ActivateM2M",
  • "state": "completed",
  • "pending_tasks": false
}

M2M

Handle sim cards in machines. The M2M related operations requires a separate agreement.

Get a list of M2M subscriptions (IDs only)

Authorizations:
bearerAuth

Responses

Response samples

Content type
application/json
[
  • 12,
  • 23,
  • 34
]

Create a new M2M subscription order

Authorizations:
bearerAuth
Request Body schema: application/json
required
required
object

Responses

Request samples

Content type
application/json
{
  • "order": {
    }
}

Response samples

Content type
application/json
{
  • "order": {
    }
}

Create an M2M subscription removal/cancellation order

Authorizations:
bearerAuth
Request Body schema: application/json
required
required
object

Responses

Request samples

Content type
application/json
{
  • "order": {
    }
}

Response samples

Content type
application/json
{
  • "order": {
    }
}

Get a specific M2M subscription

Authorizations:
bearerAuth
path Parameters
id
required
integer

M2M subscription ID

Responses

Response samples

Content type
application/json
{
  • "id": 4567,
  • "description": "Gylletank 34",
  • "order_id": 1234,
  • "product_name": "m2m-small-one",
  • "state": "active",
  • "icc_id": "89450123456789012346",
  • "ordered_on": "2024-01-10",
  • "activated_on": "2024-01-10",
  • "cancelled_on": null,
  • "contract_expired_on": "2024-01-10",
  • "overuse_limit_dkk": 1500
}

Update select fields of an M2M subscription

Authorizations:
bearerAuth
path Parameters
id
required
integer

Subscription ID

Request Body schema: application/json
required
required
object

Responses

Request samples

Content type
application/json
{
  • "subscription": {
    }
}

Response samples

Content type
application/json
{
  • "id": 4567,
  • "description": "John's autocamper",
  • "order_id": 1234,
  • "product_name": "m2m-small-one",
  • "state": "active",
  • "icc_id": "89450123456789012346",
  • "ordered_on": "2024-01-10",
  • "activated_on": "2024-01-10",
  • "cancelled_on": null,
  • "contract_expired_on": "2024-01-10",
  • "overuse_limit_dkk": 100
}

Download a month's consumption/overuse for all M2M subscriptions

Authorizations:
bearerAuth
query Parameters
object
numbers
Array of strings

Phonenumbers to filter charges by.

subscription_ids
Array of strings

Ids of the subscriptions

Responses

Response samples

Content type
text/csv
subscription_id,subscription_state,phone_number,product_name,icc,type,count,dkk_to_vat,dkk_no_vat,subscription_activated_on,subscription_cancelled_on,formatted_phone_number,description
1234,"active","4571991234","m2m-large","89450123456789012349","sms_roam","123","5.34","0.0","2024-01-05","2024-02-01","71 99 12 34","Tractor 12"

Create a subscription removal/cancellation order

Authorizations:
bearerAuth
Request Body schema: application/json
required
required
object

Responses

Request samples

Content type
application/json
{
  • "order": {
    }
}

Response samples

Content type
application/json
{
  • "order": {
    }
}

Change a M2M phone number's product.

Authorizations:
bearerAuth
Request Body schema: application/json
required
required
object

Responses

Request samples

Content type
application/json
{
  • "order": {
    }
}

Response samples

Content type
application/json
{
  • "order": {
    }
}

Contacts

Contacts are used to show information on the other party in a call and are shared with the entire company.

Get all contacts

query Parameters
number
string

Show contacts with the specified number

limit
integer <= 100
Default: 10

Number of contacts to fetch

id_gt_or_eq
integer

Show contacts where ID is greater than or equal to specified value

Responses

Response samples

Content type
application/json
{
  • "contacts": [
    ]
}

Create a contact

Create a new contact in the authenticated company

Request Body schema: application/json
required
object (Contact)

Responses

Request samples

Content type
application/json
{
  • "contact": {
    }
}

Response samples

Content type
application/json
{
  • "contact": {
    }
}

Get a single contact by ID

path Parameters
id
required
integer

Contact ID

Responses

Response samples

Content type
application/json
{
  • "contact": {
    }
}

Update a contact

path Parameters
id
required
integer

Contact ID

Request Body schema: application/json
required
object (Contact)

Responses

Request samples

Content type
application/json
{
  • "contact": {
    }
}

Response samples

Content type
application/json
{
  • "contact": {
    }
}

Delete a contact

path Parameters
id
required
integer

Contact ID

Responses

Response samples

Content type
application/json
{
  • "message": "Contact deleted successfully"
}

Get a single contact by phone number

path Parameters
number
required
string

Contact phone number

Responses

Response samples

Content type
application/json
{
  • "contact": {
    }
}

Get all comments for a contact

path Parameters
contact_id
required
integer

Contact ID

Responses

Response samples

Content type
application/json
{
  • "comments": [
    ]
}

Create a comment on a contact

path Parameters
contact_id
required
integer

Contact ID

Request Body schema: application/json
required
object

Responses

Request samples

Content type
application/json
{
  • "comment": {
    }
}

Response samples

Content type
application/json
{
  • "comment": {
    }
}

Delete a comment

path Parameters
contact_id
required
integer

Contact ID

id
required
integer

Comment ID

Responses

Response samples

Content type
application/json
{
  • "message": "Comment deleted successfully"
}

Employee

Interact with employees, set do not disturb, send message and list all employees.

Get all employees

Responses

Response samples

Content type
application/json
{
  • "employees": [
    ]
}

Get a single employee by ID

path Parameters
id
required
integer

Employee ID

Responses

Response samples

Content type
application/json
{
  • "employee": {
    }
}

Update an employee (Admin only)

path Parameters
id
required
integer

Employee ID

Request Body schema: application/json
required
employee
object

Responses

Request samples

Content type
application/json
{
  • "employee": { }
}

Response samples

Content type
application/json
{
  • "employee": {
    }
}

Delete an employee (Admin only)

path Parameters
id
required
integer

Employee ID

Responses

Response samples

Content type
application/json
{
  • "message": "Employee deleted successfully"
}

Get the currently authenticated employee

Responses

Response samples

Content type
application/json
{
  • "employee": {
    }
}

Update the currently authenticated employee

Request Body schema: application/json
required
employee
object

Responses

Request samples

Content type
application/json
{
  • "employee": { }
}

Response samples

Content type
application/json
{
  • "employee": {
    }
}

Send an SMS to an employee

Sends a Web SMS to the given employee's mobile number on behalf of the authenticated employee. See the Message tag description for sender-name rules, limits, and pricing.

Authorizations:
bearerAuth
path Parameters
id
required
integer

Employee ID

Request Body schema: application/json
required
required
object

Responses

Request samples

Content type
application/json
{
  • "message": {
    }
}

Response samples

Content type
application/json
{
  • "sent": 0,
  • "failed_numbers": [
    ]
}

EmployeeGroup

Employee groups are collections of employees that can be used to dial or transfer to multiple employees at once.

Get all employee groups

Responses

Response samples

Content type
application/json
{
  • "employee_groups": [
    ]
}

Create a new employee group (Admin only)

Request Body schema: application/json
required
object

Responses

Request samples

Content type
application/json
{
  • "employee_group": {
    }
}

Response samples

Content type
application/json
{
  • "type": "EmployeeGroup",
  • "id": 0,
  • "name": "string",
  • "live_presence": "available",
  • "speed_dial": {
    },
  • "employee_ids": [
    ],
  • "endpoint": "EmployeeGroup#1",
  • "avatar": "string"
}

Get a single employee group by ID

path Parameters
id
required
integer

Employee group ID

Responses

Response samples

Content type
application/json
{
  • "type": "EmployeeGroup",
  • "id": 0,
  • "name": "string",
  • "live_presence": "available",
  • "speed_dial": {
    },
  • "employee_ids": [
    ],
  • "endpoint": "EmployeeGroup#1",
  • "avatar": "string"
}

Update an employee group (Admin only)

path Parameters
id
required
integer

Employee group ID

Request Body schema: application/json
required
employee_group
object

Responses

Request samples

Content type
application/json
{
  • "employee_group": { }
}

Response samples

Content type
application/json
{
  • "type": "EmployeeGroup",
  • "id": 0,
  • "name": "string",
  • "live_presence": "available",
  • "speed_dial": {
    },
  • "employee_ids": [
    ],
  • "endpoint": "EmployeeGroup#1",
  • "avatar": "string"
}

Add the authenticated employee to an employee group

path Parameters
employee_group_id
required
integer

Employee group ID

Responses

Response samples

Content type
application/json
{
  • "type": "EmployeeGroup",
  • "id": 0,
  • "name": "string",
  • "live_presence": "available",
  • "speed_dial": {
    },
  • "employee_ids": [
    ],
  • "endpoint": "EmployeeGroup#1",
  • "avatar": "string"
}

Remove the authenticated employee from an employee group

path Parameters
employee_group_id
required
integer

Employee group ID

Responses

Response samples

Content type
application/json
{ }

Send an SMS to every member of an employee group

Sends a Web SMS to every employee in the group, on behalf of the authenticated employee. sent in the response reflects how many group members were reached. See the Message tag description for sender-name rules, limits, and pricing.

Authorizations:
bearerAuth
path Parameters
employee_group_id
required
integer

Employee group ID

Request Body schema: application/json
required
required
object

Responses

Request samples

Content type
application/json
{
  • "message": {
    }
}

Response samples

Content type
application/json
{
  • "sent": 0,
  • "failed_numbers": [
    ]
}

Reception

Receptions are called main numbers in the interface.

Get all receptions

Responses

Response samples

Content type
application/json
{
  • "receptions": [
    ]
}

Get a single reception by ID

path Parameters
id
required
integer

Reception ID

Responses

Response samples

Content type
application/json
{
  • "id": 0,
  • "name": "string",
  • "phone_number": {
    },
  • "brand_name": "string",
  • "short_brand_name": "string",
  • "number": "string",
  • "number_formatted": "string",
  • "endpoint": "Reception#1",
  • "company_id": 0,
  • "is_smiley_enabled": true,
  • "is_smiley_nps_enabled": true,
  • "is_open": true,
  • "is_shadow": true,
  • "has_main_sms": true,
  • "is_cloakable": true
}

Get call statistics for a given reception (requires at least Contact Center)

Get call statistics for a given period. You can provide answer targets, and the server will calculate how many calls is within the given targets.

path Parameters
id
required
integer

Reception ID

query Parameters
answer_target
required
integer

Target call answer time in seconds

from_time
required
string <date-time>

Start of time interval as ISO8601 timestamp

to_time
required
string <date-time>

End of time interval as ISO8601 timestamp

phase
string
Enum: "open" "closed" "backup"

Comma-separated list of phases to include in statistics

Responses

Response samples

Content type
application/json
{
  • "statistics": {
    }
}

Get call status for a given reception (requires at least Contact Center)

Get the number of current calls to this reception grouped by their status.

path Parameters
id
required
integer

Reception ID

Responses

Response samples

Content type
application/json
{
  • "new": 0,
  • "ringing": 0,
  • "answered": 0
}

Smileys

Smileys are the feedback from people who have contacted a reception.

After the call or chat has ended, the caller will receive an SMS or email asking for feedback on how the conversation went. This feedback is called a smiley.

Get smileys (requires at least Professional)

Authorizations:
bearerAuth
query Parameters
limit
integer <= 100
Default: 10

Number of smileys to return

number
string

Filter smileys by caller number

rated_at_lt_or_eq
string <date-time>

Return smileys where rated_at is less than or equal to this value

rated_at_gt_or_eq
string <date-time>

Return smileys where rated_at is greater than or equal to this value

endpoint
string

Filter smileys by endpoint name

reception_id
integer
Deprecated

Filter smileys by reception ID (deprecated)

employee_id
integer

Filter smileys by employee ID

rating
integer
Enum: 0 1

Filter smileys by rating

commented
boolean

Filter smileys that have comments

Responses

Response samples

Content type
application/json
{
  • "smileys": [
    ]
}

Get smiley statistics for a given period.

Authorizations:
bearerAuth
query Parameters
from_time
required
string <date-time>

Start of time interval as ISO8601 timestamp

to_time
required
string <date-time>

End of time interval as ISO8601 timestamp

endpoint
string

Filter statistics by endpoint name (optional)

reception_id
integer
Deprecated

Filter statistics by reception ID (optional, deprecated)

employee_id
integer

Filter statistics by employee ID (optional)

Responses

Response samples

Content type
application/json
{
  • "statistics": {
    }
}

Statistics

The Statistics API allows you to get aggregated stats about calls and chats. The data is updated every 1-2 hours, not in real-time like the other APIs.

Get aggregated statistics about calls and chats.

query Parameters
endpoint_type
required
string
Enum: "Reception" "ChatReception" "Employee"

Type of statistics to return

group_by
required
string
Enum: "employee_id" "reception_id" "chat_reception_id" "ivr_key" "period_month" "period_week" "period_day" "period_hour"

How to group the statistics

start
required
string <date-time>

Start of interval as ISO8601 timestamp

end
required
string <date-time>

End of interval as ISO8601 timestamp

endpoint
string

Filter by specific endpoints (comma-separated, optional)

Responses

Response samples

Content type
application/json
{
  • "rows": [
    ]
}

Voicemail

Voice mail messages for both mobile and main numbers.

Get all voicemails.

query Parameters
created_at_lt_or_eq
string <date-time>

Filter voicemails recorded at or before this timestamp

endpoint
string

Filter voicemails by endpoint

limit
integer <= 100
Default: 10

Number of voicemails to return

number
string

Filter voicemails by phone number

Responses

Response samples

Content type
application/json
{
  • "voice_mails": [
    ]
}

Get a single voicemail by ID.

path Parameters
id
required
integer

Voicemail ID

Responses

Response samples

Content type
application/json
{
  • "id": 0,
  • "created_at": "2019-08-24T14:15:22Z",
  • "heard": true,
  • "sound": {
    },
  • "duration": 0,
  • "from_number": "string",
  • "from_number_formatted": "string",
  • "from_contact": {
    },
  • "endpoint_name": "string",
  • "endpoint": "Employee#1"
}

Update a voicemail.

path Parameters
id
required
integer

Voicemail ID

Request Body schema: application/json
required
object

Responses

Request samples

Content type
application/json
{
  • "voice_mail": {
    }
}

Response samples

Content type
application/json
{
  • "id": 0,
  • "created_at": "2019-08-24T14:15:22Z",
  • "heard": true,
  • "sound": {
    },
  • "duration": 0,
  • "from_number": "string",
  • "from_number_formatted": "string",
  • "from_contact": {
    },
  • "endpoint_name": "string",
  • "endpoint": "Employee#1"
}

Delete a voicemail.

path Parameters
id
required
integer

Voicemail ID

Responses

Download a voicemail as MP3.

path Parameters
id
required
integer

Voicemail ID

Responses

Calls

Phone call records and call management

Get all calls

query Parameters
started_at_lt_or_eq
string <date-time>

Return calls where started_at is less than or equal to this value

started_at_gt_or_eq
string <date-time>

Return calls where started_at is greater than or equal to this value

ended_at_lt_or_eq
string <date-time>

Return calls where ended_at is less than or equal to this value

ended_at_gt_or_eq
string <date-time>

Return calls where ended_at is greater than or equal to this value

limit
number

Maximum number of calls to return

direction
string
Enum: "incoming" "outgoing"

Filter calls by direction

endpoint
string

Filter calls by endpoint name

Responses

Response samples

Content type
application/json
{
  • "calls": [
    ]
}

Get a single call by UUID

path Parameters
uuid
required
string

Responses

Response samples

Content type
application/json
{
  • "call": {
    }
}

Initiate a phone call

CAUTION: When using this API, please be aware that an actual call will be made every time the endpoint is called. Once the authenticated employee's phone is answered, a call will be made to the specified recipient.

Request Body schema: application/json
required
to_number
string

The number you want to dial. Should be prepended with country code.

restrict_to
string
Enum: "" "web_call" "mobile"

Can be empty, "web_call", or "mobile". If present, only rings on that device.

cloak_reception_id
string

(Optional) If present, the phone number associated with this reception is used as the from-number. See the Reception documentation.

Responses

Request samples

Content type
application/json
{
  • "to_number": 4571999999,
  • "restrict_to": "",
  • "cloak_reception_id": "string"
}

Response samples

Content type
application/json
{
  • "message": "Call initiated successfully"
}

Message

SMS and messaging functionality.

Web SMS

Send SMS programmatically through the Relatel SMS gateway. Three endpoints are available:

  • POST /messages — send to one or more arbitrary phone numbers via to_numbers.
  • POST /employees/{id}/message — send to a specific employee's mobile number.
  • POST /employee_groups/{id}/message — send to every member of an employee group.

All three send on behalf of the authenticated employee and consume the company's Web SMS allowance.

Availability and pricing

Web SMS requires an active Switch subscription that includes a web_smses allowance — see the price list for the included monthly amount per plan and the per-message rate for sends beyond it. International rates differ from domestic rates. The feature is not available during trial.

Each SMS segment counts as one unit against the allowance. Messages longer than the standard SMS length are split into multiple segments per GSM concatenation rules and consume the corresponding number of units.

Sender name

The sender shown on the recipient's device is either the authenticated employee's mobile number, or — when the message is sent on behalf of a Reception (endpoint: "Reception#<id>") with from_number_hidden: true — the reception's short brand name.

Short brand names must be approved before they can be used as sender. Names matching well-known brands (banks, public authorities, payment providers, etc.) are auto-rejected; names matching the company or debtor name are fast-tracked. Until a name is approved, sends from that reception with from_number_hidden: true are rejected with HTTP 400.

Limits

  • A daily per-company safety cap protects against abuse; reaching it returns HTTP 400 with rate_limit_reached.
  • Once the company's Web SMS allowance is exhausted, further sends are billed as priced overuse against the sending employee's monthly DKK overuse limit. Sends that would exceed that limit are rejected with HTTP 400 with overuse_full.

Get all messages.

query Parameters
created_at_lt_or_eq
string <date-time>

Filter messages created before this timestamp

created_at_gt_or_eq
string <date-time>

Filter messages created after this timestamp

endpoint
string

Filter messages by endpoint

Responses

Response samples

Content type
application/json
{
  • "messages": [
    ]
}

Send an SMS to one or more phone numbers

Sends a Web SMS to each recipient in to_numbers on behalf of the authenticated employee. See the Message tag description for sender-name rules, limits, and pricing.

Authorizations:
bearerAuth
Request Body schema: application/json
required
required
object
to_numbers
required
Array of strings

One or more recipient phone numbers, including country calling code, without + or 00 prefix.

Responses

Request samples

Content type
application/json
{
  • "message": {
    },
  • "to_numbers": [
    ]
}

Response samples

Content type
application/json
{
  • "sent": 0,
  • "failed_numbers": [
    ]
}

Tags

Tag management for organizing contacts and data

Get a list of tags

query Parameters
name
string

Filter tags by name

Responses

Response samples

Content type
application/json
[
  • {
    }
]