Skip to main content

Hook Public API: Overview and Getting Started

Getting started with using Hook's public API

Overview

Customer Success teams and technical admins often need to get Hook data into other systems, or query Hook programmatically for reporting, automation, and integrations that go beyond what's available natively. Doing this without an API means manual exports, local filtering of thousands of records, and unreliable workarounds.

The Hook Public API provides programmatic read access to your Hook data. It is authenticated using API tokens and scoped to your organisation.

Full documentation can be found at docs.api.hook.co.

What the API currently covers

The following endpoints are available from the API:

  • Members: Access member profiles and role assignments

  • Customers: List and query customer records

  • Products: Access product data

  • Signals: Read risk and engagement signals, including the ability to set a primary risk signal on creation

  • Notes: Notes added on account pages

When to use the API

There are several use cases for accessing Hook data using the API, including:

  • Pulling Hook data into an external dashboard or reporting tool

  • Running scheduled exports of customer, signal, or notes data in CSV or JSON format

  • Powering custom integrations that aren't covered by Hook's native connectors

  • Add notes created using Hook to your CRM using the notes endpoint

💡 Hook's public API is currently read-only.

Getting Started with the Hook API

Step 1: Generate an API Token

API tokens are generated through the Hook UI. Tokens are scoped to your organisation, ensuring strict data isolation, and include rate limiting and expiry controls.

  1. Go to Profile settings > API Tokens in Hook

  2. Click + Create Token

  3. Give the token a name and set the time period the API token should be valid for (default value is 30 days). Note: the token will expire after this time period, and any future API requests will not be valid.

  4. Click Create token

  5. Copy your API token (it will not appear after exiting this screen)

Creating a new API token in Profile settings

Step 2: Make your First Request

Use the token copied in Step 1 to authenticate requests against the Hook API endpoints.

Full documentation can be found at docs.api.hook.co.

Example Use Case: Exporting Automation Logs

Use the Automations endpoints to pull a full history of an automation's activity for reporting, auditing, or record-keeping outside Hook.

  1. Find the automation and its trigger/action IDs.
    Call GET /organizations/{organizationId}/automations to list all automations, or GET /organizations/{organizationId}/automations/{automationId} for a specific one. The response includes the automation's triggers and actions, each with an ID you'll need for the next step.

  2. Pull the logs. There are two log types, depending on what you want to see:

    • Action logs (what the automation did): GET /organizations/{organizationId}/automations/{automationId}/actions/{actionId}/logs - these are the outputs of the automation e.g. emails, signals, alerts etc

    • Trigger logs (when the automation fired): GET /organizations/{organizationId}/automations/{automationId}/triggers/{triggerId}/logs - this shows which accounts or users are triggered by the automation

  3. Page through the results. Both endpoints accept offset and limit query parameters (limit maxes out at 250, default 100) and return a totalCount so you know how many records exist in total. Keep incrementing offset until you've retrieved everything.

  4. Export. Since the API returns JSON, save the combined items from each page as a CSV or JSON file to complete your export.

All requests require a bearer token in the header:

Authorization: Bearer <YOUR_TOKEN>
​

Example request for action logs:
​

curl -i -X GET \   'https://api.hook.co/v1/organizations/{organizationId}/automations/{automationId}/actions/{actionId}/logs?offset=0&limit=250' \   -H 'Authorization: Bearer <YOUR_TOKEN_HERE>'

Example Use Case: Building Signal Adoption Reports

There are standardised CSM performance reports in Hook. The guidance below is for creating a fully customisable signal adoption report.

Use the API to build a recurring report showing how your team is engaging with signals in Hook - who owns what, what's being actioned, and what's being dismissed - and feed it into your own BI tool.
​

1. Pull your team members

GET /organizations/{organizationId}/members
​

Returns every member with id, firstName, lastName, email and managerId. Use managerId to build your reporting hierarchy so the report can be rolled up by manager as well as by individual.
​

2. Pull your customer list and account ownership

GET /organizations/{organizationId}/customers
​

Each customer includes memberRoles (who is assigned as CSM, AM, etc.), plus segment, employeeCount, and per-product arr, renewalDate and engagement.level. This is what lets you attribute signals to the right account owner and slice the report by segment or ARR band.
​

Supports offset/limit (limit max 250) and status (Active, Churned, Upcoming, Unassigned).
​

3. Pull signals - the core of the report

GET /organizations/{organizationId}/signals
​

The status query parameter is what makes this useful for adoption reporting. Call the endpoint once per status and count the results:

  • status=Detected: signals Echo has surfaced but nobody has reviewed yet (your triage backlog)

  • status=Active: signals accepted and being worked

  • status=Cleared: signals resolved, after being active

  • status=Dismissed: signals rejected, optionally with a dismissalReason

Each signal also returns ownerId, createdById, createdDate, raisedDate, closedDate, updatedDate, severity, source, category, type and outcome: enough to calculate per-person volumes, time-to-close, and accept vs dismiss rates over any time window you choose.
​

Use scope (mine, team, all) if you want the report restricted to a particular team's accounts.
​

4. Page through and store the results

All list endpoints return totalCount alongside items. Increment offset by your limit until you've retrieved totalCount records, then write the combined results to a CSV, a warehouse table, or a Google Sheet.
​

5. Schedule it

Run the script on a schedule (daily or weekly) and append each run with a snapshot date. Storing snapshots rather than overwriting is what turns a point-in-time export into a trend report - you can then show week-on-week movement in triage backlog, dismissal rate, and signals cleared per person.
​

What you can build with signals data

  • Signal triage funnel: Detected → Active → Cleared/Dismissed, showing where signals stall

  • Per-CSM scorecard: Signals owned, cleared in last 7/30 days, and average days-to-close, rolled up by manager via managerId

  • Dismissal analysis: Grouped by dismissalReason and category, to spot where Echo is generating noise and needs prompt tuning

  • Coverage gaps: Accounts with active high-severity signals and no assigned owner in memberRoles

  • Renewal risk view: Active signals joined to renewalDate and arr, to surface at-risk revenue in the next 90 days

Any tool that reads CSV or JSON will work: Looker Studio, Power BI, Tableau, or a Google Sheet fed by Apps Script.

The API doesn't currently expose login activity, page views, Hook Chat usage, or action completion data, so those metrics can't be included in a self-built report. For logins activity, use the Usage report in Hook.
​
If you need a report covering these other data points, speak to your Account Manager.

❓Frequently Asked Questions

Who can use the Hook API?

Anyone with a Hook account can generate a API token.

Are there limits to the data I can access?

Each token is scoped to the permissions of the user who created it. API requests made with a token cannot exceed the access level of that user. For example, if your permissions are Can view: My customers, then the API will only return data for customers you're assigned to. Find out more about permissions here.

Can I generate multiple API tokens for different applications?

Create more than one API token by clicking + Create token in Profile settings > API Tokens, naming each one appropriately.


What is the maximum token lifetime for API tokens?

365 days. Token lifetime can be configured when creating an API token.

What is the rate limit and quota limit?

The rate limit is 100 requests per second. Requests exceeding this rate will receive a 429 Too Many Requests response.

The quota limit is 100,000 requests per day. The quota resets every 24 hours. Once exhausted, further requests will receive a 429 Too Many Requests response until the quota renews.

Did this answer your question?