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 & Resource | Day | Time 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.
| Property | Description | Required | Valid 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 https://datafied.api.edgar-online.com/ntf/subscriptions?appkey={Appkey} HTTP/1.1
Host: datafied.api.edgar-online.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 https://datafied.api.edgar-online.com/ntf/subscriptions?appkey={Appkey} HTTP/1.1
Host: datafied.api.edgar-online.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 https://datafied.api.edgar-online.com/ntf/subscriptions/{Id}?appkey={Appkey} HTTP/1.1
Host: datafied.api.edgar-online.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 https://datafied.api.edgar-online.com/ntf/subscriptions/{Id}?appkey={Appkey}} HTTP/1.1
Host: datafied.api.edgar-online.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 https://datafied.api.edgar-online.com/ntf/subscriptions?limit=2&offset=1&appkey={Appkey} HTTP/1.1
Host: datafied.api.edgar-online.com
Get Subscriptions with specific UserId
https://datafied.api.edgar-online.com/ntf/subscriptions/user/{UserId}?appkey={Appkey} HTTP/1.1
Host: datafied.api.edgar-online.com
Get all subscriptions for specific ApplicationKey
GET https://datafied.api.edgar-online.com/ntf/subscriptions?appkey={Appkey} HTTP/1.1
Host: datafied.api.edgar-online.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 Name | Data Type & Length | Description |
| 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 Name | Data Type | Description |
| 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: https://datafied.api.edgar-online.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 https://datafied.api.edgar-online.com/ntf/templates?appkey={appkey} HTTP/1.1
Host: datafied.api.edgar-online.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 https://datafied.api.edgar-online.com/ntf/templates/54211885dbb747b894be6c44ea175bcf?appkey={appkey} HTTP/1.1
Host: datafied.api.edgar-online.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 https://datafied.api.edgar-online.com/ntf/subscriptions?appkey={Appkey} HTTP/1.1
Host: datafied.api.edgar-online.com
Content-Type: application/json
Content-Length: length
Get a Specific Template: to retrieve a specific template, specify the Id in the URL.
GET https://datafied.api.edgar-online.com/ntf/templates/daaa93288b2a4284be3dae4e5f4cd96e?appkey={appkey} HTTP/1.1
Host: datafied.api.edgar-online.com
Content-Type: application/json
Delete a Specific Template: to delete a specific template, specify the Id in the URL.
DELETE https://datafied.api.edgar-online.com/ntf/templates/54211885dbb747b894be6c44ea175bcf?appkey={appkey} HTTP/1.1
Host: datafied.api.edgar-online.com
Content-Type: application/json