ResponsSuite Permission API API Reference

Welcome to the ResponsSuite Permission API reference. This document provides a concise description the usage of the API. It is organized around the REST methodology and uses resource-oriented URLs together with common HTTP response codes indicating API errors.

              The Permission system can be used to store collections (*databases*) of mobile numbers (*permissions*)
                        enriched with extra information (*metadata*) such as name, zip code, age, etc. It is tightly
                        integrated with the rest of the ResponsSuite and it is straightforward to communicate using SMS with
                        (parts of) the databases.
          
                        Requests must be authenticated using an `apiKey`, which can be found in the ResponsSuite portal.
          
                        **Terminology**
                        * *MSISDN* is a number uniquely identifying a subscription in a GSM or a UMTS mobile network. It
                        consists of a country code and the local mobile number. The format of an MSISDN for a Danish
                        subscriber is therefore 45XXXXXXXX.
                        * *Database:* A database contains a number of permissions. Furthermore, each database has at least one
                        method of unsubscribing using SMS.
                        * *Permission:* A permission is simply an MSISDN that can be linked to metadata
                        * *Metadata:* Metadata is information about the (user of the) mobile number. The system allows various
                        types of metadata.
                        * *Source:* A source is a tag, that can be used to identify how a permission has interacted with the
                        database (e.g., if metadata has come from different sources). It is possible to have more than one
          
                        **Internal error**
          
                        The HTTP error `500 Internal Server Error` indicates that something is wrong internally in the system,
                        and the user cannot expect to fix this by changing their request. The error is usually _not_
                        permanent, but if it persists, please contact our support team.
          
API Endpoint
https://permission.m2go.dk/api
Contact: support@linkmobility.dk
Schemes: http, https
Version: 1.0

Authentication

API Key

Database

Database methods provide access to the underlying permission database, which contains information on how to unsubscribe from the database.

List available databases

GET /public/database/list

Gets all available database

apiKey

(no description)

type
string
in
query

Successful operation

Response Example (200 OK)
[
  {
    "customerId": "integer(int32)",
    "description": "string",
    "hooks": "array",
    "id": "integer(int32)",
    "name": "string",
    "routes": "array",
    "senderAlias": "string",
    "serviceId": "integer(int32)"
  }
]

Find database by ID

GET /public/database/{id}

Gets data for one specific database

id

Database ID

type
integer (int32)
in
path
apiKey

(no description)

type
string
in
query

Successful operation

400 Bad Request

One or more parameters missing or invalid

401 Unauthorized

The request is not allowed

Response Example (200 OK)
{
  "customerId": "integer(int32)",
  "description": "string",
  "hooks": "array",
  "id": "integer(int32)",
  "name": "string",
  "routes": "array",
  "senderAlias": "string",
  "serviceId": "integer(int32)"
}

Update database by ID

PUT /public/database/{id}

Updates a database

Database object

id

Database ID

type
integer (int32)
in
path
apiKey

(no description)

type
string
in
query
Request Example
{
  "customerId": "integer(int32)",
  "description": "string",
  "hooks": "array",
  "id": "integer(int32)",
  "name": "string",
  "routes": "array",
  "senderAlias": "string",
  "serviceId": "integer(int32)"
}

Successful operation

400 Bad Request

One or more parameters missing or invalid

401 Unauthorized

The request is not allowed

404 Not Found

The database could not be found

Response Example (200 OK)
{
  "customerId": "integer(int32)",
  "description": "string",
  "hooks": "array",
  "id": "integer(int32)",
  "name": "string",
  "routes": "array",
  "senderAlias": "string",
  "serviceId": "integer(int32)"
}
Response Example (400 Bad Request)
{
  "errors": "array"
}

Delete database by ID

DELETE /public/database/{id}

Deletes a database

id

Database ID

type
integer (int32)
in
path
apiKey

(no description)

type
string
in
query
200 OK

Successful operation

400 Bad Request

One or more parameters missing or invalid

401 Unauthorized

The request is not allowed

404 Not Found

The database could not be found

Metadata

Metadata methods can create and edit metadata for a permission database. This should be done, before metadata is added to a permission.

List metadata for database

