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:

metadata

`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:

Property	Type	Required	Description
`name`	String	No	The name of the generated document.
`folder_id`	String	No	The ID of the folder that the document will be generated in.
`expire_after_n_views`	Integer	No	The number of views of the generated document before it expires.
`retain_for`	Object	No	The amount of time before the generated document expires.

`retain_for`

Property	Type	Required	Descriptions
`minutes`	Integer	No	The number of minutes before the document expires.
`hours`	Integer	No	The number of hours before the document expires.
`days`	Integer	No	The number of days before the document expires.
`months`	Integer	No	The number of months before the document expires.
`years`	Integer	No	The 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:

Property	Type	Required	Description
`record_id`	String	Yes	The Salesforce LinkedEntityId.
`file_name`	String	No	The name of the generated document.
`description`	String	No	The description of the generated document.
`salesforce_type`	String	No	Whether you are sending a `file` or a `link` to Salesforce.
`sandbox`	Boolean	No	Whether 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:

Property	Type	Required	Description
`address_line_1`	String	No	The first line of the recipient's address.
`address_line_2`	String	No	The second line of the recipient's address.
`address_city`	String	No	The recipient's city.
`address_zip`	String	No	The recipient's zip code.
`address_state`	String	No	The recipient's state.
`address_country`	String	No	The recipient's country.
`first_name`	String	No	The recipient's first name.
`last_name`	String	No	The recipient's last name.
`verify_address`	Boolean	No	Whether or not to verify the address.
`mail_product_name`	String	No	Whether the product is a `letter` or a `postcard`.
`mail_product_data`	Object	No	Product data.

`mail_product_data`

Property	Type	Required	Description
`mail_type`	String	No	Whether delivery type is `usps_first_class` or `usps_standard`.
`letter_address_placement`	String	No	Whether the placement of the address is `top_first_page` or `insert_blank_page` if `mail_product_name` is `letter`.
`letter_return_envelope`	Boolean	No	Whether or not to include a return envelope if `mail_product_name` is `letter`.
`letter_perforated`	Integer	No	Whether perforated (`1`) or not (`0`) if `mail_product_name` is `letter`.
`letter_double_sided`	Boolean	No	Whether or not output should be double-sided if `mail_product_name` is `letter`.
`letter_color`	Boolean	No	Whether or not output should be in color if `mail_product_name` is `letter`.
`letter_additional_service`	String	No	Whether one of the following additional services is included: `certified`, `certified_return_receipt` or `registered` if `mail_product_name` is `letter`.
`postcard_size`	String	No	The 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:

Property	Type	Required	Description
`signers`	List<Object>	Yes	A list of signers in the generated document.
`copy_receivers`	Object[]	No	An array of people receiving a copy of the generated document.
`routing`	String	No	Whether the routing of the generated document is `ordered` or `unordered`.

`signers`

Property	Type	Required	Description
`[id]`	Object	Yes	The description of the signer specifed by `id`.

`[id]`

Property	Type	Required	Description
`name`	String	Yes	The name of the signer.
`email`	String	Yes	The email address of the signer.
`routing_number`	Integer	No	The routing number of the signer if `routing` is set to `ordered`.

`copy_receivers`

Property	Type	Required	Description
`name`	String	No	The name of the person receiving a copy of the generated document.
`email`	String	No	The 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:

Property	Type	Required	Description
`auth_email`	String	Yes	The authorization email address.
`recipient_email`	String	Yes	The recipient email address.
`name`	String	No	The name of the generated document.
`description`	String	No	The description of the generated document.
`auth_method`	String	No	Whether the authorization method is `email` or `social`.
`retain_from_created`	Object	No	The amount of time before the generated document expires from the time it was created.
`retain_from_first_opened`	Object	No	The amount of time before the generated document expires from the time it was first opened.
`expire_after_n_views`	Integer	No	The number of views of the generated document before it expires.

`retain_from_created` and `retain_from_first_opened`

Property	Type	Required	Descriptions
`minutes`	Integer	No	The number of minutes before the document expires.
`hours`	Integer	No	The number of hours before the document expires.
`days`	Integer	No	The number of days before the document expires.
`months`	Integer	No	The 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:

Property	Type	Description
`pagination`	Object	List pagination data, which allows you to page through lists.
`sort`	Object	List sort data.

`pagination`

Property	Type	Description
`current_page`	Integer	The current page of the list.
`next_page`	Integer	The next page of the list.
`page_count`	Integer	The number of pages in the list.
`page_size`	Integer	The number of records in each page of the list.
`prev_page`	Integer	The previous page of the list.
`total_count`	Integer	The total number of records in the list.

`sort`

Property	Type	Description
`key`	String	The key used to sort the list.
`order`	Integer	The 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
  }
}

merge_parameters

destinations

Inkit Storage

retain_for

Salesforce

Sepire

mail_product_data

DocuSign

signers

[id]

copy_receivers

Magic Link

retain_from_created and retain_from_first_opened

metadata

pagination

sort

`merge_parameters`

`destinations`

`retain_for`

`mail_product_data`

`signers`

`[id]`

`copy_receivers`

`retain_from_created` and `retain_from_first_opened`

`metadata`

`pagination`

`sort`