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.

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:

{
  "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 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, or the language of your choice.

• Use the GraphiQL App
• Use curl

Use the GraphiQL App

Visit the GraphiQL Explorer 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.

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:

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, 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.

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

With curl:

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 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.