API Object Shapes

This is a reference area where you can learn about the shapes of many of our API's shared objects. Many of our GraphQL and REST endpoints will require these shapes as part of their input parameters or output results.

CastField

An object specifying the configuration of a field in a Cast/PDF:

id: (string) required An ID with which to reference this field in its PDF. Must be unique within the PDF itself.
type: (string) required The type of field. E.g. "signature".
format: (string) The special format, if any, of the field.
name: (string) The human-friendly name of the field.
pageNum: (integer) required The page number in the document where this field is located. Starts at 0.
rect: (Rectangle) required The rectangular area/location of the field on its page.
fontFamily: (FontFamily) The font family to use when filling out this field.
fontSize: (FontSize) The font size to be used when filling out this field.
fontWeight: (FontWeight) The font weight to use when filling out this field.
textColor: (TextColor) The text color to be used when filling out this field.
alignment: (FontAlignment) The text alignment for the field.

CastReference

An object for referencing an existing PDF template to be used when creating Etch e-sign packets.

castEid: (string) required The EID of an existing Cast to be used.
id: (string) required An ID with which to refer to this file in other objects.
title: (string) The title of the document to be used.
filename: (string) A file name that will override the template's intrinsic file name.
fontFamily: (FontFamily) The font family for fields in this file.
fontSize: (FontSize) Default font size for fields in this file.
fontWeight: (FontWeight) The font weight for fields in this file.
textColor: (TextColor) Default text color for fields in this file.
alignment: (FontAlignment) The text alignment for fields in this file.

EtchFileGenerate

An object representing a new file to be generated when creating Etch e-sign packets:

id: (string) required An ID with which to refer this file in various places.
title: (string) required The title encoded into the PDF and the PDF's first page header.
filename: (string) required The generated PDF will be given this file name.
markup: (Object) required The HTML and CSS of your generated document. e.g. { html: '<h1>...</h1>', css: 'h1 { ... }' } fields: (array) required An array of CastFields and ContentBlocks making up the content of the PDF.
logo: (Logo) A logo to be placed onto the top-right corner of the PDF if specified.
includeTimestamp: (boolean) Show or hide the timestamp at the bottom of the PDF.
fontFamily: (FontFamily) The font family for fields in this file.
fontSize: (FontSize) Default font size for fields in this file.
fontWeight: (FontWeight) The font weight for fields in this file.
textColor: (TextColor) Default text color for fields in this file.
alignment: (FontAlignment) The text alignment for fields in this file.

EtchFillData

An object that allows for providing payload data for PDFs in an Etch Packet, as well as for providing / overriding signer information:

signers: (object) An object where each key is a signer ID and each value is a PacketSigner.
payloads: (object) An object where each key is a document Alias ID and each value is a PDFFill.

EtchSigner

An object representing a signer to be used in an Etch Packet. See the adding signers section of the e-sign guide for usage.

id: (string) required An ID with which to reference this Signer on various fields. Must be unique in the Etch Packet.
name: (string) The name of this Signer to be used in greetings.
email: (string) The email address for this Signer.
routingOrder: (integer, min 1) What position in the signing order this Signer should be. Defaults to its position in the array that contains it.
isPending: (boolean) When true, creates the signer in a pending state. Pending signers are skipped until explicitly activated. Requires allowUpdates: true on the packet.
signatureMode: (enum["draw", "text"]) Whether the signer draws their signature or types it. Defaults to "draw".
acceptEachField: (boolean) When true, the signer clicks through each field on the signing page. When false, a document list is shown. Defaults to true.
showFinishSigningButton: (boolean) When true and acceptEachField is also true, shows a final "Finish signing" button for review before completion.
addUuidToSignatures: (boolean) When true, a UUID is appended to the signer's signature images.
addTimestampToSignatures: (boolean) When true, a timestamp is appended to the signer's signature images.
signatureImageVerticalJustificationDefault: (enum["dynamic", "bottom", "none"]) Controls vertical alignment of text-mode signature images within their field bounds. Defaults to "dynamic".
signatureExperience: (enum["signWhileReviewing", "signBeforeReviewing"]) Controls when signers accept their signatures. signWhileReviewing (current default) is the modern field-by-field flow; signBeforeReviewing is the traditional accept-then-review flow.
fields: (array[SignerField]) Array of file + field combinations that this Signer is responsible for. Not required when using text tags with a matching signer ID.
fieldsAreOrdered: (boolean) When true, the signer's fields are presented in a defined order during signing.
signerType: (enum["email", "embedded", "in-person"]) Whether the signer should be prompted via email, embedded into your own flow, or signing in person. Defaults to "email".
redirectURL: (string) A URL to redirect the signer to after completing signatures, on errors, or on expired tokens.
enableEmails: (boolean or array[string]) Controls which emails the signer receives. true/undefined enables all, false/[] disables all, or an array of email types (e.g. ['etchComplete']). Defaults to true.
tokenValidUntil: (string, ISO 8601 datetime) An absolute expiry datetime for the signing URL. Alternative to tokenValidForMinutes.
tokenValidForMinutes: (integer, min 1, max 86400) Duration in minutes before the signer's signing URL expires. Defaults to 20160 (14 days) for email signers and 120 (2 hours) for embedded signers.
allowNameChange: (boolean) When true, the signer can update their own name during signing.
allowEmailChange: (boolean) When true, the signer can update their own email address during signing.
requireNameOnLoad: (boolean) When true, a modal prompts the signer to enter their legal name immediately on accessing the signing interface.
requireEmailOnLoad: (boolean) When true, a modal prompts the signer to enter their email immediately on accessing the signing interface. Not available for email or in-person signer types.

