Standard API request and response objects

The following request objects apply when generating documents in Inkit through the API:

The following response objects apply when retrieving lists of documents, batches, folders and templates through the API:

merge_parameters

The merge_paremeters object is where you store the key-value pairs that you'll use when generating your document. It will replace the fields that you have embedded in your document template with the data you supply here.

For example:

{
  "merge_parameters": {
    "Name": "John"
  }
}

If you use the above merge_paremeters when you generate your document, Inkit will replace the field Name in your template with John.

destinations

The destinations object is where you provide details on how and where you want to store a generated document.

πŸ“˜

Note: You can specify multiple destinations when generating a document.

Inkit Storage

You specify data related to an Inkit Storage destination in a subobject called inkit_storage, which has the following properties:

PropertyTypeRequiredDescription
nameStringNoThe name of the generated document.
folder_idStringNoThe ID of the folder that the document will be generated in.
expire_after_n_viewsIntegerNoThe number of views of the generated document before it expires.
retain_forObjectNoThe amount of time before the generated document expires.

retain_for

PropertyTypeRequiredDescriptions
minutesIntegerNoThe number of minutes before the document expires.
hoursIntegerNoThe number of hours before the document expires.
daysIntegerNoThe number of days before the document expires.
monthsIntegerNoThe number of months before the document expires.
yearsIntegerNoThe number of years before the document expires.

For example:

{
  "destinations": {
    "inkit_storage": {
      "retain_for": {
        "hours": 1
      },
      "name": "Mail Merge",
      "folder_id": "fold_6UpetHRzr73eyl4jCbfYBl",
      "expire_after_n_views": 1
    }
  }
}

If you use the above destinations object when generating your document, Inkit will save the document as Mail Merge and will place it in the folder specified by the ID fold_6UpetHRzr73eyl4jCbfYBl. The document will expire either after one view or one hour after its generation, whichever comes first.

Salesforce

You specify data related to a Salesforce destination in a subobject called salesforce, which has the following properties:

PropertyTypeRequiredDescription
record_idStringYesThe Salesforce LinkedEntityId.
salesforce_typeStringYesWhether you are sending the generated document as a link or as a file to Salesforce. The default is link.
file_nameStringNoThe name of the generated document.
descriptionStringNoThe description of the generated document.
sandboxBooleanNoWhether you are using the Salesforce sandbox. The default is false.

For example:

{
  "destinations": {
    "salesforce": {
      "record_id": "Your salesforce LinkedEntityId",
      "salesforce_type": "link",
      "file_name": "My awesome PDF",
      "description": "Salesforce PDF description"
    }
  }
}

Sepire

You specify data related to a Sepire destination in a subobject called sepire, which has the following properties:

PropertyTypeRequiredDescription
address_line_1StringNoThe first line of the recipient's address.
address_line_2StringNoThe second line of the recipient's address.
address_cityStringNoThe recipient's city.
address_zipStringNoThe recipient's zip code.
address_stateStringNoThe recipient's state.
address_countryStringNoThe recipient's country.
first_nameStringNoThe recipient's first name.
last_nameStringNoThe recipient's last name.
verify_addressBooleanNoWhether to verify the address.
mail_product_nameStringNoWhether the product is a letter or a postcard.
mail_product_dataObjectNoProduct data.

mail_product_data

PropertyTypeRequiredValue ofmail_product_nameDescription
mail_typeStringNoletter or postcardWhether the delivery type is usps_first_class or usps_standard.
letter_address_placementStringNoletterWhether the placement of the address is top_first_page or insert_blank_page.
letter_return_envelopeBooleanNoletterWhether to include a return envelope.
letter_perforatedIntegerNoletterWhether perforated (1) or not (0).
letter_double_sidedBooleanNoletterWhether output should be double-sided.
letter_colorBooleanNoletterWhether output should be in color.
letter_additional_serviceStringNoletterWhether one of the following additional services is included: certified, certified_return_receipt or registered.
postcard_sizeStringNopostcardThe postcard size, which can be 4x6, 6x9 or 6x11.

For example:

{
  "destinations": {
    "sepire": {
      "address_line_1": "1234 Main St.",
      "address_line_2": "#1",
      "address_city": "New York",
      "address_zip": "10001",
      "address_state": "NY",
      "address_country": "US",
      "first_name": "John",
      "last_name": "Doe",
      "verify_address": true,
      "mail_product_name": "letter",
      "mail_product_data": {
        "mail_type": "usps_first_class",
        "letter_address_placement": "top_first_page",
        "letter_return_envelope": true,
        "letter_perforated": 1,
        "letter_double_sided": true,
        "letter_color": true,
        "letter_additional_service": "certified",
      }
    }
  }
}

DocuSign

You specify data related to a DocuSign destination in a subobject called docusign, which has the following properties:

