API

Settings > API is where you create a key. A key lets something outside Gene App read your data and, if you allow it, change it.

Typical uses:

• syncing contacts into your own database
• copying your conversations into another tool, for example for quality checks or an archive
• building a report in a tool Gene App does not have
• wiring an automation in Zapier or Make
• handing the key to an AI assistant so it can answer questions about your pipeline

A key belongs to this workspace and nothing else. It cannot see or touch another company's data, whatever it is asked to do.

Creating a key#

1. Give it a name you will recognise later.
2. Tick what it is allowed to do (see below).
3. Optionally set an expiry date. It is worth setting for a key you are giving to somebody outside the company.
4. Press Create, then copy the key straight away.

There are two lists of ticks:

• Can read. Contacts (including where each one sits in your pipeline), pipelines and their stages, tasks, properties, which Gene App features this workspace has switched on, conversations and their messages (Read conversations and messages), your team (Read team members), and how your email and WhatsApp campaigns are doing (Read campaign analytics).
• Can change. Contacts, pipeline stages, tasks and properties.

Only tick something under "Can change" if the thing you are connecting genuinely needs to edit your data. A key handed to an outside developer for reporting should be read only.

Ticking a change also grants the matching read, because whenever the key changes a record, Gene App answers with the updated version of it.

Conversations, the team and campaign analytics can only be read. Nothing through the API sends a message or changes who is on your team.

Reading conversations and the team#

• Read conversations and messages gives the Inbox threads, most recently active first, and the messages in each one, newest first. Internal notes come with them and are marked as notes. Warm-up threads and threads whose contact was deleted are left out, as they are in the Inbox.
• Read team members gives the people a contact, task or conversation can be assigned to, so the "assigned to" on everything else can be turned into a name.

Note

Keys created before October 7, 2026 do not have these two ticks, and a key's ticks cannot be changed after it is made. To read conversations or the team, create a new key with them ticked and revoke the old one.

Reading campaign analytics#

Read campaign analytics gives the numbers on Analytics > Outreach, so a report in another tool can show them:

• every email and WhatsApp campaign that sent in the last 7, 30 or 90 days, or all time, with how many people it reached, how many messages were sent, delivered, opened or read, how many people replied, and on email the bounces and unsubscribes, with the rate for each
• the totals for email and for WhatsApp, as on the cards at the top of the tab
• for any one campaign, the same numbers for each step of its sequence

They are the same numbers as on the tab, worked out the same way. The campaign list comes back newest send first and can be narrowed to email or WhatsApp. Instead of "only what changed since this date", each request picks its window (7, 30 or 90 days, or all time; 30 days if none is given).

Note

Keys created before October 14, 2026 do not have this tick. Create a new key with Read campaign analytics ticked to read campaign results.

The key is shown once#

Important

When the key is created it appears on screen once. Gene App keeps only a scrambled copy that cannot be turned back into the key, so it can never be shown again. Copy it straight into wherever it is going.

If it is lost, or if you think somebody has it who should not, revoke it and make a new one. Revoking takes effect immediately: the next request made with that key is refused.

You can have five keys at a time. Revoke one to make room for another.

What the key can do#

Whatever holds the key sends it with each request. Your developer will know what to do with this:

Authorization: Bearer gene_live_...

• Lists come back newest change first, in pages.
• Lists can be asked for "only what changed since this date", so a nightly or hourly sync does not have to pull everything down every time. Messages are never edited, so for them it is "only what arrived since this date". A new message also moves its conversation into "changed since", which is how a sync knows which threads to read again.
• There are limits, so a mistake in somebody's script cannot run away with your data: 120 requests a minute, of which 30 may change something.
• Nothing in the API deletes anything except listings a key sent itself.

A key with Create and update properties can also keep your listings in step with your website or CRM. See Sync listings from your website.

Keeping an eye on it#

The list of keys shows, for each one, whether it is read only or can change data, how many requests it has served, and when it was last used.

• A key that has never been used is usually a sign the connection was never finished.
• A key you do not recognise should be revoked.

Every change made with a key is recorded against that key. If something in your workspace changed unexpectedly, it is possible to tell which connection did it.

If the tab is not there#

The API is switched on per workspace. If you do not see Settings > API, it is not enabled for you yet, and your Gene contact can turn it on.