Live API Reference

This API is an add-on feature of Notificare. It can be used by other systems to get notified about almost everything in your application. From device registration, user data changes, geo-triggers and notifications sent in real-time. Build complex integrations of Notificare that react to users behaviour and other app events using your own infrastructure. Please contact sales@notifica.re to find out the pricing for your current plan.

Configure Service

Before you can use this API, please make sure you read and configure your app as described here.

After successful configuration and activation of this API, you will start receiving Live API events as described below. Note that any change to the Target Endpoint will reset the public and private keys and therefore you will need to repeat the whole process again.

Example Projects

For a hands-on approach, we've created some example projects to help you understand how you would set up your server and handle all the events streamed by this API. Please checkout these examples:

• LIVE API Client for Java
• LIVE API Client for Node.js
• LIVE API Console Example in Node.js
• LIVE API Example for AWS Lambda

LIVE API Events

Below you will find a list of all the events available for you. Live API events are based in Notificare namespaces. The data received will be always directly connected to the type of event and should be handled accordingly.

Events

Sent whenever a public event is created. Only events over notifications received and opened, regions and beacons visits, passes added, removed or redeemed, as well as your own custom events are sent to this API.

1
2
3
4
5
{
"id":"54ac46e8...2e39ca0",
"deviceID":"09260d8b1de06...948c516a",
"userID":"support@notifica.re"
}

Geo-Triggers

Sent whenever a geo-trigger is executed. Geo-triggers can be created based on a region or beacon.

1
2
3
4
5
6
{
"id":"54ac46e8...2e39ca0",
"source":"54ac46e8...2e39ca0",
"deviceID":"09260d8b1de06...948c516a",
"userID":"support@notifica.re"
}

Products

Sent whenever a product is purchased. Only applicable if you are using the Monetize add-on.

1
2
3
4
5
6
{
"id":"54ac46e8...2e39ca0",
"identifier":"com.example.app.prod",
"deviceID":"09260d8b1de06...948c516a",
"userID":"support@notifica.re"
}

Replies

Sent whenever a user replies to an actionable notification.

1
2
3
4
5
6
{
"id":"54ac46e8...2e39ca0",
"notification":"54ac46e8...2e39ca0",
"deviceID":"09260d8b1de06...948c516a",
"userID":"support@notifica.re"
}

Users

Sent whenever a user profile changes. This includes changes to user data, segments or devices.

1
2
3
4
5
6
7
8
9
{
"segment":"54ac46e8...2e39ca0",
"deviceID":"09260d8b1de06...948c516a",
"userID":"support@notifica.re",
"location": {
	"type":"Point",
	"coordinates":[4.773456,51.59808]
	}
}

Devices

Sent whenever device properties changes. This includes changes to tags.

1
2
3
4
{
"tag":"tag_example",
"deviceID":"09260d8b1de06...948c516a"
}

Import

Sent whenever an import job changes status.

1
2
3
{
"id":"54ac46e8...2e39ca0"
}

Expected Response

Your server should reply in a certain manner whenever you handle the verification or the payload of events. This is crucial for this API to be able to either activate the service, discard handled events or retry events whenever your server cannot handle them.

Verification

Before you can start receiving any events, you must implement a verification endpoint. This is the first step to activate the service. Only after a successful verification this LIVE API will start sending all the events that occur in your application. For that make sure you respond with a 200 status code whenever you attempt to validate the service. The response also should include a digest of the public key as the response payload body.

Payload Handling

Once the service is active you will start receiving all events that happen in your application. To signal the LIVE API that you've handle the event and it should be discarded, reply with a 200s code range. In case your server is busy, not accessible or simply you when cannot handle the event, reply with a 400s or 500s code range and our API will keep retrying any event until it gets a successful response from your server.