Add workflow recipients and auto place their fields¶

Add anchors tag to your document¶

For YumiSign to be able to auto place the fields on your document you need to add an anchor for each field on your original document. The anchors need to have a specific format. Anchors can also be the same color as the document background color. This way it will not be visible on the original document.

Anchor tag format¶

To be able to have a unique anchor format for YumiSign and to avoid adding fields just from document text, the anchor should have this format: yumisign_{field_type}_{recipient_tag} .

Field types¶

The field_type is case-sensitive, and must contain one of the following field types:

date
email
signature
initials
title
company
fullName
address

Recipient tags¶

The recipient tag, is a tag that you will attach to each recipient, to be able to know which anchor tag from the document is for which recipient. It can contain any string you want to give to identify your recipient.

For example, if you have a selling car contract, you can use seller and buyer tags, so when you add your recipients, you need to define the right tag for the right recipient in the field anchorTag

Best practices¶

For better results, you can define the documents and pages where you have added the anchors in your recipient anchorTag. For example if you have a document with 10 pages, and you have added the tags to the only last two pages, it is better to add the document id/page number to the tag when attaching it to the recipient. If the anchors where for both seller and buyer, the tags should have this format for example: seller-1_9,1_10 and buyer-1_9,1_10 where we have tag-documentId_pageNumber, documentId_pageNumber, etc.. You should make sure that you either define all the pages or do not define them at all. You cannot define some of the pages and expect YumiSign to define the other ones.

Route¶

You are going to use the same route as adding the recipients, just with passing anchorAutoPlace with value true, and add the anchorTag to the recipients.

Method	Path
PUT	/api/v1/workspaces/{workspaceId}/workflows/{workflowId}/roles

Warning

Add workflow recipients using /api/v1/workflows/{id}/roles is deprecated. You need to pass the workspace id on the path.

Parameters¶

anchorAutoPlace bool | optional

The flag that will determine if you want YumiSign to check the document for anchors and auto place fields.

recipients array | required

The list of recipients for your workflow. It must contain at least one item.

recipients[0].id string | optional

The optional recipient id to use in updating context.

recipients[0].name string | required

The recipient name.

recipients[0].email string | required

The recipient email address.

recipients[0].anchorTag string | optional

The anchor tag that you have added so YumiSign can link the anchor with this recipient.

recipients[0].roles array | required

An array of roles for your recipient.

recipients[0].roles[0].type enum | required

Value	Description
sign	A recipient must sign the document
review	A recipient must review the document

recipients[0].roles[0].color string | required

A hexadecimal color representing your recipient role.

Example¶

In this image you can see the format of the anchors that has been already added to the document.

In this image you cannot see the anchors, because their color is the same as the background, but they are still there.

In this picture you can see the result after auto placing the fields with YumiSign.

curl --request PUT 'https://app.yumisign.com/api/v1/workspaces/1/workflows/1/roles' \
    --header 'Content-Type: application/json' \
    --data-raw '{
        "anchorAutoPlace": true,
        "recipients": [
            {
                "name": "Johnny Depp",
                "email": "recipient1@email.com",
                "anchorTag": "seller"
                "roles": [
                    {
                        "id":1,
                        "type": "sign",
                        "color": "#EE8320"
                    }
                ]
            },
            {
                "name": "Amber Heard",
                "email": "recipient2@email.com",
                "anchorTag": "buyer"
                "roles": [
                    {
                        "id":1,
                        "type": "sign",
                        "color": "#EE8320"
                    }
                ]
            }
        ]
    }'

[
    {
        "picture": null,
        "roles": [
            {
                "type": "sign",
                "color": "#EE8320",
                "id": 24
            }
        ],
        "email": "recipient1@email.com",
        "id": 24,
        "name": "Johnny Depp"
    },
    {
        "picture": null,
        "roles": [
            {
                "type": "sign",
                "color": "#EE8320",
                "id": 25
            }
        ],
        "email": "recipient2@email.com",
        "id": 25,
        "name": "Amber Heard"
    }
]