A.nnotate API reference - Part 2

This is Part 2 of the A.nnotate API reference guide (see also Part 1 - Introduction and Part 3 - Folders). It includes calls to create accounts, upload documents, add notes, and allow authorized users to annotate particular documents.

1. Create a new user account

The createAccount.php call allows you to create a user account. The request must be signed by the api-user (see authentication. Accounts are initially created as 'annotating users' - to allow the user to upload documents, see the next section. 

  http://yoursite.com/annotate/php/createAccount.php?
    api-user=joe@example.com               # The admin user for the account
    &api-requesttime=123456                # the Unix timestamp (GMT)
    &api-annotateuser=jill@example.com     # The user's account
    &api-auth=xyz1234543983jeflgnwefgdgd   # The signed hash code.

    &sig=jill                              # The user's signature
    &tagsfile=inittags                     # (optional) init user tags from php/inittags.txt
    &passwd=sesame                         # (optional) set the initial passwd 
                                           # (a random one will be allocated if none is provided)

[new in v4:]
    &firstname=Jill                        # (optional) To set full name,
    &lastname=Jones                        # (optional) set these fields

The return value is either "OK" or "ERR {error message}".

Setting the initial set of available note tags: The optional tagsfile parameter can be set to load initial note tags from a file tagsfile.txt in the php/ directory. The default is to use 'php/inittags.txt' - if you want to initialise the tags to the contents of 'php/mytags.txt', set tagsfile=mytags (i.e. without the .txt extension)

2. Licensing / updating user accounts

The updateAccount.php call lets you change user signatures / passwords and also upgrade an account from an 'annotating user' to a fully licensed user (able to upload documents): 

  updateAccount.php?
    api-user=joe@example.com               # The admin user for the account
    &api-requesttime=123456                # the Unix timestamp (GMT)
    &api-annotateuser=jill@example.com     # The user's account
    &api-auth=xyz1234543983jeflgnwefgdgd   # The signed hash code.

    &sig=jill                              # (optional) The user's signature
    &passwd=sesame                         # (optional) The user's new a.nnotate password
    &licensed=1                            # (optional) To upgrade to a licensed user      
[new in v4:]
    &firstname=Jill                        # (optional) To update full name,
    &lastname=Jones                        # (optional) set both these fields

The return value is either "OK" or "ERR {error message}".

3. Login as a given user and display the given A.nnotate page

The loginAs.php call lets you create a link which logs a user in to their A.nnotate account and then displays either the notes / document index page or a particular document. 

  loginAs.php?
    api-user=joe@example.com               # The admin user for the account
    &api-requesttime=123456                # the Unix timestamp (GMT)
    &api-annotateuser=jill@example.com     # The user's account
    &api-auth=xyz1234543983jeflgnwefgdgd   # The signed hash code.

    &loc=documents.php                     # The page to display after login
    &errloc=http://mysite.org/error.php    # An error page to display if login fails
    &remember=1                            # Store login info in browser cookie

Added Oct 2009:
    &create=1                              # (optional) Create user account if not present:
    &sig=joe                               # (optional) - sig for new account if creating
    &licensed=1                            # (optional) - upgrade new account to licensed user

[new in v4, May 2011:]
    &firstname=Jill                        # (optional) - To set full name for new account
    &lastname=Jones                        # (optional) - set these fields

On visiting the link, the user will be logged in and redirected to the loc address. If there is a problem logging in, the link will redirect the user to the errloc url, with the msg parameter set, e.g. error.php?msg=some_error_msg.

The loc parameter determines the page which will be displayed on login. Suitable values are: documents.php for the list of documents, notes.php for the index of notes, pdfnotate.php?d=2008-01-01&c=abc123 for a particular document.

You may wish to post-date the request if including the loginAs.php link in a web page - simply increase the request time by the desired number of seconds you want the link to be valid for.

[added in Aug 2010] If you need to end the user session, you can use the apiLogout call.

3.1 Creating new accounts on the fly if needed [new in v3.0.30, Oct 2009]

If you set the 'create=1' flag, then a new A.nnotate account will be created for the given annotateuser if they do not already have an account. You can also set the 'licensed=1' flag to enable the new account to upload documents. This is a shortcut which combines the standard calls to createAccount.php and updateAccount.php. This can be useful for integrations with external web applications - you can add a signed 'loginAs.php' link on your web application which creates an annotate user account and logs the user in. If the user already has an a.nnotate account, then the create=1 settings are ignored and it uses their existing account.

4. Uploading a document

The uploadDocument.php call lets you do a HTTP POST to upload a document to the A.nnotate server and add it to the given annotateuser's account. The URL should include the normal GET parameters, with the other fields as POST parameters. To post a file, use multipart/form-data as with standard HTML form file uploads. The sample here is given as an HTML form, but you can also simulate a form HTTP POST call from scripting languages, or use a HTTP utility such as CURL. 

  <form method='POST' enctype='multipart/form-data' action='uploadDocument.php?
      api-user=joe@example.com           
      &api-requesttime=123456            
      &api-annotateuser=jill@example.com  
      &api-auth=xyz1234543983jeflgnwefgdgd'>

     <input name='desc'>                     # the description
     <input name='tags'>                     # comma separated list of tags

     # option 1: include a file browse component:
     <input type='file' name='Filedata'>    

     # option 2: provide the URL of the document to fetch
     <input name='url'>                   
     <input name='urlfilename'>              # (optional) filename to use

(optional: v4 added June 2011 - specify that this doc is revision of earlier one
 --- subsequent versions should all refer to original date + code               
     <input name='revisionOf'>               # e.g. 2011-01-01/abc123  
     <input name='revisionNumber'>           # e.g. 2 

  <form>

You can either upload a file by posting it (a normal file upload), or by providing the URL of the document to fetch in the url parameter.

The default return value is "OK {document date} {document code}", or "ERR " + an error message, e.g.: 

  OK 2008-01-02 abc123

There are alternative return formats (see 4.1 and 4.2 below) which may be useful if you are running annotate on a different web server from your web application.

You can make a link to the uploaded document using a url like: pdfnotate.php?d=2008-01-02&c=abc123 - see also the previous section on the loginAs.php call which lets you create a link to log in as a given user and display a document.

To control detailed settings of the displayed document, e.g. hiding particular buttons in the interface, opening on a particular page or note, or with a particular zoom level, please see the embedding a PDF guide.

4.1 Uploading a document and redirect to given page [new in v3.0.14]

Instead of returning a plain text string like "OK 2009-01-01 abc123" you can get uploadDocument.php to redirect to a user supplied URL, with the date and code as GET parameters. This can be useful if you need to store the uploaded date and code in your own database, and then show the document in an iframe. 

  <form method='POST' target='_blank' enctype='multipart/form-data' action='uploadDocument.php?
      api-user=joe@example.com           
      &api-requesttime=123456            
      &api-annotateuser=jill@example.com  
      &api-auth=xyz1234543983jeflgnwefgdgd'>

     <input type='hidden' name='fmt' value='redir' />
     <input type='hidden' name='loc' value='http://yoursite.com/yourscript.php?arg123=abc' />
     <input type='hidden' name='errloc' value='http://yoursite.com/yourerrscript.php?arg456=def' />

     <input name='desc'>                     # the description
     <input name='tags'>                     # comma separated list of tags

     # option 1: include a file browse component:
     <input type='file' name='Filedata'>    

     # option 2: provide the URL of the document to fetch
     <input name='url'>                   
  <form>

When the upload has completed, it will do a redirect to the url supplied in the loc post parameter, e.g.: 

   http://yoursite.com/yourscript.php?arg123=abc&d=2009-01-01&c=abc123&status=OK&annotateuser=jill@example.com
-or-
   http://yoursite.com/yourerrscript.php?arg456=def&errmsg=...&status=ERR&annotateuser=jill@example.com

You can use the return values to show the document in an iframe. Note that the redirect is performed by uploadDocument.php generating a simple html web page which uses javascript to set document.location = ... It uses this technique in preference to a HTTP redirect as a work-around for Microsoft Internet Explorer's implementation of iframes.

4.2 Uploading a document and calling script in parent window [new in v3.0.14]

As another alternative callback mechanism, you can get uploadDocument.php to generate a javascript callback to your application, providing the document's date and code. Browsers typically allow iframes to call javascript methods in the parent window, even if the iframe is loaded from a different web server. If you have an iframe on your page with id iframeid, and javascript methods documentUploaded and uploadError on your page, you can add a form like: 

  <form method='POST' target='iframeid' enctype='multipart/form-data' action='uploadDocument.php?
      api-user=joe@example.com           
      &api-requesttime=123456            
      &api-annotateuser=jill@example.com  
      &api-auth=xyz1234543983jeflgnwefgdgd'>

     <input type='hidden' name='fmt' value='js' />
     <input type='hidden' name='cb' value='parent.documentUploaded' />
     <input type='hidden' name='errcb' value='parent.uploadError' />

     <input name='desc'>                     # the description
     <input name='tags'>                     # comma separated list of tags

     # option 1: include a file browse component:
     <input type='file' name='Filedata'>    

     # option 2: provide the URL of the document to fetch
     <input name='url'>                   
  <form>

When the upload has completed, it will call back one of the javascript functions you supply in the cb or errcb fields, e.g. 

 // Callbacks on finishing uploading.
function documentUploaded(date, code, user) {
  alert('Document uploaded ok: ' + date + ' '+code+' '+user);
}
function uploadError(errmsg) {
  alert('Document upload error: ' + errmsg);
}

5. Adding a note to a document using the API

The addNote.php call lets you add a note to a particular phrase of a document programmatically. It is also used for posting note edits, replies and deletions. 

Request URL:
  addNote.php?
    api-user=joe@example.com               # The admin user for the account
    &api-requesttime=123456                # the Unix timestamp (GMT)
    &api-annotateuser=jill@example.com     # The annotate user
    &api-auth=xyz1234543983jeflgnwefgdgd   # The signed hash code.    

    &d=2008-01-02                          # The document upload date
    &c=abc123                              # the document code

HTTP POST parameters:
  notetext              # e.g. 'this is a note'
  tags                  # e.g. 'person, important'
  subject               # the highlighted phrase
  context               # the sentence the note came from
  type                  # 'note' or 'reply'
  match                 # e.g. page-1:10:13  is a note on page 1 from word 10-13
  state                 # 'live' or 'dead'
  gid                   # leave empty for new note; set for edits / replies
  signed                # leave empty for default; can override user signature here
  replyid               # only needed for editing / deleting existing replies

  linkTo                # (optional) target URL if this is a note about a link
  linkTitle             # (optional) target URL title if this is a note about a link
  drawing               # (optional, added Aug 2010) the drawing commands for freehand 
                        #  annotations as a json array

The return value is "OK {note number}" or "ERR {error message}".

You might find it useful to try creating some notes using the normal a.nnotate gui, and fetching the list of notes using the calls in the api reference part 1 which also includes a more detailed explanation of the note parameters.

To edit a note, simply call addNote.php and set the gid field to be the same as the note you are editing. To reply to a note, again set the gid of the note, and set the type field to 'reply'. To delete a note, set the gid of the note and the state field to 'dead'.

To edit/delete a reply to a note, you need to know its replyid; this is the note number of the reply when first added, and is also set on loading the notes in the 'replyid' field. For new replies, leave the replyid parameter empty.

5.1 Deleting all notes on a document

[new in v4 oct 2011] The apiDeleteNotes.php call lets you wipe all notes on a document permanently. If you just want to delete an individual note, see the addNote call above (and append a note with a given ID and state='dead'). 

Request URL:
  apiDeleteNotes.php?
    api-user=joe@example.com               # The admin user for the account
    &api-requesttime=123456                # the Unix timestamp (GMT)
    &api-annotateuser=jill@example.com     # The annotate user
    &api-auth=xyz1234543983jeflgnwefgdgd   # The signed hash code.    

    &d=2008-01-02                          # The document upload date
    &c=abc123                              # the document code

    &bak=1                                 # (optional) backup old notes

[added Feb 2012, v4.0.18]
    &leavelinks=1                          # (optional) don't delete links

The return value is "OK" or "ERR {error message}". If you set bak=1 it will take a backup copy of the old notes on the server.

6. Editing a document's metadata and permissions

The updateDocumentMeta.php call lets you modify a document's metadata (title, tags, authors). It uses HTTP POST for the metadata; the document to use is specified by the date and code in the request URL: 

Request URL:
  updateDocumentMeta.php?
    api-user=joe@example.com               # The admin user for the account
    &api-requesttime=123456                # the Unix timestamp (GMT)
    &api-annotateuser=jill@example.com     # The annotate user
    &api-auth=xyz1234543983jeflgnwefgdgd   # The signed hash code.    

    &d=2008-01-02                          # The document upload date
    &c=abc123                              # the document code

POST parameters:
   title              # Document title
   authors            # authors
   notes              # Notes on the document as a whole
   tags               # Document level tags

# Added in v4:
   ref                # (optional) a user id for the document (e.g. ref#, invoice# etc)
   doctypeid          # (optional) an integer ID for the workspace document type

The return value is "OK" or "ERR {error message}". There are a number of optional POST parameters to the updateDocumentMeta.php call - these are described below. If the extra parameters are not included in the call, the settings will not be modified.

6.1 Advanced document metadata flags

There are a number of optional settings on a document, which can be used to control who is authorized to add comments, down to the level of individual pages. 

Optional POST parameters for updateDocumentMeta.php:
   defaultNoteStatus     # shared / private / feedback
                         # The default setting for new notes.

   allowNoteStatusChange # 1 / 0
                         # Whether to allow users to change the status.

   allowNewNoteTags      # 1 / 0
                         # Whether to allow users to add new tags.

   closedForComments     # 1 / 0
                         # If set, don't allow new comments

   addToContacts         # 1 / 0
                         # If set, add new document viewers to 
                         # contacts list of doc owner

   linkSharable          # 1 / 0  
                         # If set, enable access to document
                         # to anyone with a link  [*added Dec 2009*]

6.2 Advanced document annotation permissions

It is also possible to control which users are permitted to annotate a document, and optionally set the allowed page ranges. 

Optional POST parameters for updateDocMeta.php:
   allowAnnotationUsers    # comma or \n separated list of user emails
                           # e.g. for nobody except joe and jane:
                           # "_none,joe@example.com,jane@example.com"

   denyAnnotationUsers     # comma or \n separated list of user emails
                           # e.g. "badguy@example.com,badgal@example.com"
                           
# Special values for entries in the allow / deny lists:
#   "_any"  --- any user with access to document
#   "_none" --- no user
# the allow list is processed first, then deny.
# allow defaults to all users allowed, so to restrict to set users use 
# "_none" first:
# e.g.  allowAnnotationUsers : "_none, joe@example.com, jane@example.com"
#

To control whether particular users can annotate particular pages of a document, set the perPagePermissions list. The perPagePermissions list overrides the settings in the allowAnnotationUsers list, so just set one or the other, or the allow list will be ignored. The denyAnnotationUsers list can be used in conjunction with perPagePermissions though - it is checked afterwards and trumps the perPagePermissions settings to block particular users. 

Optional POST parameters for updateDocMeta.php:
   perPagePermissions      # one entry per line, format as below:

# Format one entry per line, each entry is {user email}:{page range}\n
# Special values for the user field are: 
#   _any
#   _none
# The page range is specified as a comma-separated list of 
# page numbers; ranges like "10-20" can be included in the list.
# and an item can be prefixed by "!" to exclude that page. 
# To match any page, use "1-".
# Note that the page numbers are those of the PDF file
# starting at 1 - 
# If perPagePermissions is set, there is an implied: "_none:1-"
# rule preceeding any user rules. 

# Example page ranges:
  1,2,10-20     -- pages 1, 2 and 10-20 only
  1-,!22        -- any page apart from 22
  1-50,!10-20   -- equivalent to 1-9,21-50
  50-           -- pages 50 to the end of the document.
  -20           -- all pages from start to #20

#
# Items are processed in the order of the entries.
# Example values for perPagePermissions array (NB there
# is a Colon (:) separator between the user name and the 
# page range)

  joe@example.com:12
  jack@example.com:1-11,13-
  jill@example.com:1-100,!33

Some examples: 

# Only joe and jill allowed to annotate the document
  allowAnnotationUsers:"_none, joe@example.com, jill@example.com"
  denyAnnotationUsers:
  perPagePermissions:

# Anyone apart from joe@example.com can annotate any page
  allowAnnotationUsers:
  denyAnnotationUsers:"joe@example.com"
  perPagePermissions:

# joe can annotate all pages, other users only pp1-10, jack blocked:
  allowAnnotationUsers:
  denyAnnotationUsers:"jack@example.com"
  perPagePermissions:"_any:1-10\njoe@example.com:1-"

# anyone can annotate all pages, but joe can't annotate page 22
  perPagePermissions:"_any:1-\njoe@example.com:!22"

# nobody can annotate any pages except joe who can annotate 1,3,5,7,9-
  perPagePermissions:"_none:1-\njoe@example.com:1,3,5,7,9-"

6.3 User defined document metadata fields [*new in v3.0.13 *]

You can store additional fields such as x_myfield in the document metadata object; any fields starting with x_ in the POST call to updateDocumentMeta.php will be stored in the metadata object. 

Sample optional POST parameters for updateDocMeta.php for user defined fields:

   x_myfield: "some data item",
   x_mydatabaseid: "123456"

7. Deleting a document

The deleteDocument.php call removes a document. If the given user is not the owner of the document it will just remove the document from their list. Arguments can be either GET or POST: 

  deleteDocument.php?
    api-user=joe@example.com               # The admin user for the account
    &api-requesttime=123456                # the Unix timestamp (GMT)
    &api-annotateuser=jill@example.com     # The selected user
    &api-auth=xyz1234543983jeflgnwefgdgd   # The signed hash code.    

    &d=2008-01-02                          # The document upload date
    &c=abc123                              # the document code

    &ws=123445                             # (optional) the workspace ID

The return value is "OK" or "ERR {message}".

8. Adding a document to a given user's list

The authorizeReader.php call adds a document to the given user's list. 

  authorizeReader.php?
    api-user=joe@example.com               # The admin user for the account
    &api-requesttime=123456                # the Unix timestamp (GMT)
    &api-annotateuser=jill@example.com     # The annotate user
    &api-auth=xyz1234543983jeflgnwefgdgd   # The signed hash code.    

    &d=2008-01-02                          # The document upload date
    &c=abc123                              # the document code

The return value is "OK" or "ERR {message}".

9. Listing user accounts

The listUsers.php call lists the a.nnotate users on the server administered by the given api-user: 

  listUsers.php?
    api-user=joe@example.com               # The admin user for the account
    &api-requesttime=123456                # the Unix timestamp (GMT)
    &api-annotateuser=joe@example.com      # Set this to the api-user
    &api-auth=xyz1234543983jeflgnwefgdgd   # The signed hash code.

The response is "ERR {error message}" or a JSON string with two arrays; "members" lists email addresses of group members, and "annotators" lists email addresses of unlicensed users, e.g.: 

  { 
    members : ["joe@example.com","jill@example.com"],
    annotators : [ "other@example.com" ] 
  }

10. Get guest access code for a document

The apiGetAnonAuthCode.php call [Added: July 2010] returns the guest access code for a document needed to allow annotation without logging in. The api-annotateuser supplied must be the owner of the document. 

  apiGetAnonAuthCode.php?
    api-user=joe@example.com               # The admin user for the account
    &api-requesttime=123456                # the Unix timestamp (GMT)
    &api-annotateuser=joe@example.com      # the owner of the document.
    &api-auth=xyz1234543983jeflgnwefgdgd   # The signed hash code.    

    &d=2010-01-01   # the document date
    &c=abc1234      # the document code

The response is "ERR {error message}" or a "OK {anon auth code}". You can use this code to generate a document link like pdfnotate.php?d=...&c=...&aac=xxxx&asig=client123.

11. Logout via API

The apiLogout.php call [Added: Aug 2010] ends the user's browser session and redirects to the URL in the loc parameter. If you have used the loginAs call to start a user session, you can use the apiLogout call to end it (e.g. by setting the src of an iframe to apiLogout.php). The argument should be URI encoded; you need to set the browser window location (or iframe src) to the apiLogout url to use it. 

  apiLogout.php?loc=http://example.com/yourpage.html

12. Delete a user account

The apiDeleteAccount.php call [Added: Aug 2010] removes a user account. It needs to be called by an admin user. The call de-licenses the user before deleting. To downgrade a user to an annotating user, you can use the updateAccount api call and set licensed=0. 

  
  apiDeleteAccount.php?
    api-user=joe@example.com                   # The admin user for the account
    &api-requesttime=123456                # the Unix timestamp (GMT)
    &api-annotateuser=jill@example.com     # The user to delete
    &api-auth=xyz1234543983jeflgnwefgdgd   # The signed hash code.    

POST parameter:
    delete=1                                   # To confirm delete

The return value is either "OK {message}", or "ERR {message}".

13. Add contacts to a user account

The apiAddContacts.php call [Added: Oct 2010] adds a list of email contacts to a given user; these will appear in the 'share' dialog for a document. 

  
  apiAddContacts.php?
    api-user=joe@example.com                   # The admin user for the account
    &api-requesttime=123456                # the Unix timestamp (GMT)
    &api-annotateuser=jill@example.com     # The user to delete
    &api-auth=xyz1234543983jeflgnwefgdgd   # The signed hash code.    

POST parameter:
    e=contact1@example.com,contact2@example.com  # List of emails, separated by commas.

The return value is either "OK {message}", or "ERR {message}".

14. Get contacts for a user account

The apiGetContacts.php call [Added: Oct 2010] lists the email contacts for a given user. 

  
  apiGetContacts.php?
    api-user=joe@example.com                   # The admin user for the account
    &api-requesttime=123456                # the Unix timestamp (GMT)
    &api-annotateuser=jill@example.com     # The user to delete
    &api-auth=xyz1234543983jeflgnwefgdgd   # The signed hash code.

The return value is either a json-encoded array of emails, or "ERR {message}".

15. Delete contacts for a user account

The apiDeleteContacts.php call [Added: Oct 2010] deletes the given email contacts for a given user. 

  
  apiDeleteContacts.php?
    api-user=joe@example.com                   # The admin user for the account
    &api-requesttime=123456                # the Unix timestamp (GMT)
    &api-annotateuser=jill@example.com     # The user to delete
    &api-auth=xyz1234543983jeflgnwefgdgd   # The signed hash code.    

POST parameter:
    e=contact1@example.com,contact2@example.com  # List of emails, separated by commas.

The return value is either "OK {message}", or "ERR {message}".

16. Get account details for a user

The apiGetAccountDetails.php call [Added: Oct 21 2010] returns the subscription account details for a given user. 

  
  apiGetAccountDetails.php?
    api-user=joe@example.com                   # The admin user for the account
    &api-requesttime=123456                # the Unix timestamp (GMT)
    &api-annotateuser=jill@example.com     # The user to get
    &api-auth=xyz1234543983jeflgnwefgdgd   # The signed hash code.

The return value is either a json object with fields subtype, credits, subinfo, billing and sig or "ERR {message}".

17. Set user preferences for a user [new in v4]

The apiSetUserPref.php call [Added in v4] sets the user preferences on the account page; noteColor, noteDisplayStyle. 

  
  apiSetUserPref.php?
    api-user=joe@example.com                   # The admin user for the account
    &api-requesttime=123456                # the Unix timestamp (GMT)
    &api-annotateuser=jill@example.com     # The user to set
    &api-auth=xyz1234543983jeflgnwefgdgd   # The signed hash code.  

POST  # you only need to set the prefs you want to update.
    &noteColor=2                           # note background color (an index from 0 - 20)  
    &noteDisplayStyle=m                    # {m, b, h, f} for margin, boxes, hide, footnotes
    &sharableLinkDefault=1                 # {0,1} - whether document links sharable by default

The return value is OK + msg or ERR + msg.

18. Add credits to a user account [new in v4]

The apiAddCredit.php call [Added in v4] can be used with multi-group installations of an annotate server, which control document uploads using a system of credits. 

  
  apiAddCredit.php?
    api-user=joe@example.com                   # The admin user for the account
    &api-requesttime=123456                # the Unix timestamp (GMT)
    &api-annotateuser=jill@example.com     # The user to set
    &api-auth=xyz1234543983jeflgnwefgdgd   # The signed hash code.  

POST  # you only need to set the prefs you want to update.
    &amount=1000                           # number of credits to add

The return value is OK {new balance} or ERR + msg.

19. Set email notification preferences for a user [Aug 2011]

The apiSetNotifyPref.php call [Added Aug 2011, since v3.1.20+, v4.0.12+] sets the email notification preferences for the user. See the modules installation guide for details of setting up email notifications on your server. 

  
  apiSetNotifyPref.php?
    api-user=joe@example.com                   # The admin user for the account
    &api-requesttime=123456                # the Unix timestamp (GMT)
    &api-annotateuser=jill@example.com     # The user to set
    &api-auth=xyz1234543983jeflgnwefgdgd   # The signed hash code.  

POST  # you only need to set the prefs you want to update.
    &notifications=on                      # {on,off}- whether to send emails at all
    &frequency=immediate                   # {immediate, hourly, daily} 
    &doneonly=no                           # {yes,no} - only when someone clicks 'done'
    &others=yes                            # {yes,no} - email if notes on docs of others

The return value is OK + msg or ERR + msg.

20. Copy notes to a duplicate document [Feb 2012]

The apiCopyNotes.php call [Added Feb 2012, since v3.1.21+] copies notes from one document to a duplicate copy. It can be useful if you gather internal comments on one copy, then want to make a tidied up version for an external client. You supply dates and codes for original and duplicate, and can replace the note ownership (e.g. if you want to make all notes editable by a given user before sending to the client). 

  
  apiCopyNotes.php?
    api-user=joe@example.com                    # The admin user for the account
    &api-requesttime=123456                # the Unix timestamp (GMT)
    &api-annotateuser=joe@example.com      # The admin user too.
    &api-auth=xyz1234543983jeflgnwefgdgd   # The signed hash code.  


    &d1=2011-01-01&c1=abc123          # Date and code of orig doc
    &d2=2011-01-01&c2=xyz456          # Date and code of target doc
    &newauthor=jack@example.com            # {optional} set the author of all copied notes
    &newsig=jack                           # {optional} set the signed field of all copied notes

The return value is OK + msg or ERR + msg.