NewsEdge API

Alerts of Story Searches

Alerts are email messages that contain saved search results. To setup and activate an alert requires the following steps:

Create the alert using alert/create.
Set the "when", "what", and "who" for the alert:

Use alert/addschedule to define when the alert is to occur.
Use alert/addsearch to define the content of the alert by associating one or more saved searches with it.
Use alert/destination to define email addresses that will receive the alert.

Activate the alert with alert/activate to start sending alerts based on the alert schedules.

Creating a News Alert
Creating Periodic Alerts of Stories

Creating a News Alert

Back to Top

This example shows the basic steps to create an alert that will be sent on specific days of the week at a specific time of day.

Create an alert.

Create and name an alert with alert/create using the required parameters session and name. This example also includes the subject parameter to set the alert's email subject.

Request

https://secure.newsedge.com/opensapi/20/alert/create?session=935DA0B364E9E130F0EC3827FC3CCC9C&name=Drug%20Trials&subject=Drug%20Trials%20Alert

Response

<opens-api>
    <message>Alert 34729 created</message>
</opens-api>

Get a list of alerts and alert IDs.

To identify an alert in other API requests, use the id attribute of the alert element from alert/list.

Request

https://secure.newsedge.com/opensapi/20/alert/list?session=935DA0B364E9E130F0EC3827FC3CCC9C

Response

<opens-api>
  <alerts>
    <alert id="34729" name="Drug Trials" status="Inactive"/>
  </alerts>
</opens-api>

Get an alert's information.

To get details about an alert, use alert/info with the required parameters session and alert. In the returned results, notice the first three sub-elements of the alert element, which need to be filled in using the following API requests:

Use alert/addschedule to fill in an alertSchedule element.
Use alert/addsearch to fill in an alertSearches element.
Use alert/adddestination to fill in an additionalDestinations element.

Use alert/update to add or update the other alert information.

Request

https://secure.newsedge.com/opensapi/20/alert/info?session=935DA0B364E9E130F0EC3827FC3CCC9C&alert=34729

Response

<opens-api>
  <alerts>
    <alert id="34729" name="Drug Trials" status="Inactive">
      <alertSchedule></alertSchedule>
      <alertSearches></alertSearches>
      <additionalDestinations></additionalDestinations>
      <alertSubject>Drug Trials Alert</alertSubject>
      <alertComment/>
      <emailContents value="briefs"/>
      <tocLocation value="top"/>
      <lastExecTime value="19700101T000000+0000"/>
      <maxResults value="50"/>
      <maxStories value="50"/>
      <maxTotalStories value="500"/>
      <enableHighlighting/>
    </alert>
  </alerts>
</opens-api>

Define a schedule for an alert.
You schedule alerts for specific days of the week with specific times for those days using alert/addschedule. The request requires the parameters session, alert, and days, with additional parameters to set the times. You can set two types of time schedules:
- type=settime sets a specific time of day for the alert to occur. This example uses type=settime.
- type=period sets a period of time between recurrences of the alert throughout the day.
This example sets a schedule for Monday, Wednesday, and Friday at the set time of 5:15PM.

Note the schedule is identified with an ID number, which you can also find in the scheduleId attribute of the dayOfWeek element from alert/info.

You can add multiple schedules as needed. To delete a schedule use alert/deleteschedule.
Request
```
https://secure.newsedge.com/opensapi/20/alert/addschedule?session=935DA0B364E9E130F0EC3827FC3CCC9C&alert=34729&days=Monday,Wednesday,Friday&type=settime&setTime=171500
```
Response
```
<opens-api>
   <message>Schedule 3411 added to alert 34729 for user 32594</message>
</opens-api>
```

Get a saved search ID for the alert.

An alert's content is generated from one or more saved searches. You associate a saved search using alert/addsearch, which is shown in the following step. First, this step uses savedsearch/list to get the ID of the saved search we want the alert to use. A saved search ID is the ss attribute of the savedsearch element from savedsearch/list. In this example we'll use the saved search identified as 13818.

Request

https://secure.newsedge.com/opensapi/20/savedsearch/list?session=935DA0B364E9E130F0EC3827FC3CCC9C

Response

<opens-api>
  <status>OK</status>
  <savedsearches>
    <savedsearch ss="6762" owner="NewsEdge.com" level="SYSTEM" name="NewsEdge" permission="OPAQUE"/>
    <savedsearch ss="13818" owner="API User" level="PERSONAL" name="Pharmaceutical Development" permission="WRITE"/>
    <savedsearch ss="6761" owner="NewsEdge.com" level="SYSTEM" name="Pharmaceuticals Industry" permission="OPAQUE"/>
    . . .
  </savedsearches>
</opens-api>

Define the content of an alert from a saved search.
To add the saved search obtained from the previous step, use alert/addsearch with the required session, alert, and savedSearch parameters.

Note the search is identified with its saved search ID number, which you can also find in the id attribute of the alertSearch element from alert/info.

You can add multiple searches to an alert if desired. To delete a search from an alert use alert/deletesearch.

Request
```
https://secure.newsedge.com/opensapi/20/alert/addsearch?session=935DA0B364E9E130F0EC3827FC3CCC9C&alert=34729&savedSearch=13818
```
Response
```
<opens-api>
  <message>Search 13818 added to alert 34729 for user 32594</message>
</opens-api>
```
Define an email destination to receive an alert.
Use alert/adddestination to add an email address destination for the alert. The required parameters include the session identifier, the alert identifier, an emailAddress, and an emailFormat, which can have the value HTML, smartphone, text, mobile, or Webalert.

Note the destination is identified by the email address, which you can also find as the value of a destination element from alert/info.

You can add more email destinations to the alert as needed. To delete an email from an alert use alert/deletesearch.

Request
```
https://secure.newsedge.com/opensapi/20/alert/adddestination?session=935DA0B364E9E130F0EC3827FC3CCC9C&alert34729&emailAddress=name@example.com&emailFormat=HTML
```
Response
```
<opens-api>
  <message>Destination name@example.com, format HTML added to alert 34729 for user 32594</message>
</opens-api>
```

