Version 1.2

Base Information
Auth
Rate Limits
Postman Collection
Root
References
Sandbox
Validation
Distribution Lists
Subscribers
Account
Standard Campaigns
Campaigns' folders
Custom fields
Expand All Collapse All

Subscribers


Create a subscriber

POST /subscribers/email

Create a subscriber

Request Parameters:
Name Example Value Default Value Description Type Data Type Required
email john.doe@example.com null Email body string(100)
first_name John null First name body string(50)
last_name Doe null Last name body string(50)
reactivate true false Reactivates subscriber body boolean
company Example null Company name body string(50)
salutation Mr. null Salutation body string(100)
alias John null Alias body string(100)
anniversary 2016-01-07T00:00:00+01:00 null Anniversary body ISO 8601
vip true false VIP subscriber body boolean
preferred_com 1 1 Prefferred communication body reference: preferred_com
contacts null Contacts - others body array
contacts: contact City 1 null Contact body string(50)
contacts: contact_type 99 99 Contact type body reference: contact_type
tags null Tags body array
tags: tag my-group null Tag body string(50)
lists null Distribution lists body array
lists: list 82eaba02-1c49-48d1-942d-7eb32a3722d7 null List ID body string(38)
fields null Custom fields body array
fields: field_id 591f290e-a2ee-7210-e77b-9245c9290dfc null Custom field ID or Custom field code body string(50)
fields: auto_create_value false true Automatically creates new value for 'list' and 'select' custom field type body boolean
fields: values null Custom field values body array
fields: values: value Lorem ipusm null Custom field value body mixed
Request Example:
{
    "email": "mike.johnson@example.com",
    "first_name": "Mike",
    "last_name": "Johnson",
    "company": "My Company",
    "lists": [
        "c2d73a4d-b66b-17c3-801e-8769f22e1fc2",
        "5d16b01e-6927-651b-ef08-548485a0fd55"
    ],
    "contacts": [
        {
            "contact": "My City",
            "contact_type": 1
        }
    ],
    "tags": [
        "my-tag"
    ],
    "fields": [
        {
            "field_id": "591f290e-a2ee-7210-e77b-9245c9290dfc",
            "values": [
                10
            ]
        }
    ]
}
Example Request URL:
https://api.clevermonitor.com/v1.2/subscribers/email
Response Parameters:
Name Data Type Reference Description
email string(100) Email
email_id string(38) Email ID
record_status integer(3) record_status Subscriber creation status
contacts array Contacts - others
contacts: contact string(50) Contact
contacts: record_status integer(3) record_status Contact creation status
tags array Tags
tags: tag string(50) Tag
tags: record_status integer(3) record_status Tag creation status
lists array Distribution lists
lists: list_id string(38) List ID
lists: record_status integer(3) record_status List creation status
fields array Custom fields
fields: field_id string(38) Custom field ID
fields: code string(30) Custom field code
fields: record_status integer(3) record_status Custom field record status
fields: values array Custom field values
fields: values: value mixed Custom field value
fields: values: value_status integer(3) record_status Custom field value assignment Status
Response Messages:
Code Status Example Body
201 OK 
{
    "email": "mike.johnson@example.com",
    "email_id": "882f7ed8-0eaf-4d36-6f0d-ea91b1bd239c",
    "record_status": 202,
    "contacts": [
        {
            "contact": "My City",
            "record_status": 202
        }
    ],
    "tags": [
        {
            "tag": "my-tag",
            "record_status": 202
        }
    ],
    "lists": [
        {
            "list_id": "c2d73a4d-b66b-17c3-801e-8769f22e1fc2",
            "record_status": 202
        },
        {
            "list_id": "5d16b01e-6927-651b-ef08-548485a0fd55",
            "record_status": 202
        }
    ],
    "fields": [
        {
            "field_id": "591f290e-a2ee-7210-e77b-9245c9290dfc",
            "code": "lorem_ipsum",
            "record_status": 202,
            "values": [
                {
                    "value": 10,
                    "value_status": 200
                }
            ]
        }
    ]
}
Detail of a subscriber

