Version 1.2


Custom fields


Create a custom field


Request Parameters:
Name Example Value Default Value Description Type Data Type Required
code lorem null Custom field code (can contain only lowercase letters, numbers and underscores) body string(30)
name Lorem same as code Custom field name body string(50)
source 1 1 Custom field source body reference: field_source
type 32 null Custom field type body reference: field_type
length 10 null Maximum length (only if enabled for given type, otherwise ignored) body integer(5)
digits 5 null No. decimal places (only if enabled for given type, otherwise ignored) body integer(2)
min_value 10 null Minimum value (only if enabled for given type, otherwise ignored) body mixed(depends on type)
max_value 1000 null Maximum value (only if enabled for given type, otherwise ignored) body mixed(depends on type)
default second test null Default value body mixed(depends on type)
values null Allowed values (only if enabled for given type, otherwise ignored) body array
values: value first test null Value body string(500)
Request Example:
{
    "code": "lorem",
    "name": "Lorem",
    "source": 1,
    "type": 32,
    "default": "second test",
    "values": [
        "first test",
        "second test",
        "third test"
    ]
}
Example Request URL:
https://api.clevermonitor.com/v1.2/fields
Response Parameters:
Name Data Type Reference Description
field_id string(50) Custom field ID
code string(30) Custom field code
name string(50) Custom field name
source integer(1) field_source Custom field source
type integer(2) field_type Custom field type
length integer(5) Maximum length (only if enabled for given type)
digits integer(2) No. decimal places (only if enabled for given type)
min_value mixed(depends on type) Minimum value (only if enabled for given type)
max_value mixed(depends on type) Maximum value (only if enabled for given type)
default mixed(depends on type) Default value
values array Allowed values (only if enabled for given type)
values: value string(500) Value
Response Messages:
Code Status Example Body
201 OK
{
    "field_id": "597620e2-3023-8233-4ace-2348061a40a1",
    "code": "lorem",
    "name": "Lorem",
    "source": 1,
    "type": 32,
    "default": "second test",
    "values": [
        {
            "value": "first test",
            "status": 200
        },
        {
            "value": "second test",
            "status": 200
        },
        {
            "value": "third test",
            "status": 200
        }
    ]
}

Custom fields overview


Request Parameters:
Name Example Value Default Value Description Type Data Type Required
source 1 all sources Custom field source Query reference: field_source
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/fields/?source=1&count=10&offset=0
Response Parameters:
Name Data Type Reference Description
field_id string(50) Custom field ID
code string(30) Custom field code
name string(50) Custom field name
source integer(1) field_source Custom field source
type integer(2) field_type Custom field type
length integer(5) Maximum length (only if enabled for given type)
digits integer(2) No. decimal places (only if enabled for given type)
min_value mixed(depends on type) Minimum value (only if enabled for given type)
max_value mixed(depends on type) Maximum value (only if enabled for given type)
default mixed(depends on type) Default value
Response Messages:
Code Status Example Body
200 OK
[
    {
        "field_id": "84aa546d-cfc9-783e-0c96-dcf9c2c2c71c",
        "code": "ipsum",
        "name": "Ipsum",
        "source": 1,
        "type": 21,
        "length": 1000,
        "default": "Lorem ipsum dolor sit amet"
    },
    {
        "field_id": "d3c0b14a-1e98-ebb6-c5a2-c24e9621cba4",
        "code": "lorem",
        "name": "Lorem",
        "source": 1,
        "type": 1,
        "length": 4,
        "min_value": "10",
        "max_value": "1000",
        "default": "100"
    }
]

Custom field detail


Request Parameters:
Name Example Value Default Value Description Type Data Type Required
field_id lorem null Custom field ID or Custom field code Query string(38)
Example Request URL:
https://api.clevermonitor.com/v1.2/fields/lorem
Response Parameters:
Name Data Type Reference Description
field_id string(38) Custom field ID
code string(30) Custom field code
name string(50) Custom field name
source integer(1) field_source Custom field source
type integer(2) field_type Custom field type
length integer(5) Maximum length (only if enabled for given type)
digits integer(2) No. decimal places (only if enabled for given type)
min_value mixed(depends on type) Minimum value (only if enabled for given type)
max_value mixed(depends on type) Maximum value (only if enabled for given type)
default mixed(depends on type) Default value
Response Messages:
Code Status Example Body
200 OK
{
    "field_id": "d3c0b14a-1e98-ebb6-c5a2-c24e9621cba4",
    "code": "lorem",
    "name": "Lorem",
    "source": 1,
    "type": 1,
    "length": 4,
    "min_value": "10",
    "max_value": "1000",
    "default": "100"
}

