API

GraphQL

The GraphQL API gives you insight into your account and the objects it owns, allow you to create, update, start, and submit data to workflows.

First check out the API basics to learn how to get an API key and use it to authenticate to the API. Additionally, brushing up on our terminology will be helpful in understanding the queries below.

Your First Query

All queries are POSTs to a single URL: https://graphql.useanvil.com.

A good place to start is with the currentUser query. This query will return your API user with all the main objects (welds: workflows, forges: web forms, and casts: PDF templates) on your account.

POST https://graphql.useanvil.com
{
  currentUser {
    eid
    organizations {
      eid
      name
      slug
      casts {
        eid
        name
        config
      }
      welds {
        eid
        title
        config
        forges {
          eid
          name
          config
        }
      }
    }
  }
}

Fetching submission data is best done through the weld query.

Undocumented Queries

This document only contains the most common queries and mutations we have seen customers use thus far. If you want access to something that is not specified in this document, you can

  • Contact us and let us know what you want to do. We will suggest an approach and let you know what queries and mutations are available.
  • Or use GraphQL introspection queries.

For example, you can get all available queries with this query:

query availableQueries {
  __schema {
    queryType { // or mutationType for mutations
      fields {
        name
        description
      }
    }
  }
}

Queries

currentUser

Returns the currently logged in user. You can generally get a lot of what you may need from this query.

currentUser: User

weld

Fetching the weld is the best way to fetch the data submitted to a given workflow (weld). An instances of a workflow is called a weldData.

weld(
  organizationSlug: String!,
  slug: String!,
): Weld

POST https://graphql.useanvil.com
{
  weld(organizationSlug: ..., slug: ...) {
    id
    eid
    slug
    title

    // weldDatas is paginated via the limit & offset options
    // Other options:
    // * isTest - show only test items; default: false
    // * isArchived - show only archived items; default: false
    // * statuses - Array use like ['completed'] to get only completed items
    weldDatas (offset: $offset, limit: $limit, ...) {
      rowCount
      pageCount
      page
      pageSize
      items {
        id
        eid
        displayTitle // The title of the submission
        status  // created, in-progress, ready-to-sign, awaiting-signatures, completed
        isComplete // true when submissions complete, but not yet signed
        isCompleteAndSigned
        isTest
        completionPercentage // 0 to 1
        numberRemainingSigners

        // DocumentGroup is the group of output PDFs. This will be null until
        // all submissions are complete and the signature process has been
        // kicked off
        documentGroup {
          id
          eid
          status // uninitialized, sent, partial, completed, voided, declined
          currentRoutingStep // where in the routing order things are
          signers {
            id
            eid
            status // sent, completed, voided
            name
            email
            routingOrder
          }
        }
      }
    }
  }
}

weldData

Fetch a single weldData from a weld.

weldData(
  eid: String!,
): WeldData

POST https://graphql.useanvil.com
{
  weldData(eid: ...) {
    id
    eid
    displayTitle // The household name
    status // created, in-progress, ready-to-sign, awaiting-signatures, completed
    isComplete // true when submissions complete, but not yet signed
    isCompleteAndSigned // true when status === 'completed'
    isTest
    completionPercentage // 0 to 1
    numberRemainingSigners

    // DocumentGroup is the group of output PDFs
    documentGroup {
      ...
    }

    // There will be one submission for Admin Details, Client Details, each account
    submissions {
      id
      eid

      // created, in-progress, completed, waiting-to-sign,
      // users-turn-to-sign-email, users-turn-to-sign-ui,
      // user-signed-and-waiting, someone-else-signed-and-waiting
      status

      // On Client Details, this is the URL the client will fill out
      continueURL

      forge {
        id
        eid
        name // Client Details, Account Transfer, etc.
      }
    }
  }
}

Mutations

forgeSubmit

forgeSubmit allows you to create new submissions and update data for a given workflow. Use forgeSubmit only if you need total programmatic control. A simpler way to start workflows is with our Form UI URLs.

Any time data is submitted to a workflow, it flows through forgeSubmit. There are a couple situations forgeSubmit handles:

  1. Starting a workflow. Use forgeSubmit to create a brand new WeldData and Submission on a given Weld. e.g.
  2. Submitting data to an existing Submission. After a workflow has been started, you can submit data to the Submission, adding data to the payload or overwriting data already in the payload
  3. Continuing a workflow. When there are multiple web forms that need to be filled to complete a workflow, forgeSubmit can create a Submission for an unstarted Forge.
forgeSubmit (
  forgeEid: String!,
  weldDataEid: String,
  submissionEid: String,
  payload: JSON!,
  currentStep: Int,
  complete: Boolean,
  isTest: Boolean=false,
  timezone: String,
): Submission

Starting A Workflow

Starting a workflow entails passing a forgeEid and an optional payload. It will return a new Submission on the specified Forge with a new WeldData.

// Create a Submission and a WeldData
forgeSubmit({
  variables: {
    forgeEid: forge.eid,
    payload: {}, // Seed the submission with data here...
    complete: false,
    isTest: false,
  },
})
// => submission: {
//   eid: 'abc123'
//   payload: {} // the actual data
//   weldData: {
//     eid: 'def456'
//   }
//   forge: {
//     eid: 'ghi789'
//   }
// }

// UI URL for this Forge Submission is
// https://app.useanvil.com/form/${organization.slug}/${forge.slug}/abc123

Submitting Data

Submitting data to the created submissions requires the forgeEid, weldDataEid, and submissionEid.

forgeSubmit({
  variables: {
    forgeEid: forge.eid,
    weldDataEid: subimssion.weldData.eid,
    submissionEid: subimssion.eid,
    payload: {
      // payload keys correspond to the `id` of a forge field
      email: 'bobby@tables.com'
    },
    complete: false,
  },
})

Continuing A Workflow

Say you have a workflow with 2 webforms: Admin Form and Client Form. There will be two Forges, one for Admin Form and one for Client Form. In order to complete the workflow, there needs to be one WeldData with two completed Submissions, one Submission for the Admin Form Forge, and one for the Client Form Forge.

Often in this situation, there will already be a WeldData and one Submission, the other Submission just needs to be created. Create the other submission this way:

forgeSubmit({
  variables: {
    forgeEid: clientForge.eid,
    weldDataEid: subimssion.weldData.eid, // the weldData.eid that was created earlier
    payload: {},
    complete: false,
    isTest: false,
  },
})
// => submission: {
//   eid: 'abcdef'
//   payload: {} // the actual data
//   weldData: {
//     eid: 'def456'
//   }
// }

// UI URL for this Forge Submission is
// https://app.useanvil.com/form/${organization.slug}/${clientForge.slug}/abcdef