Activate an alert.

Alerts are not sent until the alert is activated using alert/activate with the session and alert parameters.

Request

https://secure.newsedge.com/opensapi/20/alert/activate?session=935DA0B364E9E130F0EC3827FC3CCC9C&alert=34729

Response

<opens-api>
    <message>Alert 34729 for user 32594 activated</message>
</opens-api>

Review an alert's information.

Use alert/info with the session and alert parameters to get all the details about the alert.

Note the following in the results:

status - Set this using alert/activate or alert/deactivate.
dayOfWeek - Add more schedules using alert/addschedule.
alertSearch - Add more saved searches using alert/addsearch.
destination - Add more email destinations using alert/adddestination.

See the next step for how to add or modify the other alert values.

Request

https://secure.newsedge.com/opensapi/20/alert/info?session=935DA0B364E9E130F0EC3827FC3CCC9C&alert=34729

Response

<opens-api>
  <alerts>
    <alert id="34729" name="Drug Trials" status="Active">
      <alertSchedule>
        <dayOfWeek scheduleId="3411" number="3,5">
        <setTime>T171500-0400</setTime>
        </dayOfWeek>
      </alertSchedule>
      <alertSearches>
        <alertSearch id="13818" name="Pharmaceutical Development"/>
      </alertSearches>
      <additionalDestinations>
        <destination type="email" format="HTML">name@example.com</destination>
      </additionalDestinations>
      <alertSubject>Drug Trials Alert</alertSubject>
      <alertComment/>
      <emailContents value="briefs"/>
      <tocLocation value="top"/>
      <lastExecTime value="19700101T000000+0000"/>
      <maxResults value="50"/>
      <maxStories value="50"/>
      <maxTotalStories value="500"/>
      <enableHighlighting/>
    </alert>
  </alerts>
</opens-api>

Update an alert.

Modify an alert's settings using alert/update with the required parameters session and alert, plus any of the parameters in the following table. The left column contains an attribute or element shown in the results of the previous step. The right column indicates the alert/update parameter to use to change the value:

Attribute or Element	The alert/update Parameter to Use
alert name attribute	Use the parameter name to change the alert's name.
alertSubject element	Use the parameter subject to set or change the email subject line.
alertComment element	Use the parameter comment to add a text comment to the top of the email.
emailContents value attribute	Use the parameter contents=briefs to include headlines and a brief description of the story in the email or use contents=headlines to show only headlines.
tocLocation value attribute	Use the parameter tocLocation=top to add a table of contents to the top of the email.
maxResults value attribute	Use the parameter maxResultsPerSearch to set the maximum number of results for each search included in the alert.
maxStories value attribute	Use the parameter maxStoriesPerEmailto set the maximum number of stories to include in an alert email message.
maxTotalStories value attribute	Use the parameter maxStoriesPerAlert to set the maximum total number of saved search results to be emailed for the alert.
enableHighlighting element	Use the parameter highlighting=TRUE to highlight search terms in the email results.

Request

https://secure.newsedge.com/opensapi/20/alert/update?session=935DA0B364E9E130F0EC3827FC3CCC9C&alert=34729&highlighting=TRUE

Response

<opens-api>
  <message>Alert 34729 updated</message>
</opens-api>

Deactivating and deleting an alert.

If you no longer need an alert, use alert/deactivate and alert/delete, each with the session and alert parameters.

Request

https://secure.newsedge.com/opensapi/20/alert/deactivate?session=935DA0B364E9E130F0EC3827FC3CCC9C&alert=34729

Response

<opens-api>
  <message>Alert 34729 for user 32594 deactivated</message>
</opens-api>

Creating Periodic Alerts of Stories

Back to Top

This example shows how to add an additional schedule to an alert so that the the alert occurs on a regular schedule, such as every 15 minutes.

Get an alert's ID.

Request

https://secure.newsedge.com/opensapi/20/alert/list?session=935DA0B364E9E130F0EC3827FC3CCC9C

Response

<opens-api>
  <alerts>
    <alert id="34729" name="Drug Trials" status="Inactive"/>
  </alerts>
</opens-api>

Add a periodic schedule to an alert.
To schedule an alert to be sent periodically throughout the day, use the alert/addschedule request with the required parameters session, alert, days, and the following additional parameters to set the periodic times:
- type=period
- startTime=hhmmss. This example uses the value 090000, which represents 9AM.
- endTime=hhmmss. This example uses the value 153000, which represents 3:30 PM.
- periodInSeconds=seconds. This example uses 900, which represents a period of every 15 minutes. (900 seconds is the lowest value allowed.)
Note also that the days of the week can be set using the numbers 1 through 7, where 1 represents Monday and so on.
Request
```
https://secure.newsedge.com/opensapi/20/alert/addschedule?session=935DA0B364E9E130F0EC3827FC3CCC9C&alert=34729&days=1,2,3,4,5&type=period&startTime=090000&endTime=153000&periodInSeconds=900
```
Response
```
<opens-api>
  <message>Schedule 3413 added to alert 34729 for user 32594</message>
</opens-api>
```

Get an alert's information.

Request

https://secure.newsedge.com/opensapi/20/alert/info?session=935DA0B364E9E130F0EC3827FC3CCC9C&alert=34729

Response

