Overview

The Label resource designates a categorization tag that can be attached to a Signature Request. Labels make it easier to organize, filter, and find Signature Requests both in your Yousign app and via the API.

Labels are often named based on criteria that match your internal processes, such as document type, department, or project name.

Examples of labels include: "Contract", "Invoice", "HR team", "Legal documents", etc.

Using the API, you can:

• Add Labels to a Signature Request
• Filter Signature Requests on Label name
• Manage your organization’s Labels list

You can manage Labels from the app as well, see this article for more details.

Add Labels to a Signature Request

You can add and remove Labels from a Signature Request using the following methods:

1 - Adding or Removing Multiple Labels at Once

To add or remove multiple Labels in a single Signature Request, provide a list of Label IDs in the request body when calling these endpoints:

• Initiate a Signature Request - POST /signature_requests
• Update a Signature Request - PATCH /signature_requests/{signatureRequestId}

{
    "name": "My Signature Request",
    "delivery_mode": "email",
    "labels":[
      "55455ca2-6b36-41a8-b60c...",
      "87df727f-9708-4839-9e14..."
    ]
}

{
    "labels": [
      "55455ca2-6b36-41a8-b60c...",
      "87df727f-9708-4839-9e14..."
    ]
}

2 - Managing Labels Individually

If you need to add or remove Labels one at a time, use these dedicated endpoints:

• Associate a Label with a Signature Request - PUT /signature_requests/{signatureRequestId}/labels/{labelId}
• Remove Label from a Signature Request - DELETE /signature_requests/{signatureRequestId}/labels/{labelId}

You can update the list of Labels on a Signature Request at any time, regardless of its status.

🚧

Limits

You can add up to 50 Labels to a Signature Request.

Retrieve the Label ID

You can retrieve the ID of a specific Label from the app. Go to the Signature Settings, then click Manage Labels. Select the Label of your choice, and Copy labelID.

You can also get the list of Labels in your organization with dedicated API endpoints (see section below).

Retrieve the list of Labels associated with a given Signature Request

You can use the following endpoint to retrieve the list of Labels associated with a given Signature Request:

• List Labels of a Signature Request - GET /signature_requests/{signatureRequestId}/labels

Filter Signature Requests on Label name

You can filter Signature Requests according to their Labels name in the List Signature Requests endpoint (GET /signature_requests).

• label.name[eq]=<name>
• label.name[in]=<name1>,<name2>,…

Manage your organization’s Labels list

You can retrieve, create, update and delete Labels with the following endpoints:

• Create a new Label - POST /labels
  You must give it a name , and each Label name must be unique within your organization.
• Update a Label - PATCH /labels/{labelId}
• Delete a Label - DELETE /labels/{labelId}
  Deleting a Label will remove the Label from all Signature Requests it is associated with.
• List Labels - GET /labels
  You can filter Labels on names, using the following filter: name[eq]=<name>
• Get a Label - GET /labels/{labelId}

🚧

Limits

You can create up to 1000 Labels within your organization.