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

{
    "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: https://{{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

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

Response

200 OK + Body

{
    "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

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

Response

400 Bad Request + Body

{
    "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

{
    "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

{
    "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 https://{{URL}}/api/v1/recipient/recipients?test=value

Response

400 Bad Request + Body

{
    "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

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

Response

200 OK + Body

{
    "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

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

Response

400 Bad Request + Body

{
    "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

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

Response

400 Bad Request + Body

{
    "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

{
    "phoneNumber": "4915735987904"
}

Response

200 OK + Body

Contact #14045931 deleted successfully

Example 2

Request

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

Body

{
    "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

{
    "email": "test.email@gmail.com"
}

Response

400 Bad Request + Body

{
    "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