v1.0

Routeon Recipients API

## Authentication

API authentication is implemented using the API key, which must be added to the X-API-Key header.

The API key will be generated in your personal account in the API Accesses interface. Specify recipients (for contacts) and/or broadcast (for broadcasts) for Scopes.

## Response

If the request is successful, the API will respond with a 200 OK code, with the details in the response body.

If the request is unsuccessful, the API will respond with the appropriate HTTP code, with details in the response body.

## Working with contacts through API
### Working with attributes
### Connection

API URL path:

`https://{{URL}}/api/v1/recipient/attributes`

Requests to API are sent using GET method.

### Getting attribute list
### Method and endpoint

`GET /api/v1/recipient/attributes`

### Description

Displays the attribute list.

### Parameters

N/A.

### Response

Possible responses:

* 200 — OK — Successful. The body contains ResourceList«AttributeDto» data model;
* 400 — Bad Request — Invalid request. The body contains ApiError data model.
* 401 — Unauthorized — Request lacks valid authentication credentials. The body contains ApiError data model.
* 403 — Forbidden — Access denied. The body contains ApiError data model.
* 500 — Internal Server Error — Server-side error. The body contains ApiError data model.

### Example

Request
`GET https://{{URL}}/api/v1/recipient/attributes`

Response
`200 OK + Body`
````json
{
"limit": 0,
"offset": 0,
"size": 8,
"results": [
{
"id": 1,
"name": "phoneNumber",
"typeId": 5,
"type": null,
"title": "Phone number",
"nullable": false
},
{
"id": 3,
"name": "name",
"typeId": 7,
"type": null,
"title": "Name",
"nullable": true
},
{
"id": 4,
"name": "surname",
"typeId": 8,
"type": null,
"title": "Surname",
"nullable": true
},
{
"id": 2,
"name": "city",
"typeId": 6,
"type": null,
"title": "City",
"nullable": true
},
{
"id": 5,
"name": "email",
"typeId": 9,
"type": null,
"title": "Email",
"nullable": true
},
{
"id": 256,
"name": "Age",
"typeId": 2,
"type": null,
"title": "Age",
"nullable": true
},
{
"id": 291,
"name": "rcsCapable",
"typeId": 4,
"type": null,
"title": "RCS capable",
"nullable": true
},
{
"id": 292,
"name": "lastCheckRcs",
"typeId": 1,
"type": null,
"title": "RCS capability last checked",
"nullable": true
}
]
}
````
## Working with contact list
### Connection
API URL path:
`http://{{URL}}/api/v1/recipient/recipients`

The service provides a set of methods for performing various operations with contacts (recipients) and includes the following methods:
* PUT — changing recipient parameters;
* POST — creating recipients;
* GET — getting contact list;
* DELETE — deleting recipients.
### Creating new contacts
### Method and endpoint
`POST /api/v1/recipient/recipients`
### Description
Serves to create new recipients with specified parameters.
### Parameters
CreateRequest data model.
### Response
Possible responses:
* 200 — OK — Successful. The body contains data model of the following format:

| Field | Type | Reqd. | Description |
|-------------|---------|-------|-------------------------------------------------------------------|
| imported | integer | Yes | Number of imported records. |
| overwritten | integer | Yes | Number of overwritten records. |
| failed | integer | Yes | The number of records that could not be imported due to an error. |
| enriched | integer | Yes | Number of enriched records. |

* 400 — Bad Request — Invalid request. The body contains ApiError data model.
* 401 — Unauthorized — Request lacks valid authentication credentials. The body contains ApiError data model.
* 403 — Forbidden — Access denied. The body contains ApiError data model.
* 500 — Internal Server Error — Server-side error. The body contains ApiError data model.

### Example 1
Request

`POST https://{{URL}}/api/v1/recipient/recipients`

Body
````json
{
"recipients": [
{
"email": "test.email@gmail.com",
"tags": [
"test1"
]
},
{
"name": "Alice",
"phoneNumber": "48732231255",
"tags": [
"test2"
]
}
],
"tag": "test-test",
"type": "ENRICH"
}
````
Response