<opens-api>
  <alerts>
    <alert id="34729" name="Drug Trials" status="Active">
      <alertSchedule>
        <dayOfWeek scheduleId="3411" number="3,5">
          <setTime>T171500-0400</setTime>
        </dayOfWeek>
        <dayOfWeek scheduleId="3413" number="1,2,3,4,5">
          <startTime>T090000-0400</startTime>
          <endTime>T153000-0400</endTime>
          <period>PT15M</period>
        </dayOfWeek>
      </alertSchedule>
      <alertSearches>
        <alertSearch id="13818" name="Pharmaceutical Development"/>
      </alertSearches>
      <additionalDestinations>
        <destination type="email" format="HTML">name@example.com</destination>
      </additionalDestinations>
      <alertSubject>Drug Trials Alert</alertSubject>
      <alertComment/>
      <emailContents value="briefs"/>
      <tocLocation value="top"/>
      <lastExecTime value="19700101T000000+0000"/>
      <maxResults value="50"/>
      <maxStories value="50"/>
      <maxTotalStories value="500"/>
      <enableHighlighting/>
    </alert>
  </alerts>
</opens-api>

Activate an alert.

Remember to activate the alert if it is not already activated using alert/activate with the session and alert parameters.

Request

https://secure.newsedge.com/opensapi/20/alert/activate?session=935DA0B364E9E130F0EC3827FC3CCC9C&alert=34729

Response

<opens-api>
  <message>Alert 34729 for user 32594 activated</message>
</opens-api>

Deactivating and deleting an alert.

If an alert is no longer needed, use alert/deactivate and alert/delete, each with the session and alert parameters.

Request

https://secure.newsedge.com/opensapi/20/alert/deactivate?session=935DA0B364E9E130F0EC3827FC3CCC9C&alert=34729

Response

<opens-api>
  <message>Alert 34729 for user 32594 deactivated</message>
</opens-api>

alert/create - Create an email alert

Use alert/create to create an alert that sends email notifications containing stories from a saved search. See also api/info where noun=alert and verb=create. Do the following steps after you create an alert:

Use alert/addsearch to specify what stories to send by associating one or more saved searches with the alert.
Use alert/addschedule to specify when to send the alert.
Use alert/adddestination to specify where to send the alert by associating one or more email addresses.
Use alert/activate to enable the system to start sending the alert.

Example

https://secure.newsedge.com/opensapi/20/alert/create?session=<<user-token>>&name=<<alert-name>>[&parameter=value][& . . .]

Required Parameters

Parameter	Values	Description
name		A name for the alert.
session		The ID of the OPENS API session. Use the user-token value returned from the session/login request.

Optional Parameters

Parameter	Values	Description
json	Default:0 0,1,2	The json parameter controls the format of the return data. If the parameter is not provided, the data is returned in XML format. 0 - Return data in XML format. 1 - Return data in compact JSON format. If the caller is planning on using JSON in production, this value should be used. 2 - Return data in expanded JSON format. This parameter value sets the return data to be in a more human-readable JSON form.
comment		Introductory text added to the beginning of the email message.
contents	Default:briefs headlines, briefs	Sets what type of story content the alert is to include. briefs - headlines and summaries. headlines - headlines only.
highlighting	Default:false true, false	Sets whether the search terms of the saved search are to be highlighted in the alert's email message. true - highlight search terms in email message. false - do not highlight search terms.
maxResultsPerSearch	Default:50 1, 2, . . ., 50	Sets the maximum number of results per saved search to include in the alert each time it executes. To control the number of stories and emails an alert sends, coordinate together the values for the parameters maxStoriesPerAlert, maxResultsPerSearch, and maxStoriesPerEmail.
maxStoriesPerEmail	Default:100 1, 2, . . ., 100	Sets the maximum number of search results included in an alert email message. Note that multiple emails may be sent each time an alert executes, depending on the value of maxStoriesPerAlert and the total number of stories specified in maxResultsPerSearch. To control the number of stories and emails an alert sends, coordinate together the values for the parameters maxStoriesPerAlert, maxResultsPerSearch, and maxStoriesPerEmail.
maxStoriesPerAlert	Default:500 1, 2, . . ., 500	Sets the maximum number of stories sent each time the alert executes. When an alert executes, the search results contain a list of stories up to the number of maxResultsPerSearch. Then an email is sent containing a list of stories up to the number of maxStoriesPerEmail. However, if all the stories could not be included in the first email, additional emails are sent for the alert up to the number of maxStoriesPerAlert. For example, if maxResultsPerSearch=50, and maxStoriesPerEmail=25, you might set maxStoriesPerAlert=50 or greater, to ensure all the stories in the current alert search results are included. To control the number of stories and emails an alert sends, coordinate together the values for the parameters maxStoriesPerAlert, maxResultsPerSearch, and maxStoriesPerEmail.
subject		The text for the email subject line.
tocLocation	Default:top top, none	top - Sets the alert email to include a table of contents at the top. The table of contents contains links to the beginning of a set of search stories within the email body. Note this setting is useful if the alert uses more than one saved search. none - No table of contents is included in the alert email.

Returned Results

The returned results include an opens-api element with a single message child-element.

opens-api

Name	Values	Description
message		If the request is successful the text message indicates the alert was created and includes the alert ID. For example: <message>Alert 34729 created</message> If an error occurs, the text message contains an explanation of the error.

Name

Values

Description

message

If the request is successful the text message indicates the alert was created and includes the alert ID. For example:

<message>Alert 34729 created</message>

If an error occurs, the text message contains an explanation of the error.

alert/list - Get a list of alerts

Use alert/list to get a list of alerts. See also api/info where noun=alert and verb=list.

Example

https://secure.newsedge.com/opensapi/20/alert/list?session=<<user-token>>

Required Parameters

Parameter	Values	Description
session		The ID of the OPENS API session. Use the user-token value returned from the session/login request.

Optional Parameters

Parameter	Values	Description
json	Default:0 0,1,2	The json parameter controls the format of the return data. If the parameter is not provided, the data is returned in XML format. 0 - Return data in XML format. 1 - Return data in compact JSON format. If the caller is planning on using JSON in production, this value should be used. 2 - Return data in expanded JSON format. This parameter value sets the return data to be in a more human-readable JSON form.

Returned Results

The returned results include an opens-api element with an alerts sub-element.

opens-api

