Why is my envelope created from a template via API remaining in "created" status instead of being sent?

Hi DocuSign Community,

I'm having trouble sending an envelope via the DocuSign API using a template. I have verified that my template is set up correctly (it works as expected when I create and send an envelope manually from the console). However, when I create an envelope using the API, the envelope is created with a status of "created" (i.e., a draft) rather than "sent".

Here’s my setup:

• Template Details:

  • Template ID: templateId
  • The template contains two recipient roles: one with the role name "provider" and one with "site".
  • The template has required fields and signature tabs already configured.
• Envelope Definition (API Payload):

  const envelopeDefinition = {
      templateId: 'templateId',
      templateRoles: [
          {
              email: 'provider@ajay.com',
              name: 'Ajay Parashar',
              recipientId: '1',
              routingOrder: '1',
              roleName: 'provider'  // matches template role (case-sensitive)
          },
          {
              email: 'site1@ajay.com',
              name: 'Sample Hospital',
              recipientId: '2',
              routingOrder: '2',
              roleName: 'site'  // matches template role (case-sensitive)
          }
      ],
      status: 'sent'
  };
  

   

• API Call: 

  const envelopesApi = new docusign.EnvelopesApi(apiClient);
  const resultsEnvelope = await envelopesApi.createEnvelope(ACCOUNT_ID, envelopeDefinition);
  console.log('Envelope Result:', resultsEnvelope);
  

• The API response returns an envelope with: 

  {
    "envelopeId": "some-id",
    "status": "created",
    "statusDateTime": "2025-02-03T05:20:07.4970000Z",
    "uri": "/envelopes/some-id"
  }
  

   

• What I've Checked:

  • Role Names: I’ve confirmed that the role names in the API payload ("provider" and "site") exactly match those in the template.

  • Template Validity: I can successfully create and send the envelope manually from the DocuSign console using the same template.

  • Envelope Completeness: I verified that all required fields are present in the template.

  • Base URL and Account ID: I'm using the correct environment (demo) and the correct account ID as retrieved from the user info.

• Questions:

  • What could cause the envelope to remain in "created" (draft) status even when I explicitly set "status": "sent" in my API call?

  • Are there any additional checks or required fields/tabs that might prevent the envelope from being sent immediately when using a template?

  • Should I update the envelope status manually using the updateEnvelope API if all required data is present, or is there a better approach to ensure the envelope is sent right away?

  • Any help or guidance on diagnosing this issue would be greatly appreciated. Thanks in advance!