How to read your data with an API key

Settings → Integrations → API keys → Make key. A key lets your own scripts list contacts, jobs or invoices, or use the cold email services. Shown once, revocable, 60 requests a minute, every use listed.

Updated 2026-10-31

An API key lets a script you or your developer write (a reporting spreadsheet, a nightly copy, an agency dashboard) read lists from Otto. Keys for contacts, jobs and invoices only read: there is no way to add, change or delete anything with one. Keys can also use the cold email services; see how to use the cold email API. Only someone who manages the business makes, sees and revokes keys.

Every route, with what it takes and gives back, is in the API reference.

Make a key

1. Open Settings → Integrations and scroll to API keys.
2. Name the key after what will use it, such as "Reporting sheet".
3. Tick what it may use: Contacts, Jobs or Invoices (read only), or Leads and lookups, Cold campaigns or Cold email replies. Invoices carry amounts, so only a position that sees money can tick them.
4. Press Make key, then Copy key.

The key is shown once. Otto keeps only a fingerprint of it, so it cannot show it again: if you lose it, revoke it and make a new one. A business can have 10 keys in use.

Use it

Send a GET request with the header Authorization: Bearer followed by the key, to one of these addresses on your Otto site:

• /hooks/api/v1/contacts: name, email, phone, company, stage, and when each was added and changed.
• /hooks/api/v1/jobs: title, client, state, start and end, and when it was done.
• /hooks/api/v1/invoices: number, client, state, total and paid (in cents), currency and due date. Drafts are left out.

Each list is newest first, at most 100 at a time (limit can ask for fewer). When there are more, the answer has next_before: send it back as before for the next page.

Limits and the log

• A key reads only what was ticked. Asking for anything else is refused, and so is a list whose feature is switched off.
• A key answers at most 60 requests a minute. Past that it is told to wait a minute; those refusals are not logged.
• Every other request a key makes, answered or refused, is listed under Recent uses, with the key, the list and the time. Each key also shows when it was last used.
• Press Revoke to stop a key at once, for every script that uses it.