Skip to main content

Creating Instances Programmatically

Before deploying an instance of an integration, you'll need to know the ID of the version of the integration you want to deploy.

Find Integrations Through the API​

You can use the integrations query to list integrations. You'll want to deploy a specific version of the integration, so including the allVersions: true and versionIsAvailable: true parameters will show you all available published versions of your integration (not just your canonical integration ID).

This query also uses sortBy, so results are sorted by version, and the latest version is returned first.

Find all available versions of the Acme Inventory integration
query ($integrationName: String!) {
  integrations(
    name: $integrationName
    allVersions: true
    versionIsAvailable: true
    sortBy: {direction: DESC, field: VERSION_NUMBER}
  ) {
    nodes {
      id
      name
      versionNumber
    }
  }
}
Query Variables
{
  "integrationName": "Acme Inventory"
}
Try It Out ❯

Creating a New Instance Through the API​

The createInstance mutation requires four pieces of information:

  • The ID of a customer this instance is for. This can be found through the customers query.
  • The ID of the version of the integration you want to deploy. This can be found through above query.
  • A name for your instance.

Once you've collected that information, you can create your instance:

Create a New Instance of an Integration
mutation ($customerId: ID!, $integrationId: ID!, $name: String!) {
  createInstance(
    input: {customer: $customerId, integration: $integrationId, name: $name}
  ) {
    instance {
      id
      name
      flowConfigs {
        nodes {
          flow {
            name
          }
          webhookUrl
        }
      }
    }
    errors {
      field
      messages
    }
  }
}
Query Variables
{
  "customerId": "Q3VzdG9tZXI6OThiMjU3MDUtZmMzNC00NWYwLTk0ZDItODA0ZjFkYzEyYTZk",
  "integrationId": "SW50ZWdyYXRpb246ZjY1Y2I5YTktMmZiZC00ZGE0LWIwYzktMjQ4Njc0YTY2NGMz",
  "name": "Acme Inventory"
}
Try It Out ❯

This query returns some additional data about the instance, including a list of flows and their respective webhook URLs for invoking the flows.

Config variables can be set during the createInstance mutation. They can also be set with an updateInstance or updateInstanceConfigVariables mutation, which we address here. If you'd like to set the config variables as part of the createInstance mutation, follow the same pattern that we show in the updateInstance mutation below.