UploadDocument2 API¶

Uploads a new document or creates a new version of an existing document at the specified path using a raw byte array, with a post-upload checkout option. When checkout=true, the document is immediately locked (checked out) to the calling user after upload, preventing others from creating new versions.

Endpoint¶

/srv.asmx/UploadDocument2

Methods¶

• POST /srv.asmx/UploadDocument2 (form data -" recommended for binary content)
• SOAP Action: http://tempuri.org/UploadDocument2

Parameters¶

Response¶

Success Response¶

<root success="true" DocumentId="12345" VersionId="1000002" />

Error Response¶

<root success="false" error="[901] Session expired or Invalid ticket" />

Required Permissions¶

The calling user must have write (upload) permission on the destination folder.

Example¶

POST Request¶

POST /srv.asmx/UploadDocument2 HTTP/1.1
Content-Type: multipart/form-data; boundary=----FormBoundary

------FormBoundary
Content-Disposition: form-data; name="authenticationTicket"

3f2504e0-4f89-11d3-9a0c-0305e82c3301
------FormBoundary
Content-Disposition: form-data; name="path"

/Finance/Reports/Q1-2024-Report.pdf
------FormBoundary
Content-Disposition: form-data; name="fileContent"; filename="Q1-2024-Report.pdf"
Content-Type: application/octet-stream

[binary file content]
------FormBoundary
Content-Disposition: form-data; name="checkout"

true
------FormBoundary--

SOAP Request¶

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"
               xmlns:tns="http://tempuri.org/">
  <soap:Body>
    <tns:UploadDocument2>
      <tns:authenticationTicket>3f2504e0-4f89-11d3-9a0c-0305e82c3301</tns:authenticationTicket>
      <tns:path>/Finance/Reports/Q1-2024-Report.pdf</tns:path>
      <tns:fileContent>JVBERi0xLjQ...</tns:fileContent>
      <tns:checkout>true</tns:checkout>
    </tns:UploadDocument2>
  </soap:Body>
</soap:Envelope>

JavaScript¶

// Anything carrying bytes is POST-only: a byte[] cannot be bound from a query string, and a GET is
// answered HTTP 415 before the operation runs.
async function post(action, fields) {
  const response = await fetch(`/srv.asmx/${action}`, {
    method: 'POST',
    headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
    body: new URLSearchParams({ authenticationTicket: ticket, ...fields })
  });

  const root = new DOMParser()
    .parseFromString(await response.text(), 'text/xml').documentElement;

  if (root.getAttribute('success') !== 'true') {
    throw new Error(`${root.getAttribute('errorCode')}: ${root.getAttribute('error')}`);
  }
  return root;
}

const base64 = bytes => btoa(String.fromCharCode(...bytes));

await post('UploadDocument2', {
  Path: '/Finance/Reports/Q1.pdf',
  FileContent: base64(bytes),
  Checkout: 'true'          // check it out for me if it is not already
});

Checkout means "check it out for me if it is not already", not "leave it checked out". A second upload to a path is a new version, and only whoever holds the checkout may make one - so false on a document nobody has checked out is refused 4000. With true the operation checks out, uploads and checks back in, and the document is free afterwards.

The upload family¶

Two ways in. Either the bytes travel with the call, or they are staged first and the call names the handler that holds them.

Uploading over a document that already exists is a new version, and only whoever holds the checkout may make one. Without a checkout the answer is 4000 "this document is not checked out". The Checkout flag means check it out for me if it is not already: the operation then checks out, uploads and checks back in, leaving the document free. It does not mean "leave it checked out".

Notes¶

• When checkout=true, the document is checked out to the calling user immediately after upload. Other users cannot create new versions until the document is unlocked.
• For large files, use the chunked upload approach with CreateUploadHandler -' UploadFileChunk -' UploadDocumentWithHandler.
• Use UploadDocument3 if you also need a version comment along with checkout.

Related APIs¶

• UploadDocument - Upload without checkout
• UploadDocument1 - Upload with version comment
• UploadDocument3 - Upload with both version comment and checkout
• UploadDocument4 - Upload with extended XML parameters
• UnLock - Unlock (check in) a document after editing

Error Codes¶

The errorCode values this operation returns, checked against a running server: