Refresh instance token | Docusign

{
  "id": "00000000-0000-0000-0000-000000000000",
  "formUrl": "https://webforms-ux/v1.0/forms/82356c8f286b4e4df592af7d0984f51d",
  "instanceToken": "string",
  "tokenExpirationDateTime": "2024-01-15T09:30:00Z",
  "formId": "00000000-0000-0000-0000-000000000000",
  "accountId": "00000000-0000-0000-0000-000000000000",
  "clientUserId": "customer_id@domain.com",
  "tags": [
    "loan_application",
    "finance_dept"
  ],
  "status": "INITIATED",
  "envelopes": [
    {
      "id": "00000000-0000-0000-0000-000000000000",
      "createdDateTime": "2024-01-15T09:30:00Z"
    }
  ],
  "instanceMetadata": {
    "expirationDateTime": "2023-08-16T10:30:00Z",
    "createdDateTime": "2023-08-15T10:30:00Z",
    "createdBy": {
      "userId": "00000000-0000-0000-0000-000000000000",
      "userName": "DocuSign User"
    },
    "lastModifiedDateTime": "2023-08-15T20:30:00Z",
    "lastModifiedBy": {
      "userId": "00000000-0000-0000-0000-000000000000",
      "userName": "DocuSign User"
    }
  },
  "formValues": {
    "Checkbox_hobbies": [
      "singing",
      "dancing"
    ],
    "Date_birth": "2020-01-01",
    "Email_primary": "example@example.com",
    "ID_card_attachment": {
      "documentName": "id_card.pdf"
    },
    "Number_age": 52,
    "Radio_Gender": "Female",
    "Select_state": "California",
    "Textbox_Name": "First Last"
  },
  "brandId": "00000000-0000-0000-0000-000000000000",
  "recipients": [
    {
      "recipientViewId": "00000000-0000-0000-0000-000000000000",
      "instanceRecipientStatus": "SUBMITTED",
      "roleName": "Applicant"
    }
  ]
}

The Web Forms API is available in all developer accounts, but only in certain production account plans. Contact Docusign Support or your account manager to find out whether the Web Forms API is available for your production account plan.

Generates a new instance token for an existing web form instance. Tokens expire after five minutes.

Required authentication scopes: signature, webforms_instance_write.

Authentication

AuthorizationBearer

Bearer authentication of the form Bearer <token>, where token is your auth token.

Path parameters

accountIdstringRequiredformat: "uuid"

The ID of the account to which the web form belongs.

formIdstringRequiredformat: "uuid"

The ID of the web form configuration.

instanceIdstringRequiredformat: "uuid"

The ID of the form instance.

Response

Web Form Instance with new instance token and metadata

idstringformat: "uuid"

Unique identifier for a webform instance that is consistent until its expiration

formUrlstringOptional

The instance url which can be rendered by the user

instanceTokenstringOptional

Unique token associated with an instance that is required to render the form instance. This token is valid for 5 minutes after which it needs to be refreshed using refreshToken api

tokenExpirationDateTimedatetimeOptional

The DateTime after which the token is expired and form instance is inaccessible.

formIdstringOptionalformat: "uuid"

Unique identifier for a webform entity that is consistent for it's lifetime

accountIdstringOptionalformat: "uuid"

Account identifier in which the webform resides

clientUserIdstringOptional<=100 characters

A unique identifier for a user that should originate from client's system. This value can be anything your backend system would use to track individual form instances. Examples include employee IDs, email addresses, surrogate key values, etc.

tagslist of stringsOptional

Metadata to help your application identify the web form instance.

Example: ["Client A", "Agreement Category B"]

statusenumOptional

The status of the form instance

Allowed values:

envelopeslist of objectsOptional

This object represents the eSignature envelope that is associated with the web form instance. An instance has an associated envelope if any of the following is true:

The instance was created from a template-based web form configuration, was displayed to the user in an embedded view, and the user submitted the instance, which resulted in the generation of an envelope.
The instance was created from a template-based web form configuration, was displayed to the user via a redirect to the Docusign platform, and the user submitted the instance, which resulted in the generation of an envelope.
The instance was created from a template-based web form configuration, and the Instances:createInstance request specified a remote web form instance. For this flow, an envelope is generated when the instance is created.

Web form instances generated from standalone configurations do not have envelopes associated with them.

instanceMetadataobjectOptional

Metadata associated with the web form instance.

formValuesmap from strings to anyOptional

Key-value pairs that represent the current values of the fields in the web form instance. The keys correspond to the componentName values of the formContent.components object on the WebForm (configuration) object. See Form field definitions for more information.

See Request that retrieves web form instance values for an example of a formValues object returned by this request.

brandIdstringOptionalformat: "uuid"

Brand Id for web form

recipientslist of objectsOptional

This object contains information about the users who fill out a web form instance and its associated envelope.

If the web form template has roles that do not fill out the web form instance, this object does not include users associated with those roles.

Errors

400

Bad Request Error

401

Unauthorized Error

403

Forbidden Error

404

Not Found Error

500

Internal Server Error

503

Service Unavailable Error