Introduction

The REST API for administration of MEX Connections is used to activate Swedish geographical telephone numbers for receiving SMS on a mobile phone number.

The user account used with the MEX Connection REST API can also be used with Generic Mobiles send and receive SMS REST API.

Getting started

Irrelevant headers will be omitted and json pretty-printed for clarity.

To use the MEX REST API you need an account. Please get in touch with our friendly support team or your sales contact and you'll be up and running in no time!

Email: kund@genericmobile.se
Phone: 020-31 00 41
International: +46 86016666

Base URL: https://api.genericmobile.se/mex/api/v2/

MEX connections configured with the REST API will be visible in the Web portal.

Authentication

All requests must contain an Authorization header. Two different methods are supported, Basic authentication or OAuth 2.0 Bearer token authentication.

Basic Authentication

Basic Authorization header

curl -X GET 'https://api.genericmobile.se/mex/api/v2/' \
  --basic -u Alice:secretPwd

Example HTTP session

GET /mex/api/v2/ HTTP/1.1
Host: api.genericmobile.se
Authorization: Basic QWxpY2U6c2VjcmV0UHdk

Basic authentication can be used for access control, see RFC 7617 for details. In basic authentication the Authorization header contains Basic as first parameter followed by a base64-encoded username:password.

401 Unauthorized

Will be returned if your credentials are wrong or you have insufficient privileges.

Bearer Token Authentication

Get a Bearer token

curl -X GET 'https://api.genericmobile.se/GMIdentity/token' \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -d 'grant_type=password&username=Alice&password=secretPwd'

200 OK
{
    "access_token": "Ec87w-vdziBQW9-tMy87OJRh... ...fkM00O0yFZ",
    "token_type": "bearer",
    "expires_in": 86399
}

Example HTTP session

GET /mex/api/v2/ HTTP/1.1
Host: api.genericmobile.se
Authorization: Bearer Ec87w-vdziBQW9-tMy87OJRh... ...fkM00O0yFZ

In OAuth 2.0 Bearer token authentication the grant type password is used, see RFC 6749 for details.

A token is first generated.

Token URL: https://api.genericmobile.se/GMIdentity/token

The generated token is valid 24 hours and shall be placed in the Authorization header after the Bearer parameter.

401 Unauthorized

Will be returned if your credentials are wrong or you have insufficient privileges.

MEX Connections

Number formats

Telephone numbers shall in variables be given in international format starting with +. When telephone numbers are given in a URL the + sign shall be excluded.

Add connection

Add connection

curl -X POST 'https://api.genericmobile.se/mex/api/v2/connections' \
  --basic -u Alice:secretPwd \
  -H 'Content-Type: application/json' \
  -d '{
        "number": "+46101234567",
        "mobile": "+46707659443",
        "groupId": "d8a6c7bf-287e-11e9-8523-005056a25b64",
        "comment": "MEX connection for Alice"
      }'

201 Created
{
  "id": "46101234567",
  "number": "+46101234567",
  "mobile": "+46707659443",
  "groupId": "d8a6c7bf-287e-11e9-8523-005056a25b64",
  "comment": "MEX connection for Alice",
  "lastmodified": "2022-01-13T15:08:36+00:00"
}

A connection is added by sending a POST with a JSON-object to /connections, see Connection object for details. To add a connection to a group the group must first be created, see MEX Groups.

POST /connections

HTTP Response

201 Created

A successful request contains a connection object.

400 Bad Request

Most error responses from the API will include an error object.

Delete connection

Delete connection

curl -X DELETE 'https://api.genericmobile.se/mex/api/v2/connections/46101234567' \
  --basic -u Alice:secretPwd

204 No Content

A connection is deleted by sending a DELETE to /connections/{id} where {id} is the number without the + sign.

DELETE /connections/{id}

HTTP Response

204 No Content

The connection was successfully deleted.

404 Not Found

The connection was not found.

Delete all connections in a group

Delete all connection in a group

