Why does the Send Document API return a document ID, but the document is not created?

If the Send Document API returns a document ID, but the document does not appear in BoldSign, the request may have failed validation after it was accepted for processing.
 
A 201 Created response indicates that BoldSign accepted the request for processing. Before creating the document, BoldSign validates the document configuration, recipients, and form fields.

Important notes

To identify processing or validation failures, subscribe to the SendFailed webhook event and review the error details included in the webhook payload.
 
If document creation fails after the request is accepted:

• The document does not appear in the dashboard.
• The document is not available through document APIs.
• Document-level operations may return errors such as Forbidden or Invalid Document ID.
• A SendFailed webhook event is generated with error details.

How document processing works?

The Send Document API processes requests asynchronously.

If validation succeeds

• The document is created.
• The document appears in the dashboard.
• Signature requests are sent to recipients.
• A Sent event is generated.

If validation fails

• The document is not created.
• The document does not appear in the dashboard.
• Signature requests are not sent.
• A SendFailed event is generated.

How do I identify the validation error?

Step 1: Review SendFailed webhook events

1. Configure an account-level webhook.
2. Subscribe to the SendFailed event.
3. Review the webhook payload when the event is received.

The webhook payload contains information about the validation or processing error that prevented the document from being created.

For more information, refer to:

• Account-level webhooks
• Available webhook events
• Sample webhook event data

Step 2: Review the request configuration
 
Verify that:

• Required recipient information is provided.
• Recipient email addresses are valid.
• Required form fields are configured correctly.
• Fields are assigned to the correct recipients.
• Recipient roles and signing order settings are configured correctly.
• Document settings contain valid values.

Common validation errors

Document creation can fail after the request is accepted if the request contains invalid or unsupported configuration values.
 
Examples include:

• Invalid recipient information.
• Incorrect field assignments.
• Unsupported field configurations.
• Invalid document settings.
• Using field properties that are not supported by a specific field type.

For example, placeholders are supported only for Text Box fields. Using a placeholder with another field type can cause document validation to fail and prevent the document from being created.

Resolution

1. Review the SendFailed webhook event details.
2. Correct the validation or configuration error identified in the webhook payload.
3. Submit the document request again.

Once the request passes validation:

• The document is created successfully.
• The document appears in the dashboard.
• Document API operations work as expected.
• The signing process begins normally.

After correcting the validation error and resubmitting the request, the document is created successfully, appears in the dashboard, and can be accessed through document APIs. The SendFailed webhook event helps identify issues that occur after the request has been accepted for processing.