Edit a custom field


Request Parameters:
Name Example Value Default Value Description Type Data Type Required
field_id 597620e2-3023-8233-4ace-2348061a40a1 null Custom field ID or Custom field code path string(38)
code lorem null Custom field code (can contain only lowercase letters, numbers and underscores) body string(30)
name Lorem same as code Custom field name body string(50)
type 32 null Custom field type body reference: field_type
length 10 null Maximum length (only if enabled for given type, otherwise ignored) body integer(5)
digits 5 null No. decimal places (only if enabled for given type, otherwise ignored) body integer(2)
min_value 10 null Minimum value (only if enabled for given type, otherwise ignored) body mixed(depends on type)
max_value 1000 null Maximum value (only if enabled for given type, otherwise ignored) body mixed(depends on type)
default fifth test null Default value body mixed(depends on type)
values null Allowed values (only if enabled for given type, otherwise ignored) body array
values: value third test null Value body string(500)
Request Example:
{
    "name": "New Name",
    "default": "fifth test",
    "values": [
        "third test",
        "fourth test",
        "fifth test"
    ]
}
Example Request URL:
https://api.clevermonitor.com/v1.2/fields/597620e2-3023-8233-4ace-2348061a40a1
Response Parameters:
Name Data Type Reference Description
field_id string(50) Custom field ID
code string(30) Custom field code
name string(50) Custom field name
source integer(1) field_source Custom field source
type integer(2) field_type Custom field type
length integer(5) Maximum length (only if enabled for given type)
digits integer(2) No. decimal places (only if enabled for given type)
min_value mixed(depends on type) Minimum value (only if enabled for given type)
max_value mixed(depends on type) Maximum value (only if enabled for given type)
default mixed(depends on type) Default value
values array Allowed values (only if enabled for given type)
values: value string(500) Value
Response Messages:
Code Status Example Body
200 OK
{
    "field_id": "597620e2-3023-8233-4ace-2348061a40a1",
    "code": "lorem",
    "name": "New Name",
    "source": 1,
    "type": 32,
    "default": "fifth test",
    "values": [
        {
            "value": "third test",
            "status": 202
        },
        {
            "value": "fourth test",
            "status": 200
        },
        {
            "value": "fifth test",
            "status": 200
        }
    ]
}

Delete a custom field


Request Parameters:
Name Example Value Default Value Description Type Data Type Required
field_id 597620e2-3023-8233-4ace-2348061a40a1 null Custom field ID or Custom field code Query string(38)
Example Request URL:
https://api.clevermonitor.com/v1.2/fields/597620e2-3023-8233-4ace-2348061a40a1
Response Parameters:
Name Data Type Reference Description
field_id string(38) Custom field ID
message string Message
Response Messages:
Code Status Example Body
200 OK
{
    "field_id": "597620e2-3023-8233-4ace-2348061a40a1",
    "message": "Custom field deleted"
}

Add values to a custom field


Request Parameters:
Name Example Value Default Value Description Type Data Type Required
field_id 597620e2-3023-8233-4ace-2348061a40a1 null Custom field ID or Custom field code Query string(38)
values null Values to add to custom field body array
value first test null Value body string(500)
Request Example:
{
    "values": [
        "first test",
        "second test",
        "third test"
    ]
}
Example Request URL:
https://api.clevermonitor.com/v1.2/fields/597620e2-3023-8233-4ace-2348061a40a1/values
Response Parameters:
Name Data Type Reference Description
field_id string(38) Custom field ID
code string(30) Custom field code
processed integer Number of processed values
value_new integer No. of newly added values
value_exists integer No. of already existing values
value_error integer No. of incorrect values
processed_values array Processed values
processed_values: value string(500) Requested value
processed_values: value_status integer(3) record_status Record status
Response Messages:
Code Status Example Body
200 OK
{
    "field_id": "597620e2-3023-8233-4ace-2348061a40a1",
    "code": "lorem",
    "processed": 3,
    "value_new": 2,
    "value_exists": 1,
    "value_error": 0,
    "processed_values": [
        {
            "value": "first test",
            "status": 202
        },
        {
            "value": "second test",
            "status": 200
        },
        {
            "value": "third test",
            "status": 200
        }
    ]
}

