---
title: "GraphQL API"
---

The Quikly GraphQL API lets you build apps and other integrations using Quikly's urgency marketing platform. With the API, you can create unique experiences for your audiences natively within your app, or more tightly integrated with your website than the Javascript SDK may allow. This is the same API that powers Quikly's campaign microsites and embedded experiences.

## Authentication
The GraphQL API requires a Quikly access token for making authenticated requests. Include the access token as a `X-Quikly-Access-Token` header in your requests. Independent of this header, some API calls may require a `Bearer` authorization token that uniquely identifies a user accessing the API (whereas the access token identifies your app).

## Endpoint and Queries
All queries are run by sending a POST HTTP request to a single GraphQL endpoint:

```
POST https://api.quikly.com/graphql
```

In GraphQL, queries are the the equivalent of REST's GET actions, but they allow you to fetch exactly the data you need. Any requests made to the GraphQL endpoint will be a POST request regardless if you are retrieving or modifying data.


## Example Query
The following example shows a query for fetching basic details about a Quikly campaign, include the name, description, and customized labels used at various spots in the UI.

```graphql
query promoLandingQuery() {
  quikly(hashid: "XqyhklE") {
    id
    name
    description
    header: customContentFor(key: "embedded_instant_sign_in_header")
    finePrint
    buttonText: customContentFor(key: "embedded_instant_sign_in_button_text")
    image {
      url(variant: "original")
    }
  }
}
```

The response will be a json structure with a root-level "data" key and then data that mirrors what was requested in the query:

```json
{
  "data": {
    "quikly": {
      "id": "RGVhbC04Mzc3",
      "name": "Flash Promo Demo",
      "description": "",
      "header": "Sign into your account to get this offer.",
      "cookieNotRequired": true,
      "finePrint": "",
      "buttonText": "Sign in",
      "signInPixel": null,
      "image": {
        "url": "/assets/missing.png"
      }
    }
  }
}
```

Visit the official [GraphQL site](https://graphql.org/learn/queries/) to learn more about queries.

## Exploring the API
While specific GraphQL client libraries exist, you can access the GraphQL API from any programming language or framework that supports HTTP requests and JSON. While you are learning the API, a good way to test out queries and explore the schema is to the Quikly GraphQL API, but you can also use curl, a tool like [Postman](https://postman.org), or the language of your choice.
- [Use the GraphiQL App](#usethegraphiqlapp)
- [Use curl](#usecurl)

### Use the GraphiQL App
Visit the [GraphiQL Explorer](https://graphql-explorer.quiklydemo.com) to explore the schema and test out your queries. The GraphiQL Explorer allows you to authenticate, paste in your queries, supports autocompletion and syntax highlighting, and provides a detailed schema reference.

### Use curl
Here is an example of loading data you might want to display on the first screen of a Quikly Drop. You could extend this example to work from any language that is capable of making HTTP requests. Note the POST body must be a valid JSON with a "query" key that contains the actual GraphQL query.

```bash
curl -X POST https://api.quikly.com/graphql \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json; charset=utf-8' \
  -H 'X-Quikly-Access-Token: {account-token}' \
  -d @- << 'EOF'
{
  "query": "{
    quikly(hashid: \"WLYhqa\") {
      id
      name
      description
      header: customContentFor(key: \"embedded_instant_sign_in_header\")
      cookieNotRequired
      finePrint
      buttonText: customContentFor(key: \"embedded_instant_sign_in_button_text\")
      signInPixel: getPixel(placement: \"embedded-sign-in-js\") {
        content
        repeatable
      }
      image {
        url(variant: \"original\")
      }
    }
  }"
}
EOF
```
If you were making this request via Javascript, you could build your request body with something like this:

 ```javascript
const accountToken = '';
const options = {
  method: 'POST',
  headers: {Accept: 'application/json; charset=utf-8', 'Content-Type': 'application/json', 'X-Quikly-Access-Token': accountToken},
  body: JSON.stringify({
    query: `
      query promoLandingQuery {
        quikly(hashid: "XqyhklE") {
          id
          name
        }
      }
    `
  })
};

fetch('https://api.quikly.com/graphql', options)
  .then(response => response.json())
  .then(response => console.log(response))
  .catch(err => console.error(err));
 ```


# Mutations
In GraphQL, mutations are like any of the data-modifying REST verbs (PUT, POST, DELETE) that modify data on the server, but you can also specify the fields contained in (or the "shape of") the response. This example shows a mutation that attempts to claim a Quikly offer. This example makes use of [variables](https://graphql.org/learn/queries/#variables), but you could also include the values directly in the mutation. If you do use variables, you pass them in a separate (usually JSON) variables dictionary.

```graphql
  mutation createEmbeddedClaim(
    $dealHashid: String!
    $email: String!
  ) {
    createEmbeddedClaim(
      input: { dealId: $dealHashid, email: $email }
    ) {
      errors {
        key
        message
      }
      user {
        id
        authToken
      }
      order {
        id
        qid
        receiptToken
      }
    }
  }
```

With curl:

```bash
curl -X POST \
  http://api.quikly.com/graphql \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json; charset=utf-8' \
  -H 'X-Quikly-Access-Token: {account-token}' \
  -d @- << 'EOF'
{
  "query": "mutation createEmbeddedClaim(
      $dealHashid: String!,
      $email: String!
    ) {
    createEmbeddedClaim(
      input: { dealId: \$dealHashid, email: \$email }
    ) {
      errors {
        key
        message
      }
      user {
        id
        authToken
      }
      order {
        id
        qid
        receiptToken
      }
    }
  }",
  "variables": "{
    \"dealHashid\": \"WLYhqa\",
    \"email\": \"scott@quikly.com\"
  }"
}
EOF
```

Visit the official [graphql.org](https://graphql.org/learn/queries/#mutations) site for more background on mutations.

We have built a collection of queries and mutations common to specific Quikly campaign types. Check out the [GraphQL Examples](/graphql-api/examples).