Notifications

Overview

The Notifications Resource provides the ability to subscribe to alerts, triggered when there is new data or data changes. When you subscribe, you will define parameters for alerts. If and when the conditions are met, DataFied’s Notifications Resource will trigger a message to the specified email address. Alerts are delivered in a pre-defined template; however, there is an option to create custom templates.

Data Update Timing

Datasets available via DataFied are updated according to the following schedule. Note that all times are UTC time zone.

Dataset & ResourceDayTime of Daily Data Refresh
Companies Resource (e.g. HackPack) Tuesday - Saturday 7:13am
Core Financials (e.g. HackPack) Tuesday - Saturday 7:13am
Insider Trade Data Monday - Friday 11:30pm
Institutional Ownership Data Monday - Friday
12:00am
02:00am
04:00am
02:00pm
04:00pm
06:00pm
08:00pm
10:00pm
Content Type

The content types used by the system are JSON (default) or XML. To override the content type used in your HTTP Accept Header, append one of the following to your request:

  • .json suffix, or ?format=json
  • .xml suffix or ?format=xml

Note that the content-type parameter is case-insensitive.

Subscription API

The Subscriptions API supports CRUD operations to manage subscriptions for notification alerts for developers. The table below outlines the available common properties for creating and updating subscriptions.

PropertyDescriptionRequiredValid Values
Name Provide name for subscription (e.g. UpdatedPeerGroupFinancials) Yes Unique for particular user. Length of 3 to 255 characters; acceptable characters include alphanumeric characters, lower and/or uppercase, digits (0-9) and “_”
UserId User ID third party application the notifications support. Yes Length of 1 to 255 characters; acceptable characters include alphanumeric characters, lower and/or uppercase, digits (0-9) and “_”
AppKey DataFied application key for the dataset (e.g. Insider Trades) being monitored for changes/updates and alerts Yes Must be a valid DataFied AppKey
ResourceName Defines which resource and dataset to monitor (e.g. Companies Resource) Yes Length of 3 to 255 characters; must be a valid resource name
Expression Defines the rule of what to track for change/update within the specified resource Yes Use Filter Expression syntax; field must be defined
SubscriberEmail Destination email of subscription owner for alerts Yes Can not be empty;  must satisfy email validation rules: address length capped at 254 characters, labels length of 63 characters; example:  title@label1.label2.label3
SubscriberFullName Full name of subscription owner;  optional parameter to serve as input into an email’s ‘To’ field No Length of 3 to 255 character; NULL is acceptable
SubscriberSecondEmail Optional second email address for alerts; parameter cannot be used in place of ‘SubscriberEmail’ parameter No Must satisfy email validation rules: address length capped at 254 characters, labels length of 63 characters; example:  title@label1.label2.label3
SubscriberSecondFullName Optional full name of second subscription owner/email address; parameter to serve as input into an email’s ‘To’ field No

 

Note: Must be used with SubscriberSecondEmail parameter
Length of 3 to 255 character; NULL is acceptable
TemplateId Template for notification email No Should be valid GUID of created template; NULL is acceptable value and default template will be used; Use Template API to receive template IDs
DataFiApplicationKey Application key used to access DataFied resources Yes Must use a valid AppKey
ID ID of the subscription used during delete, update and get Yes,during delete, and update, in some circumstances for get Assigned to a particular subscription during creation
Create

To create a subscription, use the http verb POST,where the body describes the subscription.

Request format with Template:

POST http://edgaronline.api.mashery.com/ntf/subscriptions?appkey={Appkey} HTTP/1.1
Host: edgaronline.api.mashery.com
Content-Type: application/json

{
"DataFiApplicationKey":"SomeKey",
"Expression":"primarysymbol eq \"msft\" and totalrevenue gt 1000 and numperiods eq 1",
"Name":"ExampleName",
"ResourceName":"CoreFinancials-ANN",
"SubscriberEmail":"Str@adsasd.com",
"SubscriberFullName":"John Black",
"UserId":"12345",
"TemplateId": " fa1dfb726af341dbb9e9045923043469"
}