Custom field values overview


Request Parameters:
Name Example Value Default Value Description Type Data Type Required
field_id 597620e2-3023-8233-4ace-2348061a40a1 null Custom field ID or Custom field code Query string(38)
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/fields/597620e2-3023-8233-4ace-2348061a40a1/values?count=10&offset=0
Response Parameters:
Name Data Type Reference Description
values array Values of custom field
values: value string(500) Value
Response Messages:
Code Status Example Body
200 OK
{
    "values": [
        "first test",
        "second test",
        "third test",
        "fourth test"
    ]
}

Delete values from a custom field


Request Parameters:
Name Example Value Default Value Description Type Data Type Required
field_id 597620e2-3023-8233-4ace-2348061a40a1 null Custom field ID or Custom field code Query string(38)
values null Values to delete from custom field body array
value second test null Value body string(500)
Request Example:
{
    "values": [
        "second test",
        "third test",
        "fourth test"
    ]
}
Example Request URL:
https://api.clevermonitor.com/v1.2/fields/597620e2-3023-8233-4ace-2348061a40a1/values
Response Parameters:
Name Data Type Reference Description
field_id string(38) Custom field ID
code string(30) Custom field code
processed integer Number of processed values
value_delete array Deleted values
value_delete: value string(500) Value
value_error array Incorrectly processed values
value_error: value string(500) Value
Response Messages:
Code Status Example Body
200 OK
{
    "field_id": "597620e2-3023-8233-4ace-2348061a40a1",
    "code": "lorem",
    "processed": 3,
    "value_delete": [
        "second test",
        "third test"
    ],
    "value_error": [
        "fourth test"
    ]
}

Add values of a custom field to subscribers


Request Parameters:
Name Example Value Default Value Description Type Data Type Required
field_id 597620e2-3023-8233-4ace-2348061a40a1 null Custom field ID or Custom field code Query string(38)
merge true true Replace all already stored values of subscriber body boolean
auto_create_value true true Automatically create new values for custom field definition body boolean
auto_create_subscriber true false Automatically create new subscriber, if non-existent body boolean
subscribers null Subscribers and values for them body array
subscribers: email james@smith.com null Subscriber's Email (this or email_id required) body string(100)
subscribers: email_id d7789c9c-30e6-12c4-b00c-3706e4582058 null Subscriber's Email ID (this or email required) body string(38)
subscribers: values null Values for subscriber body array
subscribers: values: value first test null Value body string(500)
Request Example:
{
    "merge": true,
    "auto_create_value": true,
    "auto_create_subscriber": true,
    "subscribers": [
        {
            "email_id": "d7789c9c-30e6-12c4-b00c-3706e4582058",
            "values": [
                "first test",
                "second test"
            ]
        },
        {
            "email": "james@smith.com",
            "values": [
                "third test"
            ]
        },
        {
            "email": "not-email",
            "values": [
                "fourth test"
            ]
        }
    ]
}
Example Request URL:
https://api.clevermonitor.com/v1.2/fields/597620e2-3023-8233-4ace-2348061a40a1/subscribers
Response Parameters:
Name Data Type Reference Description
field_id string(38) Custom field ID
code string(30) Custom field code
subscribers_new integer No. of newly created subscribers
subscribers_exists integer No. of already existing subscribers
subscribers_error integer No. of incorrect subscribers
processed_subscribers array Processed subscribers
processed_subscribers: email string(100) Subscriber's Email (if an error occurs, this value is taken from the request)
processed_subscribers: email_id string(38) Subscriber's Email ID (if an error occurs, this value is taken from the request)
processed_subscribers: subscriber_status integer(3) record_status Subscriber's status
processed_subscribers: values array Values given for subscriber
processed_subscribers: values: value string(500) Value
processed_subscribers: values: value_status integer(3) Value status
Response Messages:
Code Status Example Body
200 OK
{
    "field_id": "597620e2-3023-8233-4ace-2348061a40a1",
    "code": "lorem",
    "subscribers_new": 1,
    "subscribers_exists": 1,
    "subscribers_error": 1,
    "processed_subscribers": [
        {
            "email": "john@doe.com",
            "email_id": "d7789c9c-30e6-12c4-b00c-3706e4582058",
            "subscriber_status": 202,
            "values": [
                {
                    "value": "first test",
                    "value_status": 200
                },
                {
                    "value": "second test",
                    "value_status": 200
                }
            ]
        },
        {
            "email": "james@smith.com",
            "email_id": "6aa9ab71-853b-6306-ed9f-897075e40901",
            "subscriber_status": 200,
            "values": [
                {
                    "value": "third test",
                    "value_status": 200
                }
            ]
        },
        {
            "email": "not-email",
            "email_id": null,
            "subscriber_status": 401,
            "values": {
                "value": "fourth test",
                "value_status": 411
            }
        }
    ]
}

