NAV Nav

Introduction

The Notific API allows you to manage your recipients and notifications through a simple REST API.

URI

Notific API is hosted on the following base URI:

https://api.notific.io/v1/APP_ID_HERE

Note! Use your APP_ID as part of the URI. You can generate your API key and API token at:

https://app.notific.io/api

Headers

Make sure you have the following content type headers set on every request:

Accept: application/json Content-Type: application/json

Authentication

In order to use the API, you should authenticate your request by including your API key as a bearer token value:

Authorization: Bearer API_TOKEN_HERE

Response & Pagination

Response item(s) are wrapped into data. In case of list, additional information is wrapped into links and meta.

{
    "data": [
        {
            "id": "123",
            "name": "Kung Fury",
            "email": "kung.fury@mail.com"
        }
    ],
    "links": {
        "first": "https://api.notific.io/v1/APP_ID/recipients?page=1",
        "last": "https://api.notific.io/v1/APP_ID/recipients?page=1",
        "prev": null,
        "next": null
    },
    "meta": {
        "current_page": 1,
        "from": 1,
        "last_page": 1,
        "path": "https://api.notific.io/v1/APP_ID/recipients",
        "per_page": 15,
        "to": 1,
        "total": 1
    }
}

Requests that return multiple items respond to ?page and ?limit parameters. By default response limit is set to 15. For example:

/recipients?page=2&limit=25

Errors

Notific uses conventional https response codes to indicate the success or failure of an API request. The table below contains a summary of the typical response codes:

Code Meaning
200 OK
201 Created -- The resource was created
204 No content -- The resource was deleted
400 Bad Request
401 Unauthorized -- No valid API Key was given.
403 Forbidden
404 Not Found
422 Unprocessable Entity -- The payload has missing required parameters or invalid data was given.
429 Too Many Requests
500 Internal Server Error
503 Service Unavailable -- We*re temporarially offline for maintanance. Please try again later.

Recipients

List Recipients

https Request

GET v1/APP_ID/recipients

GET v1/APP_ID/recipients?filter[tags]=foo,bar

GET v1/APP_ID/recipients?filter[tags]=foo,bar&filter[name]=kung&sort=-created_at

Query Parameters

Parameter Description
filter Allowed filters tags, name and email.
sort Sort by name, email or created_at. Sorting is ascending by default. Adding a hyphen (-) to the start of the property name will reverse the results collection.

Example request:

curl -X GET "https://api.notific.io/v1/APP_ID/recipients" \
-H "Accept: application/json" \
-H "Authorization: Bearer API_TOKEN_HERE"

Example response:

{
    "data": [
        {
            "id": "123",
            "name": "Kung Fury",
            "email": "kung.fury@mail.com",
            "meta": {
              "tile" : "detective"
            },
            "created_at": {
                "date": "2018-03-23 10:11:25.000000",
                "timezone_type": 3,
                "timezone": "UTC"
            },
            "tags": [
              "Foo"
            ]
        }
    ],
    "links": {
        "first": "https://api.notific.io/v1/APP_ID/recipients?page=1",
        "last": "https://api.notific.io/v1/APP_ID/recipients?page=1",
        "prev": null,
        "next": null
    },
    "meta": {
        "current_page": 1,
        "from": 1,
        "last_page": 1,
        "path": "https://api.notific.io/v1/APP_ID/recipients",
        "per_page": 15,
        "to": 1,
        "total": 1
    }
}

Create Recipient

https Request

POST v1/APP_ID/recipients

Parameters

Parameter Type Status Rules Description
id string required Minimum: 1, Maximum: 255, Unique Unique identifier for recipient. For example running number, UUID or hash.
name string optional Maximum: 255 Recipient name that you can refer in notifications.
email email optional Maximum: 255 An email address where you can optionally send notifications.
meta string optional Must be a valid JSON string. Meta information about recipients can be referred in notification just as name.
tags array optional Recipients can be tagged to send private notifications easily for certain groups.
remove-tags array optional Remove tags from recipient.
remove-all-tags boolean optional Remove all tags from recipient. You can remove all tags and add new tags in the same request.

