DocuSign TAB_REFERS_TO_MISSING_DOCUMENT but document is attached (REST API) - docusignapi

Question

I'm using the DocuSign REST API to create an envelope from a template. My code works with single document templates or templates with multiple documents where only one document has tabs. If there are tabs on both documents I receive a 400 response with error code TAB_REFERS_TO_MISSING_DOCUMENT.
The response I receive is:
{
"error": "invalid HTTP response",
"message": {
"errorCode": "TAB_REFERS_TO_MISSING_DOCUMENT",
"message": "The DocumentId specified in the tab element does not refer to a document in this envelope. Tab refers to DocumentId 45159457 which is not present."
},
"status": 400,
"url": "https://demo.docusign.net/restapi/v2/accounts/2826983/envelopes/"
}
My request is as follows:
{
"status": "sent",
"templateId": "bb283bfb-4049-431d-942a-9a485e4ebb41",
"emailSubject": "[[Signer UserName]], please sign this document",
"documents": [
{
"documentId": "27069418",
"documentBase64": "...",
"name": "name.pdf"
},
{
"documentId": "45159457",
"documentBase64": "...",
"name": "secondName.pdf"
}
]
}
From what I've seen people receive this request when they submit invalid documentId's like 1 but the document that's "missing" is clearly attached. Am I missing something?
The final and working JSON request looks like so:
{
"status": "sent",
"emailSubject": "...",
"compositeTemplates": [{
"serverTemplates": [{
"sequence": 2,
"templateId": "..."
}],
"inlineTemplates": [{
"sequence": 1,
"documents": [{
"documentId": "...",
"name": "...",
"documentBase64": "..."
}, {
"documentId": "...",
"name": "...",
"documentBase64": "..."
}]
}]
}]
}

Answer 1

You can overcome the error using composite Templates. Specifying the new documents in an inlineTemplate with lower sequence number("sequence": "1") will ensure the inlineTemplate documents will replace the server template documents.
Here is a sample CreateEnvelope request.
{
"emailSubject": "[[Signer UserName]], please sign this document",
"status": "sent",
"compositeTemplates": [
{
"inlineTemplates": [
{
"sequence": "1",
"documents": [
{
"documentId": "27069418",
"name": "name.pdf",
"documentBase64": ""
},
{
"documentId": "45159457",
"name": "secondName.pdf",
"documentBase64": ""
}
]
}
],
"serverTemplates": [
{
"sequence": "2",
"templateId": "bb283bfb-4049-431d-942a-9a485e4ebb41"
}
]
}
]
}

Answer 2

To replace the document(s) in a template you must use composite templates instructions in your Envelopes: create call.
In your use case, you want to composite together the template and then a new document "in front" of the existing document in the template.
"Compositing templates" is like compositing together multiple pieces of film to produce a final print.