Name	Values	Description
alerts		The alerts element represents the list of alerts with one or more alert sub-elements.
alert		Represents an alert and includes the following attributes: id - The identifier of the alert. Use this value in other API requests to identify a particular alert. name - A name for the alert. To change this value, use the name parameter in alert/update. status - An indicator as to whether the alert is activated to send alert email messages. Valid values are Active or Inactive. Use alert/activate or alert/deactivate to modify the alert's status.

alert/info - Get alert information

Use alert/info to get alert information including the alert ID, the alert's activation status, which saved searches it uses, and details about when and where the alert will execute. See also api/info where noun=alert and verb=info.

Example

https://secure.newsedge.com/opensapi/20/alert/info?session=<<user-token>>&alert=<<alert-id>>

Required Parameters

Parameter	Values	Description
alert		An alert identifier. Use the value of the alert element's id attribute returned from an alert/list request.
session		The ID of the OPENS API session. Use the user-token value returned from the session/login request.

Optional Parameters

Parameter	Values	Description
json	Default:0 0,1,2	The json parameter controls the format of the return data. If the parameter is not provided, the data is returned in XML format. 0 - Return data in XML format. 1 - Return data in compact JSON format. If the caller is planning on using JSON in production, this value should be used. 2 - Return data in expanded JSON format. This parameter value sets the return data to be in a more human-readable JSON form.

Returned Results

The returned results include an opens-api element with an alerts sub-element.

opens-api

Name	Values	Description
alerts		The list of alerts, each of which is represented by an alert sub-element.
alert		This represents an alert and includes the following attributes: id - The identifier of the alert. name - The name of the alert. To change this value, use the name parameter in alert/update. status - An indicator as to whether the alert is activated to send alert email messages. Valid values are Active or Inactive. Use alert/activate or alert/deactivate to modify the alert's status. The alert element also contains the following sub-elements: alertSchedule alertSearches additionalDestinations alertSubject alertComment emailContents tocLocation lastExecTime maxResults maxStories maxTotalStories enableHighlighting
alertSchedule		An alert's list of schedules, each of which is represented by a dayOfWeek sub-element. Schedules are added to alerts using alert/addschedule, and removed from alerts using alert/deleteschedule.
dayOfWeek	1, 2, 3, 4, 5, 6, 7	A dayOfWeek element represents when the alert executes. A dayOfWeek element contains the following attributes to represent the days the alert is scheduled to execute: scheduleId - An identifier for the alert schedule. number - Identifies the days of the week the alert is scheduled to execute. See also the days parameter of alert/addschedule. The numbers represent the following days: Monday Tuesday Wednesday Thursday Friday Saturday Sunday A dayOfWeek element also contains sub-elements to represent the times the alert is scheduled to execute. See also the type parameter of alert/addschedule. If the schedule is set for a specific time, the dayOfWeek element contains the sub-element setTime. If the schedule is set to be periodic throughout the day, the dayOfWeek element contains the sub-elements startTime, endTime, and period. The first periodic alert of the day is sent at the time of the startTime element. Thereafter, alerts are sent periodically based on the value of the period element until the time set in the endTime element occurs.
setTime	Thhmmss-hhmm	Indicates a specific time of the day the alert will execute. Time is in hours minutes and seconds with an offset from Greenwich Mean Time.
startTime	Thhmmss-hhmm	Indicates the time when this periodic alert is scheduled to start for the day.
endTime	Thhmmss-hhmm	Indicates the time after which no more periodic alerts are sent for the day.
period	PTmmM	Indicates the time in minutes between the executions of periodic alerts during a day.
alertSearches		A list representing an alert's saved searches, each of which is represented by an alertSearch sub-element. Saved searches are added to alerts using alert/addsearch.
alertSearch		A source of stories for the alert. An alertSearch element represents a saved search with the following attributes: id - The saved search identifier. name - The saved search name.
additionalDestinations		A list of alert destinations, where each destination is represented by a destination sub-element. Destinations are added to alerts using alert/adddestination.
destination		An email address where the alert is sent. The destination element also includes the following attributes: type - The type of destination is email. format - The format of the body of the email message. Valid values include HTML, mobile, smartphone, text, and Webalert. See also the emailFormat parameter of alert/adddestination.
alertSubject		Text of the alert's email subject line. See also the subject parameter of alert/update or alert/create.
alertComment		Optional additional text added to the beginning of the alert's email message. See also the comment parameter of alert/update or alert/create.
emailContents	briefs, headlines	The type of story content the alert email is to include. Valid values include: briefs - The contents will contain headlines and summaries. headlines - The contents will contain headlines only. See also the contents parameter of alert/update or alert/create.
tocLocation	top, none	Indicates whether the alert email has a table of contents: top - Indicates the alert email includes a table of contents at the top. The table of contents contains links to the beginning of a set of search stories within the email body. none - No table of contents is included in the alert email. See also the tocLocation parameter of alert/update or alert/create.
lastExecTime	YYYYMMDDTHHMMSS-ZZZZ	Indicates the last time the alert executed. This is the receive date of the most recent story sent in the alert email. This value is used by the system to determine how far back the next alert will start the search for new stories. See also the timeRangeInMinutes parameter of alert/addschedule to set a different time for the alert search to use. If the value is 19700101T000000+0000, it means the alert has not yet been executed.
maxResults	1, 2, . . .,50	Indicates the maximum number of results for each alertSearch to be sent each time the alert executes. See also the maxStoriesPerAlert parameter of alert/update or alert/create. When an alert executes, the search results contain a list of stories up to the number of the maxResults element. Then an email is sent containing a list of stories up to the number of maxStories element. However, if all the stories could not be included in the first email, additional emails are sent for the alert up to the number of maxTotalStories element.
maxStories	1, 2, . . .,100	Indicates the maximum number of search results included in an email message. See also the maxStoriesPerEmail parameter of alert/update or alert/create. Note that multiple emails may be sent each time an alert executes, depending on the value of the maxResults element and the total number of stories specified in maxTotalStories.
maxTotalStories	1, 2, . . .,500	Indicates the maximum number of stories to be included in the alert. See also the maxStoriesPerAlert parameter of alert/update or alert/create.
enableHighlighting	Y, or empty tag	Indicates if the search terms in the alert's email message are to be highlighted. See also the highlighting parameter of alert/update or alert/create.