curl -X DELETE 'https://api.genericmobile.se/mex/api/v2/connections?groupId=d8a6c7bf-287e-11e9-8523-005056a25b64' \
  --basic -u Alice:secretPwd

204 No Content

All connections in a group can be deleted in one DELETE call.

DELETE /connections?groupId={groupId}

HTTP Response

204 No Content

The connections were successfully deleted.

404 Not Found

The group was not found.

Delete all connections

Delete all connections

curl -X DELETE 'https://api.genericmobile.se/mex/api/v2/connections?all=true' \
  --basic -u Alice:secretPwd

204 No Content

All connections can be deleted in one DELETE call.

DELETE /connections?all=true

HTTP Response

204 No Content

All connections were successfully deleted.

Update connection

Update connection

curl -X PUT 'https://api.genericmobile.se/mex/api/v2/connections/46101234567' \
  --basic -u Alice:secretPwd \
  -H 'Content-Type: application/json' \
  -d '{
        "mobile": "+46707659443",
        "groupId": null,
        "comment": "MEX connection for Alice"
      }'

200 OK
{
  "id": "46101234567",
  "number": "+46101234567",
  "mobile": "+46707659443",
  "comment": "MEX connection for Alice",
  "lastmodified": "2022-01-13T15:08:36+00:00"
}

To update an existing connection PUT a connection object to /connections/{id}. The number cannot be changed, it's ignored and can be omitted.

PUT /connections/{id}

HTTP Response

200 OK

A successful request contains a connection object.

404 Not Found

The connection was not found.

400 Bad Request

Most error responses from the API will include an error object.

List all connections

List all connections

curl -X GET 'https://api.genericmobile.se/mex/api/v2/connections' \
  --basic -u Alice:secretPwd

200 OK
{
  "connections": [
    {
      "id": "46101234567",
      "number": "+46101234567",
      "mobile": "+46707659443",
      "comment": "MEX connection for Alice",
      "lastmodified": "2022-01-06T15:08:36+00:00"
    },
    {
      "id": "46107654321",
      "number": "+46107654321",
      "mobile": "+46707659443",
      "groupId": "d8a6c484-287e-11e9-8523-005056a25b64",
      "comment": "MEX connection for Bob",
      "lastmodified": "2022-01-10T15:08:36+00:00"
    }
  ]
}

List your MEX connections with GET as the example shows.

GET /connections

HTTP Response

200 OK

A successful request contains a JSON-object with an array of connection objects in connections .

List all connections in a group

List all connections in a group

curl -X GET 'https://api.genericmobile.se/mex/api/v2/connections?groupId=d8a6c484-287e-11e9-8523-005056a25b64' \
  --basic -u Alice:secretPwd

200 OK
{
  "connections": [
    {
      "id": "46107654321",
      "number": "+46107654321",
      "mobile": "+46707659443",
      "groupId": "d8a6c484-287e-11e9-8523-005056a25b64",
      "comment": "MEX connection for Bob",
      "lastmodified": "2022-01-10T15:08:36+00:00"
    }
  ]
}

You can list all connections in a group by using groupId or groupName.

GET /connections?groupId={id}

HTTP Response

200 OK

A successful request contains a JSON-object with an array of connection objects in connections .

404 Not Found

The group was not found.

Get connection

Get connection

curl -X GET 'https://api.genericmobile.se/mex/api/v2/connections/46101234567' \
  --basic -u Alice:secretPwd

200 OK
{
  "id": "46101234567",
  "number": "+46101234567",
  "mobile": "+46707659443",
  "comment": "MEX connection for Alice",
  "lastmodified": "2022-01-06T15:08:36+00:00"
}

Fetch one connection with GET as the example shows.

GET /connections/{id}

HTTP Response

200 OK

A successful request contains a connection object.

404 Not Found

The connection was not found.

Connection object

MEX Groups

The geographical telephone numbers that are activated for receiving SMS can be related to a group. Groups are only used for administrational reasons, for example it is possible to use a separate group name for all telephone numbers belonging to a certain company or part of a company.

