Corporate reporting API
Feed the figures from your corporate dashboard into your HR or finance reporting, without ever exposing what employees put in their wills.
Last reviewed
What you can read
The TheWILL.ai corporate API lives under /api/v1/corporate/ext/ and mirrors your corporate dashboard:
overview/,trends/andfeature-adoption/: aggregate adoption figuresinvoices/: your organisation’s invoices, read onlyroster/: who has been invited and who has activated their account
Never will content
No corporate key can read an employee’s will, vault documents or estate details. The API gives you the same figures as your dashboard and nothing more.
Corporate keys
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 invoicescorporate: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.
Rotating a key
Rotate a key on a regular schedule, when someone who knew it leaves, and straight away if it may have leaked. Choose Rotate on the key in the API access card. You get a replacement key with the same name, scopes and expiry date, shown once, and you choose what happens to the old one:
- Keep the old key working for 24 hours, so you can move your systems across without a gap
- Stop the old key now, for a key you believe has leaked
Rotating asks the owner to confirm their identity first, as creating a key does. Revoking a key stops it at once.
Allowed IP addresses
You can lock a key to your own network. Add allowed IP addresses when you create the key, or later with Edit IP addresses on its row in the API access card. With no addresses, which is the default, the key works from anywhere; the row reads “Allowed IP addresses: any address” or how many addresses it allows.
- Up to 20 entries, each an IPv4 or IPv6 address or a CIDR range such as
198.51.100.0/24 - Only public addresses are accepted. Private, loopback and link-local addresses are refused, as are ranges wider than
/8(IPv4) or/32(IPv6) - A call from any other address gets
403witherror_codeIP_NOT_ALLOWED. The error never lists the addresses that are allowed - Owners are emailed when a key is refused this way, at most once a day for each key, with the address that was refused
- The request log on each key lists refused calls too, so you can check which address your system calls from
Key history
Choose History on a key in the API access card to see what has happened to it, newest first: when it was created, rotated (and whether the old key kept working for 24 hours), when its allowed IP addresses changed, when expiry reminders were sent and when it was revoked, including automatically because it was found in a public code repository. Each entry shows who did it, or System for automatic actions. A rotated key keeps the history of the key it replaced, and a revoked key’s history stays available.
Your first call
Fetch the overview to check that your key works. Replace BASE_URL with the address you sign in at:
curl "BASE_URL/api/v1/corporate/ext/overview/" \ -H "Authorization: Bearer twcorp_your_api_key_here"
- A working key returns your adoption overview as JSON
401means the key is wrong, revoked or expired403means the key does not carry the scope the endpoint needs (corporate:reporting:readfor the overview)403witherror_codeIP_NOT_ALLOWEDmeans the key has allowed IP addresses and your call came from a different one
Every endpoint, field and error is described in the API reference. Try requests in the interactive console, or download the OpenAPI schema to generate a client or import it into an API tool of your choice.
Small numbers are hidden
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.
Keeping a roster in step
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.
Webhooks
Webhooks tell your systems when a seat, your contract, an invoice or an adoption campaign changes. Each receiver chooses the events it wants. Every payload carries ids, dates and times only: never a name, an email address, an amount or anything from an employee’s will. Look the id up through the API if you need more.
employee.activated: An employee’s seat went live, by invitation, single sign-on or reactivation. Payload:event,employee_id,activated_at.employee.deactivated: An employee’s seat was deactivated, including when the contract expired. Payload:event,employee_id,deactivated_at.employee.reactivated: A deactivated employee’s seat was switched back on. Payload:event,employee_id,reactivated_at.contract.expiring: Your contract ends in 90, 60 or 30 days. Sent once for each of those points. Payload:event,client_id,contract_end_date,days_remaining,notified_at.contract.renewed: Your contract end date moved later, after an invoice was paid or the contract was extended. Payload:event,client_id,previous_contract_end_date,contract_end_date,renewed_at.contract.expired: The grace period after your contract ended has passed and every seat has been deactivated. Payload:event,client_id,contract_end_date,expired_at.invoice.issued: An invoice was issued to your organisation. Payload:event,invoice_id,issued_at.invoice.paid: An invoice was paid. Payload:event,invoice_id,paid_at.campaign.sent: An adoption campaign finished sending to your employees. Payload:event,campaign_id,sent_at.
Times are ISO 8601 with their UTC offset and dates are YYYY-MM-DD. Each delivery is signed under the Standard Webhooks scheme (webhook-id, webhook-timestamp and webhook-signature headers), and a failed delivery is retried with the same webhook-id, so use it to ignore a repeat.
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.
Checking a delivery is genuine
- Join
{webhook-id}.{webhook-timestamp}.{raw body}, using the raw request body exactly as received - Compute an HMAC-SHA256 of that string, keyed with the UTF-8 bytes of the receiver’s signing secret, and base64-encode it
- Compare it, in constant time, with each value after
v1,in the space-separatedwebhook-signatureheader - Reject a delivery whose
webhook-timestamp(Unix seconds) is more than a few minutes old, so a captured delivery cannot be replayed
import base64
import hashlib
import hmac
def verify_corporate_webhook(raw_body, secret, headers):
signed = (
f"{headers['webhook-id']}.{headers['webhook-timestamp']}.".encode()
+ raw_body
)
expected = base64.b64encode(
hmac.new(secret.encode("utf-8"), signed, hashlib.sha256).digest()
).decode()
return any(
hmac.compare_digest(f"v1,{expected}", candidate)
for candidate in headers["webhook-signature"].split(" ")
)An off-the-shelf Standard Webhooks library works too. It expects the key base64-encoded, so pass it the base64 encoding of your signing secret.
Retries
Answer with any 2xx status within 10 seconds to acknowledge a delivery. Any other answer, a redirect or no answer in time counts as a failure, and the delivery is tried again:
- Immediately (first attempt)
- After 1 minute
- After 5 minutes
- After 30 minutes
- After 2 hours
- Then once a day for up to 5 days
These are the earliest each attempt is made. Retries are picked up by a periodic sweep, so a gap can be longer. After 10 consecutive 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.
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/.
The limit is counted for each key on its own. Every response reports what is left in the X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset headers. When you get a 429, wait for the number of seconds in Retry-After before you try again, and back off further if it happens again rather than retrying in a tight loop.
Related
- The full reference for each endpoint is in the Corporate reporting API reference.
- Corporate admin guide: running your organisation’s account day to day.
- Privacy for corporates: what you can and cannot see about employees.
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