GET /subscribers/email/{email}

Detail of a subscriber

Request Parameters:
Name Example Value Default Value Description Type Data Type Required
email john.doe@example.com null Email or Email ID body string(100)
Example Request URL:
https://api.clevermonitor.com/v1.2/subscribers/email/john.doe@example.com
Response Parameters:
Name Data Type Reference Description
email string(100) Email
email_id string(100) Email ID
first_name string(50) First name
last_name string(50) Last name
email_status integer(2) contact_status Email status
subscriber_status integer(2) contact_status Subscriber status
company string(50) Company name
salutation string(100) Salutation
alias string(100) Alias
anniversary ISO 8601 Anniversary
vip boolean VIP subscriber
preferred_com integer(3) preferred_com Prefferred communication
contacts array Contacts - others
contacts: contact string(50) Contact
contacts: contact_type integer(2) contact_type Contact type
tags array Tags
tags: tag string(50) Tag
lists array Distribution lists
lists: list string(38) List ID
lists: name string(100) List name
lists: date_from ISO 8061 Assigned since
fields array Custom fields
fields: field_id string(50) Custom field ID
fields: code string(30) Custom field code
fields: values array Custom field values
fields: values: value mixed Custom field value
Response Messages:
Code Status Example Body
200 OK 
{
    "email": "john.doe@example.com",
    "email_id": "89dae0a6-14fe-c46c-cc4b-95440e95c1a0",
    "first_name": "John",
    "last_name": "Doe",
    "email_status": 1,
    "subscriber_status": 1,
    "company": null,
    "salutation": null,
    "alias": null,
    "anniversary": null,
    "vip": 1,
    "preferred_com": 1,
    "contacts": [],
    "tags": [],
    "lists": [
        {
            "list_id": "51aa2978-f1ac-37a2-cc15-443177b3581e",
            "name": "Name 1",
            "date_from": "2016-02-26T00:00:00+01:00"
        },
        {
            "list_id": "70639670-b5d6-443c-c56a-7d93593e2c95",
            "name": "Name 2",
            "date_from": "2016-02-26T00:00:00+01:00"
        }
    ],
    "fields": [
        {
            "field_id": "591f290e-a2ee-7210-e77b-9245c9290dfc",
            "code": "lorem_ipsum",
            "values": [
                10
            ]
        }
    ]
}
Unsubscribe

GET /subscribers/email/unsubscribe/{email}

Unsubscribe

Request Parameters:
Name Example Value Default Value Description Type Data Type Required
email john.doe@example.com null Email or Email ID path string(100)
Example Request URL:
https://api.clevermonitor.com/v1.2/subscribers/email/unsubscribe/john.doe@example.com
Response Parameters:
Name Data Type Reference Description
email string(100) Email
email_id string(38) Email ID
message string Message
Response Messages:
Code Status Example Body
200 OK 
{
    "email": "john.doe@example.com",
    "email_id": "89dae0a6-14fe-c46c-cc4b-95440e95c1a0",
    "message": "Subscriber unsubscribed"
}
Delete a subscriber

DELETE /subscribers/email/{email}

Delete a subscriber

Request Parameters:
Name Example Value Default Value Description Type Data Type Required
email john.doe@example.com null Email or Email ID path string(100)
Example Request URL:
https://api.clevermonitor.com/v1.2/subscribers/email/john.doe@example.com
Response Parameters:
Name Data Type Reference Description
email string(100) Email
email_id string(38) Email ID
message string Message
Response Messages:
Code Status Example Body
200 OK 
{
    "email": "john.doe@example.com",
    "email_id": "89dae0a6-14fe-c46c-cc4b-95440e95c1a0",
    "message": "Subscriber deleted"
}
Overview of subscribers

