REST Resources

We've attempted to make the Doculicious API adhere to the REST architecture. This means that the "things" within Doculicious, such as your templates and the entries made to them are represented as resources that have a unique URI and one or more representations defined by the file extension used to call the resource. Resources can be collections of other resources, in which case you can access an individual resource by calling its UID after the collection resource, ie:<resource-collection>/<resourceUID>.<representation>

  • <resource-collection>: This is a collection of resources, such as entries or templates. eg /do/api/templates, /do/api/entries
  • <resourceUID>: This is the Unique ID (UID) of an individual thing you are requesting. Eg: it could be the unique ID of a Template or Entry.
  • <representation>: How you want the result returned. See below...


A representation is the format that you want to retrieve a particular resource in. For example, many Doculicious resources can be viewed as documents, such as printable PDF files made from a template, but these resources are also individual pieces of data that can be represented in text formats such as XML, CSV or HTML, or image formats like JPG. Representations allow you to choose different ways to work with the data in your account.

Each resource and method combination may support different representations, and this will be outlined in the relevant description of each resource. Doculicious supports text based formats such as XML, JSON and HTML and also binary formats like PDF.

XML is the default representation for all resources, but you can easily change this by providing an extension when you call a resource, such as .json or .pdf. The resource section of this help documentation describes the available representations.

A note on JSON representations

JSON does not have an inherent way to include meta-data about elements it is modelling, such as XML does with attributes. To ensure that our JSON and XML representations are as compatible as possible, elements that would contain an attribute if output as XML, will be represented as a JSON object with the attributes as single fields in the object, each preceded with the "@" sign, and the actual value or data of the element in a field called "$". Here's an example:

<value class="string">The Value</value>

  "$":"The Value"

API Key Authentication

Most Doculicious API calls will require the caller to identify and authenticate themselves before access to a resource is given. Each Doculicious account has an API Access ID and an API Secret Access Key that act as a username and password to the API. When you send a request to act on a resource, you must provide the ID and the Key. This can be sent in one of two ways, in the header or in POST form variables.

PLEASE NOTE: all API requests MUST use SSL so that this information is secured. So the URL should always begin with:

Any calls to will return an error

Header Authentication

You can send the API ID and API Key in the authorization header of the request by including the following header:

authorization: DCS APIAccessID:APISecretAccessKey

POST Variable Authentication

You may also send the authentication information using POST variables. This allows you to use a HTTP form post to submit details to a resource. To do this, use the following form fields:


Security Note: Please ensure that you use HTTPS so your request is sent through a secure connection, and don't hardcode your API Access Secret Key into web forms. 

Optional Authentication

With some API calls, authentication is optional and can be turned on or off for individual templates. The "api" section of a templates dashboard entry will contain checkboxes to enable/disable the security for certain methods. If the checkbox is "checked", security is enabled for that method, and the authentication procedures documented above must be implemented. If the checkbox is off, no authentication is needed.

Why would I want the security off?
Sometimes there is no security risk to allow a method to be called without authenticating the the caller. For example, when creating new entries for a specific template that should be publicly accessible. By not requiring authentication, it's easy to create a simple HTML web form that can submit directly to this method, without the need to proxy the request and add authentication details when they're not really needed.

Property Types

 Resources are made up of different properties, each of which is of a certain type. The types are described below:

Type Description
String A text value made up of characters. If the representation is XML, any special characters will be HTML encoded. ie, the "<" and ">" characters become &lt; and &gt;
Integer A value from 0 to 9.
Boolean A value of True or False.
Timestamp A date & time format. Dates passed to Doculicious must match this format exactly -  YYYY-MM-DDThh:mm:ssTZD (eg 1997-07-16T19:20:30+01:00).

Note: When passing dates to the API via the URL you will need to encode them.


As stated previously, resource collections can be filtered on the properties of the individual resources that make up the collection. Each of these properties is of a certain type, and each type has different filter conditions that can be used. Below is an outline of these types and their valid conditions. Each resource will state which of its properties can be filtered on, and what type the property is.

Comparison Operator Valid Types Examples
Equal To (=) (None) Boolean
Greater Than or Equal To (>=)  __gte Timestamp
Less Than or Equal To (<=)  __lte Timestamp

Multiple filters can be used for a single property, for example you could do this to retrieve values between two dates:{template_uid}.xml?createdDate__gte=2009-04-23T21:34:23%2B10:00&createdDate__lte=2009-04-23T21:34:24%2B10:00

Note: The plus ("+") sign needs to be HTML encoded to "%2B" for use in the URL.

Filtering collections

Resource collections can be filtered by providing values for the properties of the resources you want returned. Ie: The Doculicious Element resource has a property called "readOnly" that can be true or false. To retrieve all the Elements flagged as read only from a Template collection you can call:<template_uid>/elements.xml?readOnly=true

To retrieve only writable elements, change readOnly=true to readOnly=false. To retrieve all the elements of the collection, leave out the filter. Multiple filters can be joined together to filter the collection more. Read more on filters here.

Each resource collection will describe which properties can be filtered on.

Filtering sub-collections

If a resource has a collection of resources within it, you may be able to filter the sub-collection using filters and parameters. To do this, you use "dot notation" to reference the collection and parameter or filter you want to filter on. For example, the entries resource contains a sub-collection of elements within each entry. You can pass the parameter value elements._rows=10 to limit that collection to 10 rows. You could also pass through the filter elements.readOnly=false to limit the collection to only elements that are not set as read only. The resources help documentation will outline which sub-collections can be references this way, and which fields are applicable.

