Getting Started with Corporate Actions API: Announcements

Corporate action announcements refer to the notification of future reorganization events that impact shareholder positions. Alpaca's Corporate Actions API: Announcements allows users to access detailed information on the four main categories of corporate action events: dividends, mergers, spinoffs, and stock splits.

Stay informed about upcoming events to enhance trading strategies and look back at previous announcements for easier bookkeeping and reconciliation – all within the Alpaca platform.  

Alpaca’s announcement database contains previous and upcoming corporate actions that are made available shortly after the announcement’s declaration date.

Announcement Details through Alpaca’s API

Announcement information is typically available on the endpoint no later than the following trading day after the corporate action’s declaration date. In the case when a company has multiple term updates to an upcoming reorganization event, new announcements will be generated each time without overwriting previous data.

For a full list of data points that are accessible through Alpaca’s API, please refer to our Broker API and Trading API documentation.

How to Optimize the Corporate Actions API

Trading API

With Corporate Actions API, Trading API users are now able to stay up-to-date on all upcoming announcements and create custom updates based on holdings or trading strategies, all within the Alpaca platform.

The Corporate Actions API also helps operations teams improve bookkeeping, which can be useful in reconciling account position and cash balance changes caused by a corporate action. Additionally, the API supports retrieving a specific announcement by pasting its ID into the query parameter to simplify any necessary information gathering.

Broker API

Broker partners gain the ability to integrate announcement updates into their trading platforms. It’s now possible to create custom notifications of upcoming announcements for all users on the declaration date, as well as shareholders on the ex-date or payable date.

As with Trading API, the Corporate Actions API can also be used for enhanced bookkeeping and retrieving specific announcements. On top of this, knowing the details of upcoming announcements can help with necessary system preparations for bespoke announcements or reorganization events that affect a large number of accounts.

The new API also enables users to implement trading strategies centered around corporate actions. Broker partners are able to offer announcement data within their own platforms to diversify target audiences and product offerings.

Let’s Get Started!

Follow these steps to get started with the Corporate Actions API: Announcements using Postman.

First, make sure that Postman is set up with Alpaca’s API and that all environment settings are correct. If you need help setting up your workspace, please view Alpaca's Postman step-by-step guide.

How to Search for Announcements Using Search Criteria

The Corporate Actions API: Announcements endpoint broadly queries an array of announcements given user-specified criteria. You may search announcements by type, symbol, and cusip over a specified date range. Furthermore, the endpoint allows you to determine which announcement date type should be used when applying the date range.

Let’s step through this functionality with an example, which will be centered around KKR’s dividend payment to shareholders in November of 2021. Start by pasting the endpoint into Postman. This tutorial will utilize the sandbox endpoint for Broker API, however, you may substitute this with the relevant endpoint based on your use case.

GET v1/corporate_actions/announcements

Now we can add in our search criteria. All of the search parameters should be listed as keys in Postman, so start by filling in the three fields marked as required for the endpoint: since, until, and ca_types. The ‘since’ and ‘until’ parameters serve as our date range which defaults to an announcements payable date, while the 'ca_types' parameter specifies which type of corporate actions to return. Let’s look at all dividends with a payable date on November 1st and November 2nd of 2021 by adding the following values.

GET v1/corporate_actions/announcements/?since=2021-11-01&until=2021-11-02&ca_types=dividend

Press ‘Send’ to make your first Corporate Actions API: Announcements call. Postman will show the response in the lower half of the screen as an array of announcement objects. You can now scroll through the returned result to view all of the corporate actions data in Alpaca’s systems.

Next, let’s filter down the returned data by adding additional search criteria. Set date_type to declaration_date and symbol to KKR as the respective key-value pairs.

GET v1/corporate_actions/announcements/?since=2021-11-01&until=2021-11-02&ca_types=dividend&date_type=declaration_date&symbol=KKR

This request returns a very specific announcement - the KKR dividend that was announced on November 1st, 2021 - as it is the only corporate action that fits within the given criteria.

How to Search for a Specific Announcement

Another way to retrieve a specific announcement is using the GET /v1/corporate_actions/announcements/{id} endpoint, which returns the information for a specific corporate action announcement. In order to do this, use the returned ID in the response body of an announcement and pass it through the request path.

Let’s continue the example with KKR’s dividend. Instead of adding in the search criteria as detailed above, we can save the ID in the returned announcement object.

Next, we can append the ID onto the endpoint path and send the request.

GET v1/corporate_actions/announcements/322075f8-6555-4bf7-9882-daceb82b22a4

This will return a single announcement object instead of an array. In this case, we will see the same KKR dividend with a declaration date on November 1st, 2021. This methodology can be applied for any corporate action available in Alpaca’s database to increase query efficiency, which can help with implementing corporate action-based trading strategies and improving bookkeeping and reconciliation.

Summary

The Corporate Actions API: Announcements is available to use across Alpaca Trading API and Broker API to retrieve upcoming announcements, perform retroactive bookkeeping, implement enhanced trading strategies, and more.

Check out our blog to learn more about the corporate action announcements product offering. For additional details on how to interact with the new API endpoint, please refer to the Trading API documentation or Broker API documentation, or reach out to an Alpaca team member at [email protected].

This content is for general information only. Alpaca does not recommend any specific investments or investment strategies. Investments in securities involve the risk of losses and past performance does not guarantee future results. Before investing you should carefully consider your investment objectives, time horizon, and overall risk tolerance as well as the information stated in the product offering prospectuses.

Securities brokerage services are provided by Alpaca Securities LLC (“Alpaca”), member FINRA/SIPC, a wholly-owned subsidiary of AlpacaDB, Inc. Technology and services are offered by AlpacaDB, Inc.

This is not an offer, solicitation of an offer, or advice to buy or sell securities, or open a brokerage account in any jurisdiction where Alpaca is not registered (Alpaca is registered only in the United States).