docusign.envelopes.put-status

Retrieves envelope statuses for a set of envelopes. Envelopes: listStatus has both a GET and a PUT implementation: * PUT /restapi/v2.1/accounts/{accountId}/envelopes/status is passed a set of envelope IDs in the request body. This version of the method returns a smaller subset of envelope information. * GET /restapi/v2.1/accounts/{accountId}/envelopes/status is passed a list of envelope IDs in a query string. <ds-inlinemessage> To search for envelopes using a broad range of filters, use <a href="/docs/esign-rest-api/reference/envelopes/envelopes/liststatuschanges/">Envelopes: listStatusChanges</a> instead of this method. </ds-inlinemessage> You must specify exactly one of the following query parameters: | Parameter | Description | | :---------------- | :------------------------------------------------------------------------------- | | from_date | a valid UTC DateTime: 2016-01-01 | | envelope_ids | <ul><li>For the <code>GET</code> implementation of this method, include the envelope IDs in a comma-separated list. </li><li>For the <code>PUT</code> version of this method, you should use the <code>request_body</code> value for this parameter and include the list of envelope IDs in the request body.</li></ul> | | transaction_ids | A comma-separated list of transaction IDs<br>or the special value <code>request_body</code> | When you use the special value request_body, the request body looks like this: { "envelopeIds": [ "44c5ad6c-xxxx-xxxx-xxxx-ebda5e2dfe15", "8e26040d-xxxx-xxxx-xxxx-1e29b924d237", "c8b40a2d-xxxx-xxxx-xxxx-4fe56fe10f95" ] } <ds-inlinemessage kind="warning"> Omitting the request body altogether causes the endpoint to return an error. The request body must be at least <code>{}</code>. </ds-inlinemessage> ### Related topics - Searching for envelopes - How to list envelope status changes

Gets envelope statuses for a set of envelopes.

Overview

Property	Value
Workflow type	Atomic
Library	App-docusign
Version	1.0

Input Schema

Field	Type	Required	Default	Description
base_url	string	Yes	—	Docusign API root, e.g. https://<host>/api
api_token	string	No	—	Bearer token; omit to use the workflow's token env var
accountid	string	Yes	—	The external account number (int) or account ID GUID.
ac_status	string	No	—	Specifies the Authoritative Copy Status for the envelopes. Valid values: - Unknown - Original - Transferred - AuthoritativeCopy - AuthoritativeCopyExportPending - AuthoritativeCopyExported - DepositPending - Deposited - DepositedEO - DepositFailed
block	string	No	—	When true, removes any results that match one of the provided transaction_ids.
count	string	No	—	The maximum number of results to return. Use start_position to specify the number of results to skip.
email	string	No	—	The email address of the sender.
envelope_ids	string	No	—	The envelope IDs to include in the results. The value of this property can be: * For the GET implementation of this method, use a comma-separated list of envelope IDs. * For the PUT implementation of this method, use the request_body value, and include the envelope IDs in the request body.
from_date	string	No	—	The date/time setting that specifies when the request begins checking for status changes for envelopes in the account. This is required unless parameters envelope_ids and/or transaction_Ids are provided. Note: This parameter must be set to a valid DateTime, or envelope_ids and/or transaction_ids must be specified.
from_to_status	string	No	—	The envelope status that you are checking for. Possible values are: - Changed (default) - Completed - Created - Declined - Deleted - Delivered - Processing - Sent - Signed - TimedOut - Voided For example, if you specify Changed, this method returns a list of envelopes that changed status during the from_date to to_date time period.
start_position	string	No	—	The zero-based index of the result from which to start returning results. Use with count to limit the number of results. The default value is 0.
status	string	No	—	A comma-separated list of envelope status to search for. Possible values are: - completed - created - declined - deleted - delivered - processing - sent - signed - template - voided
to_date	string	No	—	Optional date/time setting that specifies the last date/time or envelope status changes in the result set. The default value is the time that you call the method.
transaction_ids	string	No	—	The transaction IDs to include in the results. Note that transaction IDs are valid for seven days. The value of this property can be: - A list of comma-separated transaction IDs - The special value request_body. In this case, this method uses the transaction IDs in the request body.
user_name	string	No	—	Limits results to envelopes sent by the account user with this user name. email must be given as well, and both email and user_name must refer to an existing account user.
envelopeids	list	No	—	A comma-separated list of envelope IDs to include in the results.
transactionids	list	No	—	A comma-separated list of transaction IDs to include in the results. Note that transaction IDs are valid for seven days.