GET /public/database/{id}/metadata
id

(no description)

type
integer (int32)
in
path
apiKey

(no description)

type
string
in
query
200 OK

Successful operation

401 Unauthorized

The request is not allowed

404 Not Found

Metadata not found

Response Example (200 OK)
[
  {
    "contents": {
      "$ref": "#/definitions/MetadataContents",
      "description": "extra info for the field - e.g. validation option"
    },
    "created": "string(date-time)",
    "databaseId": "integer(int32)",
    "key": "string",
    "label": "string",
    "multiValue": "boolean",
    "type": "string",
    "updated": "string(date-time)"
  }
]

Add metadata to database

POST /public/database/{id}/metadata
id

(no description)

type
integer (int32)
in
path
apiKey

(no description)

type
string
in
query
200 OK

Successful operation

400 Bad Request

One or more parameters missing or invalid

401 Unauthorized

The request is not allowed

404 Not Found

Metadata not found

Response Example (200 OK)
{
  "contents": {
    "$ref": "#/definitions/MetadataContents",
    "description": "extra info for the field - e.g. validation option"
  },
  "created": "string(date-time)",
  "databaseId": "integer(int32)",
  "key": "string",
  "label": "string",
  "multiValue": "boolean",
  "type": "string",
  "updated": "string(date-time)"
}
Response Example (400 Bad Request)
{
  "errors": "array"
}

Get metadata by key

GET /public/database/{id}/metadata/{key}
id

(no description)

type
integer (int32)
in
path
key

(no description)

type
string
in
path
apiKey

(no description)

type
string
in
query
200 OK

Successful operation

401 Unauthorized

The request is not allowed

404 Not Found

Metadata not found

Response Example (200 OK)
{
  "contents": {
    "$ref": "#/definitions/MetadataContents",
    "description": "extra info for the field - e.g. validation option"
  },
  "created": "string(date-time)",
  "databaseId": "integer(int32)",
  "key": "string",
  "label": "string",
  "multiValue": "boolean",
  "type": "string",
  "updated": "string(date-time)"
}

Delete metadata by key

POST /public/database/{id}/metadata/{key}
id

(no description)

type
integer (int32)
in
path
key

(no description)

type
string
in
path
200 OK

Successful operation

401 Unauthorized

The request is not allowed

404 Not Found

Metadata not found

Update metadata by key

PUT /public/database/{id}/metadata/{key}
id

(no description)

type
integer (int32)
in
path
key

(no description)

type
string
in
path
200 OK

Successful operation

401 Unauthorized

The request is not allowed

404 Not Found

Metadata not found

Response Example (200 OK)
{
  "contents": {
    "$ref": "#/definitions/MetadataContents",
    "description": "extra info for the field - e.g. validation option"
  },
  "created": "string(date-time)",
  "databaseId": "integer(int32)",
  "key": "string",
  "label": "string",
  "multiValue": "boolean",
  "type": "string",
  "updated": "string(date-time)"
}

Permission

Permission methods can be used to get a list of all permissions (at once or in batches), and to add, update or delete (i.e. deactivate) permissions. All operations on specific permissions use MSISDN as key.

Bulk import (add/update)

POST /public/database/{id}/permission/bulk

List FlattenedPermission

object
object
id

(no description)

type
integer (int32)
in
path
apiKey

(no description)

type
string
in
query
skipImportOnError

(no description)

type
boolean
in
query
Request Example
200 OK

Successful operation

400 Bad Request

One or more parameters missing or invalid

401 Unauthorized

The request is not allowed

Response Example (200 OK)
{
  "errors": "array",
  "importId": "string",
  "permissionsInserted": "integer(int32)",
  "permissionsUpdated": "integer(int32)",
  "status": "string"
}
Response Example (400 Bad Request)
{
  "errors": "array"
}

Get status of bulk import

POST /public/database/{id}/permission/bulk/status
id

(no description)

type
integer (int32)
in
path
importId

(no description)

type
string
in
query
apiKey

(no description)

type
string
in
query
200 OK

Successful operation

400 Bad Request

One or more parameters missing or invalid

404 Not Found

Import not found

