Gong User Management API Guide

Auth method: HTTP Basic Auth (Access Key + Access Key Secret) or OAuth 2.0 (for partner integrations)

Setup steps

1. Log in to Gong as a Technical Administrator.
2. Navigate to Company Settings → API.
3. Click 'Create' to generate an Access Key and Access Key Secret.
4. Base64-encode the string 'AccessKey:AccessKeySecret'.
5. Pass the encoded value in the Authorization header as 'Basic '.
6. For OAuth 2.0 partner flows, register your app with Gong and obtain client_id/client_secret; use the authorization code flow to obtain bearer tokens.

Required scopes

List Users

• Method: GET
• URL: https://api.gong.io/v2/users
• Watch out for: Pagination cursor expires; always fetch the next page promptly. Max 100 users per page.

Request example

GET /v2/users?cursor=<cursor>&includeAvatars=false HTTP/1.1
Authorization: Basic <base64(key:secret)>

Response example

{
  "requestId": "abc123",
  "records": {"totalRecords":250,"currentPageSize":100,"cursor":"next_cursor"},
  "users": [{"id":"7782342274025","emailAddress":"jane@acme.com","firstName":"Jane","lastName":"Doe","active":true}]
}

Get Single User

• Method: GET
• URL: https://api.gong.io/v2/users/{id}
• Watch out for: Use Gong's internal numeric user ID, not email address, in the path.

Request example

GET /v2/users/7782342274025 HTTP/1.1
Authorization: Basic <base64(key:secret)>

Response example

{
  "requestId": "def456",
  "user": {"id":"7782342274025","emailAddress":"jane@acme.com","firstName":"Jane","active":true,"title":"AE"}
}

Get Users by Filter (extensive)

• Method: POST
• URL: https://api.gong.io/v2/users/extensive
• Watch out for: Batch lookup; userIds array limit not publicly documented - keep batches small (<100).

Request example

POST /v2/users/extensive HTTP/1.1
Content-Type: application/json

{"filter":{"userIds":["7782342274025","8891234567890"]}}

Response example

{
  "requestId": "ghi789",
  "users": [{"id":"7782342274025","emailAddress":"jane@acme.com","firstName":"Jane"}]
}

List Calls (per user)

• Method: GET
• URL: https://api.gong.io/v2/calls
• Watch out for: Date range is required; maximum range per request is 90 days.

Request example

GET /v2/calls?fromDateTime=2024-01-01T00:00:00Z&primaryUserIds=7782342274025 HTTP/1.1
Authorization: Basic <base64(key:secret)>

Response example

{
  "requestId": "jkl012",
  "records": {"totalRecords":42,"cursor":"next_cursor"},
  "calls": [{"id":"call_id","title":"Demo Call","started":"2024-01-15T14:00:00Z"}]
}

Get User Settings

• Method: GET
• URL: https://api.gong.io/v2/users/{id}/settings
• Watch out for: Settings endpoint availability may depend on Gong plan tier.

Request example

GET /v2/users/7782342274025/settings HTTP/1.1
Authorization: Basic <base64(key:secret)>

Response example

{
  "requestId": "mno345",
  "settings": {"webConferencesRecorded":true,"emailsImported":true}
}

List Scorecards (user-level)

• Method: GET
• URL: https://api.gong.io/v2/settings/scorecards
• Watch out for: Not a user-management endpoint per se, but required for user coaching workflows.

Request example

GET /v2/settings/scorecards HTTP/1.1
Authorization: Basic <base64(key:secret)>

Response example

{
  "requestId": "pqr678",
  "scorecards": [{"scorecardId":"sc_1","name":"Discovery Call","active":true}]
}

• Rate limits: Gong enforces per-company rate limits. The documented limit is 3 concurrent API requests and a daily quota of API calls that varies by endpoint family. Exceeding limits returns HTTP 429.
• Rate-limit headers: Yes
• Retry-After header: Yes
• Rate-limit notes: Gong returns Retry-After header on 429 responses. The API documentation notes a 'request-per-day' quota per endpoint group; exact per-plan quotas are not publicly disclosed. Pagination cursors expire; do not cache them long-term.
• Pagination method: cursor
• Default page size: 100
• Max page size: 100
• Pagination pointer: cursor

• Webhooks available: No
• Webhook notes: Gong does not offer outbound webhooks for user lifecycle events (create/update/deactivate) via its public REST API as of early 2025. Event-driven user sync is not natively supported.
• Alternative event strategy: Poll GET /v2/users on a schedule to detect changes. Use SCIM provisioning (Enterprise) for IdP-driven lifecycle events.

• SCIM available: Yes

• SCIM version: 2.0

• Plan required: Enterprise

• Endpoint: https://app.gong.io/scim/v2