Limiting how many records a sub-collection returns can be used to decrease the size of your requests. If you don't need the sub-collections you can set the _rows value to 0 and none will be returned, or you can filter to only retrieve the records that are required for your query. Some resources will automatically filter their sub-collections, such as the entries resource, which only retrieves the elements within each entry that are not read only - as these elements are the only ones within an entry that can have user inputed data.


Some resource URI's allow parameters to be passed which will effect the response in some way. We've already mentioned Authorisation, and how you can send the APIAccessID and APIAccessSecretKey as form fields in a POST request, but there are other paramaters that can be sent when calling a collection resource or an individual resource.

The parameters will be flagged in the resource help section as Parameters as opposed to Filters. Parameters always begin with an underscore "_". Here are some of the current parameters available:

Name Valid Resources Description
_rows Collection Resources How many rows of data to return per page
_page Collection Resources Which page of data to return.
_hideLinks All resources Hides all navigation links in resulting resources.

HTTP Requests and Methods

Using the Doculicious API is a simple matter of making HTTP requests to different resources using the standard HTTP methods. Below is a list of the available methods and what they mean when used with the Doculicious API:

Method Description
GET Use to retrieve the resource that is identifed by the request URI. This can be a particular entry made to one of your templates, a template itself or a list of elements that make up a template.
POST Use to add a new resource to a collection of resources. For example, to add a new entry for a particular template, you would POST to the entries collection URI for a specific template.
DELETE This method is used to delete a particular resource.
PUT Is used to update a specific resource with a new value. It will completely replace the old value with the new value.
The resources section will explain the available methods for each method.


Using POST for DELETE or PUT

Some clients do not support the use of the DELETE or the PUT methods. A work around we've implemented is the use of the POST method with a query string containing _method=put or _method=delete. Our system will then convert to the stated method.

HTTP Status Codes

Each request you make to the Doculicious API will recieve a particular HTTP status code upon completion.  The table below lists them all:

Code Name Description What will return this?
200 OK  The request has succeeded.
  • GET requests which successfully return a representation of a resource.
  • PUT requests that successfully update a resource.
  • DELETE requests that successfully remove a resource.
201 Created The request has been fulfilled and resulted in a new resource being created.
  • POST requests which successfully create a new resource.
400 Bad Request Some part of the request you made was incomrehensible to the server.
  •  An error message will be returned containing more detail on what caused the issue.
403 Forbidden There was a problem authenticating your request.
404 Not Found The requested resource could not be found.
405 Method Not Allowed The method used is invalid for the resource.
500 Internal Server Error We caused an error.
501 Not Implemented The resource and method you requested have not yet been implemented.

Error Messages

If an API request results in an error, the HTTP reply will:

  • contain an error resource that is in the format specified by the request. If format is invalid or not JSON or XML the error message will be in JSON format.
  • have a Content-Type appropriate for the format requested. If the format is invalid, the Content-Type will be text/plain.
  • contain an appropriate 3xx, 4xx, 5xx HTTP status code.

List of error codes

Here are some examples of error responses:

Error Code HTTP Status Code Message
AccessDenied 403 - Forbidden Access Denied.
AuthenticationCredentialsMissing 403 - Forbidden No Authentication details were found with your request. Please ensure that you are sending your API Access ID and Secret API Access Key (if required) correctly.
InternalError 500 - Internal Server Error We encountered an internal error. Please try again later.
InvalidAPIAccessId 403 - Forbidden The Doculicious API Access ID you provided does not exist in our database.
InvalidElementValue 400 - Bad Request The element value you passed through is invalid.
InvalidFilter 400 - Bad Request A filter you passed to this resource is invalid.
InvalidJSON 400 - Bad Request The JSON you passed through to this resource is invalid.
InvalidParameter 400 - Bad Request A parameter you passed to this resource is invalid.
InvalidPropertyValue 400 - Bad Request The value you passed to this property resource is invalid. Please check the accepted data types for this property.
InvalidRepresentationFormat 400 - Bad Request The representation format requested is invalid for this method. Check that the file-extension you are using is a valid one for this method.
InvalidXML 400 - Bad Request The XML you passed through to this resource is invalid.
MethodNotAllowed 405 - Method Not Allowed That method is not allowed against this resource.
NoSuchResource 404 - Not Found The resource you are trying to reach could not be found.
(Note: This will be returned when filtering a collection causes no resources to be returned, even though the unfiltered collection contains resources.)
NotAuthorised 403 - Forbidden You are not authorised to access or interact with the requested resource.
NotImplemented 501 - Not Implemented The resource and method you requested have not yet been implemented.
SchemeNotAllowed 403 - Forbidden That scheme is not allowed against this resource. You must use HTTPS to access this resource.
TemplateInactive 400 - Bad Request The Template you are trying to act on is inactive and cannot be used for this purpose.
TemplateSettingsIncorrect 400 - Bad Request There is a problem with one of the template settings. (Note: More specific information should be provided in each individual error message)
UnsafeResourceCall 403 - Forbidden Requests to HTTP resources MUST not contain an API Secret Key. This should only be sent using HTTPS requests.


<?xml version="1.0" encoding="UTF-8"?>
    <message>The supplied APIAccessID was not found in our system.</message>



        "message":"The supplied APIAccessID was not found in our system.",