Response Example (200 OK)
{
  "errors": "array",
  "importId": "string",
  "permissionsInserted": "integer(int32)",
  "permissionsUpdated": "integer(int32)",
  "status": "string"
}
Response Example (400 Bad Request)
{
  "errors": "array"
}

List all permissions in database

GET /public/database/{id}/permission/list

Non-paged list

id

(no description)

type
integer (int32)
in
path
apiKey

(no description)

type
string
in
query

Successful operation

404 Not Found

The database could not be found

Response Example (200 OK)
[
  {
    "active": "boolean",
    "msisdn": "string",
    "source": "string"
  }
]

List page of permissions in database

POST /public/database/{id}/permission/paged/list

Paged list

Segmentation

id

(no description)

type
integer (int32)
in
path
apiKey

(no description)

type
string
in
query
Request Example
{
  "ascending": "boolean",
  "endRow": "integer(int32)",
  "groups": "array",
  "metadata": "array",
  "msisdnList": "array",
  "onlyActive": "boolean",
  "quickFilterText": "string",
  "sort": "string",
  "sources": "array",
  "startRow": "integer(int32)"
}

Successful operation

Response Example (200 OK)
{
  "columns": "array",
  "page": "integer(int32)",
  "permissions": "array",
  "sources": "array",
  "totalActive": "integer(int32)",
  "totalElements": "integer(int32)",
  "totalPages": "integer(int32)"
}

Permanently delete permission by MSISDN

DELETE /public/database/{id}/permission/permanent/{msisdn}
id

(no description)

type
integer (int32)
in
path
msisdn

(no description)

type
string
in
path
apiKey

(no description)

type
string
in
query
200 OK

Successful operation

400 Bad Request

One or more parameters missing or invalid

401 Unauthorized

The request is not allowed

404 Not Found

Permission was not found

Response Example (400 Bad Request)
{
  "errors": "array"
}

Add/update permission using query parameters

GET /public/database/{id}/permission/query

Default parameters are msisdn, active (true or false), apiKey and source. Metadata can be added using keyname.

id

(no description)

type
integer (int32)
in
path

Successful operation

400 Bad Request

One or more parameters missing or invalid

401 Unauthorized

The request is not allowed

404 Not Found

Permission was not found

Response Example (200 OK)
{
  "active": "boolean",
  "msisdn": "string",
  "source": "string"
}
Response Example (400 Bad Request)
{
  "errors": "array"
}

Get permission by MSISDN

GET /public/database/{id}/permission/{msisdn}
id

(no description)

type
integer (int32)
in
path
msisdn

(no description)

type
string
in
path
apiKey

(no description)

type
string
in
query
200 OK

Successful operation

401 Unauthorized

The request is not allowed

404 Not Found

Permission was not found

Add permission

POST /public/database/{id}/permission/{msisdn}

flatten permission

object
id

(no description)

type
integer (int32)
in
path
msisdn

(no description)

type
string
in
path
apiKey

(no description)

type
string
in
query
Request Example

Successful operation

400 Bad Request

One or more parameters missing or invalid

401 Unauthorized

The request is not allowed

404 Not Found

Permission was not found

Response Example (200 OK)
{
  "active": "boolean",
  "msisdn": "string",
  "source": "string"
}
Response Example (400 Bad Request)
{
  "errors": "array"
}

Update permission by MSISDN

PUT /public/database/{id}/permission/{msisdn}

Updates permissions for specific msisdn

flatten permission

object
id

(no description)

type
integer (int32)
in
path
msisdn

(no description)

type
string
in
path
apiKey

(no description)

type
string
in
query
Request Example

Successful operation

401 Unauthorized

The request is not allowed

404 Not Found

Permission was not found

Response Example (200 OK)
{
  "active": "boolean",
  "msisdn": "string",
  "source": "string"
}

Delete permission by MSISDN

DELETE /public/database/{id}/permission/{msisdn}

Note that "delete" means that the permission is deactivated. It will not be deleted from the database.

id

(no description)

type
integer (int32)
in
path
msisdn

(no description)

type
string
in
path
apiKey

(no description)

type
string
in
query
200 OK

Successful operation

400 Bad Request

One or more parameters missing or invalid

401 Unauthorized

