Ctrlk
For the complete documentation index, see llms.txt. This page is also available as Markdown.

List responses

This document explains how to paginate, filter, sort, and search list responses in DocStudio API.

This guide focuses on mailbox envelope lists and mailbox search. Use the API reference for each endpoint's complete parameter list and response schema.

Use pagination for mailbox envelope lists

Pagination processes a large result set in smaller pages. Request one page, process its records, and then request the next page.

Use pagination when you synchronize or process envelopes regularly. Avoid loading an entire mailbox in one request.

Pagination parameters

Use these query parameters where the endpoint supports them:

  • limit — maximum records in one response

  • offset — records to skip before returning the page

Start with a moderate page size, such as 20, 50, or 100. Confirm supported limits in the endpoint reference.

Request the first page

GET /api/v1/mailbox/{mailboxUuid}?limit=20&offset=0
Authorization: Bearer {token}
Content-Type: application/json
mailboxUuid: {mailboxUuid}

This request returns the first page with up to 20 records.

Request the next page with the same limit and an increased offset.

GET /api/v1/mailbox/{mailboxUuid}?limit=20&offset=20
Authorization: Bearer {token}
Content-Type: application/json
mailboxUuid: {mailboxUuid}

Process pages safely

Use response metadata to decide whether another page exists.

Use these values like this:

  • totalElements — total matching records

  • sizeRequested — page size accepted by the server

  • numberOfElements — records in the current response

  • data — returned records

Stop when data is empty or numberOfElements is smaller than sizeRequested.

Follow this flow:

  1. Send the first request with limit=20 and offset=0.

  2. Process the returned records.

  3. Send the next request with limit=20 and offset=20.

  4. Continue increasing offset by limit.

  5. Stop when the response is empty or shorter than sizeRequested.

Offset pagination does not create a fixed data snapshot. New or changed envelopes can cause duplicates or skipped records. Save processed envelope UUIDs and deduplicate results during synchronization.

Filter and sort envelope lists

Keep every filter and the sorting direction unchanged during one pagination run. Changing them can return unexpected records or skip matching envelopes.

Use scope=inbox for received envelopes. Use scope=outbox for sent envelopes.

Use sort=desc to process newer results first. Use sort=asc to process older results first.

Use specific filters when possible. The mailbox endpoint supports filters for status, archive state, sender, template, labels, subject, and date periods. It also supports q where text search is appropriate.

Use this pattern to synchronize completed, unarchived envelopes from one template.

Check the Check Envelope Status reference for supported filter values and date-period formats.

Encode query values

Encode spaces and special characters in query values. Use an HTTP client or URL builder that encodes parameters automatically.

Search mailboxes and contacts

Use mailbox search before assigning a recipient to a template role. The required q parameter searches mailbox UUIDs, aliases, names, and contact names.

Save the returned mailbox UUID and use it when you assign a recipient role.

Do not use mailbox search to check envelope status. Use the mailbox envelope endpoint for envelope lists and status checks.

Get one envelope

Pass UUID when you already know the envelope UUID and need full envelope data with its template.

mailboxUuid identifies the target mailbox and current mailbox context. envelopeUuid identifies the requested envelope.

Do not use an envelope UUID where a mailbox UUID is required. Do not use mailbox search when you need an envelope.

Synchronize envelope lists

Use this pattern for regular polling:

  1. Set stable filters, sorting, limit, and offset.

  2. Request one page of envelopes.

  3. Process only envelope UUIDs that were not processed already.

  4. Increase offset by limit and request the next page.

  5. Stop when the page is empty or shorter than sizeRequested.

  6. Retry temporary request failures with the same query parameters.

Avoid requesting very large pages unless the endpoint supports your required size.

Troubleshoot list requests

Check pagination and filters:

  • The limit value is supported by the endpoint.

  • The offset matches the requested page.

  • Filters and sorting remain stable.

  • Query values are URL-encoded.

  • The requested status and scope are supported.

Check identifiers and access:

  • The token owner can access the mailbox.

  • The path mailbox UUID is correct.

  • The mailboxUuid header has the correct context.

  • Template, label, sender, and envelope UUIDs use the correct environment.

  • UUID is used only for one known envelope.

Related topics

PreviousEnvelope callbacks
NextAPI versioning

Last updated

Was this helpful?