Live API Reference

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 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.

PropertyExampleDescriptionType
serviceMy ServiceThe human readable string that describes this Live API serviceString
typere.notifica.event.notification.Received The event's Notificare namespace. Available namespaces for events:
  • re.notifica.event.notification.Receive
  • re.notifica.event.notification.Open
  • re.notifica.event.region.Session
  • re.notifica.event.beacon.Session
  • re.notifica.event.asset.Load
  • re.notifica.event.scannable.Scan
  • re.notifica.event.pass.Add
  • re.notifica.event.pass.Remove
  • re.notifica.event.pass.Redeem
  • re.notifica.event.custom.*
String
data
1
2
3
4
5
{
"id":"54ac46e8...2e39ca0",
"deviceID":"09260d8b1de06...948c516a",
"userID":"support@notifica.re"
}
The data relative to this Live API event
id The Id of the event executed
region The Id of the region (optional)
beacon The Id of the beacon (optional)
serial The serial of the pass (optional)
pass The Id of the pass (optional)
notification The Id of the notification (optional)
deviceID The device where it was executed
userID The user profile corresponding to that device
Mixed
timestamp1421656451382The numeric value corresponding to milliseconds since Unix epochNumber

Geo-Triggers

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

PropertyExampleDescriptionType
serviceMy ServiceThe human readable string that describes this Live API serviceString
typere.notifica.trigger.region.Enter The triggers' Notificare namespace. Available namespaces for geo-triggers:
  • re.notifica.trigger.region.Enter
  • re.notifica.trigger.region.Exit
  • re.notifica.trigger.beacon.Enter
  • re.notifica.trigger.beacon.Exit
String
data
1
2
3
4
5
6
{
"id":"54ac46e8...2e39ca0",
"source":"54ac46e8...2e39ca0",
"deviceID":"09260d8b1de06...948c516a",
"userID":"support@notifica.re"
}
The data relative to this Live API event
id The Id of the geo-trigger executed
source The Id of the region or beacon
deviceID The device where it was executed
userID The user profile corresponding to that device
Mixed
timestamp1421656451382The numeric value corresponding to milliseconds since Unix epochNumber

Products

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

PropertyExampleDescriptionType
serviceMy ServiceThe human readable string that describes this Live API serviceString
typere.notifica.product.Buy The purchases' Notificare namespace. Available namespaces for purchases:
  • re.notifica.product.Buy
String
data
1
2
3
4
5
6
{
"id":"54ac46e8...2e39ca0",
"identifier":"com.example.app.prod",
"deviceID":"09260d8b1de06...948c516a",
"userID":"support@notifica.re"
}
The data relative to this Live API event
id The Id of the purchase
identifier The product's SKU identifier
deviceID The device where it was executed
userID The user profile corresponding to that device
Mixed
timestamp1421656451382The numeric value corresponding to milliseconds since Unix epochNumber

Replies

Sent whenever a user replies to an actionable notification.

PropertyExampleDescriptionType
serviceMy ServiceThe human readable string that describes this Live API serviceString
typere.notifica.reply.Receive The replies' Notificare namespace. Available namespaces for replies:
  • re.notifica.reply.Receive
String
data
1
2
3
4
5
6
{
"id":"54ac46e8...2e39ca0",
"notification":"54ac46e8...2e39ca0",
"deviceID":"09260d8b1de06...948c516a",
"userID":"support@notifica.re"
}
The data relative to this Live API event
id The Id of the reply executed
notification The Id of the notification that was replied to
deviceID The device where it was executed
userID The user profile corresponding to that device
Mixed
timestamp1421656451382The numeric value corresponding to milliseconds since Unix epochNumber

Users

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

PropertyExampleDescriptionType
serviceMy ServiceThe human readable string that describes this Live API serviceString
typere.notifica.user.Register The users' Notificare namespace. Available namespaces for users:
  • re.notifica.user.Register
  • re.notifica.user.Create (only if Users & Authentication is available)
  • re.notifica.user.Validate (only if Users & Authentication is available)
  • re.notifica.user.AddDevice
  • re.notifica.user.RemoveDevice
  • re.notifica.user.Deactivate
  • re.notifica.user.Reactivate
  • re.notifica.user.AddSegment
  • re.notifica.user.RemoveSegment
  • re.notifica.user.LocationUpdate
String
data
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]
	}
}
The data relative to this Live API event
segment The Id of a segment (optional)
deviceID The device where it was executed
userID The user profile corresponding to that device
location GeoJSON point (optional)
Mixed
timestamp1421656451382The numeric value corresponding to milliseconds since Unix epochNumber

Devices

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

PropertyExampleDescriptionType
serviceMy ServiceThe human readable string that describes this Live API serviceString
typere.notifica.device.AddTag The users' Notificare namespace. Available namespaces for devices:
  • re.notifica.device.AddTag
  • re.notifica.device.RemoveTag
String
data
1
2
3
4
{
"tag":"tag_example",
"deviceID":"09260d8b1de06...948c516a"
}
The data relative to this Live API event
tag The name of the tag
deviceID The device where it was executed
Mixed
timestamp1421656451382The numeric value corresponding to milliseconds since Unix epochNumber

Import

Sent whenever an import job changes status.

PropertyExampleDescriptionType
serviceMy ServiceThe human readable string that describes this Live API serviceString
typere.notifica.import.Imported The imports' Notificare namespace. Available namespaces for imports:
  • re.notifica.import.Imported
  • re.notifica.import.Verified
  • re.notifica.import.Failed
String
data
1
2
3
{
"id":"54ac46e8...2e39ca0"
}
The data relative to this Live API event
job The Id of the import job executed
Mixed
timestamp1421656451382The numeric value corresponding to milliseconds since Unix epochNumber

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.