Skip to main content
Qwilr API

API Reference

v1.0.0

Introduction

Welcome to the Qwilr Public API documentation. With our API you'll be able to generate Qwilr Pages programmatically. This means you can generate custom quotes, create pages when someone fills out a form, or anything else.

Our API is organized around REST. All calls made are to your live account.

If you're looking for help with the Qwilr app you can find that in our help documentation.

If you have any questions about our API, please get in touch at help@qwilr.com.

Getting started?Check out our to walk through the process of getting set up
Base URL
https://api.qwilr.com/v1

Authentication

bearerAuth

All API requests need to be authenticated with your account's access token. You can find your access token in the Qwilr API Settings.

Your access token allows anyone to access your Qwilr pages and account. Be sure to keep it secret! Do not share your access tokens in any public spaces such as your source repository client-side code, and so forth.

When making a request:

  • Use your access token with bearer authentication in the headers. For example: Authorization: Bearer fakeaccesstoken
  • Send all requests over HTTPS
Security Scheme Typehttp
HTTP Authorization Schemebearer
Bearer formatJWT
API settings page with a modal open to copy the API token

Pages

Page objects correspond to pages in the Qwilr UI, allowing for the creation of a public-facing Qwilr Page. The Qwilr API allows you to create, delete and replace your Pages by sending through JSON objects.

Create a page

Creates a page from saved blocks or template.

Authorizations

bearerAuth

Attributes

  • blocksRequiredarray of objects
  • namestring

    Title of the page, visible as the browser page title.

  • publishedboolean

    Whether the page is publically available; false means the page will be in Draft status. Default is false.

  • substitutionsobject

    Mapping of variable API reference keys to substitution values used throughout the page. The values can be overwritten if the same keys are defined in the block-level substitutions.

  • metadataobject

    Data you provide, that will be returned as part of all Webhooks.

  • tagsarray of strings

    The tags for your page. Tags are case-sensitive.

  • ownerIdstring(Id) ^[a-z0-9]{24}$

    ID of the user that should own the page. If not specified, the owner of the access token will be the owner of the page.

  • expiryobject

    Page auto-link expiry settings. When enabled, the page's public link automatically expires and the page is declined after the configured number of days. The expiry clock starts when the page is published, so a draft page just stores the setting until it goes live.

Responses

post/pages
{
  "blocks": [
    {
      "id": "uCHq6B6_S1EqZ2pyam8YVfUldvoF-Q",
      "foldable": {
        "enabled": true,
        "isFolded": true,
        "label": "string"
      },
      "splashSettings": {
        "imageUrl": "https://images.unsplash.com/photo-1530281700549-e82e7bf110d6"
      },
      "acceptSettings": {
        "postAcceptance": {
          "enabled": true,
          "url": "string",
          "continueLabel": "string"
        }
      },
      "quoteSettings": {
        "selectionType": "single",
        "selectionRequired": true,
        "currency": "USD",
        "showTotalDiscount": true,
        "showTaxTotals": true,
        "showTotalExcludingTax": true,
        "quoteDiscount": {
          "type": "fixed",
          "amount": 0
        }
      },
      "quoteSections": [
        {
          "displayMode": "table",
          "itemSingleSelect": true,
          "description": "string",
          "lineItems": [
            {
              "type": "fixedCost",
              "description": "string",
              "unitPrice": 0,
              "unitLabel": "string",
              "quantity": 0,
              "quantityRange": {
                "min": 0,
                "max": 0
              },
              "taxExempt": true,
              "optional": true,
              "selected": true,
              "lineItemDiscount": {
                "type": "fixed",
                "amount": 0
              },
              "billingSchedule": "one-off",
              "recommended": true,
              "featuresList": [
                "string"
              ],
              "metadata": {}
            }
          ],
          "settings": {
            "showSubtotal": true,
            "showUnitPrice": true,
            "showQuantity": true,
            "showCost": true,
            "selected": true,
            "selectionRequired": true,
            "sectionDiscount": {
              "type": "fixed",
              "amount": 0
            },
            "showFeatures": true,
            "groupItemsByBillingSchedule": true
          },
          "metadata": {}
        }
      ],
      "substitutions": {
        "block_variable_key": "Example value",
        "repeating_variable_key": [
          {
            "item_property": "value1"
          },
          {
            "item_property": "value2"
          }
        ]
      }
    }
  ],
  "name": "string",
  "published": true,
  "substitutions": {
    "page_variable_key": "Example value",
    "repeating_variable_key": [
      {
        "item_property": "value1"
      },
      {
        "item_property": "value2"
      }
    ]
  },
  "metadata": {},
  "tags": [
    "string"
  ],
  "ownerId": "6ee0f841f3cc8900090d82dc",
  "expiry": {
    "enabled": true
  }
}

