Anvil Logo
Products
Industries
Resources
Developers

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.

API Keys

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.

View Anvil API Postman workspace

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:

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.

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.

Encryption Keypair Settings

We provide encryption libraries in the following languages:

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:

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:

Plan typeRequestsTime window
Maker plan4 requests1 second
Maker plan with metered billing20 requests1 second
Growth plan40 requests1 second
Enterprise plan40 requests1 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

Sign up for a live demo

Request a 30-minute live demo today and we'll get in touch shortly. During the meeting our team will help you find the right solution, including:
  • Simplifying data gathering
  • Streamlining document preparation
  • Requesting e-signatures
  • Building and scaling your business
Ready to experience document workflow automation?Sign up for free
Ready to experience document workflow automation?Sign up for free