Request format without Template:

POST http://edgaronline.api.mashery.com/ntf/subscriptions?appkey={Appkey} HTTP/1.1
Host: edgaronline.api.mashery.com
Content-Type: application/json

{
"DataFiApplicationKey":"SomeKey",
"Expression":"primarysymbol eq \"msft\" and totalrevenue gt 1000 and numperiods eq 1",
"Name":"ExampleName",
"ResourceName":"CoreFinancials-ANN",
"SubscriberEmail":"Str@adsasd.com",
"SubscriberFullName":"John Black",
"UserId":"12345",
}

Possible response:

{
"Expression": "primarysymbol eq \"msft\" and totalrevenue gt 1000 and numperiods eq 1",
"DataFiApplicationKey": "String",
"Id": "baef982a07fd4664a37a1169c47b1fb2",
"Name": "Example",
"ResourceName": "CoreFinancials-ANN",
"SubscriberEmail": "Str@adsasd.com",
"SubscriberFullName": "TestName",
"UserId": "12345"
}

Update

To update a subscription, use the http verb PUT and provide Subscription ID.

Request format:

PUT http://edgaronline.api.mashery.com/ntf/subscriptions/{Id}?appkey={Appkey} HTTP/1.1
Host: edgaronline.api.mashery.com
Content-Type: application/json

{
"Expression": "primarysymbol eq \"msft\" and totalrevenue gt 1000 and numperiods eq 1",
"DataFiApplicationKey": "SomeKey",
"Name": "ChangedExample",
"ResourceName": "SomeResource",
"SubscriberEmail": "Some@email.com",
"SubscriberFullName": "SomeFullName",
"UserId": "SomeUSerId",
"TemplateId": "fa1dfb726af341dbb9e9045923043469"
}

Delete

To delete a subscription, use http verb DELETE and provide Subscription Id.

Request format:

DELETE http://edgaronline.api.mashery.com/ntf/subscriptions/{Id}?appkey={Appkey}} HTTP/1.1
Host: edgaronline.api.mashery.com

Status code 204 with status message: “Subscription has been deleted” will be confirmation that the delete action was complete.

If a template is not found based on the ID provided, status code 404 Not Found will be returned.

Get Examples
Get subscriptions with specific range

Return Subscriptions with specific limit and offset: Note that if no limit parameter is defined, then the default limit = 25

GET http://edgaronline.api.mashery.com/ntf/subscriptions?limit=2&offset=1&appkey={Appkey} HTTP/1.1
Host: edgaronline.api.mashery.com

Get Subscriptions with specific UserId

http://edgaronline.api.mashery.com/ntf/subscriptions/user/{UserId}?appkey={Appkey} HTTP/1.1
Host: edgaronline.api.mashery.com

Get all subscriptions for specific ApplicationKey

GET http://edgaronline.api.mashery.com/ntf/subscriptions?appkey={Appkey} HTTP/1.1
Host: edgaronline.api.mashery.com

Notification Templates API

Notification Templates can be used to create and customize email messages and alerts, which will be sent when the notification subscription parameter is met or event is triggered.

Template Structure

Property NameData Type & LengthDescription
Id string (32) ID of template entity
Name string (255) Name of template entity
Subject string (9999) String to render for email message Subject property
Body string (50000) String to render for email message Body property

When creating a subscription, if the TemplateId parameter is omitted, the default template will be used to send notification messages.

Default Template Settings

