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 VerbatimFields 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) What position in the signing order this Signer should be. Defaults to its position in the array that contains it.
signerType: (enum["email", "embedded"]) Whether the signer should be prompted via email, or if you plan to embed the signature completion into one of your own flows. Defaults to "email".
redirectURL: (string) A URL that you would like us to redirect your signer to after they complete their signature(s).
fields: (array[SignerField]) required Array of file + field combinations that this Signer is responsible for.

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, 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".

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.

VerbatimField

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...,
    ...
  },
  {...}
]