Corporate Reporting API

The Orchard72 corporate API lives under /api/v1/corporate/ext/ and mirrors your corporate dashboard:

• overview/, trends/ and feature-adoption/: aggregate adoption figures
• invoices/: your organisation’s invoices, read only
• roster/: who has been invited and who has activated their account

Corporate keys start with twcorp_ and are sent as Authorization: Bearer <your key>. Each key carries one or both of two scopes:

• corporate:reporting:read: overview, trends, feature adoption and invoices
• corporate:roster:read: the employee roster

Only an owner of the organisation can create or revoke a key. A key can be given an expiry date, the full key is shown once when it is created, and we store only a fingerprint of it, so a lost key cannot be recovered: revoke it and create another.

To create or revoke a key, open Settings under Corporate Dashboard and use the API access card.

To stop figures pointing at individuals, usage counts stay hidden until enough employees have activated their account. Until then overview/ returns its counts as null, sets usage_below_threshold to true, and gives the number of activations needed in usage_privacy_threshold.

feature-adoption/ applies the same idea feature by feature: a feature used by too few employees comes back with users_active and adoption_rate as null and is_below_threshold as true, and privacy_threshold gives the number needed. Your dashboard applies exactly the same rules.

The roster supports cursor pagination (?cursor=), a page_size and updated_since, so after one full read you can fetch only the rows that changed. The rules are the same as on the Professional API.

The employee.activated webhook tells your systems when an invited employee activates their account. It carries the employee id and the time only, so you can mark the seat as taken up without receiving anything personal you did not already hold.

An organisation owner manages receivers in the Webhooks card of organisation settings, or through /api/v1/corporate/settings/webhooks/ while signed in. A corporate API key cannot register one. Adding a receiver or rotating its signing secret asks the owner to confirm their identity first. The receiver must use HTTPS and a public host. The signing secret is shown once, when the receiver is added or its secret is rotated. Every owner can list, test, rotate and delete the organisation’s receivers, and each change is recorded in the audit log without the receiver address.

After repeated failed deliveries a receiver is deactivated and receives no further events. Every owner is emailed when that happens. To resume, register a working receiver and delete the deactivated one.

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.

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

• The full reference for each endpoint is in the interactive API documentation at /api/v1/corporate/ext/docs/.
• Corporate admin guide: running your organisation’s account day to day.
• Privacy for corporates: what you can and cannot see about employees.