The request is not allowed

404 Not Found

Permission was not found

Response Example (400 Bad Request)
{
  "errors": "array"
}

Models

FlattenedPermission: object

This class represents a permission - there are three special fields: msisdn, actice and source. Each metadata field can be added as a field of this object - with its value - so if you e.g. have a metadate field with name as key the flattened permission will look like:

{ "msisdn": "4531503823",
  "active": true,
  "source": "source1,source2",
  "name": "Erik"
}
msisdn: string

phone number

active: boolean

if permission is active in the database

source: string

comma separated list of sources

Group: object

type: string
operation: string
groups: object[]
metadata: object[]

ImportError: object

msisdn: string
errors: string[]

ImportStatus: object

Use this model to get the import id and get the status of the import

importId: string

Import id

status: string

Import status: CREATED, VALIDATING, SAVING, DONE (FINAL), ERROR (FINAL)

permissionsInserted: integer (int32)

Number of permissions inserted into database

permissionsUpdated: integer (int32)

Number of permissions updated in database

errors: object[]

Import errors (List of ImportError)

Keyword: object

This represent an unsubscription route for a database

id: integer (int32)

internal database id of the route

permissionDatabaseId: integer (int32)

id of the database it belongs to

routeId: integer (int32)

the route the keyword is configured on

keyword: string

keyword for the route

extra: string

extra word (second word in the sms) for unsubscribing (empty or null means all)

Metadata: object

This represents a metadata field of a permission database

databaseId: integer (int32)

id of the database

key: string

key for the field (used for the value internally - cannot be changed after creation)

label: string

label for the field (used for displaying in the interface)

type: string , x ∈ { INTEGER , TEXT , ENUMERATION }

the type of field

contents: MetadataContents

extra info for the field - e.g. validation option

created: string (date-time)

created date of the field

updated: string (date-time)

deletion date of the field

multiValue: boolean

if the field is a multi value field

MetadataContents: object

Contains extra info for a field

rangeStart: integer (int32)

start on range for validation on INTEGER field

rangeEnd: integer (int32)

end on range for validation on INTEGER field

values: string[]

Possible enumeration of values for ENUMERATION field

validation: string , x ∈ { NONE , EMAIL }

type of validation on TEXT field

MetadataDto: object

field: string
headerName: string
type: string , x ∈ { INTEGER , TEXT , ENUMERATION , BOOLEAN , DATE }
multiValue: boolean
contents: MetadataContents
visible: boolean
pinned: boolean
cellRenderer: string

PaginatedPermissionList: object

Container for a page in a list of permissions

page: integer (int32)

page number

totalPages: integer (int32)

total number of pages

totalElements: integer (int32)

total number of permissions

totalActive: integer (int32)

total number of active permissions

permissions: object[]

the permissions for the page

sources: string[]

the possible sources for the database

columns: object[]

the column data

PermissionDatabase: object

id: integer (int32)
serviceId: integer (int32)
customerId: integer (int32)
name: string
description: string
senderAlias: string
routes: object[]
hooks: object[]

PermissionWebHookDto: object

id: integer (int32)
hookId: integer (int32)
hookName: string
hookKey: string
name: string
enabled: boolean

Rule: object

value: object
value2: object
op: string , x ∈ { EQUALS , RANGE , NONE , ONE_OF , ALL_OF , NONE_OF , IS_EMPTY , IS_NOT_EMPTY , SETDIFF , AMOUNT , PERCENTAGE , DAY_OF_YEAR_TODAY , DAY_OF_WEEK , DAYS_AGO , DAYS_UNTIL }

Rules: object

key: string
rules: object[]

Segmentation: object

startRow: integer (int32)
endRow: integer (int32)
quickFilterText: string
sources: string[]
metadata: object[]
sort: string
groups: object[]
msisdnList: string[]
ascending: boolean
onlyActive: boolean

UnsubscribeRouteDto: object

id: integer (int32)
name: string
channel: string
keywords: object[]
unsubscriptionText: string

ValidationError: object

represents an error

message: string

human friendly error message

code: string

code for error

properties: object

relevant properties for error

ValidationResult: object

result of a validation

errors: object[]

list of errors after validation