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
Gets all available database
(no description)
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
Gets data for one specific database
Database ID
(no description)
Successful operation
One or more parameters missing or invalid
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
Updates a database
Database object
Database ID
(no description)
Request Example
{
"customerId": "integer(int32)",
"description": "string",
"hooks": "array",
"id": "integer(int32)",
"name": "string",
"routes": "array",
"senderAlias": "string",
"serviceId": "integer(int32)"
}
Successful operation
One or more parameters missing or invalid
The request is not allowed
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
Deletes a database
Database ID
(no description)
Successful operation
One or more parameters missing or invalid
The request is not allowed
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
(no description)
(no description)
Successful operation
The request is not allowed
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
(no description)
(no description)
Successful operation
One or more parameters missing or invalid
The request is not allowed
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
(no description)
(no description)
(no description)
Successful operation
The request is not allowed
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
(no description)
(no description)
Successful operation
The request is not allowed
Metadata not found
Update metadata by key
(no description)
(no description)
Successful operation
The request is not allowed
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)
List FlattenedPermission
(no description)
(no description)
(no description)
Request Example
Successful operation
One or more parameters missing or invalid
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
(no description)
(no description)
(no description)
Successful operation
One or more parameters missing or invalid
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
Non-paged list
(no description)
(no description)
Successful operation
The database could not be found
Response Example (200 OK)
[
{
"active": "boolean",
"msisdn": "string",
"source": "string"
}
]
List page of permissions in database
Paged list
Segmentation
(no description)
(no description)
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
(no description)
(no description)
(no description)
Successful operation
One or more parameters missing or invalid
The request is not allowed
Permission was not found
Response Example (400 Bad Request)
{
"errors": "array"
}
Add/update permission using query parameters
Default parameters are msisdn, active (true or false), apiKey and source. Metadata can be added using keyname.
(no description)
Successful operation
One or more parameters missing or invalid
The request is not allowed
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
(no description)
(no description)
(no description)
Successful operation
The request is not allowed
Permission was not found
Add permission
flatten permission
(no description)
(no description)
(no description)
Request Example
Successful operation
One or more parameters missing or invalid
The request is not allowed
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
Updates permissions for specific msisdn
flatten permission
(no description)
(no description)
(no description)
Request Example
Successful operation
The request is not allowed
Permission was not found
Response Example (200 OK)
{
"active": "boolean",
"msisdn": "string",
"source": "string"
}
Delete permission by MSISDN
Note that "delete" means that the permission is deactivated. It will not be deleted from the database.
(no description)
(no description)
(no description)
Successful operation
One or more parameters missing or invalid
The request is not allowed
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
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 }
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