List and Search Documents

List Documents endpoint provides a wide range of options to list and search documents.

You may filter documents by:

• Document's parent template_id or form_id.
• Document's owner using membership_id.
• A recipient or approver using contact_id.
• Document's status or excluding a status by passing status_ne.
• folder_uuid, if documents organized in folder.
• tag if you are adding the tags to the documents.
• metadata if you associated it with the document.
• id.
• Document's name using parameter q. Also allows to search by a document's ref number.

Pass deleted=true if you want to display only deleted documents.

📘

List by Linked Objects

To get a list of documents by their linked objects from external integrated systems, use special endpoint.

Limiting list of results

You may limit search results using:

• completed_from and/or completed_to dates to include only documents completed between those dates.
• created_from and/or created_to date to include only document create between those dates.
• modified_from and/or modified_to date. Note, only changes to document's status and settings are affecting modification date.

For pagination, use count (default is 50, maximum is 100), and page (starts with 1).

Ordering the results

While the default order is by date_status_changed, you may specify order_by to sort a list by another field, see the list in the endpoint references.

To guarantee the stable order and best performance, order the list by date_created. It never changes, so you alway get the same order of the documents.

With workspaces containing hundreds of thousands and more documents, we recommend always order by date_created.

👍

Pro Tip

To get the best performance while ordering documents by any field, limit the result by setting created_from and created_to parameters. Run the request in batches by sliding this timeframe.

Listing by a timeframe: example

• Limit search result to 1 month by creation date:
  count=100&order_by=date_created&created_from=2023-08-01T00:00:00Z&created_to=2023-09-01T00:00:00Z
  This request returns only documents created in August.
• The next request is for page = 2 (still listing documents created in August):
  count=100&page=2&order_by=date_created&created_from=2023-08-01T00:00:00Z&created_to=2023-09-01T00:00:00Z
  Once you receive an empty response, it means you listed all the documents created in the provided time range.
• Continue listing them by setting another month:
  count=100&order_by=date_created&created_from=2023-09-01T00:00:00Z&created_to=2023-10-01T00:00:00Z
  This request lists the documents created in September 2023.