Any additional parameters will be merged into meta information.

Example request:

curl -X POST "https://api.notific.io/v1/APP_ID/recipients" \
-H "Accept: application/json" \
-H "Authorization: Bearer API_TOKEN_HERE" \
    -d "id"="123" \
    -d "name"="Kung Fury" \
    -d "email"="kung.fury@mail.com" \
    -d "meta"=*{"title":"detective"}* \
    -d "phone"="+358 40 123 4567" \
    -d "tags[]"="Foo" \

Example response:

{
    "data":
        {
            "id": "123",
            "name": "Kung Fury",
            "email": "kung.fury@mail.com",
            "meta": {
              "title" : "detective",
              "phone" : "+358 40 123 4567"
            },
            "created_at": {
                            "date": "2018-03-23 10:11:25.000000",
                            "timezone_type": 3,
                            "timezone": "UTC"
            },
            "tags": [
              "Foo"
            ]
        }
}

Get Recipient

https Request

GET v1/APP_ID/recipients/{id}

Example request:

curl -X GET "https://api.notific.io/v1/APP_ID/recipients/{id}" \
-H "Accept: application/json" \
-H "Authorization: Bearer API_TOKEN_HERE" \

Example response:

{
    "data": {
        "id": "123",
        "name": "Kung Fury",
        "email": "kung.fury@mail.com",
        "meta": {
          "title" : "detective",
          "phone" : "+358 40 123 4567"
        },
        "created_at": {
                        "date": "2018-03-23 10:11:25.000000",
                        "timezone_type": 3,
                        "timezone": "UTC"
        },
         "tags": [
          "Foo"
        ],
        "notifications": [
            {
                "id": "y7zpq9z5o9",
                "type": 1,
                "title": "Kung Fury meets the Viking valkyries Barbarianna",
                "body": "Proin rhoncus quam et ante hendrerit faucibus. Aenean tincidunt semper sapien sit amet placerat. Morbi eu lorem sit amet erat pharetra dignissim. Phasellus ultrices lectus in ante posuere iaculis.",
                "url": null,
                "template": false,
                "created_at": {
                    "date": "2018-02-26 01:13:52.000000",
                    "timezone_type": 3,
                    "timezone": "UTC"
                },
                "delivered_at": {
                    "date": "2018-02-26 01:13:52.000000",
                    "timezone_type": 3,
                    "timezone": "UTC"
                },
                "read_at": null
            }
        ]
    }
}

Update Recipient

https Request

PUT v1/APP_ID/recipients/{id}

Parameters

Parameter Type Status Rules Description
id string optional Minimum: 1, Maximum: 255, Unique Unique identifier for recipient. For example running number, UUID or hash.
name string optional Maximum: 255 Recipient name that you can refer in notifications.
email email optional Maximum: 255 An email address where you can optionally send notifications.
meta string optional Must be a valid JSON string. Meta information about recipients can be referred in notification just as name.
tags array optional Recipients can be tagged to send private notifications easily for certain groups.
remove-tags array optional Remove tags from recipient.
remove-all-tags boolean optional Remove all tags from recipient. You can remove all tags and add new tags in the same request.

Example request:

curl -X PUT "https://api.notific.io/v1/APP_ID/recipients/{id}" \
-H "Accept: application/json" \
-H "Authorization: Bearer API_TOKEN_HERE" \
    -d "name"="Kung Fury" \
    -d "email"="kung.fury@mail.com" \
    -d "tags[]"="Bar" \
    -d "remove-all-tags"="1" \

Example response:

{
    "data":
        {
            "id": "123",
            "name": "Kung Fury",
            "email": "kung.fury@mail.com",
            "meta": {
              "title" : "detective",
              "phone" : "+358 40 123 4567"
            },
            "tags": [
              "Bar"
            ]
        }
}