Add group

Add group

curl -X POST 'https://api.genericmobile.se/mex/api/v2/groups' \
  --basic -u Alice:secretPwd \
  -H 'Content-Type: application/json' \
  -d '{
        "name": "Group One"
      }'

201 Created
{
  "id": "d8a6c7bf-287e-11e9-8523-005056a25b64",
  "name": "Group One"
}

A group is added by sending a POST with a JSON-object to /groups, see group object for details.

POST /groups

HTTP Response

201 Created

A successful request contains a group object.

400 Bad Request

Most error responses from the API will include an error object.

Delete group

Delete group

curl -X DELETE 'https://api.genericmobile.se/mex/api/v2/groups/d8a6c7bf-287e-11e9-8523-005056a25b64' \
  --basic -u Alice:secretPwd

204 No Content

Deleting a group does not delete the group members but they will no longer belong to any group.

DELETE /groups/{id}

HTTP Response

204 No Content

404 Not Found

The group was not found.

Update group

Update group

curl -X POST 'https://api.genericmobile.se/mex/api/v2/groups/d8a6c7bf-287e-11e9-8523-005056a25b64' \
  --basic -u Alice:secretPwd \
  -H 'Content-Type: application/json' \
  -d '{
        "name": "Group One"
      }'

201 Created
{
  "id": "d8a6c7bf-287e-11e9-8523-005056a25b64",
  "name": "Group One"
}

To update an existing group PUT a group object to /groups/{id}. The id cannot be changed, it's value in the group object is ignored and can be omitted.

PUT /groups/{id}

HTTP Response

200 OK

A successful request contains a group object.

404 Not Found

The group was not found.

400 Bad Request

Most error responses from the API will include an error object.

Update group name or cost

Update group name

curl -X POST 'https://api.genericmobile.se/mex/api/v2/groups/d8a6c7bf-287e-11e9-8523-005056a25b64/name' \
  --basic -u Alice:secretPwd \
  -H 'Content-Type: application/json' \
  -d '"New name"'

201 Created
{
  "id": "d8a6c7bf-287e-11e9-8523-005056a25b64",
  "name": "New name"
}

To update a single parameter, name or cost, in an existing group PUT the new value to /groups/{id}/name or /groups/{id}/cost.

PUT /groups/{id}/name

HTTP Response

200 OK

A successful request contains a group object.

404 Not Found

The group was not found.

400 Bad Request

Most error responses from the API will include an error object.

List all groups

List all groups

curl -X GET 'https://api.genericmobile.se/mex/api/v2/groups' \
  --basic -u Alice:secretPwd

200 OK
{
  "groups": [
    {
        "id": "d8a6c7bf-287e-11e9-8523-005056a25b64",
        "name": "Group One"
    }
  ]
}

List your groups with GET as the example shows.

GET /connections

HTTP Response

200 OK

A successful request contains a JSON-object with an array of group objects in groups .

Get group

Get group

curl -X GET 'https://api.genericmobile.se/mex/api/v2/groups/d8a6c7bf-287e-11e9-8523-005056a25b64' \
  --basic -u Alice:secretPwd

200 OK
{
  "id": "d8a6c7bf-287e-11e9-8523-005056a25b64",
  "name": "Group One"
}

Fetch a group with GET as the example shows.

GET /groups/{id}

HTTP Response

200 OK

A successful request contains a group object.

404 Not Found

The group was not found.

Group object

Errors

HTTP response codes

Success

Client Errors

Server Errors

Error object

Example of error object

400 Bad Request
{
  "error": {
    "code": "ERR_VALIDATION_FAILED",
    "message": "Validation failed",
    "target": "MexConnection",
    "details": [
      {
        "code": "ERR_INVALID_NUMBER",
        "message": "Number must be in international format",
        "target": "mobile"
      }
    ]
  }
}

Most error responses from the API will include an error object. The error object always contains code and message. It may contain target, details and innererror.

Error codes