`200 OK + Body`
````json
{
"imported": 1,
"overwritten": 0,
"failed": 1,
"enriched": 0
}
````
Only one entry was created because the `phoneNumber` parameter is required.
### Example 2
If the required type parameter type is not specified in the request, the API will respond with code 400.

Request

`POST https://{{URL}}/api/v1/recipient/recipients`

Body
````json
{
"recipients": [
{
"name": "Kevin",
"phoneNumber": "48732289523",
"tags": [
"test"
]
}
],
"tag": "test-test"
}
````
Response

`400 Bad Request + Body`
````json
{
"execId": null,
"key": null,
"code": null,
"message": "Recipient type can`t be null",
"args": null
}
````
## Getting contact list
### Method and endpoint
`GET /api/v1/recipient/recipients`
### Description
Displays the recipient list.
### Parameters

| Field | Type | Reqd. | Description |
|-------------|---------|-------|----------------------------------------------------------------------------------------|
| email | string | No | Recipient's email. |
| limit | integer | No | Maximum number of entries. Default value: 10. |
| offset | integer | No | Offset for the list (which entry to start output from). Default value: 0. |
| phoneNumber | string | No | Recipient's phone number. With country code, without “+”. |
| tags | string | No | List of tags assigned to the recipient. Separator “,” (comma). Works using logical OR. |

You can also specify internal names (name) of attributes as parameters.
### Response
Possible responses:
* 200 — OK — Successful. The body contains RecipientsResourceList«RecipientDto» data model.
* 400 — Bad Request — Invalid request. The body contains ApiError data model.
* 401 — Unauthorized — Request lacks valid authentication credentials. The body contains ApiError data model.
* 403 — Forbidden — Access denied. The body contains ApiError data model.
* 500 — Internal Server Error — Server-side error. The body contains ApiError data model.
### Example 1
Request to display the recipient list with tags.

Request

`GET https://{{URL}}/api/v1/recipient/recipients?limit=5&tags=test,test1`

Response

`200 OK + Body`
````json
{
"limit": 5,
"offset": 0,
"size": 2,
"results": [
{
"id": 14045930,
"name": "Anna",
"phoneNumber": "48732231269",
"surname": null,
"city": null,
"email": "Anna.test@gmail.com",
"tags": [
"test"
],
"attributes": {
"Age": 30
}
},
{
"id": 13800531,
"name": "Tom",
"phoneNumber": "4915735987904",
"surname": null,
"city": null,
"email": null,
"tags": [
"test1",
"test-test"
],
"attributes": {}
}
]
}
````
### Example 2
Request to display the recipient list, indicating the attribute name and its value.

Request

`GET https://{{URL}}/api/v1/recipient/recipients?limit=5&Age=30`

Response

`200 OK + Body`
````json
{
"limit": 5,
"offset": 0,
"size": 1,
"results": [
{
"id": 14045930,
"name": "Anna",
"phoneNumber": "48732231269",
"surname": null,
"city": null,
"email": "Anna.test@gmail.com",
"tags": [
"test"
],
"attributes": {
"Age": 30
}
}
]
}
````
### Example 3
If you specify a parameter in the request that was not provided, the API will respond with code 400.

Request

`GET http://{{URL}}/api/v1/recipient/recipients?test=value`

Response

`400 Bad Request + Body`
````json
{
"execId": null,
"key": "errors.common_error",
"code": "ValidationError",
"message": "Selected filter's attributes don't exist.",
"args": null
}
````
## Changing contact parameters
### Method and endpoint
`PUT /api/v1/recipient/recipients`
### Description
Serves to change recipient’s parameters.
### Parameters
CreateUpdateRecipientRequest data model.
### Response
Possible responses:
* 200 — OK — Successful. The body contains RecipientDto data model.
* 400 — Bad Request — Invalid request. The body contains ApiError data model.
* 401 — Unauthorized — Request lacks valid authentication credentials. The body contains ApiError data model.
* 403 — Forbidden — Access denied. The body contains ApiError data model.
* 404 — Not Found — Recipient not found. The body contains ApiError data model.
* 500 — Internal Server Error — Server-side error. The body contains ApiError data model.

