​​Product Spotlight: The Segment API

At Twilio Segment, we’re building a world-class API that reinforces our commitment to our developer community to provide an exceptional developer experience. So we’re granting programmatic access to our Segment platform to manage and scale it in new ways.  We want to make it easier for you to perform provisioning tasks in bulk while giving you the option to work from an interface you’re already familiar with — your command line. 

If you’re a Segment user, you’re already familiar with our Config API. Last year, we released a new and improved version that we call our Public API. In this blog, we’ll share what's new, what’s coming, and how it will all work together to further enhance your experience.

Wait… Is the Config API going away??

Well… yes and no, actually.  We have disabled the creation of new Config API tokens for workspaces, but existing tokens and calls will continue to work.  If you’re just getting started with API use in Segment, we’d recommend starting with the Public API anyway, since it has a wider range of endpoints and capabilities!  If this has you thinking about a migration path from Config API to Public API, we cover #How To Migrate below.

New capabilities within the Public API 

The new Public API unlocks a world of possibility in terms of automation, efficiency, and innovation. We have increased the rate limit and added support for multi-region and monitoring. Error handling has also been improved, so you can spend less time troubleshooting. With more stable endpoints, a proven 99.8% success rate, and a more robust architecture, the Public API is built with enhanced security, checks for authentication, validation, supports pagination, and per-endpoint API versioning. We’ve even included dedicated EU endpoints to help streamline GDPR compliance!

One important change from the Config API to the Public API is that we’re now using IDs to identify objects (as opposed to slugs), so you have more consistent and perpetual identifiers. We’ve also made all enumerated values uppercase, like SCREAMING_UNDERSCORE so you don’t have to guess if your data is presented likeThis or LikeThis. 

The Public API also offers a broader range of capabilities - including endpoints for our newest products, Reverse ETL and Profiles Sync. Here are some of the highlights:

Now that we’ve covered the functions within the Public API, let’s take a look at some real life use cases: 

Data warehouse integration

You can now manage your Warehouse connections, which wasn’t possible with the Config API. Create, delete, update, list, validate, and connect Warehouses directly from your Bash script or terminal.

Configure Reverse ETL

With the Public API, you can use our Reverse ETL capabilities to set up your data warehouse as a source of data, create data models to be connected, and send your data warehouse data to supported Segment Destinations. These models can be fully managed using our new API, including all CRUD operations.

Configure Profiles Sync

Profiles Sync is an exciting new product that connects unified customer profiles to your data warehouse. You can enrich and use these data sets for models, such as attribution analysis, and advanced segmentation directly in the warehouse. Set it up from your terminal, and access your profile data in your data warehouse without having to change applications!

Audit trail

Actions taken within your workspace can now be seen and monitored using the Public API. All the Data Warehouses, Profiles Syncs, and Reverse ETL models you create will generate events in the audit trail endpoint automatically. You can even forward audit trail activity to set up real-time Slack alerts and quickly revert changes that could cause unwanted downstream effects, like a user unintentionally disabling a warehouse. Segment can also support your compliance goals by helping you better understand your workspace history in the last 90 days. 

Monitoring

Our monitoring endpoint lets you consume the volume of events being ingested in your workspace, and our Public API lets you group by event Name, type, and source.  Instead of waiting until your next log-in to catch errors or bad behavior, proactively monitor your workspace with automated tools (like PagerDuty, DataDog) that alert you when certain bad behaviors occur, and  get ahead of any issues within your workspace. 

SDKs

Finally, we’ve released SDKs for Go, Swift, Typescript, and Java. Build in the language you’re most comfortable with using SDKs that are secure, open-source, and provide debugging information along with auto-generated docs. Don’t see your preferred language? Reach out to us at friends@segment!

Some other great uses…

While we just showcased what’s new with Public API, we wanted to remind you of some other great ways to use the product!

Observability with Event Delivery Metrics

In addition to Delivery Overview, our event delivery metrics endpoints allow you to integrate Segment to any existing observability tool you may have, such as DataDog or Grafana, or even a data warehouse.

If you use DataDog, check out DataDog’s Segment Connector that uses our delivery metrics APIs.

Tracking Plans

Tracking Plans are a key part of successfully keeping your organization aligned and executing on consistent and reliable data. 

In addition to your standard Connections configurations, this means that Tracking Plans are often critical to keep up to date between your test and production environments, and multiple Workspaces.  Use the Tracking Plan API to create, and update your Tracking Plans programmatically to keep them consistent across Segment Workspaces.

Regulations

With our Regulations endpoints, you can programmatically delete user information upon requests from your customers.  This is useful to comply with GDPR and CCPA.   Learn more about Segment’s User Deletion and Suppression capabilities.

Usage

Segment’s Usage and Billing page provides a standard way to report on your billable usage, and in most cases our standard tool is sufficient.  

However, with our Usage endpoints you can track MTUs and APIs with more granularity, and integrate the data to another tool (like your data warehouse), for your own reporting and custom alerts that suit the needs of your organization.

Migrating to the Public API

Are you ready to make the conversion to the Public API? When migrating, it’s important to note that our Config API and our Public API don’t share common endpoints, so head to our interactive docs  to find your existing  Config API endpoints and their respective counterparts in the Public API.  While we encourage you to start using our new and improved Public API, we’re maintaining our backward compatibility so that you won't need to migrate until you are ready. However, please note that any future improvements will only be added to the Public API.

To help you get started, at the beginning of each section in our documentation we have created a table mapping the endpoints and fields of the Config API x Public API:

Coming soon to an API near you

• APIs for additional Segment functionality tailored to data/marketing centric uses.

• Programmatic support for new Segment features (most recently, Reverse ETL and Profiles Sync).

• More developer tooling and easier ways to manage Segment deployments!

To learn more about Twilio Segment for Developers, join us for the Developer Keynote and for Superclass at this year’s SIGNAL. The Public API is currently available to all Team and Business Tier customers, so head over to our documentation and try it out for yourself. 

We can’t wait to see what you build!

A special thank you to additional blog contributors- Kurt Lu and Ben Link.