DocuSign-specific fields (must have Enterprise plan to use) — only relevant when signatureProvider is set to "docusign" on the packet:

requireIdCheck: (boolean or enum["kb", "sms", "smskb", "idsms"]) Require the signer to pass an identity verification check before signing. true uses the default method; string values select a specific method (knowledge-based, SMS, or both).
requireIdCheckInTest: (boolean) When true, ID verification is required even in test mode.
idCheckPhone: (string) Phone number to use for SMS-based identity verification. Required when requireIdCheck is "sms", "smskb", or "idsms".
accessCode: (string) An access code the signer must enter before they can view and sign the document.

EtchUpload

An object representing a new file being uploaded for use with Etch:

id: (string) required An ID with which to refer to this file in various places.
title: (string) The title of the document to be used.
file: (Upload) required The actual file being uploaded.
fields: (array[CastField]) Array of fields to configure on the new file.
fontFamily: (FontFamily) The font family for fields in this file.
fontSize: (FontSize) Default font size for fields in this file.
fontWeight: (FontWeight) The font weight for fields in this file.
textColor: (TextColor) Default text color for fields in this file.
alignment: (FontAlignment) The text alignment for fields in this file.

FontAlignment

(string) The text alignment for a field. Possible values:

• 'left' (default)
  
• 'center'
  
• 'right'
  

FontFamily

(string) The font family to be used when filling a field. Possible values:

• 'Noto Sans' (default)
  
• 'Courier'
  
• 'Helvetica'
  
• 'Times New Roman'
  
• All Google fonts. Specify the name exactly as the Google fonts website indicates. Font family names are case sensitive.

FontSize

(integer) The font size to be used when filling a field.

FontWeight

(string) The font weight to be used when filling a field. Possible values:

• 'normal' (default)
  
• 'bold'
  
• 'italic'
  
• 'boldItalic'
  

Logo

An object representing a logo and its dimensions:

src: (string) required A href to the logo image. src can be a data URI as well as a HTTP URL
maxWidth: (integer) The max width of the logo image.
maxHeight: (integer) The max height of the logo image.

PDFFill

An object representing a PDF fill data:

title: (string) The title encoded into the PDF.
filename: (string) The file name of the filled PDF.
fontFamily: (FontFamily) The font family for fields in this file.
fontSize: (FontSize) Default font size for fields in this file.
fontWeight: (FontWeight) The font weight for fields in this file.
textColor: (TextColor) Default text color for fields in this file.
alignment: (FontAlignment) The text alignment for fields in this file.
data: (Object) The data to fill your PDF. e.g. { customField: 'hello world' }

Rectangle

An object representing the rectangular area of a field on a document page:

x: (number) required The x coordinate of the left-hand side of the rectangle.
y: (number) required The y coordinate of the top of the rectangle.
height: (number) required The height of the rectangle.
width: (number) required The width of the rectangle.

SignerField

An object representing a field the signer will be required to sign. For non signature fields, fields will be filled with the signer's information. Used in EtchSigner.

fileId: (string) required ID of the file for the corresponding fieldId.
fieldId: (string) required ID or field alias of the field to be signed on the relevant file.

fieldId can specify signature field types and name and email fields. A list of all fields that can be attached to a signer in the fields array:

• Signature (signature when defined in the files array)
• Signature Initial (initial when defined in the files array)
• Signature Date (signatureDate when defined in the files array)
• Name (fullName when defined in the files array)
• Email (email when defined in the files array)

TextColor

(string) The color to use for the relevant text in a field. Must be a 6 digit HEX color reference. e.g. #abc123

Upload

A binary file uploaded via a GraphQL operation. These types can be either a JSON structure with a base64 encoded file, a publicly accessible URL, or part of a multipart request.

