DocuSign EnvelopesApi::CreateRecipient API call does not create tabs

Question

i'm trying to update an existing and not completed Docusign envelope and add a new signer to the document inside. For this purpose i'm using the PHP SDK with EnvelopesApi::createRecipient method, framework is CodeIgniter btw. The API call successfully creates the recipient (I can check it in the DocuSign admin panel), but the signature I supplied with a new SignHere tab is not added to the document. I tried making the call via Postman directly but same issue.

I double-checked the supplied ids (clientUserId, recipientId, documentId) and they are ok, same for the SignHere anchor string which is auto placed.

Sample code :

public function testAddRecipient(Contrat $contrat) {
            $CI = & get_instance();
            $envelopeApi = $this->createEnveloppeApi($CI);      # returns the EnvelopesApi object
            $signer = $this->createSigner($contrat, "test@hotmail.com", 3); # returns a new Signer object with a SignHere tab
            $recipients = new Recipients();
            $recipients->setSigners([$signer]);
            $response = $envelopeApi->createRecipient($this->config['ds_account_id'], $contrat->getDsEnvelopeId(), $recipients);
            var_dump($response);
            exit;
        }

Create signer method, returning the Signer object with his SignHere tab :

public function createSigner($contrat, $recipient, $routingOrder) {
        // # Create the signer recipient model
        $signer = new Signer([# The signer
            'email' => $recipient,
            'name' => $recipient,
            'recipient_id' => $this->getRecipientId($contrat, $recipient),  # This method returns an unique id based on supplied email
            'routing_order' => $routingOrder,
            # Setting the client_user_id marks the signer as embedded
            'client_user_id' => $this->getRecipientId($contrat, $recipient)
        ]);


        // # Create a sign_here tab (field on the document)
        $roles = $contrat->getProfilsUtilisateurByMail($recipient);     #Returns a list of roles (a signer may sign several times)
        $signHereArray = [];
        foreach ($roles as $role) {
            $signHere = new SignHere([
                'document_id' => $contrat->getId(),
                'recipient_id' => $this->getRecipientId($contrat, $recipient),
                'tab_id' => 'sign_' . $role,
                'tab_label' => 'Signer Ici',
                'anchor_string' => '**sign-' . $role . '**',
                'anchor_units' => 'pixels',
                'anchor_x_offset' => '10',
                'anchor_y_offset' => '25',
                'anchor_ignore_if_not_present' => 'false',
            ]);

            $signHereArray[] = $signHere;
        }

        $signer->setTabs(new Tabs(['sign_here_tabs' => $signHereArray]));
        return $signer;
    }

JSON body posted to the API endpoint :

{
    "signers": [
        {
            "clientUserId": 15,
            "email": "test@hotmail.com",
            "name": "test@hotmail.com",
            "recipientId": 15,
            "routingOrder": 3,
            "tabs": {
                "signHereTabs": [
                    {
                        "anchorIgnoreIfNotPresent": "false",
                        "anchorString": "**sign-souscripteur**",
                        "anchorUnits": "pixels",
                        "anchorXOffset": "10",
                        "anchorYOffset": "25",
                        "documentId": 156,
                        "recipientId": 15,
                        "tabId": "sign_souscripteur",
                        "tabLabel": "Signer Ici"
                    }
                ]
            }
        }
    ]
}

API response :

{
    "signers": [
        {
            "creationReason": "sender",
            "requireUploadSignature": "false",
            "name": "test@hotmail.com",
            "email": "test@hotmail.com",
            "recipientId": "15",
            "requireIdLookup": "false",
            "routingOrder": "3",
            "status": "created",
            "completedCount": "0",
            "deliveryMethod": "email",
            "recipientType": "signer"
        }
    ],
    "agents": [],
    "editors": [],
    "intermediaries": [],
    "carbonCopies": [],
    "certifiedDeliveries": [],
    "inPersonSigners": [],
    "seals": [],
    "witnesses": [],
    "recipientCount": "1"
}

No error in response, what am I doing wrong ?

I also tried other SDK method like EnvelopesApi::updateRecipients, EnvelopesApi::updateTabs or EnvelopesApi::updateDocumentTabs with no more success

Update Thanks to Inbar Gazit's response down below, correct endpoint is

/restapi/v2.1/accounts/{accountId}/envelopes/{envelopeId}/recipients/{recipientId}/tabs

which is called via these methods in SDK : EnvelopesApi::createTabsWithHttpInfo, EnvelopesApi::updateTabsWithHttpInfo etc.

Answer 1

It looks like your request is using an anchor string to place the sign here tab:

Anchor string -> '**sign-' . $role . '**'

When you use an anchor string DocuSign will go through the text in your document and it will place a tab every time it finds an instance of the anchor string. If your document does not contains that string no tabs will be created.

You could debug the issue this way:

• Create a regular envelope manually via the DocuSign website
• Upload the same document you are using on your API call
• Add a recipient
• Go to the tagging page and add a sign here tab
• Edit the properties in the sign here tab to include and anchor string. When you are editing the tab, the anchor string value corresponds to the Location->Auto Place property of the tab in the UI
• Check if the tab was added to the document in the places where the anchor string is found

That should help you figure out if the anchor text exists in that document.

If you just want to use a regular sign here tab in a fixed position, just specify the documentId, pageNumber, and X/Y coordinates and that should work.

-Yadriel

Answer 2

I'm sorry this is harder than it should be. The correct end point is [UpdateRecipientTabs][1] It's a PUT call that looks like this

PUT
/restapi/v2.1/accounts/{accountId}/envelopes/{envelopeId}/recipients/{recipientId}/tabs
{
  "signHereTabs": [
    {
.. // fill this out
}]}