Tech admin, Business admin
Gong Engage*
The Gong Engage API gives you access to create, manage, and customize Engage flows at scale. With these endpoints, you can list available flows and folders, assign or unassign prospects, and override flow content to tailor messaging for specific campaigns or workflows. This article walks through the available API capabilities, including the scopes required and examples of how to use them.
API endpoints for Engage flows:
List Gong Engage flows (/v2/flows)
List Gong Engage flow folders (/v2/flows/folders)
List assigned flows for the given prospects (/v2/flows/prospects)
Assign prospects (contacts or leads) to an Engage flow (/v2/flows/prospects/assign)
Unassign flows by CRM Prospect ID (/v2/flows/prospects/unassign-flows-by-crm-id)
Unassign flows by Flow Instance ID (/v2/flows/prospects/unassign-flows-by-instance-id)
List Gong Engage flows (/v2/flows)
get /v2/flows
This endpoint returns all company flows, plus personal flows and flows shared with the user specified in the flowEmailOwner parameter.
Engage flows have the following visibility types:
Company. Visible to everyone in the company, can only be edited by users with edit permissions.
Personal. Reps can set up their own flows, which are only available to them.
Shared. Reps can share a flow with other reps. Those reps can then add leads to the flow.
When accessed through a Bearer token authorization method, use the api:flows:read scope.
List Gong Engage flow folders (/v2/flows/folders)
get /v2/flows/folders
This endpoint returns all company flow folders, plus personal flow folders and flow folders shared with the user specified in the flowEmailOwner parameter.
Engage flow folders have the following visibility types:
Company. Visible to everyone in the company, can only be edited by users with edit permissions.
Personal. Reps can set up their own flow folders, which are only available to them.
Shared. Reps can share a flow folders with other reps. Those reps can then add flows to the flow folder.
When accessed through a Bearer token authorization method, use the api:flows:read scope.
List assigned flows for the given prospects (/v2/flows/prospects)
post /v2/flows/prospects
Get the Gong Engage flows assigned to the given prospects.
When accessed through a Bearer token authorization method, this endpoint requires the scope api:flows:read.
Assign prospects (contacts or leads) to an Engage flow (/v2/flows/prospects/assign)
post /v2/flows/prospects/assign
Use this endpoint to assign several prospects to a flow. Prospects can be contacts or leads in your CRM.
Generate a list of comma-separated CRM IDs of the prospects you want to add to a flow. The flowInstanceOwnerEmail parameter is the email address of the Gong user who set up the flow instance and is assigned to the flow to-dos. You can assign up to 200 prospects to a flow in a single request.
When accessed through a Bearer token authorization method, this endpoint requires the scope api:flows:write.
Overriding flow content
You can override the content of each step in a flow instance, including:
Subject for all to-do types (emails, call scripts, and more)
Body for all to-do types (emails, call scripts, and more)
Variable values used in subjects or bodies. Insert custom content without replacing the entire template
Flow description, which is especially useful for flows that are triggered automatically. This helps ensure reps have the necessary context to understand their tasks and who they’re engaging with.
Override flow instance-specific step content
Step number. The number of the flow instance step you want to override
Example: '1'
If the flow instance step number is not provided, the default step chosen should be step '1'
Subject. The subject line of a flow instance step
Can use variables
Example: '{mycompany}/{account_name} Initial Call'
Body HTML. The HTML used to populate the body of a flow instance step
Can use HTML
Can use variables
Example: '<div>Hello {first_name}</div>'
Specify flow instance-specific variable values
List variables that are already part of the subject, body, or flow description, and provide their values in advance.
Can use HTML
Example:
Variable key: {first_name}
Variable Value: “<b></b>”
Although variables consist of a word or two, they can also consist of full HTML rich text paragraphs. For example:
Variable key: {value_proposition}
Variable Value: We’re on a mission to <b>empower</b> companies to unlock their full revenue potential. <br>
We help everyone on revenue teams improve productivity, increase predictability, and drive revenue growth by deeply understanding customers and business trends and taking impactful actions.
Override flow instance flow description
To override the description for a specific flow instance.
Can use HTML
A text paragraph
Example: Your goal for this flow is to <b>schedule a follow-up conversation</b> with event attendees to gather feedback, answer questions about Gong, and move them toward becoming potential customers. The target audience is <b>RevOps</b> who attended the Gong breakfast event in Stockholm, part of EMEA marketing initiatives.
Parameters sent to Gong via API when adding to flow with content override
Send Flow ID. The flow you want to start
Send Contact ID. The contact you want to add to the flow
Send Owner ID. The user you want to be assigned to the flow instance
Flow instance step content override:
Step number
Subject
Body HTML
Updating part of the content without overriding all of it
You can update specific parts of your content without overwriting the entire flow. To do this, you can use variables that have already been placed in your content. When you send new variable values through the API, they will automatically replace the existing variables in the flow.
These are the parameters that will be sent to Gong via API:
Send Flow ID. The flow you want to start
Send Contact ID. The contact you want to add to the flow
Send Owner ID. The user you want to be assigned to the flow instance
Variable Values
Variable key
Variable Value
Updating the flow description
To do this, you can use variables that have already been placed in your content. When you send new variable values through the API, they will automatically replace the existing variables in the flow.
These are the parameters that will be sent to Gong via API:
Send Flow ID. The flow you want to start
Send Contact ID. The contact you want to add to the flow
Send Owner ID. The user you want to be assigned to the flow instance
Variable Values
Variable key
Variable Value
Flow Instance Description. A text paragraph
Unassign flows by CRM Prospect ID (/v2/flows/prospects/unassign-flows-by-crm-id)
post /v2/flows/prospects/unassign-flows-by-crm-id
This endpoint lets you remove a specific prospect from the flows they’re assigned to. To remove the prospect from all flows they are assigned to, send the crmProspectId only.
To remove the prospect from a specific flow, get the flow ID from the /v2/flows/prospects endpoint and include the crmProspectId and flowId in the request.
The IDs of the flows the prospect was successfully removed from are returned in the response.
When accessed through a Bearer token authorization method, this endpoint requires the scope api:flows:write.
Unassign flows by Flow Instance ID (/v2/flows/prospects/unassign-flows-by-instance-id)
post /v2/flows/prospects/unassign-flows-by-instance-id
This endpoint lets you specify flow instances to remove prospects from. A flow instance is created when a prospect is added to a flow. Retrieve the flow instance ID from the /v2/flows/prospects endpoint.
The flow instance IDs the prospect was successfully removed from are returned in the response. If a prospect couldn’t be removed from a flow for any reason, the ID isn’t returned in the response, and the prospect is still assigned to the flow. You can remove prospects from up to 200 flows in a single request.
When accessed through a Bearer token authorization method, this endpoint requires the scope api:flows:write.
*The features available to you depend on your company’s plan and your assigned seats.