alert/update - Update alert settings

Use alert/update to change or add settings for an existing alert. See also api/info where noun=alert and verb=update.

Example

https://secure.newsedge.com/opensapi/20/alert/update?session=<<user-token>>&alert=<<alert-id>>[&parameter=value][& . . .]

Required Parameters

Parameter	Values	Description
alert		An alert identifier. Use the value of the alert element's id attribute returned from an alert/list request.
session		The ID of the OPENS API session. Use the user-token value returned from the session/login request.

Optional Parameters

Parameter	Values	Description
json	Default:0 0,1,2	The json parameter controls the format of the return data. If the parameter is not provided, the data is returned in XML format. 0 - Return data in XML format. 1 - Return data in compact JSON format. If the caller is planning on using JSON in production, this value should be used. 2 - Return data in expanded JSON format. This parameter value sets the return data to be in a more human-readable JSON form.
comment		Adds or changes introductory text at the beginning of the email message.
contents	headlines, briefs	Resets what type of story content the alert is to include. briefs - headlines and summaries. headlines - headlines only.
highlighting	true, false	Resets whether the search terms of the saved search are to be highlighted in the alert's email message. true - highlight search terms in email messages. false - do not highlight search terms.
maxResultsPerSearch	1, 2, . . ., 50	Resets the maximum number of results per saved search to include in the alert each time it executes. To control the number of stories and emails an alert sends, coordinate together the values for the parameters maxStoriesPerAlert, maxResultsPerSearch, and maxStoriesPerEmail.
maxStoriesPerEmail	1, 2, . . ., 100	Resets the maximum number of search results included in an alert email message. Note that multiple emails may be sent each time an alert executes, depending on the value of the maxEmailsPerAlert parameter and the total number of stories specified in the maxResultsPerSearch parameter. To control the number of stories and emails an alert sends, coordinate together the values for the parameters maxStoriesPerAlert, maxResultsPerSearch, and maxStoriesPerEmail.
maxStoriesPerAlert	1, 2, . . ., 500	Resets the maximum number of stories sent each time the alert executes. When an alert executes, the search results contain a list of stories up to the number of the maxResultsPerSearch parameter. Then an email is sent containing a list of stories up to the number of the maxStoriesPerEmail parameter. However, if all the stories could not be included in the first email, additional emails are sent for the alert up to the number of maxStoriesPerAlert parameter. For example, if maxResultsPerSearch=50, and maxStoriesPerEmail=25, you might set maxEmailsPerAlert=2 or greater, to ensure all the stories in the current alert search results are included. To control the number of stories and emails an alert sends, coordinate together the values for the parameters maxStoriesPerAlert, maxResultsPerSearch, and maxStoriesPerEmail.
name		Changes the name of the alert.
subject		Changes or adds text for the email subject line.
tocLocation	top, none	top - Resets the alert email to include a table of contents at the top. The table of contents contains links to the beginning of a set of search stories within the email body. Note this setting is useful if the alert uses more than one saved search. none - Resets the alert to not include a table of contents in the alert email.

Returned Results

The returned results include an opens-api element with a single message child-element.

opens-api

Name	Values	Description
message		If the request is successful the text message indicates the alert updated and includes the alert ID. For example: <message>Alert 34729 updated</message> If an error occurs the text message contains an explanation of the error.

Name

Values

Description

message

If the request is successful the text message indicates the alert updated and includes the alert ID. For example:

<message>Alert 34729 updated</message>

If an error occurs the text message contains an explanation of the error.

alert/adddestination - Add an email destination for an alert

Use alert/adddestination to add one, or up to 6, email addresses where alert emails are to be sent. See also api/info where noun=alert and verb=adddestination.

Example

https://secure.newsedge.com/opensapi/20/alert/adddestination?session=<<user-token>>&alert=<<alert-id>>&emailAddress=<<address>>&emailFormat=<<format>>

Required Parameters

Parameter	Values	Description
alert		An alert identifier. Use the value of the alert element's id attribute returned from an alert/list request.
session		The ID of the OPENS API session. Use the user-token value returned from the session/login request.
emailAddress	email address format	An email address to which the alert email is to be sent. The format is: name@my-company.com
emailFormat	HTML, smartphone, text, mobile, Webalert	The format of the body of the email message. Valid values include: HTML - The format is in HTML suitable for viewing in a browser. smartphone - The format is suitable for viewing on a smartphone. text - The format is plain text, with line wrapping at character position 80. mobile - The format is plain text, with line wrapping at character position 30. Webalert - The email message will include a link to view the latest alert on a hosted web page.

Optional Parameters

Parameter	Values	Description
json	Default:0 0,1,2	The json parameter controls the format of the return data. If the parameter is not provided, the data is returned in XML format. 0 - Return data in XML format. 1 - Return data in compact JSON format. If the caller is planning on using JSON in production, this value should be used. 2 - Return data in expanded JSON format. This parameter value sets the return data to be in a more human-readable JSON form.

Returned Results

The returned results include an opens-api element with a single message sub-element.

opens-api

Name	Values	Description
message		If the request is successful the text message indicates the destination and format was added to the alert for the current user and includes the destination email address, the email format type, the alert ID, and the user ID. For example: <message>Destination name@my-company.com, format HTML added to alert 34729 for user 32594</message> If an error occurs, the text message contains an explanation of the error. e.g. the email address is not submitted with the proper for amt. <message>Invalid email address: name@my-companycom</message>

Name

Values

Description

message

If the request is successful the text message indicates the destination and format was added to the alert for the current user and includes the destination email address, the email format type, the alert ID, and the user ID. For example:

