NAV Navbar
cURL

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": "2019-05-16T12:43:00+02: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": "2019-05-16T12:43:00+02: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": "2019-05-09T12:43:00+02:00"
    },
    {
      "id": "46107654321",
      "number": "+46107654321",
      "mobile": "+46707659443",
      "groupId": "d8a6c484-287e-11e9-8523-005056a25b64",
      "comment": "MEX connection for Bob",
      "lastmodified": "2019-05-13T12:43:00+02: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": "2019-05-13T12:43:00+02: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": "2019-05-09T12:43:00+02: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

Parameter Required Type Default Description
id No String - Resource identifier (same as number but without leading +.
number In POST String - Swedish phone number +46101234567.
mobile Yes String - Swedish mobile phone number +46707659443.
groupId No String(36) null The group the connection belongs to.
comment No String(0..100) null Optional user defined text.
lastmodified No String(25) - ISO-8601 DateTime.

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

Parameter Required Type Default Description
id No String(36) - Resource identifier.
name Yes String(1..100) - A unique name for the group.
cost No UInt32 0 cost can only be used by and is only visible to selected partners.

Errors

HTTP response codes

Success

HTTPS Code Status Description
200 OK Successful request.
201 Created Successful request, content was created.
204 No Content Successful request, no content will be returned.

Client Errors

HTTPS Code Status Description
400 Bad request Something in the request is missing or wrong.
401 Unauthorized Authentication failed.
403 Forbidden The request is correct but cannot be performed.
404 Not found Resource not found.
405 Method not allowed The method specified is not allowed for the resource.
406 Not Acceptable Content generated is not matched with the Accept header.
411 Length Required Content-Length header is missing or wrong.
415 Unsupported Media Type Content-Type header is missing or wrong.

Server Errors

HTTPS Code Status Description
500 Internal Server Error Server could not process the request due to internal error.
502 Bad Gateway Invalid response or could not reach upstream server or application pool.
503 Service unavailable Server is currently unavailable or down for maintenance.

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

Code Message
ERR_UNAUTHORIZED Authorization has been denied for this request
ERR_VALIDATION_FAILED Validation failed
ERR_PROPERTY_REQUIRED Property is required
ERR_PROPERTY_NOT_ALLOWED Property not allowed
ERR_PROPERTY_LENGTH_EXCEEDED Property max length exceeded
ERR_INVALID_NUMBER Number must be in international format
ERR_SWE_ONLY Only swedish numbers allowed
ERR_MCL_NOT_ALLOWED Minicall numbers not allowed
ERR_MOBILE_NOT_ALLOWED Mobile phone numbers not allowed
ERR_MOBILE_ONLY Mobile must be to a mobile phone
ERR_NUMBER_NOT_FOUND Number not found
ERR_NUMBER_ALREADY_EXISTS Number already exists
ERR_NUMBER_CANNOT_BE_CHANGED Number cannot be changed
ERR_INVALID_GROUPID GroupId not valid
ERR_GROUP_EMPTY Group name cannot be empty
ERR_GROUP_ALREADY_EXISTS A group with this name already exists
ERR_GROUP_NOT_FOUND Group not found
ERR_INBOX_USERID_REQUIRED Inbox cannot be used, account not connected to a SmsWeb UserId
ERR_INBOX_ONLY Inbox cannot be combined with mobile
ERR_DATABASE Database error
ERR_OTHER Unexpected error