GET /subscribers[/?contact_status={contact_status}/&status_change={status_change}/&count={count}/&offset={offset}]

Overview of subscribers

Request Parameters:
Name Example Value Default Value Description Type Data Type Required
contact_status 99 1 Contact status Query reference: contact_status
status_change 2016-01-29T00:00:00+01:00 null Contacts with status changes after this date Query ISO 8061
count 10 100 Count of records Query integer(4) max(1.000)
offset 0 0 Offset Query integer(4)
Example Request URL:
https://api.clevermonitor.com/v1.2/subscribers/?contact_status=99&status_change=2016-01-29T00%3A00%3A00%2B01%3A00&count=10&offset=0
Response Parameters:
Name Data Type Reference Description
email string(100) Email
email_id string(100) Email ID
first_name string(50) First name
last_name string(50) Last name
email_status integer(2) contact_status Email status
email_status_change ISO 8061 Email status changed
subscriber_status integer(2) contact_status Subscriber status
subscriber_status_change ISO 8061 Subscriber status changed
company string(50) Company name
salutation string(100) Salutation
alias string(100) Alias
anniversary ISO 8601 Anniversary
vip boolean VIP subscriber
preferred_com integer(3) preferred_com Prefferred communication
contacts array Contacts - others
contacts: contact string(50) Contact
contacts: contact_type integer(2) contact_type Contact type
tags array Tags
tags: tag string(50) Tag
lists array Distribution lists
lists: list string(38) List ID
lists: name string(100) List name
lists: date_from ISO 8061 Assigned since
fields array Custom fields
fields: field_id string(50) Custom field ID
fields: code string(30) Custom field code
fields: values array Custom field values
fields: values: value mixed Custom field value
Response Messages:
Code Status Example Body
200 OK 
[
    {
        "email": "john.doe@example.com",
        "email_id": "6e2fc510-404a-1609-a520-627b28e508bf",
        "first_name": "John",
        "last_name": "Doe",
        "email_status": 1,
        "email_status_change": "2017-04-19T16:11:55+00:00",
        "subscriber_status": 1,
        "subscriber_status_change": "2017-04-19T16:11:55+00:00",
        "company": "My Company",
        "salutation": "Hello John",
        "alias": null,
        "anniversary": null,
        "vip": 1,
        "preferred_com": 1,
        "contacts": [],
        "tags": [],
        "lists": [
            {
                "list_id": "bfe0f29f-5a70-6037-1ed0-948d23580226",
                "name": "Name 1",
                "date_from": "2016-02-25T00:00:00+01:00"
            },
            {
                "list_id": "6eafcf0a-0a92-8788-5b7b-5c8aa8c4dafb",
                "name": "Name 2",
                "date_from": "2016-02-25T00:00:00+01:00"
            }
        ],
        "fields": [
            {
                "field_id": "591f290e-a2ee-7210-e77b-9245c9290dfc",
                "code": "lorem_ipsum",
                "values": [
                    10
                ]
            }
        ]
    },
    {
        "email": "mike.johnson@example.com",
        "email_id": "f065f84f-8824-9aa8-b1ee-6f6475106add",
        "first_name": "Mike",
        "last_name": "Johnson",
        "email_status": 99,
        "email_status_change": "2017-04-19T16:11:55+00:00",
        "subscriber_status": 99,
        "subscriber_status_change": "2017-04-19T16:11:55+00:00",
        "company": null,
        "salutation": null,
        "alias": null,
        "anniversary": null,
        "vip": 0,
        "preferred_com": 1,
        "contacts": [],
        "tags": [],
        "lists": [
            {
                "list_id": "b49170ef-8803-8517-67b8-14ee4b5f1ac9",
                "name": "Name 3",
                "date_from": "2016-02-25T00:00:00+01:00"
            }
        ],
        "fields": [
            {
                "field_id": "591f290e-a2ee-7210-e77b-9245c9290dfc",
                "code": "lorem_ipsum",
                "values": [
                    5
                ]
            }
        ]
    }
]
Update a subscriber