<message>Destination name@my-company.com, format HTML added to alert 34729 for user 32594</message>

If an error occurs, the text message contains an explanation of the error. e.g. the email address is not submitted with the proper for amt.

<message>Invalid email address: name@my-companycom</message>

alert/addschedule - Add a schedule to an alert

Use alert/addschedule to set the days and times when an alert is to be sent. See also api/info where noun=alert and verb=addschedule . Alerts are scheduled for one or more days of the week using the days parameter, then the time of day can be scheduled in two ways:

To schedule an alert for a specific time of the day, use the parameter type=settime with the parameter setTime .
To schedule an alert to be sent periodically throughout the day, use the parameter type=period with the parameters startTime , endTime and periodInSeconds .

Example

https://secure.newsedge.com/opensapi/20/alert/addschedule?session=<<user-token>>&alert=<<alert-id>>&days=<<day-list>>&type=settime&setTime=<<hhmmss>>[&timeRangeInMinutes=<<minutes>>]

https://secure.newsedge.com/opensapi/20/alert/addschedule?session=<<user-token>>&alert=<<alert-id>>&days=<<day-list>>&type=period&startTime=<<hhmmss>>&endTime=<<hhmmss>>&periodInSeconds=<<seconds>>[&timeRangeInMinutes=<<minutes>>]

Required Parameters

Parameter	Values	Description
alert		An alert identifier. Use the value of the alert element's id attribute returned from an alert/list request.
session		The ID of the OPENS API session. Use the user-token value returned from the session/login request.
days	1,2,3,4,5,6,7 Monday, Tuesday, Wednesday, Thursday, Friday, Saturday, Sunday all weekdays	Specifies the days of the week to send the alert, where each number represents a different day. Specify more than one day by separating the numbers with commas. 1 - Monday 2 - Tuesday 3 - Wednesday 4 - Thursday 5 - Friday 6 - Saturday 7 - Sunday For example: 1,3,5 specifies an alert is to be sent Monday, Wednesday and Friday. For Monday through Friday, set value as weekdays. For seven days per week, set value as all.
type	period, settime	The type of schedule used to send the alert. period - The alert will be sent periodically, for example, hourly. This setting requires values for the following parameters: startTime endTime periodInSeconds settime - The alert will be sent at a specific time of day, for example, 9 AM. This setting requires a value for the setTime parameter.

Optional Parameters

Parameter	Values	Description
json	Default:0 0,1,2	The json parameter controls the format of the return data. If the parameter is not provided, the data is returned in XML format. 0 - Return data in XML format. 1 - Return data in compact JSON format. If the caller is planning on using JSON in production, this value should be used. 2 - Return data in expanded JSON format. This parameter value sets the return data to be in a more human-readable JSON form.
endTime	hhmmss	Required only if parameter type=period . Sets the time when periodic alerts end for the day. For example, if endTime=170000 , no alerts would be sent past 5:00:00 PM. The first alert for the day begins at the time set by the startTime parameter. Alerts then occur periodically based on the value of the periodInSeconds parameter until the time set in the endTime parameter occurs.
periodInSeconds	900, . . .	Required only if parameter type=period . Sets the amount of time in seconds between periodic alerts. Lowest value is 900. For example, if periodInSeconds=900 and startTime=080000 , then the alert would first be sent at 8:00:00 AM and every 15 minutes (900 seconds) thereafter until the endTime occurs.
setTime	hhmmss	Required only if parameter type=settime . Sets a specific time of day for an alert to be sent. For example, if setTime=164500 , then the alert is sent at 4:45:00 PM.
startTime	hhmmss	Required only if parameter type=period . Sets the time when periodic alerts start for the day. The first periodic alert is sent at the startTime . Thereafter, alerts are sent periodically based on the value of the periodInSeconds parameter until the time set in the endTime parameter occurs.
timeRangeInMinutes	1, 2, . . .	Specifies the number of minutes the alert's searches will look back from the time the alert is sent. By default, an alert will look back for stories to its last execution time. See the value attribute of the alert/info lastExecTime element. Use timeRangeInMinutes if you want to use a different timeframe.

Returned Results

The returned results include an opens-api element with a single message sub-element.

opens-api

Name	Values	Description
message		If the request is successful the text message indicates the alert is scheduled for the current user and includes the schedule ID, alert ID, and user ID. For example: <message>Schedule 3349 added to alert 34729 for user 32594</message> If an error occurs, the text message contains an explanation of the error.

Name

Values

Description

message

If the request is successful the text message indicates the alert is scheduled for the current user and includes the schedule ID, alert ID, and user ID. For example:

<message>Schedule 3349 added to alert 34729 for user 32594</message>

If an error occurs, the text message contains an explanation of the error.

alert/addsearch - Add a saved search to an alert

Use alert/addsearch to add a saved search to an alert. An alert can have more than one saved search associated with it. See also api/info where noun=alert and verb=addsearch.

Example

https://secure.newsedge.com/opensapi/20/alert/addsearch?session=<<user-token>>&alert=<<alert-id>>&savedSearch=<<ss-ID>>

Required Parameters

Parameter	Values	Description
alert		An alert identifier. Use the value of the alert element's id attribute returned from an alert/list request.
savedSearch		A saved search identifier. Use the value of the savedsearch element's ss attribute from a savedsearch/list request or the original savedsearch/create request.
session		The ID of the OPENS API session. Use the user-token value returned from the session/login request.

Optional Parameters

Parameter	Values	Description
json	Default:0 0,1,2	The json parameter controls the format of the return data. If the parameter is not provided, the data is returned in XML format. 0 - Return data in XML format. 1 - Return data in compact JSON format. If the caller is planning on using JSON in production, this value should be used. 2 - Return data in expanded JSON format. This parameter value sets the return data to be in a more human-readable JSON form.

Returned Results

The returned results include an opens-api element with a single message sub-element.

opens-api