• Supported operations: GET /Users (list users), GET /Users/{id} (get user), POST /Users (create user), PUT /Users/{id} (replace user), PATCH /Users/{id} (update user, including deactivate), GET /Groups (list groups), POST /Groups (create group), PATCH /Groups/{id} (update group membership)

Limitations:

• Requires Enterprise plan.
• SSO (SAML) must be configured before SCIM can be enabled.
• Supported IdPs: Okta, Microsoft Entra ID (Azure AD), OneLogin.
• Google Workspace is not officially supported for SCIM.
• SCIM token is generated once in Gong settings; store it securely - it cannot be retrieved again.
• Group push maps to Gong Teams; not all Gong permission structures are manageable via SCIM groups.
• Deprovisioning sets active=false; it does not permanently delete the user or their call data.

Three primary automation scenarios are supported by the current API surface:

Bulk user export for directory sync: Paginate GET /v2/users (max 100/page), extract id, emailAddress, firstName, lastName, and active per record, and follow the cursor until it is absent. Do not reuse cursors across scheduled runs.

Automated provisioning via SCIM (Okta): Requires Enterprise plan and active SAML SSO. Generate the SCIM token once in Company Settings → Security → SCIM - it is shown only at generation time and cannot be retrieved again. Configure Okta with base URL https://app.gong.io/scim/v2 and map userName → emailAddress, givenName, familyName. Deprovisioning sets active=false; it does not delete call recordings or historical data.

Inactive user identification for license audit: Paginate GET /v2/users, filter to active=true, then call GET /v2/calls?primaryUserIds=<id>&fromDateTime=<90_days_ago> per user. Flag users with zero calls in the window. Note: the /v2/calls endpoint requires fromDateTime and caps the range at 90 days per request - split longer lookback periods into sequential requests. Cross-reference with your IdP before issuing a SCIM PATCH /Users/{id} with active:false.

Bulk user export for directory sync

1. Authenticate with Basic Auth using Access Key and Secret.
2. Call GET /v2/users with no cursor to retrieve the first page (up to 100 users).
3. Extract the cursor value from records.cursor in the response.
4. Repeat GET /v2/users?cursor= until cursor is absent or null in the response.
5. Store each user's id, emailAddress, firstName, lastName, active fields in your directory.

Watch out for: Do not cache cursors between scheduled runs; always start a fresh pagination from the beginning of each sync cycle.

Automated user provisioning via SCIM (Okta)

1. Confirm Gong Enterprise plan and active SAML SSO with Okta.
2. In Gong: Company Settings → Security → SCIM → Enable SCIM and copy the generated token.
3. In Okta: Add the Gong app from the Okta Integration Network.
4. Configure SCIM base URL as https://app.gong.io/scim/v2 and paste the SCIM token as Bearer token.
5. Map Okta profile attributes to Gong SCIM attributes (userName→emailAddress, givenName, familyName).
6. Enable 'Push Users' and optionally 'Push Groups' in Okta provisioning settings.
7. Assign users/groups in Okta; Gong will auto-provision and deprovision on assignment changes.

Watch out for: Deprovisioning in Gong sets the user to inactive but does not delete call recordings or historical data. Verify your data-retention policy before enabling auto-deprovision.

Identify inactive users via API for license audit

1. Paginate through GET /v2/users to collect all users.
2. Filter the list to users where active=true.
3. For each active user, call GET /v2/calls?primaryUserIds=&fromDateTime=<90_days_ago> to check recent call activity.
4. Flag users with zero calls in the past 90 days as potentially inactive.
5. Cross-reference with your IdP before deactivating via SCIM PATCH /Users/{id} with active:false.

Watch out for: The /v2/calls endpoint requires a fromDateTime parameter and has a 90-day window cap; split longer lookback periods into multiple requests.

The most common integration failure points on the Gong API are:

• No webhooks for user lifecycle events. Gong does not emit outbound events on user create, update, or deactivate via its public REST API. Event-driven sync is not natively supported; polling GET /v2/users on a schedule is the only alternative outside of SCIM.
• SCIM token is single-display. The token is shown once at generation time. Losing it requires regeneration and full IdP reconfiguration - a disruptive operation in production.
• Post-SCIM provisioning gap. SCIM creates the user record but does not assign a Gong role or license. A Technical Administrator must complete this step manually, or the provisioned user has no functional access. This gap is not surfaced in the SCIM response and will not appear as an error in your IdP provisioning logs.
• Numeric string IDs, not UUIDs. Gong user IDs are numeric strings. The /v2/users/extensive POST endpoint is required for bulk lookups by ID array; GET /v2/users does not support ID-array filtering. Always store the Gong-assigned id field - do not attempt to use emailAddress as a path parameter.
• Daily quota opacity. Per-endpoint-family daily quotas exist but are not publicly documented. Build retry logic with exponential backoff on HTTP 429 and respect the Retry-After header.