PATCH /subscribers/email/{email}

Update a subscriber

Request Parameters:
Name Example Value Default Value Description Type Data Type Required
email 5ff42ca6-1965-49ed-97d0-b2b568c88bfd null Email or Email ID body string(100)
first_name Mike null First name body string(50)
last_name Johnson null Last name body string(50)
salutation Mr. null Salutation body string(100)
alias John null Alias body string(100)
anniversary 2016-01-07T00:00:00+01:00 null Anniversary body ISO 8601
vip true false VIP subscriber body boolean
preferred_com 1 1 Prefferred communication body reference: preferred_com
contacts null Contacts - others body array
contacts: contact City 1 null Contact body string(50)
contacts: contact_type 99 99 Contact type body reference: contact_type
tags null Tags body array
tags: tag my-group null Tag body string(50)
lists null Distribution lists body array
lists: list 82eaba02-1c49-48d1-942d-7eb32a3722d7 null List ID body string(38)
fields null Custom fields body array
fields: field_id 591f290e-a2ee-7210-e77b-9245c9290dfc null Custom field ID or Custom field code body string(50)
fields: merge false true Replace already assigned values with those in request body boolean
fields: auto_create_value false true Automatically creates new value(s) for 'list' and 'select' type body boolean
fields: values null Custom field values body array
fields: values: value Lorem ipusm null Custom field value body mixed
Request Example:
{
    "first_name": "Mike",
    "last_name": "Johnson",
    "company": "My Company",
    "lists": [
        "c2d73a4d-b66b-17c3-801e-8769f22e1fc2",
        "5d16b01e-6927-651b-ef08-548485a0fd55"
    ],
    "contacts": [
        {
            "contact": "My City",
            "contact_type": 1
        }
    ],
    "tags": [
        "my-tag"
    ],
    "fields": [
        {
            "field_id": "591f290e-a2ee-7210-e77b-9245c9290dfc",
            "merge": false,
            "values": [
                10
            ]
        }
    ]
}
Example Request URL:
https://api.clevermonitor.com/v1.2/subscribers/email/5ff42ca6-1965-49ed-97d0-b2b568c88bfd
Response Parameters:
Name Data Type Reference Description
email string(100) Email
email_id string(38) Email ID
record_status integer(3) record_status Subscriber creation status
contacts array Contacts
contacts: contact string(50) Contact
contacts: record_status integer(3) record_status Contact creation status
tags array Contacts
tags: tag string(50) Tag
tags: record_status integer(3) record_status Tag creation status
lists array Contacts
lists: list_id string(38) List ID
lists: record_status integer(3) record_status List creation status
fields array Custom fields
fields: field_id string(50) Custom field ID
fields: code string(30) Custom field code
fields: record_status integer(3) record_status Custom field record status
fields: values array Custom field values
fields: values: value mixed Custom field value
fields: values: value_status integer(3) record_status Custom field value assignment status
Response Messages:
Code Status Example Body
200 OK 
{
    "email": "mike.johnson@example.com",
    "email_id": "882f7ed8-0eaf-4d36-6f0d-ea91b1bd239c",
    "record_status": 204,
    "tags": [
        {
            "tag": "my-tag",
            "record_status": 200
        }
    ],
    "contacts": [
        {
            "contact": "My City",
            "record_status": 202
        }
    ],
    "lists": [
        {
            "list_id": "c2d73a4d-b66b-17c3-801e-8769f22e1fc2",
            "record_status": 202
        },
        {
            "list_id": "5d16b01e-6927-651b-ef08-548485a0fd55",
            "record_status": 202
        }
    ],
    "fields": [
        {
            "field_id": "591f290e-a2ee-7210-e77b-9245c9290dfc",
            "code": "lorem_ipsum",
            "record_status": 202,
            "values": [
                {
                    "value": 10,
                    "value_status": 202
                }
            ]
        }
    ]
}
Remove a subscriber from a distribution list