Delete Recipient

https Request

DELETE v1/APP_ID/recipients/{id}

Example request:

curl -X DELETE "https://api.notific.io/v1/APP_ID/recipients/{id}" \
-H "Accept: application/json" \
-H "Authorization: Bearer API_TOKEN_HERE"

Public Notifications

List Public Notifications

https Request

GET v1/APP_ID/public-notifications

GET v1/APP_ID/public-notifications?filter[title]=Plot

GET v1/APP_ID/public-notifications?filter[type]=1,2,3&sort=-created_at

Query Parameters

Parameter Description
filter Allowed filters type, title, body, url, new_till, active_till, published_at, delay, created_at and published_at
sort Sort by type, title, body, url, new_till, active_till, published_at, delay, created_at or published_at. Sorting is ascending by default. Adding a hyphen (-) to the start of the property name will reverse the results collection.

Example request:

curl -X GET "https://api.notific.io/v1/APP_ID/public-notifications" \
-H "Accept: application/json" \
-H "Authorization: Bearer API_TOKEN_HERE" \

Example response:

{
    "data": [
        {
            "id": "80451o9p13",
            "type": 1,
            "title": "Plot",
            "body": "Sometime in the early 1980s, Miami-Dade Police...",
            "url": null,
            "new_till": null,
            "active_till": null,
            "created_at": {
                "date": "2018-02-26 00:55:31.000000",
                "timezone_type": 3,
                "timezone": "UTC"
            },
            "updated_at": {
                "date": "2018-02-26 00:55:31.000000",
                "timezone_type": 3,
                "timezone": "UTC"
            }
        }
    ],
    "links": {
        "first": "https://api.notific.io/v1/APP_ID/public-notifications?page=1",
        "last": "https://api.notific.io/v1/APP_ID/public-notifications?page=1",
        "prev": null,
        "next": null
    },
    "meta": {
        "current_page": 1,
        "from": 1,
        "last_page": 1,
        "path": "https://api.notific.io/v1/APP_ID/public-notifications",
        "per_page": 15,
        "to": 1,
        "total": 1
    }
}

Create Public Notification

https Request

POST v1/APP_ID/public-notifications

Parameters

Parameter Type Status Rules Description
status boolean optional Boolean Toggle notification visibility.
type string optional 1, 2, 3, 4 or 5 Notifications have different color codes. General, success, info, warning, danger.
title string required Maximum: 100 Short notification title.
body string optional Maximum: 65535 Required if the parameters url are not present. Notification body.
url url optional Maximum: 255 If url is set, the notification will open given url in a new browser tab.
new_till date optional YYYY-MM-DD HH:MM:SS Date and time, after which the notification will be marked as read regardless of whether the visitor has actually read it.
active_till date optional YYYY-MM-DD HH:MM:SS Date and time, after which the notification will not be visible to visitors anymore.
published_at date optional YYYY-MM-DD HH:MM:SS Date and time, after which the notification will be published.
delay integer optional Maximum: 600 Delay in seconds, after which the notification will be shown to a visitor.

Example request:

curl -X POST "https://api.notific.io/v1/APP_ID/public-notifications" \
-H "Accept: application/json" \
-H "Authorization: Bearer API_TOKEN_HERE" \
    -d "status"="1" \
    -d "type"="1" \
    -d "title"="Send him back in time" \
    -d "body"="" \
    -d "url"="https://en.wikipedia.org/wiki/Kung_Fury_(film)" \

Example response:

{
    "data":
        {
            "id": "80451o9p13",
            "type": 1,
            "title": "Send him back in time",
            "body": "",
            "url": "https://en.wikipedia.org/wiki/Kung_Fury_(film)",
            "created_at": {
                "date": "2018-02-26 00:55:31.000000",
                "timezone_type": 3,
                "timezone": "UTC"
            },
            "updated_at": {
                "date": "2018-02-26 00:55:31.000000",
                "timezone_type": 3,
                "timezone": "UTC"
            }
        }
 }

