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 you want to use when generating your document. It will replace the fields 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 with John.

destinations

The destinations object is where you provide details on how and where you want to store a generated document. You can specify data related to the following apps:

📘

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

Inkit Storage

You specify data related to an Inkit Storage destination in an object 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 an object called salesforce, which has the following properties:

PropertyTypeRequiredDescription
record_idStringYesThe Salesforce LinkedEntityId.
file_nameStringNoThe name of the generated document.
descriptionStringNoThe description of the generated document.
salesforce_typeStringNoWhether you are sending a file or a link to Salesforce.
sandboxBooleanNoWhether or not you are using the Salesforce sandbox.

For example:

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

Sepire

You specify data related to a Sepire destination in an object 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 or not to verify the address.
mail_product_nameStringNoWhether the product is a letter or a postcard.
mail_product_dataObjectNoProduct data.

mail_product_data

PropertyTypeRequiredDescription
mail_typeStringNoWhether delivery type is usps_first_class or usps_standard.
letter_address_placementStringNoWhether the placement of the address is top_first_page or insert_blank_page if mail_product_name is letter.
letter_return_envelopeBooleanNoWhether or not to include a return envelope if mail_product_name is letter.
letter_perforatedIntegerNoWhether perforated (1) or not (0) if mail_product_name is letter.
letter_double_sidedBooleanNoWhether or not output should be double-sided if mail_product_name is letter.
letter_colorBooleanNoWhether or not output should be in color if mail_product_name is letter.
letter_additional_serviceStringNoWhether one of the following additional services is included: certified, certified_return_receipt or registered if mail_product_name is letter.
postcard_sizeStringNoThe postcard size, which can be 4x6, 6x9 or 6x11 if mail_product_name is postcard.

For example:

{
  "destinations": {
    "sepire": {
      "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",
      },
      "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"
    }
  }
}

DocuSign

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

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

signers

PropertyTypeRequiredDescription
[id]ObjectYesThe description of the 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
nameStringNoThe name of the person receiving a copy of the generated document.
emailStringNoThe 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 DocuSign destination in an object 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
    }
  }
}

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
  }
}