DELETE /subscribers/email/{email}/list/{list_id}

Remove a subscriber from a distribution list

Request Parameters:
Name Example Value Default Value Description Type Data Type Required
email 882f7ed8-0eaf-4d36-6f0d-ea91b1bd239c null Email or Email ID path string(100)
list_id 882f7ed8-0eaf-4d36-6f0d-ea91b1bd239c null List ID path string(38)
Example Request URL:
https://api.clevermonitor.com/v1.2/subscribers/email/882f7ed8-0eaf-4d36-6f0d-ea91b1bd239c/list/882f7ed8-0eaf-4d36-6f0d-ea91b1bd239
Response Parameters:
Name Data Type Reference Description
email string(100) Email
email_id string(38) Email ID
list_id string(38) List ID
message string Message
Response Messages:
Code Status Example Body
200 OK 
{
    "email": "john.doe@example.com",
    "email_id": "b75e6092-a820-11e3-9cb5-9c8e99c49306",
    "list_id": "cec09f22-6ddb-11e5-b85d-08002789d050",
    "message": "List assign was deleted!"
}
Remove a tag from a subscriber

DELETE /subscribers/email/{email}/tag

Remove a tag from a subscriber

Request Parameters:
Name Example Value Default Value Description Type Data Type Required
email 882f7ed8-0eaf-4d36-6f0d-ea91b1bd239c null Email or Email ID path string(100)
tag example_tag null Tag body string(100)
Request Example:
{
    "tag": "example_tag"
}
Example Request URL:
https://api.clevermonitor.com/v1.2/subscribers/email/882f7ed8-0eaf-4d36-6f0d-ea91b1bd239c/tag
Response Parameters:
Name Data Type Reference Description
email string(100) Email
email_id string(38) Email ID
tag string(100) Tag
message string Message
Response Messages:
Code Status Example Body
200 OK 
{
    "email": "john.doe@example.com",
    "email_id": "b75e6092-a820-11e3-9cb5-9c8e99c49306",
    "tag": "example_tag",
    "message": "Tag was deleted!"
}
Add custom fields to a subscriber

PUT /subscribers/email/{email}/fields

Add custom fields to a subscriber

Request Parameters:
Name Example Value Default Value Description Type Data Type Required
email john@doe.com null Email or Email ID path string(100)
fields empty Custom fields body array
fields: field_id 882f7ed8-0eaf-4d36-6f0d-ea91b1bd239c null Custom field ID body string(36)
fields: code lorem_ipsum null Custom field code body string(30)
fields: type 1 null Custom field type (required only if it's a new custom field) body reference: field_type
fields: merge false true Merge values body boolean
fields: values empty Custom field values body array
fields: values: value 100 null Subscriber value body mixed
Request Example:
{
    "fields": [
        {
            "code": "lorem_ipsum",
            "merge": false,
            "type": 1,
            "values": [
                100
            ]
        }
    ]
}
Example Request URL:
https://api.clevermonitor.com/v1.2/subscribers/email/john@doe.com/fields
Response Parameters:
Name Data Type Reference Description
email_id string(36) Email ID
email string(100) Email
fields array Custom fields
fields: field_id string(36) Custom field ID
fields: code string(30) Custom field code
fields: values array Subscriber values
fields: values: value mixed Value
fields: values: value_status integer(3) record_status Value status
Response Messages:
Code Status Example Body
200 OK 
{
    "email_id": "46036c14-44ff-8ebb-db63-ce43366cf566",
    "email": "john@doe.com",
    "fields": [
        {
            "field_id": "882f7ed8-0eaf-4d36-6f0d-ea91b1bd239c",
            "code": "lorem_ipsum",
            "values": [
                {
                    "value": 100,
                    "value_status": 200
                }
            ]
        }
    ]
}
Copyright © CleverMonitor, 2018