Envelope attachments - confusing documentation and unexpected behavior

Thank you for your feedback.

Our API reference has information on our fileds and attributes.

See section Schema

https://developers.docusign.com/docs/esign-rest-api/reference/envelopes/envelopes/create/

Regards

Adrian

Dev Support

Hello
Answer does not come from me, but if you could check this :

 

It sounds like you're experiencing some challenges with the envelope creation endpoint and its associated schema in DocuSign. Let me address each of your questions and concerns in detail:

### 1. Envelope Attachment at Creation Time

**Issue:**
Adding an attachment during envelope creation does not work as expected.

**Explanation:**
This might not be a bug but a limitation or expected behavior in the current API implementation. The documentation may mention the possibility of adding attachments at the envelope creation stage, but the actual functionality could be constrained by the system's processing order. 

**Workaround:**
The recommended approach, as you've found, is to first create the envelope and then add the attachment using the `envelope attachments create` endpoint.

### 2. AttachmentId Behavior

**Issue:**
The `AttachmentId` provided at creation changes when queried.

**Explanation:**
The `AttachmentId` you provide is likely intended as a client-side reference, whereas the system generates its own unique identifier for the attachment for internal tracking. This is common in many APIs to ensure the uniqueness and integrity of resource identifiers.

**Clarification:**
While the documentation should clarify this, it's not uncommon for APIs to accept a client-provided ID for reference but ultimately replace it with a system-generated one.

More info : 

AttachmentId:

• When creating an attachment, the provided AttachmentId is not retained. Instead, a unique AttachmentId is generated by the system to ensure uniqueness and avoid conflicts. This behavior ensures that each attachment can be uniquely identified even if multiple attachments are created with similar input properties

### 3. Label Field

**Issue:**
The behavior and purpose of the `Label` field are unclear.

**Explanation:**
The `Label` field is intended to categorize or tag the attachment. The mention of `eventNotifications` seems to be a documentation error or miscommunication. Typically, a label is a simple string used for categorization and does not directly influence downstream behavior.

**Suggestion:**
Use the `Label` field for your internal categorization needs. If the field accepts any string, it can help you organize attachments but does not trigger any specific system actions.

### 4. AttachmentType Field

**Issue:**
The `AttachmentType` field lacks clear documentation.

**Explanation:**
The `AttachmentType` field is likely intended for clients to specify the type of attachment for their reference. Since it accepts any value without validation, it suggests that this field is used more for informational purposes rather than driving any backend logic.

**Clarification:**
This field allows consumers of the API to identify or classify attachments based on their own criteria. It helps in understanding how to process or decode the attachment content.

### 5. Access Control Default Value

**Feedback:**
The default value for access control is `Sender`.

**Suggestion:**
It's good to have this feedback documented. Knowing the default values helps in planning and setting appropriate values explicitly if needed.

### 6. Attachment Data in Connect Event

**Issue:**
Attachment data is not returned in the connect event.

**Explanation:**
This is likely intended behavior. Due to potential size and performance implications, only the `AttachmentId` is included in the connect event. The actual data may need to be retrieved separately using the `AttachmentId`.

**Solution:**
After receiving the connect event, you can make an API call to retrieve the attachment data using the `AttachmentId` provided in the event.

**Example:**
Python

attachment_data = docusign_client.get_attachment(envelope_id, attachment_id)

```

### Summary

- **Envelope Creation:** Add attachments after creating the envelope.
- **AttachmentId:** System-generated IDs ensure uniqueness.
- **Label:** Use for internal categorization.
- **AttachmentType:** Informational field for client-side use.
- **Access Control:** Default is `Sender`, specify otherwise if needed.
- **Connect Event:** Retrieve attachment data separately using the provided `AttachmentId`.

These clarifications should help you navigate the API more effectively. If you have further questions, consulting the latest API documentation or reaching out to DocuSign support may provide additional insights.

Don’t hesite to open a support ticket

Have a great day