UpdateDocumentKeywords API¶

Updates the user-defined keywords of the specified document. Keywords are free-text tags that help categorize and search for documents. This API replaces the entire existing keyword string with the new value. To append keywords, first retrieve the current keywords using GetDocumentKeywords, then append the new keywords and call this API.

Endpoint¶

/srv.asmx/UpdateDocumentKeywords

Methods¶

• GET /srv.asmx/UpdateDocumentKeywords?authenticationTicket=...&path=...&keywords=...
• POST /srv.asmx/UpdateDocumentKeywords (form data)
• SOAP Action: http://tempuri.org/UpdateDocumentKeywords

Parameters¶

Separators¶

Keywords are separated by a comma. Semicolon, pipe, tab and new line are accepted as separators as well.

A space does not separate keywords, so a keyword may be a phrase: acceptance letter, invoice stores two keywords, acceptance letter and invoice. Whitespace inside a keyword is collapsed to single spaces, and each keyword is capped at 128 characters.

Changed in 9.0. Earlier versions also split on spaces, so finance quarterly 2024 stored three keywords. It now stores one. Send finance, quarterly, 2024 to keep the previous result.

Response¶

Success Response¶

<response success="true" error="" />

Error Response¶

<response success="false" error="Document not found." />

Required Permissions¶

The calling user must have write (modify) permission on the document or its containing folder.

Example¶

GET Request¶

GET /srv.asmx/UpdateDocumentKeywords
  ?authenticationTicket=3f2504e0-4f89-11d3-9a0c-0305e82c3301
  &path=/Finance/Reports/Q1-2024-Report.pdf
  &keywords=finance,quarterly,2024,acceptance+letter
HTTP/1.1

POST Request¶

POST /srv.asmx/UpdateDocumentKeywords HTTP/1.1
Content-Type: application/x-www-form-urlencoded

authenticationTicket=3f2504e0-4f89-11d3-9a0c-0305e82c3301
&path=/Finance/Reports/Q1-2024-Report.pdf
&keywords=finance,quarterly,2024,acceptance letter

SOAP Request¶

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"
               xmlns:tns="http://tempuri.org/">
  <soap:Body>
    <tns:UpdateDocumentKeywords>
      <tns:authenticationTicket>3f2504e0-4f89-11d3-9a0c-0305e82c3301</tns:authenticationTicket>
      <tns:path>/Finance/Reports/Q1-2024-Report.pdf</tns:path>
      <tns:keywords>finance,quarterly,2024,acceptance letter</tns:keywords>
    </tns:UpdateDocumentKeywords>
  </soap:Body>
</soap:Envelope>

JavaScript¶

Every call answers XML with HTTP 200, success or not, so success is the thing to branch on and errorCode is the number to report.

async function call(action, params) {
  const response = await fetch(`/srv.asmx/${action}?${new URLSearchParams(params)}`);
  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;
}

Replaces the keywords on a document.

await call('UpdateDocumentKeywords', {
  authenticationTicket: ticket,
  Path: '/Finance/Reports/Q1.pdf',
  Keywords: 'quarterly,finance,board pack'
});

It replaces rather than adds, so read the current set from GetDocumentKeywords and send it back with the additions if the old ones are to survive. What comes back afterwards is sorted, not in the order it was sent, and a keyword may contain spaces - so split on the comma and never on the space.

An empty Keywords removes them all, the same way it does for SetDocumentSummary and SetDocumentTextOnlyContent. Until 9.0 the parameter was declared without a question mark, so an empty one was refused by model binding with HTTP 400 and there was no way to clear a document's keywords at all.

Notes¶

• This API replaces the entire keyword set. To append, read current keywords with GetDocumentKeywords first.
• Passing an empty string clears all keywords from the document.
• Keywords are stored one row per keyword and are included in full-text search.
• A keyword may be a phrase of several words; only the separators listed above break a keyword list apart.

Related APIs¶

• GetDocumentKeywords - Retrieve the current keywords of a document
• GetDocument - Get all document properties including keywords
• UpdateDocumentProperties - Update document name, description, and update instructions

Error Codes¶

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