PropertyTypeRequiredDescription
signersList<Object>YesA list of signers of the generated document.
copy_receiversObject[]NoAn array of people receiving a copy of the generated document.
routingStringNoWhether the routing of the generated document to signers is ordered or unordered.

signers

PropertyTypeRequiredDescription
[id]ObjectYesThe signer specifed by id.
[id]
PropertyTypeRequiredDescription
nameStringYesThe name of the signer.
emailStringYesThe email address of the signer.
routing_numberIntegerNoThe routing number of the signer if routing is set to ordered.

copy_receivers

PropertyTypeRequiredDescription
nameStringYesThe name of the person receiving a copy of the generated document.
emailStringYesThe email address of the person receiving a copy of the generated document.

For example:

{
  "destinations": {
    "docusign": {
      "signers": {
        "1": {
          "name": "John Doe",
          "email": "[email protected]",
          "routing_number": 2
        },
        "2": {
          "name": "Sally Smith",
          "email": "[email protected]",
          "routing_number": 1
        }
      },
      "copy_receivers": [{
        "name": "Tom Jones",
        "email": "[email protected]"
      }],
      "routing": "ordered"
    }
  }
}

Magic Link

You specify data related to a Magic Link destination in a subobject called magic_link, which has the following properties:

PropertyTypeRequiredDescription
auth_emailStringYesThe authorization email address.
recipient_emailStringYesThe recipient email address.
nameStringNoThe name of the generated document.
descriptionStringNoThe description of the generated document.
auth_methodStringNoWhether the authorization method is email or social.
retain_from_createdObjectNoThe amount of time before the generated document expires from the time it was created.
retain_from_first_openedObjectNoThe amount of time before the generated document expires from the time it was first opened.
expire_after_n_viewsIntegerNoThe number of views of the generated document before it expires.

retain_from_created and retain_from_first_opened

PropertyTypeRequiredDescriptions
minutesIntegerNoThe number of minutes before the document expires.
hoursIntegerNoThe number of hours before the document expires.
daysIntegerNoThe number of days before the document expires.
monthsIntegerNoThe number of months before the document expires.

For example:

{
  "destinations": {
    "magic_link": {
      "retain_from_created": {
        "hours": 1
      },
      "auth_email": "[email protected]",
      "recipient_email": "[email protected]",
      "auth_method": "email",
      "name": "Mail Merge",
      "expire_after_n_views": 1
    }
  }
}

Amazon S3

You specify data related to an Amazon S3 destination in a subobject called amazon_s3, which has the following properties:

PropertyTypeRequiredDescription
bucket_nameStringYesThe name of the Amazon S3 bucket where the document will be generated.
file_nameStringYesThe name of the document generated.

For example:

{
  "destinations": {
    "amazon_s3": {
      "bucket_name": "mybucket",
      "file_name": "test",
    }
  }
}

Google Drive

You specify data related to an Google Drive destination in a subobject called google_drive, which has the following properties:

PropertyTypeRequiredDescription
folder_idStringYesThe name of the Google Drive folder where the document will be generated.
file_nameStringYesThe name of the document generated.

For example:

{
  "destinations": {
    "google_drive": {
      "folder_id": "12HCqdH7SEJT7USqIpmxqcyn0m3gDTu8b",
      "file_name": "test",
    }
  }
}

Dropbox

You specify data related to an Dropbox destination in a subobject called dropbox, which has the following properties:

PropertyTypeRequiredDescription
pathStringYesThe Dropbox path where the document will be generated.
file_nameStringYesThe name of the document generated.

For example:

{
  "destinations": {
    "dropbox": {
      "path": "/",
      "file_name": "test",
    }
  }
}

Box

You specify data related to an Box destination in a subobject called box, which has the following properties:

PropertyTypeRequiredDescription
parent_idStringYesThe Box parent ID of the document generated.
file_nameStringYesThe name of the document generated.

For example:

{
  "destinations": {
    "box": {
      "parent_id": "0",
      "file_name": "test",
    }
  }
}

metadata

All list methods in the Inkit API return a metadata object that has the following properties:

PropertyTypeDescription
paginationObjectList pagination data, which allows you to page through lists.
sortObjectList sort data.

pagination

PropertyTypeDescription
current_pageIntegerThe current page of the list.
next_pageIntegerThe next page of the list.
page_countIntegerThe number of pages in the list.
page_sizeIntegerThe number of records in each page of the list.
prev_pageIntegerThe previous page of the list.
total_countIntegerThe total number of records in the list.

sort

PropertyTypeDescription
keyStringThe key used to sort the list.
orderIntegerThe sort order of the list. 0 means ascending while 1 means descending.

For example:

{
  "metadata": {
    "pagination": {
      "current_page": 1,
      "next_page": 2,
      "page_count": 3,
      "page_size": 25,
      "prev_page": 3,
      "total_count": 64
    },
    "sort": {
      "key": "modified_at",
      "order": 1
    }
  }
}