Output Schema

Field	Type	Required	Default	Description
base_url	string	Yes	—	Docusign API root, e.g. https://<host>/api
api_token	string	No	—	Bearer token; omit to use the workflow's token env var
accountid	string	Yes	—	The external account number (int) or account ID GUID.
ac_status	string	No	—	Specifies the Authoritative Copy Status for the envelopes. Valid values: - Unknown - Original - Transferred - AuthoritativeCopy - AuthoritativeCopyExportPending - AuthoritativeCopyExported - DepositPending - Deposited - DepositedEO - DepositFailed
block	string	No	—	When true, removes any results that match one of the provided transaction_ids.
count	string	No	—	The maximum number of results to return. Use start_position to specify the number of results to skip.
email	string	No	—	The email address of the sender.
envelope_ids	string	No	—	The envelope IDs to include in the results. The value of this property can be: * For the GET implementation of this method, use a comma-separated list of envelope IDs. * For the PUT implementation of this method, use the request_body value, and include the envelope IDs in the request body.
from_date	string	No	—	The date/time setting that specifies when the request begins checking for status changes for envelopes in the account. This is required unless parameters envelope_ids and/or transaction_Ids are provided. Note: This parameter must be set to a valid DateTime, or envelope_ids and/or transaction_ids must be specified.
from_to_status	string	No	—	The envelope status that you are checking for. Possible values are: - Changed (default) - Completed - Created - Declined - Deleted - Delivered - Processing - Sent - Signed - TimedOut - Voided For example, if you specify Changed, this method returns a list of envelopes that changed status during the from_date to to_date time period.
start_position	string	No	—	The zero-based index of the result from which to start returning results. Use with count to limit the number of results. The default value is 0.
status	string	No	—	A comma-separated list of envelope status to search for. Possible values are: - completed - created - declined - deleted - delivered - processing - sent - signed - template - voided
to_date	string	No	—	Optional date/time setting that specifies the last date/time or envelope status changes in the result set. The default value is the time that you call the method.
transaction_ids	string	No	—	The transaction IDs to include in the results. Note that transaction IDs are valid for seven days. The value of this property can be: - A list of comma-separated transaction IDs - The special value request_body. In this case, this method uses the transaction IDs in the request body.
user_name	string	No	—	Limits results to envelopes sent by the account user with this user name. email must be given as well, and both email and user_name must refer to an existing account user.
envelopeids	list	No	—	A comma-separated list of envelope IDs to include in the results.
transactionids	list	No	—	A comma-separated list of transaction IDs to include in the results. Note that transaction IDs are valid for seven days.
status_code	integer	No	—	HTTP status code of the completed call
response	json	No	—	Parsed JSON response body
failure_reason	string	No	—	—
failure_type	string	No	—	—
failed_at	string	No	—	—
failed_step	string	No	—	—
failed_layer	string	No	—	—
failed_at_state	string	No	—	—
error	string	No	—	—
error_type	string	No	—	—

States

State	Initial	Terminal	Success	Auto-advance	Description
pending	Yes	No	—	execute	Waiting to call PUT /v2.1/accounts/{accountId}/envelopes/status
completed	No	Yes	Yes	—	HTTP call succeeded
failed	No	Yes	No	—	HTTP call failed

State Diagram

Transitions

From	Action	To	Description
pending	execute	completed	Perform PUT /v2.1/accounts/{accountId}/envelopes/status
* (any state)	fail	failed	Record the failure reason

API Usage

POST /api/workflows/start
Content-Type: application/json

{
  "workflow_type": "docusign.envelopes.put-status",
  "initial_data": {
    "base_url": "value",
    "accountid": "value"
  }
}