API

Live API

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.ReceivedThe events Notificare's namespaceString
data{"id": "54ac46e8...2e39ca0", "deviceID": "09260d8b1de06...948c516a", "userID": "support@notifica.re"}The data relative to this Live API eventObject
timestamp1421656451382The numeric value corresponding to milliseconds since Unix epochNumber

Possible Types

Type
re.notifica.event.notification.Received
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.*

Payload

KeyDescription
idThe Id of the event executed
regionThe Id of the region (optional)
beaconThe Id of the beacon (optional)
serialThe serial of the pass (optional)
passThe Id of the pass (optional)
notificationThe Id of the notification (optional)
deviceIDThe device where it was executed
userIDThe user profile corresponding to that device

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.EnterThe geo-triggers Notificare's namespaceString
data{"id": "54ac46e8...2e39ca0", "source": "54ac46e8...2e39ca0", "deviceID": "09260d8b1de06...948c516a", "userID": "support@notifica.re"}The data relative to this Live API eventObject
timestamp1421656451382The numeric value corresponding to milliseconds since Unix epochNumber

Possible Types

Type
re.notifica.trigger.region.Enter
re.notifica.trigger.region.Exit
re.notifica.trigger.beacon.Enter
re.notifica.trigger.beacon.Exit

Payload

KeyDescription
idThe Id of the geo-trigger executed
sourceThe Id of the region or beacon
deviceIDThe device where it was executed
userIDThe user profile corresponding to that device

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.reply.ReceiveThe purchases Notificare's namespaceString
data{"id": "54ac46e8...2e39ca0", "identifier": "com.example.app.prod", "deviceID": "09260d8b1de06...948c516a", "userID": "support@notifica.re"}The data relative to this Live API eventObject
timestamp1421656451382The numeric value corresponding to milliseconds since Unix epochNumber

Possible Types

Type
re.notifica.product.Buy

Payload

KeyDescription
idThe Id of the purchase
identifierThe product's SKU identifier
deviceIDThe device where it was executed
userIDThe user profile corresponding to that device

Replies

Sent whenever a user replies to an actionable notification.

PropertyExampleDescriptionType
serviceMy ServiceThe human readable string that describes this Live API serviceString
typere.notifica.trigger.region.EnterThe replies Notificare's namespaceString
data{"id": "54ac46e8...2e39ca0", "notification": "54ac46e8...2e39ca0", "deviceID": "09260d8b1de06...948c516a", "userID": "support@notifica.re"}The data relative to this Live API eventObject
timestamp1421656451382The numeric value corresponding to milliseconds since Unix epochNumber

Possible Types

Type
re.notifica.reply.Receive

Payload

KeyDescription
idThe Id of the reply executed
notificationThe Id of the notification that was replied to
deviceIDThe device where it was executed
userIDThe user profile corresponding to that device

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.RegisterThe users Notificare's namespaceString
data{"segment": "54ac46e8...2e39ca0", "userID": "support@notifica.re"}The data relative to this Live API eventObject
timestamp1421656451382The numeric value corresponding to milliseconds since Unix epochNumber

Possible Types

Type
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

Payload

KeyDescription
segmentThe Id of a segment (optional)
locationGeoJSON point (optional)
deviceIDThe device where it was executed
userIDThe user profile corresponding to that device

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.AddTagThe devices Notificare's namespaceString
data{"tag": "tag_example", "deviceID": "09260d8b1de06...948c516a"}The data relative to this Live API eventObject
timestamp1421656451382The numeric value corresponding to milliseconds since Unix epochNumber

Possible Types

Type
re.notifica.device.AddTag
re.notifica.device.RemoveTag

Payload

KeyDescription
tagThe name of the tag
deviceIDThe device where it was executed

Import

Sent whenever an import job changes status.

PropertyExampleDescriptionType
serviceMy ServiceThe human readable string that describes this Live API serviceString
typere.notifica.import.ImportedThe jobs Notificare's namespaceString
data{"id": "54ac46e8...2e39ca0"}The data relative to this Live API eventObject
timestamp1421656451382The numeric value corresponding to milliseconds since Unix epochNumber

Possible Types

Type
re.notifica.import.Imported
re.notifica.import.Verified
re.notifica.import.Failed

Payload

KeyDescription
idThe Id of the import job executed

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.