Worksheet (Add Attachment)

Add Worksheet Attachment

Overview

The Add Worksheet Attachment endpoint uploads a file and attaches it to a worksheet in cieTrade. The file is sent as part of a multipart/form-data request, together with a small JSON payload that identifies the user and the target worksheet.

The document is saved using the original filename of the uploaded file as its name, and the file extension is recorded from that filename. On success the endpoint returns the document ID of the new attachment. Once saved, the attachment will appear in the results of the ListWorksheetAttachments and can be retrieved with the DownloadWorksheetAttachment endpoint.

Authentication

All calls to this endpoint require a valid bearer token passed in the HTTP Authorization header. The token is validated together with the UserID value in the request payload.

Authorization: Bearer YOUR_TOKEN

Endpoint Details

Method	POST
URL	`https://api.cietrade.net/AddWorksheetAttachment`
Headers	`Authorization: Bearer YOUR_TOKEN`
Content-Type	`multipart/form-data`

Request Body

The request body must be sent as multipart/form-data and contain the following two parts. Part names are case-sensitive.

Part Name	Type	Required	Description
file	File	Yes	The file to attach. The filename sent with this part is saved as the document name and must include a file extension (for example `invoice.pdf`). Only one file can be uploaded per request.
request	String (JSON)	Yes	A JSON object containing the fields listed below.

Request JSON Fields

Field	Type	Required	Description
UserID	String	Yes	The ID of the user making the request. Validated together with the bearer token to authorize the call and select the client database. Also recorded on the document as the API user that uploaded it.
Worksheet	String	Yes	The worksheet number the attachment will be added to.

Example request part:

{
    "UserID": "Example@cieTrade.com",
    "Worksheet": "123456"
}

Response

Success

On success the endpoint returns 200 OK. The response body is a JSON string containing the document ID (DocID) assigned to the new attachment. This ID can be passed to the Download Worksheet Attachment endpoint to retrieve the file.

Example success body:

"10046"

Errors

Error responses return a JSON body with a Message property describing the problem.

Status	Message	Cause
400 Bad Request	ERROR: No request payload provided.	The `request` part was missing or empty.
400 Bad Request	ERROR: No file provided.	The `file` part was missing or the file was empty.
401 Unauthorized	ERROR: Request must include a bearer authorization token	The `Authorization` header is missing or does not use the `Bearer` scheme.
400 Bad Request	ERROR: …	The bearer token and `UserID` could not be authenticated. The message contains the reason returned by the authentication service.
400 Bad Request	ERROR: Could not save the attached document.	The file could not be saved to the worksheet. Verify that the `Worksheet` is valid.
500 Internal Server Error	An error has occurred.	An unexpected server error occurred, such as a filename without an extension.

Example error body:

{
    "Message": "ERROR: No file provided."
}

If the request is not sent as multipart/form-data, the endpoint returns 400 Bad Request with the body "ERROR: Request must be multipart/form-data." instead of an error status. Always send the request as multipart/form-data as shown in the examples below.

Usage Examples

JavaScript (fetch with FormData)

Use a FormData object to build the multipart body. Do not set the Content-Type header manually — the browser sets it automatically, including the required multipart boundary.

var fileInput = document.getElementById('fileInput');

var formData = new FormData();
formData.append('file', fileInput.files[0]);
formData.append('request', JSON.stringify({
    UserID: userId,
    Worksheet: worksheet
}));

fetch('https://api.cietrade.net/AddWorksheetAttachment', {
    method: 'POST',
    headers: { 'Authorization': 'Bearer ' + token },
    body: formData
})
    .then(function(response) {
        return response.json().then(function(body) {
            if (!response.ok) {
                throw new Error(body.Message);
            }
            return body; // the new DocID, e.g. "10046"
        });
    })
    .then(function(docId) {
        alert('File saved. Document ID: ' + docId);
    })
    .catch(function(error) {
        alert('Upload failed: ' + error.message);
    });

Server-to-server example (cURL)

curl -X POST "https://api.cietrade.net/AddWorksheetAttachment" \
     -H "Authorization: Bearer YOUR_TOKEN" \
     -F "file=@/path/to/invoice.pdf" \
     -F 'request={"UserID":"YOUR_USER_ID","Worksheet":"123456"}'