--- title: "List Box Sign requests" method: GET path: "/sign_requests" tags: ["Box Sign requests"] --- # List Box Sign requests `GET /sign_requests` Gets signature requests created by a user. If the `sign_files` and/or `parent_folder` are deleted, the signature request will not return in the list. ## Query parameters - `marker` string - `limit` integer - `senders` string[] - `shared_requests` boolean ## Response `200` Returns a collection of sign requests. - SignRequests — The part of an API response that describes marker based pagination. - `limit` integer — The limit that was used for these entries. This will be the same as the `limit` query parameter unless that value exceeded the maximum value allowed. The maximum value varies by API. - `next_marker` string, nullable — The marker for the start of the next page of results. - `entries` SignRequest[] — A list of Box Sign requests. - `is_document_preparation_needed` boolean — Indicates if the sender should receive a `prepare_url` in the response to complete document preparation using the UI. - `redirect_url` string, nullable — When specified, the signature request will be redirected to this url when a document is signed. - `declined_redirect_url` string, nullable — The uri that a signer will be redirected to after declining to sign a document. - `are_text_signatures_enabled` boolean — Disables the usage of signatures generated by typing (text). - `email_subject` string, nullable — Subject of sign request email. This is cleaned by sign request. If this field is not passed, a default subject will be used. - `email_message` string, nullable — Message to include in sign request email. The field is cleaned through sanitization of specific characters. However, some html tags are allowed. Links included in the message are also converted to hyperlinks in the email. The message may contain the following html tags including `a`, `abbr`, `acronym`, `b`, `blockquote`, `code`, `em`, `i`, `ul`, `li`, `ol`, and `strong`. Be aware that when the text to html ratio is too high, the email may end up in spam filters. Custom styles on these tags are not allowed. If this field is not passed, a default message will be used. - `are_reminders_enabled` boolean — Reminds signers to sign a document on day 3, 8, 13 and 18. Reminders are only sent to outstanding signers. - `name` string — Name of the signature request. - `prefill_tags` SignRequestPrefillTag[] — When a document contains sign-related tags in the content, you can prefill them using this `prefill_tags` by referencing the 'id' of the tag as the `external_id` field of the prefill tag. - `document_tag_id` string, nullable — This references the ID of a specific tag contained in a file of the signature request. - `text_value` string, nullable — Text prefill value. - `checkbox_value` boolean, nullable — Checkbox prefill value. - `date_value` string, date, nullable — Date prefill value. - `days_valid` integer, nullable — Set the number of days after which the created signature request will automatically expire if not completed. By default, we do not apply any expiration date on signature requests, and the signature request does not expire. - `external_id` string, nullable — This can be used to reference an ID in an external system that the sign request is related to. - `template_id` string, nullable — When a signature request is created from a template this field will indicate the id of that template. - `external_system_name` string, nullable — Used as an optional system name to appear in the signature log next to the signers who have been assigned the `embed_url_external_id`. - `request_flow` string, nullable — The flow type of the sign request. Values can include `standard` or `cfr11`. When not specified during creation, a default is chosen based on admin settings. - `type` 'sign-request' — The value will always be `sign-request`. - `source_files` FileBase[] — List of files to create a signing document from. This is currently limited to ten files. Only the ID and type fields are required for each file. - `id` string, required — The unique identifier that represent a file. The ID for any file can be determined by visiting a file in the web application and copying the ID from the URL. For example, for the URL `https://*.app.box.com/files/123` the `file_id` is `123`. - `etag` string, nullable — The HTTP `etag` of this file. This can be used within some API endpoints in the `If-Match` and `If-None-Match` headers to only perform changes on the file if (no) changes have happened. - `type` 'file', required — The value will always be `file`. - `signers` SignRequestSigner[] — Array of signers for the signature request. - `email` string, nullable, required — Email address of the signer. The email address of the signer is required when making signature requests, except when using templates that are configured to include emails. - `role` 'signer' | 'approver' | 'final_copy_reader' — Defines the role of the signer in the signature request. A `signer` must sign the document and an `approver` must approve the document. A `final_copy_reader` only receives the final signed document and signing log. - `is_in_person` boolean — Used in combination with an embed URL for a sender. After the sender signs, they are redirected to the next `in_person` signer. - `order` integer — Order of the signer. - `embed_url_external_user_id` string, nullable — User ID for the signer in an external application responsible for authentication when accessing the embed URL. - `redirect_url` string, nullable — The URL that a signer will be redirected to after signing a document. Defining this URL overrides default or global redirect URL settings for a specific signer. If no declined redirect URL is specified, this URL will be used for decline actions as well. - `declined_redirect_url` string, nullable — The URL that a signer will be redirect to after declining to sign a document. Defining this URL overrides default or global declined redirect URL settings for a specific signer. - `login_required` boolean, nullable — If set to true, the signer will need to log in to a Box account before signing the request. If the signer does not have an existing account, they will have the option to create a free Box account. - `verification_phone_number` string, nullable — If set, this phone number will be used to verify the signer via two-factor authentication before they are able to sign the document. Cannot be selected in combination with `login_required`. - `password` string, nullable — If set, the signer is required to enter the password before they are able to sign a document. This field is write only. - `signer_group_id` string, nullable — If set, signers who have the same value will be assigned to the same input and to the same signer group. A signer group is not a Box Group. It is an entity that belongs to a Sign Request and can only be used/accessed within this Sign Request. A signer group is expected to have more than one signer. If the provided value is only used for one signer, this value will be ignored and request will be handled as it was intended for an individual signer. The value provided can be any string and only used to determine which signers belongs to same group. A successful response will provide a generated UUID value instead for signers in the same signer group. - `suppress_notifications` boolean, nullable — If true, no emails about the sign request will be sent. - `language` string, nullable — The language of the user, formatted in modified version of the [ISO 639-1](https://developer.box.com/guides/api-calls/language-codes) format. - `has_viewed_document` boolean — Set to `true` if the signer views the document. - `signer_decision` object, nullable — Final decision made by the signer. - `type` 'signed' | 'declined' — Type of decision made by the signer. - `finalized_at` string, date-time — Date and Time that the decision was made. - `additional_info` string, nullable — Additional info about the decision, such as the decline reason from the signer. - `inputs` SignRequestSignerInput[] - `document_tag_id` string, nullable — This references the ID of a specific tag contained in a file of the signature request. - `text_value` string, nullable — Text prefill value. - `checkbox_value` boolean, nullable — Checkbox prefill value. - `date_value` string, date, nullable — Date prefill value. - `type` 'signature' | 'date' | 'text' | 'checkbox' | 'radio' | 'dropdown' — Type of input. - `content_type` 'signature' | 'initial' | 'stamp' | 'date' | 'checkbox' | 'text' | 'full_name' | 'first_name' | 'last_name' | 'company' | 'title' | 'email' | 'attachment' | 'radio' | 'dropdown' — Content type of input. - `page_index` integer, required — Index of page that the input is on. - `read_only` boolean — Indicates whether this input is read-only (cannot be modified by signers). - `validation` union — Specifies the formatting rules that signers must follow for text field inputs. If set, this validation is mandatory. - union — Specifies the formatting rules that signers must follow for text field inputs. If set, this validation is mandatory. The format can be selected from a predefined list of options (e.g., email, phone number, date) or defined using a custom regular expression. - SignRequestSignerInputEmailValidation — Specifies the formatting rules that signers must follow for text field inputs. If set, this validation is mandatory. - … - SignRequestSignerInputCustomValidation — Specifies the custom validation rules for a text field input by the signer. If set, this validation is mandatory. - … - SignRequestSignerInputZIPValidation — Specifies the validation rules for a text field input by the signer. If set, this validation is mandatory. - … - SignRequestSignerInputZIP4Validation — Specifies the validation rules for a text field input by the signer. If set, this validation is mandatory. - … - SignRequestSignerInputSSNValidation — Specifies the validation rules for a text field input by the signer. If set, this validation is mandatory. - … - SignRequestSignerInputNumberWithPeriodValidation — Specifies the number with period formatting rules for a text field input by the signer. If set, this validation is mandatory. - … - SignRequestSignerInputNumberWithCommaValidation — Specifies the number with comma formatting rules for a text field input by the signer. If set, this validation is mandatory. - … - SignRequestSignerInputDateISOValidation — Specifies the ISO date formatting rules for a text field input by the signer. If set, this validation is mandatory. The date format follows `YYYY-MM-DD` pattern. - … - SignRequestSignerInputDateUSValidation — Specifies the US date formatting rules for a text field input by the signer. If set, this validation is mandatory. The date format follows `MM/DD/YYYY` pattern. - … - SignRequestSignerInputDateEUValidation — Specifies the date formatting rules used in Europe for a text field input by the signer. If set, this validation is mandatory. The date format follows `DD/MM/YYYY` pattern. - … - SignRequestSignerInputDateAsiaValidation — Specifies the date formatting rules used in Asia for a text field input by the signer. If set, this validation is mandatory. The date format follows `YYYY/MM/DD` pattern. - … - object, nullable — The definition for a null schema type in OpenAPI `3.0`. - `reason` string, nullable — The reason for the signer's input, applicable to signature or initial content types in a `cfr11` request flow. The value is `null` when not applicable. - `is_validated` boolean, nullable — Indicates whether the signer's input has been validated through re-authentication. Applicable only for signature or initial content types in a `cfr11` request flow. The value is `null` for standard request flows or non-applicable input types. - `embed_url` string, nullable — URL to direct a signer to for signing. - `iframeable_embed_url` string, nullable — This URL is specifically designed for signing documents within an HTML `iframe` tag. It will be returned in the response only if the `embed_url_external_user_id` parameter was passed in the `create Box Sign request` call. - `attachments` SignRequestSignerAttachment[], nullable — Attachments that the signer uploaded. - `id` string, nullable — Identifier of the attachment file. - `name` string, nullable — Display name of the attachment file. - `signature_color` string, nullable — Force a specific color for the signature (blue, black, or red). - `id` string — Box Sign request ID. - `prepare_url` string, nullable — This URL is returned if `is_document_preparation_needed` is set to `true` in the request. The parameter is used to prepare the signature request using the UI. The signature request is not sent until the preparation phase is complete. - `signing_log` object, nullable — Reference to a file that holds a log of all signer activity for the request. - `id` string, required — The unique identifier that represent a file. The ID for any file can be determined by visiting a file in the web application and copying the ID from the URL. For example, for the URL `https://*.app.box.com/files/123` the `file_id` is `123`. - `etag` string, nullable — The HTTP `etag` of this file. This can be used within some API endpoints in the `If-Match` and `If-None-Match` headers to only perform changes on the file if (no) changes have happened. - `type` 'file', required — The value will always be `file`. - `sequence_id` string — A numeric identifier that represents the most recent user event that has been applied to this item. This can be used in combination with the `GET /events`-endpoint to filter out user events that would have occurred before this identifier was read. An example would be where a Box Drive-like application would fetch an item via the API, and then listen to incoming user events for changes to the item. The application would ignore any user events where the `sequence_id` in the event is smaller than or equal to the `sequence_id` in the originally fetched resource. - `name` string — The name of the file. - `sha1` string, digest — The SHA1 hash of the file. This can be used to compare the contents of a file on Box with a local file. - `file_version` object — The information about the current version of the file. - `id` string, required — The unique identifier that represent a file version. - `type` 'file_version', required — The value will always be `file_version`. - `sha1` string — The SHA1 hash of this version of the file. - `status` 'converting' | 'created' | 'sent' | 'viewed' | 'signed' | 'cancelled' | 'declined' | 'error' | 'error_converting' | 'error_sending' | 'expired' | 'finalizing' | 'error_finalizing' — Describes the status of the signature request. - `sign_files` object — List of files that will be signed, which are copies of the original source files. A new version of these files are created as signers sign and can be downloaded at any point in the signing process. - `files` FileMini[] - `id` string, required — The unique identifier that represent a file. The ID for any file can be determined by visiting a file in the web application and copying the ID from the URL. For example, for the URL `https://*.app.box.com/files/123` the `file_id` is `123`. - `etag` string, nullable — The HTTP `etag` of this file. This can be used within some API endpoints in the `If-Match` and `If-None-Match` headers to only perform changes on the file if (no) changes have happened. - `type` 'file', required — The value will always be `file`. - `sequence_id` string — A numeric identifier that represents the most recent user event that has been applied to this item. This can be used in combination with the `GET /events`-endpoint to filter out user events that would have occurred before this identifier was read. An example would be where a Box Drive-like application would fetch an item via the API, and then listen to incoming user events for changes to the item. The application would ignore any user events where the `sequence_id` in the event is smaller than or equal to the `sequence_id` in the originally fetched resource. - `name` string — The name of the file. - `sha1` string, digest — The SHA1 hash of the file. This can be used to compare the contents of a file on Box with a local file. - `file_version` object — The information about the current version of the file. - `id` string, required — The unique identifier that represent a file version. - `type` 'file_version', required — The value will always be `file_version`. - `sha1` string — The SHA1 hash of this version of the file. - `is_ready_for_download` boolean — Indicates whether the `sign_files` documents are processing and the PDFs may be out of date. A change to any document requires processing on all `sign_files`. We recommended waiting until processing is finished (and this value is true) before downloading the PDFs. - `auto_expire_at` string, date-time, nullable — Uses `days_valid` to calculate the date and time, in GMT, the sign request will expire if unsigned. - `parent_folder` object — The destination folder to place final, signed document and signing log. When this value was not passed in when the signature request was created, then we will use a default folder which is either the parent folder of the first source file in the payload if we have the permission to upload to that folder or a folder called "My Sign Requests". - `id` string, required — The unique identifier that represent a folder. The ID for any folder can be determined by visiting a folder in the web application and copying the ID from the URL. For example, for the URL `https://*.app.box.com/folders/123` the `folder_id` is `123`. - `etag` string, nullable — The HTTP `etag` of this folder. This can be used within some API endpoints in the `If-Match` and `If-None-Match` headers to only perform changes on the folder if (no) changes have happened. - `type` 'folder', required — The value will always be `folder`. - `sequence_id` string — A numeric identifier that represents the most recent user event that has been applied to this item. This can be used in combination with the `GET /events`-endpoint to filter out user events that would have occurred before this identifier was read. An example would be where a Box Drive-like application would fetch an item via the API, and then listen to incoming user events for changes to the item. The application would ignore any user events where the `sequence_id` in the event is smaller than or equal to the `sequence_id` in the originally fetched resource. - `name` string — The name of the folder. - `collaborator_level` string, nullable — The collaborator level of the user to the sign request. Values can include "owner", "editor", and "viewer". - `short_id` string — Short identifier for the sign request. - `created_at` string, date-time — Timestamp marking when the sign request was created. - `finished_at` string, date-time, nullable — Timestamp indicating when all signing actions completed. - `error_code` string, nullable — When the sign request is in an error state, identifies the specific reason. Null when no error code applies. - `sender_email` string, nullable — The email address of the sender of the sign request. - `sender_id` integer, nullable — The user ID of the sender of the sign request. ## Other responses - `default` — An unexpected client error. --- [API](https://skmtc.net/box/apis/platform-api.md) · [All operations](https://skmtc.net/box/apis/platform-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/box/platform-api/revisions/ba8f087e1a4d/schema)