Name	Values	Description
message		If the request is successful the text message indicates the search was added to the alert for the current user and includes the saved search ID, the alert ID, and the user ID. For example: <message>Search 13691 added to alert 34729 for user 32594</message> If an error occurs, the text message contains an explanation of the error.

Name

Values

Description

message

If the request is successful the text message indicates the search was added to the alert for the current user and includes the saved search ID, the alert ID, and the user ID. For example:

<message>Search 13691 added to alert 34729 for user 32594</message>

If an error occurs, the text message contains an explanation of the error.

alert/activate - Activate an alert to start sending messages

Use alert/activate to enable an alert to start sending email messages. See also api/info where noun=alert and verb=activate. The following requests are prerequisites before an alert/activate request:

Use alert/addsearch to specify saved search results to send in the alert.
Use alert/addschedule to specify the days and times of when to send the alert.
Use alert/adddestination to specify email addresses of where to send the alert.

Example

https://secure.newsedge.com/opensapi/20/alert/activate?session=<<user-token>>&alert=<<alert-id>>

Required Parameters

Parameter	Values	Description
alert		An alert identifier. Use the value of the alert element's id attribute returned from an alert/list request.
session		The ID of the OPENS API session. Use the user-token value returned from the session/login request.

Optional Parameters

Parameter	Values	Description
json	Default:0 0,1,2	The json parameter controls the format of the return data. If the parameter is not provided, the data is returned in XML format. 0 - Return data in XML format. 1 - Return data in compact JSON format. If the caller is planning on using JSON in production, this value should be used. 2 - Return data in expanded JSON format. This parameter value sets the return data to be in a more human-readable JSON form.

Returned Results

The returned results include an opens-api element with a single message sub-element.

opens-api

Name	Values	Description
message		If the request is successful the text message indicates the alert is activated for the current user and includes the alert ID and the user ID. For example: <message>Alert 34729 for user 32594 activated</message> If an error occurs, the text message contains an explanation of the error.

Name

Values

Description

message

If the request is successful the text message indicates the alert is activated for the current user and includes the alert ID and the user ID. For example:

<message>Alert 34729 for user 32594 activated</message>

If an error occurs, the text message contains an explanation of the error.

alert/deletedestination - Delete an email destination from an alert

Use alert/deletedestination to delete an email address from the alert. See also api/info where noun=alert and verb=deletedestination.

Example

https://secure.newsedge.com/opensapi/20/alert/deletedestination?session=<<user-token>>&alert=<<alert-id>>&emailAddress=<<address>>&emailFormat=<<format>>

Required Parameters

Parameter	Values	Description
alert		An alert identifier. Use the value of the alert element's id attribute returned from an alert/list request.
session		The ID of the OPENS API session. Use the user-token value returned from the session/login request.
emailAddress	email address format	An email address to be deleted. Use the value of a destination element returned from an alert/info request.
emailFormat	HTML, smartphone, text, mobile, Webalert	The email format for the email address being deleted. Use the value of the format attribute from the same destination element you used for the emailAddress parameter.

Optional Parameters

Parameter	Values	Description
json	Default:0 0,1,2	The json parameter controls the format of the return data. If the parameter is not provided, the data is returned in XML format. 0 - Return data in XML format. 1 - Return data in compact JSON format. If the caller is planning on using JSON in production, this value should be used. 2 - Return data in expanded JSON format. This parameter value sets the return data to be in a more human-readable JSON form.

Returned Results

The returned results include an opens-api element with a single message sub-element.

opens-api

Name	Values	Description
message		If the request is successful the text message indicates the email destination and format were deleted from the alert for the current user and includes the destination email address, the email format type, the alert ID, and the user ID. For example: <message>Destination name@my-company.com, format HTML deleted from alert 34729 for user 32594</message> If an error occurs, the text message contains an explanation of the error.

Name

Values

Description

message

If the request is successful the text message indicates the email destination and format were deleted from the alert for the current user and includes the destination email address, the email format type, the alert ID, and the user ID. For example:

<message>Destination name@my-company.com, format HTML deleted from alert 34729 for user 32594</message>

If an error occurs, the text message contains an explanation of the error.

alert/deleteschedule - Delete alert schedule

Use alert/deleteschedule to delete a schedule of days and times when an alert is sent. See also api/info where noun=alert and verb=deleteschedule.

Example

https://secure.newsedge.com/opensapi/20/alert/deleteschedule?session=<<user-token>>&alert=<<alert-id>>&schedule=<<scheduleId>>

Required Parameters

Parameter	Values	Description
alert		An alert identifier. Use the value of the alert element's id attribute returned from an alert/list request.
schedule		A schedule identifier. Use the value of the dayOfWeek element's scheduleId attribute returned from an alert/list request.
session		The ID of the OPENS API session. Use the user-token value returned from the session/login request.

Optional Parameters

Parameter	Values	Description
json	Default:0 0,1,2	The json parameter controls the format of the return data. If the parameter is not provided, the data is returned in XML format. 0 - Return data in XML format. 1 - Return data in compact JSON format. If the caller is planning on using JSON in production, this value should be used. 2 - Return data in expanded JSON format. This parameter value sets the return data to be in a more human-readable JSON form.

Returned Results

The returned results include an opens-api element with a single message sub-element.

opens-api

Name	Values	Description
message		If the request is successful the text message indicates the alert's schedule is deleted for the current user and includes the schedule ID, alert ID, and user ID. For example: <message>Schedule 3349 deleted from alert 34729 for user 32594</message> If an error occurs, the text message contains an explanation of the error.

Name

Values

Description

message

If the request is successful the text message indicates the alert's schedule is deleted for the current user and includes the schedule ID, alert ID, and user ID. For example:

<message>Schedule 3349 deleted from alert 34729 for user 32594</message>

If an error occurs, the text message contains an explanation of the error.

alert/deletesearch - Delete a saved search from an alert

Use alert/deletesearch to delete a saved search from an alert. See also api/info where noun=alert and verb=deletesearch.

