Relatel API (2.1.2)

Download OpenAPI specification:Download

General

This API allows a developer to access data from a companyes 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 plans, Switch Starter, Switch Pro and Switch Premium.

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 here. 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" }

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

The id of the order.

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

The id of the M2M subscription.

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

The id of the subscription.

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": {
    }
}

Contact

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

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": [
    ]
}

Create an employee (Admin only)

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 a text message to the employee (Switch Premium)

Send an SMS message to the given employee. The sender will be shown as either the authenticated employee's number or name.

path Parameters
id
required
integer

Employee ID

Request Body schema: application/json
required
object

Responses

Request samples

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

Response samples

Content type
application/json
{
  • "sent": 0
}

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
{
  • "id": 0,
  • "name": "string",
  • "live_presence": "available",
  • "speed_dial": {
    },
  • "employee_ids": [
    ]
}

Get a single employee group by ID

path Parameters
id
required
integer

Employee group ID

Responses

Response samples

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

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
{
  • "id": 0,
  • "name": "string",
  • "live_presence": "available",
  • "speed_dial": {
    },
  • "employee_ids": [
    ]
}

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
{
  • "id": 0,
  • "name": "string",
  • "live_presence": "available",
  • "speed_dial": {
    },
  • "employee_ids": [
    ]
}

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 a text message to all employees in the group (Switch Premium)

Send an SMS message to all employees in this group. The sender will be shown as either the authenticated employee's number or name. Beware: these are cheap, but not free. Take a look at the pricelist for Web SMS. This feature is not available for companies in trial.

path Parameters
employee_group_id
required
integer

Employee group ID

Request Body schema: application/json
required
body
string

The content of the SMS

Responses

Request samples

Content type
application/json
{
  • "body": "string"
}

Response samples

Content type
application/json
{
  • "sent": 0
}

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": {
    }
}

Get call statistics for a given reception (Switch Premium)

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

Seconds you want your calls to be answered within

from_time
required
string <date-time>

Start of time interval as a ISO8601 timestamp

to_time
required
string <date-time>

End of time interval as a 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 (Switch Premium)

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.

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
any

The type of data to return.

group_by
required
any

Aggregation key.

start
required
any

Start of interval as an ISO 8601 date.

end
required
any

End of interval as an ISO 8601 date.

endpoint
any

(Optional) Comma-separated string of endpoints to filter by. Endpoints of different types cannot be mixed.

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
any

Show voice mails recorded at or before this time.

endpoint
any

Show calls to specified employee or reception.

limit
any

Number of voicemails to show.

number
any

Show voice mails to or from specified number.

Responses

Response samples

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

Get a single voicemail by ID.

path Parameters
id
required
any

The ID of the voicemail.

Responses

Response samples

Content type
application/json
{
  • "id": 0,
  • "created_at": "2019-08-24T14:15:22Z",
  • "heard": true,
  • "duration": 0,
  • "endpoint": "string",
  • "from_number": "string",
  • "from_contact": {
    },
  • "message": "string",
  • "comment": "string"
}

Update a voicemail.

path Parameters
id
required
any

The ID of the voicemail.

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,
  • "duration": 0,
  • "endpoint": "string",
  • "from_number": "string",
  • "from_contact": {
    },
  • "message": "string",
  • "comment": "string"
}

Delete a voicemail.

path Parameters
id
required
any

The ID of the voicemail.

Responses

Download a voicemail as MP3.

path Parameters
id
required
any

The ID of the voicemail.

Responses

Chat

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": {
    }
}

Contacts

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 the ID is greater than or equal to the 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"
}

Calls

Get all calls

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"
}

Smiley

Get smileys (Switch)

query Parameters
limit
any

Number of Smileys returned.

number
any

Number on caller. Only return smileys given by this number.

rated_at_lt_or_eq
any

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

rated_at_gt_or_eq
any

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

endpoint
any

Return smileys related to this Endpoint name.

reception_id
any
Deprecated

Return smileys related to this Reception ID (deprecated).

employee_id
any

Return smileys related to this Employee ID.

rating
any

Return smileys with this rating.

commented
any

If given, only return smileys that have a comment.

Responses

Response samples

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

Get smiley statistics for a given period.

query Parameters
from_time
required
any

The ISO 8601 representation of the wanted start of the time interval.

to_time
required
any

The ISO 8601 representation of the wanted end of the time interval.

endpoint
any

(Optional) If given, only calculate statistics for the Endpoint with this name.

reception_id
any
Deprecated

(Optional) Deprecated. If given, only calculate statistics for the Reception with this ID.

employee_id
any

(Optional) If given, only calculate statistics for the Employee with this ID.

Responses

Response samples

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

Tags

Get a list of tags

query Parameters
name
string

Filter tags by name

Responses

Response samples

Content type
application/json
[
  • {
    }
]