Using the Connect API

The Acoustic Connect API service is available to all existing clients. You only need an API key to authenticate your requests.

Getting access to the service

API key

Here is where to get an API key for your requests.

  1. Log in to Connect under an administrator account.
  2. Go to Administration > General settings > API keys.
API keys
  1. Click Generate API key.
Generate API key
  1. Enter the name of the person or application that will be using the key and provide a description.
  2. Copy your key to a secure location (for security purposes, it will not be visible in Connect after you close the dialog).

API endpoint

The API endpoint corresponds to the region where your data is hosted. There are three regions altogether. Our onboarding team provides this information to all new clients. It's also stipulated in the contract.

Region codeAPI endpoint
us-east-1connect-gql-us-1.goacoustic.com
ap-southeast-2connect-gql-ap-3.goacoustic.com
eu-central-1connect-gql-eu-1.goacoustic.com

If in doubt about your region, log in to your Connect account in Google Chrome, open developer tools, click on any graph request on the Network tab and check the x-acoustic-target-origin header.

Making API calls

Option A: Altair extension for Google Chrome

You can test all of our queries and mutations in a GraphQL IDE such as Altair. We like their free Chrome extension for its ease of use and stability. Here is how to use it:

  1. Click Set Headers in the navigation menu. 
  1. Add the X-API-Key header with your access key for the Connect API.
  1. Set request type to POST (it's the same for all queries and mutations).
  2. Enter your API endpoint.
  3. Copy any query or mutation from the current reference. dataSets is good for a quick test because it doesn't require customization.
query {
    dataSets(filter: [{ field: "type", eq: "AUDIENCE" }]) {
    nodes {
      dataSetId
      name
      consentGroups {
        id
        name
      }
    }
  }
}
Sample call in Altair

Option B: Postman

Postman also supports GraphQL and lets you make calls to our endpoints.

  1. Under Collections, click New and select GraphQL.
New GraphQL collection
  1. To prevent the disclosure of your API key, create a secret variable it.
Secret variable for API key
  1. Add a new GraphQL request to the collection.
Add request to collection
  1. Enter your API endpoint.
  2. On the Authorization tab, set Auth Type to API Key. Enter your API key (x-api-key).
Authorization using API key
  1. On the Headers tab, keep the default headers. Content-Type is required. It must be set to application/json.
  2. Copy any query or mutation from the current reference. dataSets is good for a quick test because it works out of the box. Paste it to the Query tab and send the request.
query {
    dataSets(filter: [{ field: "type", eq: "AUDIENCE" }]) {
    nodes {
      dataSetId
      name
      consentGroups {
        id
        name
      }
    }
  }
}
Sample call in Postman

Schema introspection is available. It can help you customize requests, for example by enabling filters and sorting.