API

Basics

API Key

Our GraphQL and REST APIs both require basic authentication with an API key.

You can find your API keys on the Organization Settings -> API Settings page. There will be an API Key card,

API Key Settings

Click add an API key and Anvil will generate two keys: development and production.

API Key Settings with keys

The two keys work exactly the same, except in the following ways

  • Requests made with the development key are free. The development key is meant to be used when building out your integration.
  • Development key requests are more aggressively rate-limited.
  • PDFs generated with the development key will have a watermark.

Authentication

Use Basic authentication with all API requests. In Basic auth terms, your API key is effectively the username, and there is no password. To construct, append a : to the end of your API key:

YOUR_API_KEY:

Then base64 YOUR_API_KEY: and send it in the Authorization header. An example in JavaScript:

const encodedToken = Buffer.from('YOUR_API_KEY:', 'ascii').toString('base64')
options.headers.Authorization = `Basic ${encodedToken}`

Encryption

In some cases, the Anvil API requires data to be encrypted. To use encryption, generate an RSA keypair on your Organization Settings -> API Settings page.

Encryption Keypair Settings

Our node encryption library can be use to encrypt and decrypt data. If you do not use node, the library's readme explains the encryption methodology.

Terminology

It will be helpful to get a handle on the naming of the objects in Anvil's system.

There are three main objects: Cast, Forge, and Weld. These objects hold configuration information; you can think of them as classes in OOP parlance.

  • Cast: Configuration for a single PDF template. A Cast defines the location of boxes on PDF pages, and the type of each box (e.g. date, phone number, etc.).
  • Forge: Configuration for a single web form. A Forge defines which fields are visible, the page they are on, and what types they are.
  • Weld: a weld is a workflow in the UI. It connects one or more Forges with zero or more Casts. A Weld basically glues (ahem, welds) together the other objects to create the configuration for a single workflow.

As the previous objects are OOP classes, there are instances of these objects:

  • Submission: An instance of a Forge. A Submission holds the data for one form submission on a particular Forge.
  • WeldData: An instance of a Weld. It contains the Submissions for all the Forges in a Weld.
  • DocumentGroup: A collection of all the files generated by the workflow's data. It specifies all the PDF files generated from the WeldData.

For example, say you have one workflow that has two webforms and fills three PDFs.

In this case, there will be one Weld with two Forges and three Casts. When the user completes the workflow, there will be a WeldData with 2 Submissions: one Submission for each Forge. Additionally, there will be one DocumentGroup that is a zip file containing three PDFs.

Other Terms

  • eid - a 20 character id for referencing objects in our system.
  • slug - a string that can be included in a URL.

Rate Limits

This API enforces separate rate limits for Development and Production API keys.

  • Production: 200 requests over 5 seconds
  • Development: 10 requests over 5 seconds

Each response will contain a few headers that keep track of usage:

200
X-RateLimit-Limit: 200
X-RateLimit-Remaining: 196
X-RateLimit-Reset: 148086765

When exceeded, the endpoint will respond will a 429 status code plus a Retry-After header indicating how many seconds to wait:

429
Retry-After: 5