### Example 1

Request

`PUT https://{{URL}}/api/v1/recipient/recipients`

Body
````json
{
"attributes": {
"Age": 25
},
"phoneNumber": 48732231255,
"name": "Alice",
"tags": [
"new tag"
]
}
````
Response

`200 OK + Body`
````json
{
"id": 14045932,
"name": "Alice",
"phoneNumber": "48732231255",
"surname": null,
"city": null,
"email": null,
"tags": [
"new tag"
],
"attributes": {
"Age": 25
}
}
````
### Example 2
If the recipient with this phone number was not found, the API will respond with code 400.

Request

`PUT https://{{URL}}/api/v1/recipient/recipients`

Body
````json
{
"attributes": {
"Age": 30
},
"phoneNumber": 48732200000,
"name": "Max",
"email": "test.email@gmail.com"
}
````
Response

`400 Bad Request + Body`
````json
{
"execId": null,
"key": null,
"code": null,
"message": "Recipient not found",
"args": null
}
````
### Example 3
If the required parameter phoneNumber is not specified in the request, the API will respond with code 400.

Request

`PUT https://{{URL}}/api/v1/recipient/recipients`

Body
````json
{
"attributes": {
"Age": 25
},
"name": "Alice",
"email": "test.email@gmail.com"
}
````
Response

`400 Bad Request + Body`
````json
{
"execId": null,
"key": "errors.recipient_service.phone_not_valid",
"code": "ValidationError",
"message": "Phone number can`t be null",
"args": null
}
````
## Deleting contact
### Method and endpoint
`DELETE /api/v1/recipient/recipients`
### Description
It is used to delete the recipient.
### Parameters

| Field | Type | Reqd. | Description |
|-------------|--------|-------|---------------------------|
| email | string | Yes* | Recipient’s email. |
| phoneNumber | string | Yes* | Recipient’s phone number. |

### Response
Possible responses:
* 200 — OK — Successful. The body contains RecipientDto data model.
* 400 — Bad Request — Invalid request. The body contains ApiError data model.
* 401 — Unauthorized — Request lacks valid authentication credentials. The body contains ApiError data model.
* 403 — Forbidden — Access denied. The body contains ApiError data model.
* 404 — Not Found — Recipient not found. The body contains ApiError data model.
* 500 — Internal Server Error — Server-side error. The body contains ApiError data model.
### Example 1
Request

`DELETE https://{{URL}}/api/v1/recipient/recipients`

Body
````json
{
"phoneNumber": "4915735987904"
}
````
Response

`200 OK + Body`

`Contact #14045931 deleted successfully`

### Example 2
Request

`DELETE https://{{URL}}/api/v1/recipient/recipients`

Body
````json
{
"email": "Anna.test@gmail.com"
}
````

Response

`200 OK + Body`

`Contact #14045930 deleted successfully`

### Example 3
If there are multiple recipients in the database that have the same email, the API will respond with code 400.

Request

`DELETE https://{{URL}}/api/v1/recipient/recipients`

Body
````json
{
"email": "test.email@gmail.com"
}
````

Response

`400 Bad Request + Body`
````json
{
"execId": null,
"key": null,
"code": null,
"message": "More than one recipient found",
"args": null
}
````

Open API Playground Download spec

ext-api-attributes

operations for attributes and attribute types over external API

GET /api/v1/recipient/attributes List Attributes POST /api/v1/recipient/attributes Create Attribute GET /api/v1/recipient/attributes/types List AttributeTypes PUT /api/v1/recipient/attributes/{id} Update Attribute DELETE /api/v1/recipient/attributes/{id} Delete Attribute

ext-api-creates

create operations for recipient over external API

POST /api/v1/recipient/recipients create

ext-api-recipients

Provides operations for working with recipients in the system.

GET /api/v1/recipient/filters Get list of Filters GET /api/v1/recipient/recipients Get list of Recipients GET /api/v1/recipient/tags Get list of Tags

ext-api-updates-deletes

update/delete operations for recipient over external API

PUT /api/v1/recipient/recipients update recipients DELETE /api/v1/recipient/recipients delete recipients