API Definition

Alerts of Story Searches

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

  1. Create the alert using alert/create.
  2. 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.
  3. 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.
  1. 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>
  2. 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>
  3. 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/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>
  4. 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.

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

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

    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>
  8. 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>
  9. Review an alert's information.

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

    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>
  10. 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 ElementThe alert/update Parameter to Use
    alert name attribute Use the parameter name to change the alert's name.
    alertSubject elementUse the parameter subject to set or change the email subject line.
    alertComment elementUse the parameter comment to add a text comment to the top of the email.
    emailContents value attributeUse 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 attributeUse the parameter tocLocation=top to add a table of contents to the top of the email.
    maxResults value attributeUse the parameter maxResultsPerSearch to set the maximum number of results for each search included in the alert.
    maxStories value attributeUse the parameter maxStoriesPerEmailto set the maximum number of stories to include in an alert email message.
    maxTotalStories value attributeUse the parameter maxStoriesPerAlert to set the maximum total number of saved search results to be emailed for the alert.
    enableHighlighting elementUse 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>
  11. 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.
  1. 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>
  2. 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.)

    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>
  3. 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>
  4. 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>
  5. 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:

  1. Use alert/addsearch to specify what stories to send by associating one or more saved searches with the alert.
  2. Use alert/addschedule to specify when to send the alert.
  3. Use alert/adddestination to specify where to send the alert by associating one or more email addresses.
  4. 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
nameA name for the alert.
sessionThe ID of the OPENS API session. Use the user-token value returned from the session/login request.

Optional Parameters

Parameter Values Description
jsonDefault: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.
commentIntroductory text added to the beginning of the email message.
contentsDefault:briefs
headlines, briefs		Sets what type of story content the alert is to include.
  • briefs - headlines and summaries.
  • headlines - headlines only.
highlightingDefault: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.
maxResultsPerSearchDefault: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.

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

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

subjectThe text for the email subject line.
tocLocationDefault: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
messageIf 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
sessionThe ID of the OPENS API session. Use the user-token value returned from the session/login request.

Optional Parameters

Parameter Values Description
jsonDefault: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
alertsThe alerts element represents the list of alerts with one or more alert sub-elements.
alertRepresents 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
alertAn alert identifier. Use the value of the alert element's id attribute returned from an alert/list request.
sessionThe ID of the OPENS API session. Use the user-token value returned from the session/login request.

Optional Parameters

Parameter Values Description
jsonDefault: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
alertsThe 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
    •
alertScheduleAn 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.
dayOfWeek1, 2, 3, 4, 5, 6, 7A 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:
    1. Monday
    2. Tuesday
    3. Wednesday
    4. Thursday
    5. Friday
    6. Saturday
    7. 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.
setTimeThhmmss-hhmmIndicates a specific time of the day the alert will execute. Time is in hours minutes and seconds with an offset from Greenwich Mean Time.
startTimeThhmmss-hhmmIndicates the time when this periodic alert is scheduled to start for the day.
endTimeThhmmss-hhmmIndicates the time after which no more periodic alerts are sent for the day.
periodPTmmMIndicates the time in minutes between the executions of periodic alerts during a day.
alertSearchesA 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.
alertSearchA 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.
additionalDestinationsA list of alert destinations, where each destination is represented by a destination sub-element. Destinations are added to alerts using alert/adddestination.
destinationAn 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.
alertSubjectText of the alert's email subject line. See also the subject parameter of alert/update or alert/create.
alertCommentOptional 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, headlinesThe 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, noneIndicates 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-ZZZZIndicates 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, . . .,50Indicates 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, . . .,100Indicates 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, . . .,500Indicates the maximum number of stories to be included in the alert. See also the maxStoriesPerAlert parameter of alert/update or alert/create.
enableHighlightingY, or empty tagIndicates 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
alertAn alert identifier. Use the value of the alert element's id attribute returned from an alert/list request.
sessionThe ID of the OPENS API session. Use the user-token value returned from the session/login request.

Optional Parameters

Parameter Values Description
jsonDefault: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.
commentAdds or changes introductory text at the beginning of the email message.
contentsheadlines, briefsResets what type of story content the alert is to include.
  • briefs - headlines and summaries.
  • headlines - headlines only.
highlightingtrue, falseResets 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.
maxResultsPerSearch1, 2, . . ., 50Resets 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.

maxStoriesPerEmail1, 2, . . ., 100Resets 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.

maxStoriesPerAlert1, 2, . . ., 500Resets 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.

nameChanges the name of the alert.
subjectChanges or adds text for the email subject line.
tocLocationtop, 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
messageIf 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
alertAn alert identifier. Use the value of the alert element's id attribute returned from an alert/list request.
sessionThe ID of the OPENS API session. Use the user-token value returned from the session/login request.
emailAddressemail address formatAn email address to which the alert email is to be sent. The format is: 
name@my-company.com
emailFormatHTML, smartphone, text, mobile, WebalertThe 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
jsonDefault: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
messageIf 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
alertAn alert identifier. Use the value of the alert element's id attribute returned from an alert/list request.
sessionThe ID of the OPENS API session. Use the user-token value returned from the session/login request.
days1,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.

typeperiod, settimeThe 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:
  • 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
jsonDefault: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.
endTimehhmmssRequired 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.

periodInSeconds900, . . .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.
setTimehhmmssRequired 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.
startTimehhmmssRequired 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.
timeRangeInMinutes1, 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
messageIf 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
alertAn alert identifier. Use the value of the alert element's id attribute returned from an alert/list request.
savedSearchA saved search identifier. Use the value of the savedsearch element's ss attribute from a savedsearch/list request or the original savedsearch/create request.
sessionThe ID of the OPENS API session. Use the user-token value returned from the session/login request.

Optional Parameters

Parameter Values Description
jsonDefault: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
messageIf 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:


Example

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

Required Parameters

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

Optional Parameters

Parameter Values Description
jsonDefault: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
messageIf 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
alertAn alert identifier. Use the value of the alert element's id attribute returned from an alert/list request.
sessionThe ID of the OPENS API session. Use the user-token value returned from the session/login request.
emailAddressemail address formatAn email address to be deleted. Use the value of a destination element returned from an alert/info request.
emailFormatHTML, smartphone, text, mobile, WebalertThe 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
jsonDefault: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
messageIf 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
alertAn alert identifier. Use the value of the alert element's id attribute returned from an alert/list request.
scheduleA schedule identifier. Use the value of the dayOfWeek element's scheduleId attribute returned from an alert/list request.
sessionThe ID of the OPENS API session. Use the user-token value returned from the session/login request.

Optional Parameters

Parameter Values Description
jsonDefault: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
messageIf 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
alertAn alert identifier. Use the value of the alert element's id attribute returned from an alert/list request.
savedSearchA saved search identifier. Use the value of the alertSearch element's id attribute from an alert/info request.
sessionThe ID of the OPENS API session. Use the user-token value returned from the session/login request.

Optional Parameters

Parameter Values Description
jsonDefault: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
messageIf 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
alertAn alert identifier. Use the value of the alert element's id attribute returned from an alert/list request.
sessionThe ID of the OPENS API session. Use the user-token value returned from the session/login request.

Optional Parameters

Parameter Values Description
jsonDefault: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
messageIf 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
alertAn alert identifier. Use the value of the alert element's id attribute returned from an alert/list request.
sessionThe ID of the OPENS API session. Use the user-token value returned from the session/login request.

Optional Parameters

Parameter Values Description
jsonDefault: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
messageIf 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.