Update Public Notification

https Request

PUT v1/APP_ID/public-notifications/{id}

Parameters

Parameter Type Status Rule Description
status boolean optional
type string optional 1, 2, 3, 4 or 5 Notifications have different color codes. General, success, info, warning, danger.
title string required Maximum: 100
body string optional Maximum: 65535 Required if the parameters url are not present. Notification body.
url url optional Maximum: 255
new_till date optional YYYY-MM-DD HH:MM:SS Date and time, after which the notification will be marked as read regardless of whether the visitor has actually read it.
active_till date optional YYYY-MM-DD HH:MM:SS Date and time, after which the notification will not be visible to visitors anymore.
published_at date optional YYYY-MM-DD HH:MM:SS Date and time, after which the notification will be published.
delay integer optional Maximum: 600 Delay in seconds, after which the notification will be shown to a visitor.

Example request:

curl -X PUT "https://api.notific.io/v1/APP_ID/public-notifications/{id}" \
-H "Accept: application/json" \
-H "Authorization: Bearer API_TOKEN_HERE" \
    -d "status"="1" \
    -d "type"="5" \
    -d "title"="Send him back in time" \
    -d "body"="" \
    -d "url"="https://en.wikipedia.org/wiki/Kung_Fury_(film)" \

Get Public Notification

https Request

GET v1/APP_ID/public-notifications/{id}

Example request:

curl -X GET "https://api.notific.io/v1/APP_ID/public-notifications/{id}" \
-H "Accept: application/json"
-H "Authorization: Bearer API_TOKEN_HERE"

Example response:

{
    "data":
        {
            "id": "80451o9p13",
            "type": 1,
            "title": "Send him back in time",
            "body": "",
            "url": "https://en.wikipedia.org/wiki/Kung_Fury_(film)",
            "created_at": {
                "date": "2018-02-26 00:55:31.000000",
                "timezone_type": 3,
                "timezone": "UTC"
            },
            "updated_at": {
                "date": "2018-02-26 00:55:31.000000",
                "timezone_type": 3,
                "timezone": "UTC"
            }
        }
 }

Delete Public Notification

https Request

DELETE v1/APP_ID/public-notifications/{id}

Example request:

curl -X DELETE "https://api.notific.io/v1/APP_ID/public-notifications/{id}" \
-H "Accept: application/json"
-H "Authorization: Bearer API_TOKEN_HERE"

Private Notifications

List Private Notifications

https Request

GET v1/APP_ID/private-notifications

GET v1/APP_ID/private-notifications?filter[title]=hack%20into

GET v1/APP_ID/private-notifications?filter[type]=1,2,3&filter[template]=true&sort=-created_at

Query Parameters

Parameter Description
filter Allowed filters type, title, body, url, template and created_at
sort Sort by type, title, body, url, template or created_at. Sorting is ascending by default. Adding a hyphen (-) to the start of the property name will reverse the results collection.

Example request:

curl -X GET "https://api.notific.io/v1/APP_ID/private-notifications" \
-H "Accept: application/json" \
-H "Authorization: Bearer API_TOKEN_HERE"

Example response:

