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/ and feature-adoption/: aggregate adoption figures
  • invoices/: your organisation’s invoices, read only
  • roster/: 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 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.

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 403 with error_code IP_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
  • 401 means the key is wrong, revoked or expired
  • 403 means the key does not carry the scope the endpoint needs (corporate:reporting:read for the overview)
  • 403 with error_code IP_NOT_ALLOWED means 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

  1. Join {webhook-id}.{webhook-timestamp}.{raw body}, using the raw request body exactly as received
  2. Compute an HMAC-SHA256 of that string, keyed with the UTF-8 bytes of the receiver’s signing secret, and base64-encode it
  3. Compare it, in constant time, with each value after v1, in the space-separated webhook-signature header
  4. 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

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.