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 endpoints require basic authentication with an API key.

Every Anvil organization comes with a development API key and a production API key. If you haven't already, sign up for an Anvil account. Once logged in, you can find your API keys on the Organization settings -> API keys page. There will be an API key card.

The development key and production key work exactly the same, except in the following ways:

• Development key requests are more aggressively rate-limited.
• PDFs filled or generated with the development key will have a watermark.
• See the development and test mode section for more info on working with Anvil in a development environment.

Note: At this time, your API keys are meant to be used from a server or server-like environment (lambda function, etc.), not from a browser environment. Exposing your API keys in a browser will allow anyone to access information in your Anvil organization with the exposed API key.

Authentication

Use Basic authentication with all API GraphQL and REST 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 workspace

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

For more information on using the Postman workspace, see our Postman workspace guide.

Language-specific API clients

We have created language-specific API client libraries to help you interact with our API more easily. They help to simplify:

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

At this time we offer API client libraries for the following languages:

• Node.js (JavaScript & TypeScript): @anvilco/anvil
• Python: python-anvil
• C#/.NET: dotnet-anvil
• Go: golang-anvil (community supported!)

Usage example scripts

A collection of API usage examples are on GitHub at anvilco/anvil-api-usage-examples. The examples cover common API use-cases and are designed to be easy to copy & paste into your app.

Is the repository missing the language your organization uses? Feel free to create an issue on the repo or let us know at support@useanvil.com.

Development and test mode

In an effort to help you build out your integration, each product has a way to make free development requests. Generally, we advise using your development API key in development environments.

• PDF filling and PDF generation requests made with the development key are free. Resulting PDFs will have a watermark.
• Test Workflow submissions are free. Start test Workflow submissions via GraphQL with the isTest variable set to true. To create test Workflow submissions with UI URLs, use the ?test=true query param.
• Test e-sign packets are free. Create test e-sign packets with the isTest variable set to true.

Documents filled and signed in test Workflows and test Etch e-sign packets will contain a watermark and red signatures.

Encryption

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

We provide encryption libraries in the following languages:

• NodeJS
• Python

They can be use to encrypt and decrypt data with your RSA keypair. If you do not use one of the languages above, the libraries explain the encryption methodology.

You can encrypt data in the following scenarios:

• When filling and generating PDFs.
• When creating a Workflow submission with data
• When creating an Etch e-sign packet with data
• 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.

All development API keys have the same limits: 4 requests in 1 second.

The production key rate limit is based on your organization's subscribed plan. Production key rate limits:

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