Corporate reporting API: Changelog

What has changed on the corporate reporting API, and the rules we follow when changing it. Breaking changes are announced at least 90 days.

Last reviewed

November 2026: Allowed IP addresses and provisioning token rotation

Additive, and no action is required. Keys and tokens without allowed IP addresses keep working from anywhere, as before.

  • Allowed IP addresses: an owner can lock a key or SCIM provisioning token to up to 20 public addresses or ranges. A call from anywhere else gets 403 with error_code IP_NOT_ALLOWED, and owners are emailed
  • SCIM token rotation and expiry: provisioning tokens can be rotated, with the old token kept working for 24 hours or ended at once, and can be given an expiry date. See the SCIM reference
  • Audit log: every change made over SCIM is recorded in your organisation’s audit log with the token prefix and the address it came from

October 2026: Key rotation and response headers

Additive, and no action is required. Existing keys and webhook endpoints keep working as before.

  • Rotation: an owner can rotate a key from the API access card on your corporate settings screen. The old key either keeps working for 24 hours, so you can swap it in your systems without downtime, or stops at once if you choose
  • Expiry warnings: every active owner is emailed before a key expires
  • Leaked keys: a twcorp_ key found exposed in public is revoked automatically
  • Rate-limit headers: responses carry X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset, like the other external APIs
  • Version header: every response carries API-Version, so you can log which version answered
  • Webhooks: an endpoint switched off after repeated failures can be reactivated, and the email saying it was switched off now goes to every active owner

October 2026: More webhook events

Additive, and no action is required. Existing endpoints keep receiving exactly the events they were subscribed to.

  • employee.deactivated and employee.reactivated: an employee’s seat was switched off or back on
  • contract.expiring, contract.renewed, contract.renewal_declined and contract.expired: your contract is nearing its end, moved later, an owner chose not to renew it, or it has ended
  • invoice.issued and invoice.paid: an invoice was issued to your organisation or paid
  • campaign.sent: an adoption campaign finished sending to your employees

Like the original event, each carries identifiers and timestamps only, never anything an employee put in their will.

September 2026: Initial release

The first release of the corporate reporting API, a read-only surface under /api/v1/corporate/ext/.

  • Reporting: overview/, trends/ and feature-adoption/, with small numbers hidden exactly as on your dashboard
  • Invoices: invoices/, read only
  • Roster: roster/, with cursor pagination and updated_since
  • Authentication: twcorp_ keys sent as Authorization: Bearer tokens, with the corporate:reporting:read and corporate:roster:read scopes
  • Webhooks: employee.activated, signed under the standard webhooks scheme
  • Reference: the Corporate reporting API reference, the machine-readable schema at /api/v1/corporate/ext/schema/ and the interactive console at /api/v1/corporate/ext/docs/

Rate limits

Limits are counted on a sliding window. When you go over one, the API answers 429 Too Many Requests with a Retry-After header telling you how long to wait.

Corporate reporting API

Every request to /api/v1/corporate/ext/.

  • Every plan: 120 requests per minute

Counted separately for each key. Scopes: corporate:reporting:read, corporate:roster:read.

These figures come from the limits the API enforces, also served as JSON at /api/v1/portfolio/rate-limits/.

Versioning and deprecation policy

The corporate reporting API uses URL versioning: every endpoint is prefixed with /api/v1/corporate/ext/. The same rules apply to every external API, including the tools our MCP server offers AI assistants.

What counts as a breaking change

  • Additive (not breaking): new fields on responses, new endpoints, new optional query parameters, new webhook events and new MCP tools. These can arrive at any time and do not change the version.
  • Breaking: a removed or renamed field, endpoint or MCP tool, a changed field type, a new required parameter, or a change to how you authenticate.

Notice and support periods

  • A breaking change is announced at least 90 days before it takes effect.
  • When a new API version is released, the previous version keeps working at least 180 days afterwards.
  • Security fixes and legal requirements may need shorter notice; we will say so here and explain why.

How you are told

  • This changelog: every deprecation is listed here with its retirement date.
  • Response headers: every response from a deprecated path carries Deprecation, Sunset (the retirement date) and a Link header with rel="deprecation" pointing back to this page.
  • Machine-readable policy: /api/v1/api-policy/ returns these periods and every live deprecation as JSON.

At the retirement date

From the date in the Sunset header, the retired path answers 410 Gone with the code api_sunset and the replacement to move to. Your API key keeps working for everything that has not been retired.

Have your integration ignore fields it does not recognise, and log any response that carries a Deprecation header. Together they keep an additive change from breaking you and make sure a deprecation does not go unnoticed.

Staying informed

  • This page: the record of every change to the corporate reporting API, worth a look once a month
  • The schema: /api/v1/corporate/ext/schema/ changes with the surface, so you can diff it between releases
  • Webhooks: they tell you about activity in your organisation, not about API versions. Deprecation notices are never delivered by webhook
  • Contact support: get in touch if you need help migrating

Note

The consumer and professional APIs have their own changelogs and the same rules apply to them. They version independently of this one.

Can’t find what you’re looking for?

Our support team is here to help. Contact us and we’ll get back to you as soon as possible.

Contact us

We use cookies to improve your experience. See our Cookie policy (opens in a new tab) for details.