Getting Started

Welcome to the Anvil API! This guide will help you get set up to use our APIs.

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 Keys page. There will be an API Key card,

API 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 filled, generated, or signed 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}`

Postman Collection

Take a look through our public Postman collection to see live examples of our APIs in action. All you need to do is enter your API key.

View Anvil API Postman Collection

Node Client

We have created a Node.js client to help our users interact with our API more easily. It helps to simplify:

  1. Authentication
  2. Documented REST and GraphQL calls
  3. Raw REST and GraphQL calls
  4. GraphQL calls involving binary file uploads

We strongly recommend using it if you're developing against our API in Node. Please check it out at @anvilco/anvil!

Encryption

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

Encryption Keypair Settings

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

Note: When you have a generated RSA keypair, webhook payloads will be encrypted with your keypair.

Terminology

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

See the API Reference for more information on these objects.

Common objects

These objects are shared between the workflow and e-signature systems.

  • 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.).
  • DocumentGroup: A collection of all the final files generated with data from a workflow or e-sign packet. When your users download a zip file of PDFs, that final collection of filled, generated, uploaded, and signed files is specified by the DocumentGroup.

E-sign objects

There is only one special e-sign object you need to know about: an EtchPacket.

  • EtchPacket: An e-signature packet. An EtchPacket can use one or more Cast as templates PDFs to fill and sign.

Workflow objects

There are a few main workflow objects. First, there are two that hold configuration information: Forge, and Weld. You can think of them as classes in OOP parlance.

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

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: 40 requests in 1 second
  • Development: 2 requests in 1 second

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
back to articles

Ready to upgrade your paperwork?

Start filling, generating, and signing PDFs from your app. Every account comes with free access to the Developer API.