Base64 Upload

We support the uploading of files as base64 encoded strings via the following structure. Request bodies are limited to a 1MB size. If you have files that will push the body over the 1MB size limit, use the multipart form described below.

data: (string) required The actual base64 encoded data.
filename: (string) required A filename to store this upload as.
mimetype: (string) required A string representing the MIME type of the file. E.g. "application/pdf".

URL Upload

We support the uploading of files via a publicly accessible URL via the following structure.

url: (string) required A publicly accessible URL to the file.
filename: (string) A filename to store this upload as. If not provided, it will be extracted from the URL or the server's Content-Disposition header.

Multipart Upload

The Upload type adheres to the GraphQL multipart request specification. There are several client implementations of this spec. If you are unfamiliar/uncomfortable with this pattern, we strongly recommend using our Anvil Node Client to simplify interacting with our API when binary uploads are involved.

ContentBlock

An object representing content to be embedded onto a PDF:

label: (string) A bolded label for the content section.
heading: (string) A larger bolded heading intended to break up sections of a document.
content: (string) A block of text that supports multiline and markdown formatting, including headings, bold, itatlic, bullets, tables, blockquotes, links, images.
table: (Table) An object representing a table.
fontFamily: (FontFamily) The font family for this field.
fontSize: (FontSize) Default font size for this field.
fontWeight: (FontWeight) The font weight for this field.
textColor: (TextColor) Text color for this field.
alignment: (FontAlignment) The text alignment for this field.

Submission Payloads

Submission payloads will be an Object keyed by fieldId. Values will be an Object with a String type and value keys e.g.

{
  [fieldId]: {
    type: String,
    value: Any, // can be a string, number, object, etc depending on the type
  },
  ...other ids...
}

For example:

{
  email: {
    type: 'shortText',
    value: 'bobby@tables.com'
  },
  name: {
    type: 'fullName',
    value: {
      firstName: 'Bobby',
      mi: '',
      lastName: 'Tables'
    }
  },
  ...other ids...
}

Array types are represented similarly

{
  beneficiaries: {
    type: 'array',
    value: [{
      email: {
        type: 'shortText',
        value: 'bobby@tables.com'
      },
      name: {
        type: 'fullName',
        value: {
          firstName: 'Bobby',
          mi: '',
          lastName: 'Tables'
        }
      },
    }, ...]
  }
},

Submission Payload Types

Each entry below describes payload types by field: the field name shown in
the Workflow bulder, the field's `fieldTypeString` used under the hood, and
the object type (`String`, `Object`, etc).

Example:

Field name in UI (`fieldTypeString`): <ValueType>

## Strings

Basic Text (`shortText`): <String>
Long Text (`longText`): <String>
Numeric Text (`numericText`): <String> with 0-9 characters only
Email (`email`): <String> with an `@` and a valid domain
Social Security Number (`ssn`): <String> in format `123121234`
Tax ID Number / EIN (`ein`): <String> in format `921234567`

## Dates

Date (`date`): <String> in the format `YYYY-MM-DD`
Date Dropdowns (`dateSelect`): <String> in the format `YYYY-MM-DD`

## Options

Checkbox (`checkbox`): <Boolean> `true` or `false`
Dropdown (`compoundSelect`): <Object> {
  k: 'anOptionKey',
  v: 'The option text as seen by the user',
}
Radio Buttons (`radioButtons`): <Object> {
  k: 'anOptionKey',
  v: 'The option text as seen by the user',
}

Note: when updating the payload for Dropdowns or Radio Buttons,
you can pass a <String> with the value of either `k` or `v`

## Numbers

Decimal Number (`number`): <Number>
Dollar (`dollar`): <Number>
Integer (`integer`): <Number>
Percent (`percent`): <Number> `100` is 100%

## Complex types

Phone (`phone`): <Object> {
  region: 'US',
  num: '555113333'
}
Note: when updating a phone number, you can pass a <String>.
e.g. `555113333` or `+4402012341234`

First and last name (`fullName`): <Object> {
  firstName: 'Bobby',
  mi: 'W',
  lastName: 'Jones'
}
Note: when updating a name, you can pass a <String>.
e.g.  'Taylor Jones'

Address - US (`usAddress`) and International (`intlAddress`): <Object> {
  street1: '123 Main St',
  street2: 'Apt. 14', // optional
  city: 'San Francisco',
  state: 'CA',
  zip: '94106',
  country: 'us' // ISO 3166 country code
}

## Lists

Lists will have `n` Objects and will contain the types above

List (`array`): <Array> [
  {
    aFieldId: ...one of the above types...,
    anotherFieldId: ...one of the above types...,
    ...
  },
  {...}
]