Create an API key and authenticate
Make a key, choose its access level and expiry, send it in a header, and know what each level can do.
The HeyLeads API lets other software work with your workspace: read campaigns and results, add leads to lists and campaigns, manage tags and more. Anything you call it with needs a key. Keys belong to one workspace, and every request acts inside it.
#Create a key
Open Settings, Integrations, then the HeyLeads API tile
Under API keys, choose Create API key
Give it a Name you'll recognise
For example
CRM sync. Make one key per tool, so you can revoke one without breaking the rest.Choose the Access level
Read-only, Member or Admin. Pick the lowest that works.
Choose when it Expires
Never, 30 days, 90 days or 1 year.
Choose Create key and copy it
It starts with
hl_live_and is shown once. HeyLeads keeps only a scrambled copy, so a lost key can't be recovered. Make a new one and revoke the old one.
#Access levels
| Level | What it can do |
|---|---|
| Read-only | Read campaigns, results and A/B tests. Can't see leads or accounts, and can't change anything. |
| Member | Read leads and accounts, create and edit campaigns, add leads, make lists, set do-not-contact. Can't launch campaigns. |
| Admin | All of that, plus launch, pause and resume campaigns, manage LinkedIn accounts and manage webhooks. |
A key is never an owner key: billing and deleting a workspace stay with people. A key can also never do more than the person who created it can do right now. Demote or remove them and their keys shrink or stop straight away.
#Send the key
Put it in the Authorization header of every request. The base address is https://app.heyleads.so/api/v1. Anything else gets a 401.
curl -s https://app.heyleads.so/api/v1/me \
-H "Authorization: Bearer YOUR_API_KEY"A good answer names your workspace, your plan and the key's access level.
#Revoke or rotate a key
To rotate, create the new key first and switch your tool over to it
Find the old key in the list, open Key actions and choose Revoke
Confirm Revoke this API key?
Anything still using it gets a
401on its next request. Leads, lists and campaigns it created stay in your workspace.
#Agencies: organization keys
If you run client workspaces under an organization, an organization key (hl_org_…) can create workspaces, set account caps, invite people and mint workspace keys. It never reads or writes a workspace's leads, campaigns or inbox; for that, mint a workspace key. Details are in the developer reference. To understand organizations first, see Organizations and client workspaces.