Gong Engage API capabilities

Who can use this: Tech admin
Available on: Gong Engage

Use the Gong Engage API to read flows and to add people to or remove them from flows, from another system, without opening Gong. For example, a data platform or an enrichment tool can start outreach as soon as it finds a new contact.

API requests follow the same eligibility rules as adding people in Gong. A successful response does not mean everyone was added, so check the response for each person.

See API docs

Engage must be set up before you use the API. Learn more about setting up Engage.

What the API can do

Seven endpoints read flows and move people in and out of them. Some endpoints use a flow instance, which is one contact or lead’s version of a flow. Gong creates one for each person you add to a flow.

Endpoint	What it does	API reference
`GET /v2/flows`	Returns flows and their details.	See API docs
`GET /v2/flows/folders`	Returns flow folders.	See API docs
`POST /v2/flows/prospects`	Returns people and the flows they are in.	See API docs
`POST /v2/flows/prospects/assign`	Adds contacts or leads to a flow. It also accepts the cool-off override option.	See API docs
`POST /v2/flows/prospects/assign/cool-off-override`	Adds contacts or leads to a flow regardless of the cool-off period. It requires the write scope.	See API docs
`POST /v2/flows/prospects/unassign-flows-by-crm-id`	Removes one person from their flows. You identify the person by CRM ID.	See API docs
`POST /v2/flows/prospects/unassign-flows-by-instance-id`	Removes people from flows. You identify each one by a flow instance ID.	See API docs

Authentication and scopes

Send a Bearer token with every request. Each endpoint needs a scope, which is a permission on your API credentials. Give a system only the read scope if it should view flows but never change them.

Endpoints that return flows, folders, and people need api:flows:read.
Endpoints that add or remove people need api:flows:write.

How flow visibility affects what you get back

Each flow and folder has a visibility setting, and the API returns only the flows and folders that the requesting team member is allowed to see. If a flow seems to be missing from a response, visibility is the most likely reason.

Visibility	Who can see and use it
Company	Everyone in the company can see it. Editing requires the Create and manage company flows permission.
Personal	Only the team member who created it can see it.
Shared	The creator and the team members they shared it with can see it. Those team members can add people to a shared flow, or add flows to a shared folder.

Two parameters name a team member, and they do different things.

flowEmailOwner returns the personal and shared flows of one team member.
flowInstanceOwnerEmail sets who owns the to-dos created when someone is added to a flow.

Note:
The API does not return flows in a deleted folder. It also does not return flows in a folder that the requesting team member cannot access.

Adding people to a flow

To add people, send a flow ID and a comma-separated list of CRM IDs to the assign endpoint. Gong creates a flow instance for each person and starts the outreach.

Some problems affect the whole request, and the API returns an HTTP error.

400: The request is malformed, or it lists too many people.
401: The request is not authenticated.
403: The owner is not valid, or there is no Engage license.
404: The flow does not exist or was deleted.
429: The request exceeds the rate limit.
500: Gong could not process the request.

Other problems affect one person at a time. In these cases the API still returns 200, and the response lists each failure by person, with an error code and a message. A person who is not added can fail with one of these codes, which are the documented per-person failures: InvalidArgument, InvalidState, or UnexpectedError. Gong does not add a person when:

The person has opted out.
The person is in a cool-off period, unless the flow’s ruleset overrides the cool-off requirement.
The person is already in the flow.
The person is already in another flow, and only one flow is allowed at a time.
The flow assignee (the person at your company that the flow to-dos will be assigned to) doesn’t have an Engage seat.

Overriding flow content for added people

When you add people to a flow, you can replace parts of the flow's content for the flow instances created by that request. This lets you customize outreach beyond the flow’s existing content and field placeholders. The override doesn’t change the underlying flow.

What you can override	Details
Step number	The step to override, for example `1`. If omitted, Gong uses step 1.
Subject	The subject line of that step. It applies to every to-do type, such as emails and call scripts. It can contain field placeholders, for example `{{mycompany}}/{{account_name}} Initial Call`.
Body HTML	The body of that step. It applies to every to-do type. It can contain HTML and field placeholders, for example `<div>Hello {{first_name}}</div>`.
Field placeholder values	Key-value pairs. Each key is a placeholder already in the subject, body, or flow description, and its value replaces the placeholder. A value can contain HTML, including a full paragraph. Learn more about field placeholders.
Flow description	The description of that flow instance. It can contain HTML. It is useful for flows that start automatically, because the rep who gets the to-do can see why the person was added.

A request with a content override includes:

The flow ID
The contact ID
The owner of the new to-dos
The content to override

Note:
New placeholder values replace only the values you send. The rest of the flow content stays the same, so you can change one value without resending the others.

Removing people from flows

Choose the removal method that matches the IDs you have.

Method	How it works
By CRM ID	Send `crmProspectId` alone to remove the person from every flow they are in. Add `flowId` to remove them from one flow only. Get the flow ID from the `/v2/flows/prospects` endpoint.
By flow instance	Send the flow instance IDs to remove. Get each ID from the `/v2/flows/prospects` endpoint. If an ID is not a known flow instance, the API returns `400`.

Important:
With both methods, a removal that fails is left out of the response, and the API does not return an error. The person stays in the flow. Compare the people you sent with the people in the response, and retry the ones that are missing.

Both removal endpoints return only these HTTP errors: 400, 401, 429, and 500.

Limits

Each request is capped at a set number of people, so split larger lists into several requests. The API also limits how many requests you can send.

Limit	Value
Default rate limit	3 requests per second and 10,000 requests per day
Add people to a flow	Up to 200 people per request
Remove by flow instance	200 people per request
Remove by CRM ID	One person per request

Frequently asked questions

Can the API add someone who has opted out?

No. The same opt-out and eligibility rules apply as when a rep adds someone in Gong. The API still returns 200, and the response lists the person as a failure with an error code and a message.

Why is a flow missing from the response?

Check the flow's visibility first. A personal flow belongs to one team member who created it. A shared flow is visible only to the people it was shared with. The API never returns flows in a deleted folder or in a folder the requester cannot access. The get /v2/flows endpoint returns company flows by default. To include a specific rep’s personal flows and flows shared with that rep, provide that rep’s email address in flowEmailOwner.