From the Trenches: Troubleshooting INVALID_REQUEST_PARAMETER errors in the eSignature REST API

One of the most common errors when using the eSignature REST API is the INVALID_REQUEST_PARAMETER. That error has various causes, although the error message describes precisely the cause of the issue. Let's see some examples below.

{
    "errorCode": "INVALID_REQUEST_PARAMETER",
    "message": "The request contained at least one invalid parameter. Captive Recipients not supported with WhatsApp Delivery."
}

The error message describes an issue involving the WhatsApp delivery feature, which seems incompatible with embedded recipients. When you choose WhatsApp delivery, Docusign sends notifications to the messaging app that links the recipient directly to the agreement to be signed. With embedded recipients, the signers use your application and the embedded signing link to sign from within your application. No signing notification is sent by Docusign in this case, which is why WhatsApp delivery and embedded recipients are incompatible in this scenario. Now, let's see the API request that caused the issue.

{
    "emailSubject": "Please sign this document set",
    "documents": [
        {
            "documentBase64": "{document_base64}",
            "name": "Document Name",
            "fileExtension": "txt",
            "documentId": "1"
        }
    ],
    "recipients": {
        "signers": [
            {
                "email": "recipient01@domain.com",
                "name": "Signer 01",
                "recipientId": "1",
                "routingOrder": "1",
                "clientUserId": 1000,
                "deliveryMethod": "WhatsApp",
                "phoneNumber":
                {
                    "countryCode": "1",
                    "number":"0056781234"
                },
                "tabs": {
                    "signHereTabs": [
                        {
                            "anchorString": "/SignHere01/"
                        }
                    ]
                }
            }
        ]
    },
    "status": "sent"
}

The clientUserId automatically specifies the signer as captive (embedded). Furthermore, the deliveryMethod property is set to WhatsApp.

Docusign can return INVALID_REQUEST_PARAMETER for other reasons as well:

• Passing null as the value for a mandatory parameter, such as the envelope ID in the envelope creation.

• The integration sends a request to the endpoint with no query parameters as required. That can happen, for example, on GET Envelopes:listStatusChanges, where your request must include one or more of the following parameters: from_date, envelope_ids, or transaction_ids.

• Failing to supply the URL correctly can also throw an error. Example: not supplying the accountId in the API URL endpoint.

• Incorrect ID format. The Docusign IDs (envelopes, accounts, users, etc.) are globally unique identifiers (GUIDs) using the following format: 7e5bd754-357b-4f7b-b368-3ec2fc280b56. You can get the INVALID_REQUEST_PARAMETER when using IDs in the wrong format.

• Incorrect value format. Each parameter has its correct value format. For example, if you are working on positioning the tabs using the yPosition and xPosition parameters, the values must be in integer format, not a fractional number. All the value formats may be found in our API Reference.

As you can see, knowing what is being sent in the request body is fundamental to troubleshooting the issue. The best way to do that is to get the API logging on the admin account and follow the path described in this article to identify and solve the issue.

If you have any questions about your development,  we recommend you join the Docusign Developer Community for support.

Additional resources

• From the Trenches: Find your REST request using Docusign API logs

• From the Trenches: How to use API logs

• Docusign Developer Center

• Docusign Developers Community

• @DocusignDevs on X

• Docusign for Developers on LinkedIn

• Docusign for Developers on YouTube

• Docusign Developer Newsletter