Subject: New Data Alert for @Raw(@Model.ApplicationId) via @Raw(@Model.ResourceName) for @Raw(@Model.Expression

Body:
New data is now available for the following:
Application ID: @Raw(@Model.ApplicationId)
App Key: @Raw(@Model.DataFiApplicationKey)
Defined Query: @Raw(@Model.Expression)
Retrieve new data via @Raw(@Model.ResourceName)
Use: @Raw(@Model.DataLink)

To render Notification Email Messages (subject and body) dynamically, the following context-dependent properties need to be defined.

Context properties for email message rendering:
Property NameData TypeDescription
Id string ID of Subscription entity
ApplicationId string ID of Application entity
Name string Name of Subscription entity
DataFiApplicationKey string DataFiApplicationKey property of subscription entity
Expression string Expression property of subscription entity
ResourceName string ResourceName property of subscription entity
SubscriberEmail string SubscriberEmail property of subscription entity
SubscriberFullName string SubscriberFullName property of subscription entity
DataLink string Dynamic property which contains link to the DataFi API. Can be used to retrieve data related to subscription scope.
Sample Email message rendered using default template:

Subject:New Data Alert for 2030563459116056575 via CoreFinancials-ANN for primarysymbol eq "aapl" and totalrevenue gt 150111222333

Body:
New data is now available for the following:
Application ID: Application ID: 2030563459116056575
App Key: APPKEY
Defined Query: primarysymbol eq "aapl" and totalrevenue gt 150111222333
Retrieve new data via CoreFinancials-ANN
Use: http://edgaronline.api.mashery.com/qc/v2/corefinancials/ann?filter=primarysymbol%20eq%20%22aapl%22%20and%20totalrevenue%20gt%20150111222333&limit=100&offset=0&fields=entityid%2Cisactivecompany%2Cperiodenddate%2Cprimarysymbol%2Ctotalrevenue&sortby=entityid%2Cisactivecompany%2Cperiodenddate&appkey=APPKEY

Sample Calls for Notification Templates API:
Create a Template:

POST http://edgaronline.api.mashery.com/ntf/templates?appkey={appkey} HTTP/1.1
Host: edgaronline.api.mashery.com
Content-Type: application/json
Content-Length: length

{
"Name":"Sample template",
"Subject":"New Data Alert for @Raw(@Model.ApplicationId) via @Raw(@Model.ResourceName) for @Raw(@Model.Expression)",
"Body":"New data is now available for the following: \nApplication ID: @Raw(@Model.ApplicationId) \nApp
Key: @Raw(@Model.DataFiApplicationKey) \nDefined Query: @Raw(@Model.Expression) \nRetrieve new data via @Raw(@Model.ResourceName) \nUse: @Raw(@Model.DataLink)\n\n"
}

Update a Template:

PUT http://edgaronline.api.mashery.com/ntf/templates/54211885dbb747b894be6c44ea175bcf?appkey={appkey} HTTP/1.1
Host: edgaronline.api.mashery.com
Content-Type: application/json
Content-Length: length

{
"Id":"54211885dbb747b894be6c44ea175bcf",
"Name":"Sample template",
"Subject":"New Data Alert for @Raw(@Model.ApplicationId) via @Raw(@Model.ResourceName) for @Raw(@Model.Expression)",
"Body":"New data is now available for the following: \nApplication ID: @Raw(@Model.ApplicationId) \nApp
Key: @Raw(@Model.DataFiApplicationKey) \nDefined Query: @Raw(@Model.Expression) \nRetrieve new data via @Raw(@Model.ResourceName) \nUse: @Raw(@Model.DataLink)\n\n"
}

Get All Templates:

GET http://edgaronline.api.mashery.com/ntf/subscriptions?appkey={Appkey} HTTP/1.1
Host: edgaronline.api.mashery.com
Content-Type: application/json
Content-Length: length

Get a Specific Template: to retrieve a specific template, specify the Id in the URL.

GET http://edgaronline.api.mashery.com/ntf/templates/daaa93288b2a4284be3dae4e5f4cd96e?appkey={appkey} HTTP/1.1
Host: edgaronline.api.mashery.com
Content-Type: application/json

Delete a Specific Template: to delete a specific template, specify the Id in the URL.

DELETE http://edgaronline.api.mashery.com/ntf/templates/54211885dbb747b894be6c44ea175bcf?appkey={appkey} HTTP/1.1
Host: edgaronline.api.mashery.com
Content-Type: application/json