Example

https://secure.newsedge.com/opensapi/20/alert/deletesearch?session=<<user-token>>&alert=<<alert-id>>&savedSearch=<<alertSearch-id>>

Required Parameters

Parameter	Values	Description
alert		An alert identifier. Use the value of the alert element's id attribute returned from an alert/list request.
savedSearch		A saved search identifier. Use the value of the alertSearch element's id attribute from an alert/info request.
session		The ID of the OPENS API session. Use the user-token value returned from the session/login request.

Optional Parameters

Parameter	Values	Description
json	Default:0 0,1,2	The json parameter controls the format of the return data. If the parameter is not provided, the data is returned in XML format. 0 - Return data in XML format. 1 - Return data in compact JSON format. If the caller is planning on using JSON in production, this value should be used. 2 - Return data in expanded JSON format. This parameter value sets the return data to be in a more human-readable JSON form.

Returned Results

The returned results include an opens-api element with a single message sub-element.

opens-api

Name	Values	Description
message		If the request is successful the text message indicates the search was deleted from the alert for the current user and includes the saved search ID, the alert ID, and the user ID. For example: <message>Search 13691 deleted from alert 34729 for user 32594</message> If an error occurs, the text message contains an explanation of the error.

Name

Values

Description

message

If the request is successful the text message indicates the search was deleted from the alert for the current user and includes the saved search ID, the alert ID, and the user ID. For example:

<message>Search 13691 deleted from alert 34729 for user 32594</message>

If an error occurs, the text message contains an explanation of the error.

alert/deactivate - Deactivate an alert to stop sending messages

Use alert/deactivate to disable an alert from sending email messages. See also api/info where noun=alert and verb=deactivate.

Example

https://secure.newsedge.com/opensapi/20/alert/deactivate?session=<<user-token>>&alert=<<alert-id>>

Required Parameters

Parameter	Values	Description
alert		An alert identifier. Use the value of the alert element's id attribute returned from an alert/list request.
session		The ID of the OPENS API session. Use the user-token value returned from the session/login request.

Optional Parameters

Parameter	Values	Description
json	Default:0 0,1,2	The json parameter controls the format of the return data. If the parameter is not provided, the data is returned in XML format. 0 - Return data in XML format. 1 - Return data in compact JSON format. If the caller is planning on using JSON in production, this value should be used. 2 - Return data in expanded JSON format. This parameter value sets the return data to be in a more human-readable JSON form.

Returned Results

The returned results include an opens-api element with a single message sub-element.

opens-api

Name	Values	Description
message		If the request is successful the text message indicates the alert is deactivated for the current user and includes the alert ID and the user ID. For example: <message>Alert 34729 for user 32594 deactivated</message> If an error occurs, the text message contains an explanation of the error.

Name

Values

Description

message

If the request is successful the text message indicates the alert is deactivated for the current user and includes the alert ID and the user ID. For example:

<message>Alert 34729 for user 32594 deactivated</message>

If an error occurs, the text message contains an explanation of the error.

alert/delete - Delete an alert

Use alert/delete to delete an existing alert. See also api/info where noun=alert and verb=delete.

Example

https://secure.newsedge.com/opensapi/20/alert/delete?session=<<user-token>>&alert=<<alert-id>>

Required Parameters

Parameter	Values	Description
alert		An alert identifier. Use the value of the alert element's id attribute returned from an alert/list request.
session		The ID of the OPENS API session. Use the user-token value returned from the session/login request.

Optional Parameters

Parameter	Values	Description
json	Default:0 0,1,2	The json parameter controls the format of the return data. If the parameter is not provided, the data is returned in XML format. 0 - Return data in XML format. 1 - Return data in compact JSON format. If the caller is planning on using JSON in production, this value should be used. 2 - Return data in expanded JSON format. This parameter value sets the return data to be in a more human-readable JSON form.

Returned Results

The returned results include an opens-api element with a single message sub-element.

opens-api

Name	Values	Description
message		If the request is successful the text message indicates the alert was deleted for the current user and includes the alert ID and the current user ID. For example: <message>Alert 34729 for user 32594 deleted</message> If an error occurs, the text message contains an explanation of the error.

Name

Values

Description

message

If the request is successful the text message indicates the alert was deleted for the current user and includes the alert ID and the current user ID. For example:

<message>Alert 34729 for user 32594 deleted</message>

If an error occurs, the text message contains an explanation of the error.

API Definition

Alerts of Story Searches

alert/create - Create an email alert

Example

Required Parameters

Optional Parameters

Returned Results

opens-api

alert/list - Get a list of alerts

Example

Required Parameters

Optional Parameters

Returned Results

opens-api

alert/info - Get alert information

Example

Required Parameters

Optional Parameters

Returned Results

opens-api

alert/update - Update alert settings

Example

Required Parameters

Optional Parameters

Returned Results

opens-api

alert/adddestination - Add an email destination for an alert

Example

Required Parameters

Optional Parameters

Returned Results

opens-api

alert/addschedule - Add a schedule to an alert

Example

Required Parameters

Optional Parameters

Returned Results

opens-api

alert/addsearch - Add a saved search to an alert

Example

Required Parameters

Optional Parameters

Returned Results

opens-api

alert/activate - Activate an alert to start sending messages

Example

Required Parameters

Optional Parameters

Returned Results

opens-api

alert/deletedestination - Delete an email destination from an alert

Example

Required Parameters

Optional Parameters

Returned Results

opens-api

alert/deleteschedule - Delete alert schedule

Example

Required Parameters

Optional Parameters

Returned Results

opens-api

alert/deletesearch - Delete a saved search from an alert

Example

Required Parameters

Optional Parameters

Returned Results

opens-api

alert/deactivate - Deactivate an alert to stop sending messages

Example

Required Parameters

Optional Parameters

Returned Results

opens-api

alert/delete - Delete an alert

Example

Required Parameters

Optional Parameters

Returned Results

opens-api