{
    "data": [
        {
            "id": "9ldj92z5gz",
            "type": 2,
            "title": "Tyrannosaurus hack into the timeline",
            "body": "Quisque quis mi vel neque tristique maximus at vitae velit...",
            "url": null,
            "created_at": {
                "date": "2018-02-26 01:00:09.000000",
                "timezone_type": 3,
                "timezone": "UTC"
            }
        },
        {
            "id": "gdvj8dw5x3",
            "type": 3,
            "title": "Thor drops his hammer",
            "body": "Proin rhoncus quam et ante hendrerit faucibus...",
            "url": null,
            "created_at": {
                "date": "2018-02-26 01:08:40.000000",
                "timezone_type": 3,
                "timezone": "UTC"
            }
        }
    ],
    "links": {
        "first": "https://api.notific.io/v1/APP_ID/private-notifications?page=1",
        "last": "https://api.notific.io/v1/APP_ID/private-notifications?page=1",
        "prev": null,
        "next": null
    },
    "meta": {
        "current_page": 1,
        "from": 1,
        "last_page": 1,
        "path": "https://api.notific.io/v1/APP_ID/private-notifications",
        "per_page": 15,
        "to": 2,
        "total": 2
    }
}

Create Private Notification

https Request

POST v1/APP_ID/private-notifications

Parameters

Parameter Type Status Rule Description
type string optional 1, 2, 3, 4 or 5 Notifications have different color codes. General, success, info, warning, danger.
title string required Maximum: 100 Short notification title.
body string optional Maximum: 65535 Required if the parameters url is not present. Notification body.
url url optional Maximum: 255 If url is set, the notification will open given url in a new browser tab.
template boolean optional Templates can be edited and be used when sending private notifications.
name string optional Required if the parameters template are present. A name to refer when sending private notifications that are based on template.

Example request:

curl -X POST "https://api.notific.io/v1/APP_ID/private-notifications" \
-H "Accept: application/json" \
-H "Authorization: Bearer API_TOKEN_HERE" \
    -d "type"="5" \
    -d "title"="Tyrannosaurus hack into the timeline" \
    -d "body"="Quisque quis mi vel neque tristique maximus at vitae velit..." \
    -d "url"="" \
    -d "template"="0" \
    -d "name"="" \

Get Private Notification

https Request

GET v1/APP_ID/private-notifications/{id}

Example request:

curl -X GET "https://api.notific.io/v1/APP_ID/private-notifications/{id}" \
-H "Accept: application/json" \
-H "Authorization: Bearer API_TOKEN_HERE" \
-d "id"="9ldj92z5gz"

Example response:ΒΆ

{
    "data": {
       "id": "9ldj92z5gz",
       "type": 1,
       "title": "Tyrannosaurus hack into the timeline",
       "body": "Quisque quis mi vel neque tristique maximus at vitae velit...",
       "url": null,
       "created_at": {
          "date": "2018-02-26 01:00:09.000000",
          "timezone_type": 3,
          "timezone": "UTC"
       }
    }
}

Send Private Notification

https Request

POST v1/APP_ID/private-notifications/{id}/recipients

Parameters

Parameter Type Status Rule Description
recipients string or array optional Exists. Required if the parameter tags is not present. List of recipient ID:s.
tags array optional Exists. Required if the parameter recipients is not present. To send the notification to all recipients use all -tag.
channels array optional Available channels broadcast or mail. mail channel requires valid mail settings. Delivery channels.
meta json optional Must be a valid JSON string. You may pass variables to the notification that will be accessible in message. There is two different format. Same variables to all recipients: {"link":"https://notific.io"}. Recipient specific variables: {"recipient1":{"token":"foo"}, "recipient2":{"token":"bar"}}.
test boolean optional 0 or 1 Send the notification as test to your self at https://app.notific.io.

Example request:

curl -X POST "https://api.notific.io/v1/APP_ID/private-notifications/{id}/recipients" \
-H "Accept: application/json" \
-H "Authorization: Bearer API_TOKEN_HERE"
-d "recipients[]"="123" \

Example response:

{
    "data": {
        "count": 1
    }
}

Get Private Notification Recipients

https Request

GET v1/APP_ID/private-notifications/{id}/recipients

Example request:

curl -X GET "https://api.notific.io/v1/APP_ID/private-notifications/{id}/recipients" \
-H "Accept: application/json" \
-H "Authorization: Bearer API_TOKEN_HERE"

Example response:

