Integrations endpoints
View integration types for your organization
- API: GET /api/v2/integrations/types endpoint
- Platform API Client SDK - JavaScript: getIntegrationsTypes method
The response is a paginated list of all integration types available to your organization.
View the type of a specific integration
- API: GET /api/v2/integrations/types/{typeId} endpoint, where
{typeId}
is a path parameter whose value must be a valid integration type ID - Platform API Client SDK - JavaScript: getIntegrationsType method
Create an integration of a specified type
- API: POST /api/v2/integrations endpoint
- Platform API Client SDK - JavaScript: postIntegrations method
{
name: string, // (optional: name of the new integration)
integrationType: {
id: string // ID of the type of integration to create
}
}
When you create a new integration, you can optionally specify a name. If you do not specify a name, a default name representing the type of integration created is used.
You must specify an integration type ID. For more information about how to see the integration types for your organization, see View integration types for your organization.
For information on how to update other integration details after you create an integration, see Update an integration.
View integrations for your organization
- API: GET /api/v2/integrations endpoint
- Platform API Client SDK - JavaScript: getIntegrations method
To override the default pagination behavior, provide the pageSize
and/or pageNumber
query parameters. These must be numbers from 1 to 999.
To see a single integration in your organization:
- API: GET /api/v2/integrations/{integrationId} endpoint, where
{integrationId}
is a path parameter whose value is a valid integration ID - Platform API Client SDK - JavaScript: getIntegration method
Update an integration
You can change the intended state or current configuration for an existing integration.
Update the intended state for an integration
The intended state represents the current configured state of the integration as specified by a Genesys Cloud user or admin. This is how an admin specifies whether the integration is enabled or not. The following are the valid intended states:
- ENABLED - integration should be active and running
- DISABLED - integration should be inactive
Additionally an integration has a reported state, which is the actual state of the integration. The following are the valid reported state values:
- INACTIVE
- ACTIVATING
- ACTIVE
- DEACTIVATING
- ERROR
The following diagram which shows the flow of integration state changes.
To update an integration’s intended state:
- API: PATCH /api/v2/integrations/{integrationId} endpoint, where
{integrationId}
is a path parameter whose value is a valid integration ID - Platform API Client SDK - JavaScript: patchIntegration method
The request payload must contain the desired intended state.
{
intendedState: 'ENABLED'
}
Update the current configuration for an integration
- API: PUT /api/v2/integrations/{integrationId}/config/current endpoint
- Platform API Client SDK - JavaScript: putIntegrationConfigCurrent method
{
name: string, // name of the integration, used to distinguish this integration from others of the same type
version: number, // version number required for updates
notes: string, // notes about the integration
properties: Object<>,
advanced: Object<>,
credentials: Object<string, CredentialInfo>
}
Set the version
property to the most current version of the integration's configuration. To get the current version:
- API: GET /api/v2/integrations/{integrationId}/config/current endpoint
- Platform API Client SDK - JavaScript: getIntegrationConfigCurrent method
The advanced, properties, and credentials fields are objects with their own unique schemas, as explained in the following sections:
To view the updated configuration:
- API: GET /api/v2/integrations/{integrationId}/config/current endpoint
- Platform API Client SDK - JavaScript: getIntegrationConfigCurrent method
Properties
The properties field of an integration's config contains key-value configuration settings described by the schema in the configPropertiesSchemaUri field of the integration type.
To find the configPropertiesSchemaUri field, first search for your integration's specific integration type:
- API: GET /api/v2/integrations/types/{typeId} endpoint
- Platform API Client SDK - JavaScript: getIntegration method
Then follow the URI in the configPropertiesSchemaUri field to locate the schema required for your properties field.
Note: The following example uses the properties schema of the "premium-app-pureinsights" integration type. Remember to follow the schema for the configPropertiesSchemaUri field for your integration type.
{
properties: {
url: 'https://localhost.test',
displayType: 'standalone'
}
}
Advanced
The advanced field of an integration's config contains advanced configuration options as described by the schema in the configAdvancedSchemaUri field of the integration type.
To find the configAdvancedSchemaUri field, first search for your integration's specific integration type:
- API: GET /api/v2/integrations/types/{typeId} endpoint
- Platform API Client SDK - JavaScript: getIntegration method
Then follow the URI in the configAdvancedSchemaUri field field to locate the schema required for your advanced field.
Note: The following example uses the properties schema of the "premium-app-pureinsights" integration type. Remember to follow the schema for the configPropertiesSchemaUri field for your integration type.
advanced: {
lifecycle: {
ephemeral: true,
hooks: {
bootstrap: true,
focus: false
}
}
}
Credentials
The credentials field of the configuration enumerates all credentials that are required by the integration. It is represented via an object whose keys are strings and whose values are CredentialInfo objects.
The keys represent the name of the credential. The required keys are indicated in the credentials property of the integration type. For information on getting the integration type for an integration, see View the type of a specific integration.
The values are CredentialInfo objects. They contain the ID for the credential.
Note: The credentials must already have been created before you assign them to an integration:
- API: POST /api/v2/integrations/credentials endpoint
- Platform API Client SDK - Javascript: postIntegrationsCredentials method
salesforceUser: {
id: '12345abc-1234-5678-abcd-12345abcd123'
}
credentials: {
salesforceUser: {
id: '12345abc-1234-5678-abcd-12345abcd123'
},
basicAuth: {
id: '12345abc-1234-5678-abcd-12345abcd123'
}
}
Delete an integration
To delete an integration:
- API: DELETE /api/v2/integrations/{integrationId} endpoint, where
{integrationId}
is a path parameter whose value must be a valid integration ID - Platform API Client SDK - JavaScript: deleteIntegration method
The response will be the deleted integration.