Get a page

Returns a page

Path parameters

  • pageIdRequiredstring(Id) ^[a-z0-9]{24}$
  • expandarray of enums
    "metadata""acceptance""previewAcceptance"

Responses

get/pages/{pageId}?expand=metadata,acceptance,previewAcceptance

Update page

Allows you to update the published property and the page's auto-link expiry settings.

Authorizations

bearerAuth

Path parameters

  • pageIdRequiredstring(Id) ^[a-z0-9]{24}$

Attributes

  • publishedboolean
  • expiryobject

    Page auto-link expiry settings. When enabled, the page's public link automatically expires and the page is declined after the configured number of days. The expiry clock starts when the page is published, so a draft page just stores the setting until it goes live.

Responses

put/pages/{pageId}
{
  "published": true,
  "expiry": {
    "enabled": true
  }
}

Blocks

Block objects correspond to blocks in the Qwilr UI. Pages and templates are composed of a series of blocks. The Qwilr API allows you to get the list of saved blocks from your account.

Get saved blocks

Retrieve a list of saved blocks from your account, with block names. Useful in developer workflow for mapping block names to saved block IDs.

Responses

get/blocks/saved

Taxes

Tax objects correspond to the quote tax definitions configured on your Qwilr account. The Qwilr API allows you to create, retrieve, update and delete these, so you can manage them and reference their IDs when building quotes.

Get taxes

Retrieve the quote tax definitions configured on your account, including each tax's ID, name, and rate.

Responses

get/taxes

Create a tax

Creates a new quote tax definition on your account. By default the tax's id is generated for you and returned in the response. Alternatively, supply your own id (for example, one from an external system) — it must be unique within your account and follow the format described on the request body. The id is set at creation time only and cannot be changed later; to use a different id, delete the tax and create a new one. Either way, store the returned id so you can reference the tax elsewhere in the API.

Authorizations

bearerAuth

Attributes

  • idstring^[A-Za-z0-9][A-Za-z0-9_-]{0,63}$

    An optional identifier for the tax. Supply your own id (for example, one from an external system) to reference the tax by a value you control; if omitted, Qwilr generates one for you. Must be unique within your account, and 1–64 characters of letters, digits, - or _, starting with a letter or digit. The id is set at creation time only and cannot be changed afterwards — to use a different id, delete the tax and create a new one.

  • nameRequiredstring

    The display name of the tax.

  • rateRequirednumberNullable

    The tax rate, as a percentage. Pass null to create a tax with no rate set.

Responses

post/taxes
{
  "id": "gst",
  "name": "GST",
  "rate": 10
}

Update a tax

Updates an existing quote tax definition. Only the fields you supply are changed; at least one of name or rate must be provided. A tax's id cannot be changed — to use a different id, delete the tax and create a new one.

Authorizations

bearerAuth

Path parameters

  • taxIdRequiredstring

    The id of the tax to update.

Attributes

  • namestring

    The display name of the tax.

  • ratenumberNullable

    The tax rate, as a percentage. Pass null to clear the rate.

Responses

204

The tax has been updated

patch/taxes/{taxId}
{
  "name": "GST",
  "rate": 10
}

Delete a tax

Deletes an existing quote tax definition from your account.

Path parameters

  • taxIdRequiredstring

    The id of the tax to delete.

Responses

204

The tax has been deleted

delete/taxes/{taxId}

Subscriptions

Webhooks allow you to subscribe and unsubscribe from events on your Qwilr account.

Get a list of all webhook subscriptions

Allows you to retrieve a list of all the webhook subscriptions that you have created using the create webhook subscription endpoint.

Responses

get/webhooks

Create a webhook event subscription

Creates a new webhook subscription to an event type. New events will be sent to the defined targetUrl. You should store the id field returned in case you want to cancel the subscription later on.

Authorizations

bearerAuth

Attributes

  • eventRequiredenum
    "pageAccepted""pagePartiallyAccepted""pagePreviewAccepted""pageViewed""pageFirstViewed""pageSetLive""pageRevivedLive"
  • targetUrlRequiredstring

Responses

Callbacks

post/webhooks
{
  "event": "pageAccepted",
  "targetUrl": "string"
}

Cancel a webhook event subscription

Cancels a webhook event subscription using the id field that was returned when the webhook subscription was created.

Path parameters

  • subscriptionIdRequiredstring

    The id returned when your subscription was created

Responses

204

Unsubscribed

delete/webhooks/{subscriptionId}

Account

Miscellaneous operations concerning your Qwilr account.

Get users

Retrieve the list of users from your account, with roles and team names. Useful for specifying the ownerId when creating a page.

Responses

get/users