{
    "data": [
      {
          "id": "123",
          "name": "Kung Fury",
          "email": "kung.fury@mail.com"
      }
    ],
    "links": {
        "first": "https://api.notific.io/v1/APP_ID/private-notifications/9ldj92z5gz/recipients?page=1",
        "last": "https://api.notific.io/v1/APP_ID/private-notifications/9ldj92z5gz/recipients?page=1",
        "prev": null,
        "next": null
    },
    "meta": {
        "current_page": 1,
        "from": 1,
        "last_page": 1,
        "path": "https://api.notific.io/v1/APP_ID/private-notifications/9ldj92z5gz/recipients",
        "per_page": 15,
        "to": 1,
        "total": 1
    }
}

Templates

List Templates

https Request

GET v1/APP_ID/templates

Example request:

curl -X GET "https://api.notific.io/v1/APP_ID/templates" \
-H "Accept: application/json" \
-H "Authorization: Bearer API_TOKEN_HERE"

Example response:

{
    "data": [
        {
            "id": "gdvj8dw5x3",
            "type": 1,
            "name": "back-in-miami",
            "title": "Back in 1985 Miami",
            "body": "Back in 1985 Miami, Kung Fury once again battles and defeats the arcade machine robot...",
            "url": null,
            "template": true,
            "created_at": {
                "date": "2018-02-26 01:08:40.000000",
                "timezone_type": 3,
                "timezone": "UTC"
            },
            "updated_at": {
                "date": "2018-02-26 01:08:40.000000",
                "timezone_type": 3,
                "timezone": "UTC"
            }
        }
    ],
    "links": {
        "first": "https://api.notific.io/v1/APP_ID/templates?page=1",
        "last": "https://api.notific.io/v1/APP_ID/templates?page=1",
        "prev": null,
        "next": null
    },
    "meta": {
        "current_page": 1,
        "from": 1,
        "last_page": 1,
        "path": "https://api.notific.io/v1/APP_ID/templates",
        "per_page": 15,
        "to": 1,
        "total": 1
    }
}

Create Template

https Request

POST v1/APP_ID/templates

Parameters

Parameter Type Status Rule Description
type string optional 1, 2, 3, 4 or 5 Notifications have different color codes. General, success, info, warning, danger.
title string required Maximum: 100 Short notification title.
body string optional Maximum: 65535 Required if the parameters url is not present. Notification body.
url url optional Maximum: 255 If url is set, the notification will open given url in a new browser tab.
name string optional Required if the parameters template are present. A name to refer when sending private notifications that are based on template.

Example request:

curl -X POST "https://api.notific.io/v1/APP_ID/templates" \
-H "Accept: application/json" \
-H "Authorization: Bearer API_TOKEN_HERE" \
    -d "type"="1" \
    -d "title"="Back in 1985 Miami" \
    -d "body"="Back in 1985 Miami, Kung Fury once again battles and defeats the arcade machine robot..." \
    -d "url"="" \
    -d "template"="1" \
    -d "name"="back-in-miami" \

Get Template

https Request

GET v1/APP_ID/templates/{name}

Example request:

curl -X GET "https://api.notific.io/v1/APP_ID/templates/{name}" \
-H "Accept: application/json" \
-H "Authorization: Bearer API_TOKEN_HERE"
-d "name"="back-in-miami" \

Example response:

{
    "data": {
        "id": "gdvj8dw5x3",
        "type": 1,
        "name": "back-in-miami",
        "title": "Back in 1985 Miami",
        "body": "Back in 1985 Miami, Kung Fury once again battles and defeats the arcade machine robot...",
        "url": null,
        "template": true,
        "created_at": {
            "date": "2018-02-26 01:08:40.000000",
            "timezone_type": 3,
            "timezone": "UTC"
        },
        "updated_at": {
            "date": "2018-02-26 01:08:40.000000",
            "timezone_type": 3,
            "timezone": "UTC"
        }
    }
}