Overview of values assigned to subscribers


Request Parameters:
Name Example Value Default Value Description Type Data Type Required
field_id 597620e2-3023-8233-4ace-2348061a40a1 null Custom field ID or Custom field code Query string(38)
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/fields/597620e2-3023-8233-4ace-2348061a40a1/subscribers?count=10&offset=0
Response Parameters:
Name Data Type Reference Description
field_id string(38) Custom field ID
code string(30) Custom field code
subscribers array Subscribers
subscribers: email string(100) Subscriber's Email
subscribers: values array Values assigned to subscriber
subscribers: values: value string(500) Value
Response Messages:
Code Status Example Body
200 OK
{
    "field_id": "597620e2-3023-8233-4ace-2348061a40a1",
    "code": "lorem",
    "subscribers": [
        {
            "email": "john@doe.com",
            "values": [
                "first test",
                "second test"
            ]
        },
        {
            "email": "james@smith.com",
            "values": [
                "third test"
            ]
        }
    ]
}

Delete values of a custom field from subscribers


Request Parameters:
Name Example Value Default Value Description Type Data Type Required
field_id 597620e2-3023-8233-4ace-2348061a40a1 null Custom field ID or Custom field code Query string(38)
subscribers null Subscribers and values for them body array
subscribers: email james@smith.com null Subscriber's Email (this or email_id required) body string(100)
subscribers: email_id d7789c9c-30e6-12c4-b00c-3706e4582058 null Subscriber's Email ID (this or email required) body string(38)
subscribers: values null Values for subscriber (only considered for type 32 - LIST) body array
subscribers: values: value first test null Value body string(500)
Request Example:
{
    "subscribers": [
        {
            "email_id": "d7789c9c-30e6-12c4-b00c-3706e4582058",
            "values": [
                "first test",
                "second test"
            ]
        },
        {
            "email": "james@smith.com",
            "values": [
                "second test",
                "third test"
            ]
        },
        {
            "email": "not-email",
            "values": [
                "first test"
            ]
        }
    ]
}
Example Request URL:
https://api.clevermonitor.com/v1.2/fields/597620e2-3023-8233-4ace-2348061a40a1/subscribers
Response Parameters:
Name Data Type Reference Description
field_id string(38) Custom field ID
code string(30) Custom field code
processed integer No. of processed values
value_delete array Succesfully deleted values
value_delete: email string(100) Email for assigning
value_delete: value string(500) Value
value_error array Incorrectly processed values
value_error: email string(100) Email for assigning
value_error: value string(500) Value
Response Messages:
Code Status Example Body
200 OK
{
    "field_id": "597620e2-3023-8233-4ace-2348061a40a1",
    "code": "lorem",
    "processed": 6,
    "value_delete": [
        {
            "email": "john@doe.com",
            "value": "first test"
        },
        {
            "email": "john@doe.com",
            "value": "second test"
        },
        {
            "email": "john@doe.com",
            "value": "third test"
        },
        {
            "email": "james@smith.com",
            "value": "second test"
        },
        {
            "email": "james@smith.com",
            "value": "third test"
        }
    ],
    "value_error": [
        {
            "email": "not-email",
            "value": "first test"
        }
    ]
}

Copyright © CleverMonitor, 2017