Entries

Entries are the stored details of submissions made to your templates and forms. Below we will detail the URLs and Methods which allow you to:

Retrieve a collection of Entries
Retrieve a single Entry
Retrieve a property of a single entry
Update the properties of a single Entry
Create a new Entry

Retrieve a list of Entries

Returns the latest 20 entries for the specified <template_uid> using the defined <representation>

URL: https://api.doculicious.com/entries/<template_uid>.<representation>
Method: GET
Success Status Code: 200 - OK
Authentication: Required - See the API Key Authentication section
Representations & Return values:

Format	Content/Type	Returns
JSON	application/json	Returns a collection of entry resources in JSON format.
XML	application/xml	Returns a collection of entry resources in XML format.

Parameters/Filters:

Name	Type	Description
_rows	Parameter. Integer	Default: 20. Max: 100. The number rows to return for this entries collection.
_page	Parameter. Integer	Default: 1. The page to return for this entries collection.
elements._rows	Parameter. Integer	Default: 50. Max: 200. The number of rows that will be returned within the *elements* sub-collection.
elements._page	Parameter. Integer	Default: 1. The page to return for the *elements* sub-collection.
elements.readOnly	Filter. Boolean	Default: false. Filters the *elements* sub-collection on each elements "readOnly" property.
processed	Filter. Boolean	Filter on an entries "processed" property.
deleted	Filter. Boolean	Filters on an entries "deleted" property. Note: Deleted entries do not have any data associated with them, and can only return metadata about the entry.
createdDate	Filter. Timestamp	Filters on an entries "createdDate" property.
custom1	Filter. String	Filters on an entries "custom1" property.
custom2	Filter. String	Filters on an entries "custom2" property.

Examples:
Click here for working examples of this resource
Return in JSON format, the latest 50 entries between 12/Oct/2009 12:00:00 PM GMT and 13/Oct/2009 12:00:00 PM GMT for the template with an UID of ab1234cd5678ef90
https://api.doculicious.com/entries/ab1234cd5678ef90.json?_rows=50&createdDate__after=2009-10-12T12:00:00+00:00&createdDate__before=2009-10-13T12:00:00+00:00

Return the 2nd page of the previous query
https://api.doculicious.com/entries/ab1234cd5678ef90.json?_rows=50&page=2&createdDate__after=2009-10-12T12:00:00+00:00&createdDate__before=2009-10-13T12:00:00+00:00

Return the same as the first query above, but only for entries that have not been processsed
https://api.doculicious.com/entries/ab1234cd5678ef90.json?_rows=50&createdDate__after=2009-10-12T12:00:00+00:00&createdDate__before=2009-10-13T12:00:00+00:00&processed=false

Return the last 20 entries and filter the elements sub-collection of each entry to only retrieve 10 rows
https://api.doculicious.com/entries/ab1234cd5678ef90.json?_rows=20&elements._rows=10

Retrieve a single Entry

Returns a single entry from within the <template_uid> collection for the specified <entry_uid> using the defined <representation>

URL: https://api.doculicious.com/entries/<template_uid>/<entry_uid>.<representation>
Methods: GET
Success Status Code: 200 - OK
Authentication: Required - See the API Key Authentication section
Representations & Return values:

Format	Content/Type	Returns
JSON	application/json	Returns a single entry resource in JSON format.
XML	application/xml	Returns a single entry resource in XML format.
PDF	application/pdf	Returns a PDF document of the entry.

Parameters: None
Examples:
Return a single entry with an id of: zzzzzzzzzzzzzzzz, in JSON format from the template: yyyyyyyyyyyyyyyy collection
https://api.doculicious.com/entry/yyyyyyyyyyyyyyyy/zzzzzzzzzzzzzzzz.json

Return a single entry with an id of: zzzzzzzzzzzzzzzz, in PDF format from the template: yyyyyyyyyyyyyyyy collection
https://api.doculicious.com/entry/yyyyyyyyyyyyyyyy/zzzzzzzzzzzzzzzz.pdf

Retrieve a property of a single entry

Returns the value of the <property_name> of the specified <entry_uid> within the <template_uid> collection.

URL: https://api.doculicious.com/entries/<template_uid>/<entry_uid>/<property_name>.<representation>
Method: GET
Success Status Code: 200 - OK
Authentication: Required - See the API Key Authentication section
Representations & Return values:

Format	Content/Type	Returns
JSON	application/json	Returns a single propertyvalue in JSON format.
XML	application/xml	Returns a single entry resource in XML format.

Valid properties: Below is a list of the property names within an entry which can be retrieved using this resource:

Name	Type	Description
processed	Boolean	A True or False value that flags an entry as processed or not.
custom1	String	A custom text value with a maximum of 50 characters.
custom2	String	A custom text value with a maximum of 50 characters.
adminComment	String	A string of text to update

Parameters/Values: None.
Examples:
Gets the processed property of the entry with an id of: zzzzzzzzzzzzzzzz, within the the template: yyyyyyyyyyyyyyyy collection
https://api.doculicious.com/entry/yyyyyyyyyyyyyyyy/zzzzzzzzzzzzzzzz/processed.xml

curl -H 'authorization:DCS <apiAccessId>:<aipSecretAccessKey>' https://api.doculicious.com/entry/yyyyyyyyyyyyyyyy/zzzzzzzzzzzzzzzz/processed

curl -H 'authorization:DCS <apiAccessId>:<aipSecretAccessKey>' "A new comment" https://api.doculicious.com/entry/yyyyyyyyyyyyyyyy/zzzzzzzzzzzzzzzz/adminComment

Update the properties of a single Entry

Updates the <property_name> of the specified <entry_uid> within the <template_uid> collection with the data in the body of the request. Will return the property and its value using the defined <representation> on success.

URL: https://api.doculicious.com/entries/<template_uid>/<entry_uid>/<property_name>.<representation>
Method: PUT
Success Status Code: 200 - OK
Authentication: Required - See the API Key Authentication section
Representations & Return values: On a successful update, the entry resource will be returned in the body of the request.

Format	Content/Type	Returns
JSON	application/json	Returns a single property value in JSON format.
XML	application/xml	Returns a single property value in XML format.

Valid properties: Below is a list of the property names within an entry which can be updated using this resource:

Name	Type	Description
processed	Boolean	A True or False value that flags an entry as processed or not.
custom1	String	A custom text value with a maximum of 50 characters.
custom2	String	A custom text value with a maximum of 50 characters.
adminComment	String	A string of text to update

Parameters/Values: The body of the request must contain the value to be updated in plain text. Ie, the text "false" or "true" for boolean values (without quotes), or a string.
Examples:
Updates the processed property of the entry with an id of: zzzzzzzzzzzzzzzz, within the the template: yyyyyyyyyyyyyyyy collection
https://api.doculicious.com/entry/yyyyyyyyyyyyyyyy/zzzzzzzzzzzzzzzz/processed.xml

curl -H 'authorization:DCS <apiAccessId>:<aipSecretAccessKey>' -X PUT -d "true" https://api.doculicious.com/entry/yyyyyyyyyyyyyyyy/zzzzzzzzzzzzzzzz/processed

curl -H 'authorization:DCS <apiAccessId>:<aipSecretAccessKey>' -X PUT -d "A new comment" https://api.doculicious.com/entry/yyyyyyyyyyyyyyyy/zzzzzzzzzzzzzzzz/adminComment

Create a new entry

Creates a new entry for the specified <template_uid>, returning an entry resource upon success.

When using this method you must provide the correct element_uid for each element you want to populate with data. You can view the element_uids of a template from your dashboard, in the "api" section under the templates name. There you'll find a link to download a templates elements. Alternativley, you can use the template resource api to retrieve the elements of a template.

URL: https://api.doculicious.com/entries/<template_uid>.<representation>
Methods: POST
Success Status Code: 201 - Created
Authentication: Optional - See the API Key Authentication section
Accepted Element Values: Each element type accepts a different form of data. Below we outline the acceptable values for each type, and what happens if incorrect values are sent through:

Element Type	Data Type	Notes/Examples
TextBoxElement	String	Any string value. HTML is saved, but will be encoded when displayed.
RichTextBoxElement	String	Any string value. HTML is saved and will be rendered when displayed. Some dangerous HTML will be stripped.
ToggleBoxElement	String (Boolean)	True or False (case insensitive). (Any value other than True will be treated as False)
ImageBoxElement	String (Image ID)	The 16 character ID of an Image that you have access to. If the Image is not accessable by the account, or does not exist, an error response will be returned and the entry will NOT be created.

Note: If you pass through an ID that does not match an element ID in the template, an error is NOT thrown. That element and it's value is just ignored.

Representations & Return values:

Format	Content/Type	Returns
JSON	application/json	Returns a single entry resource in JSON format.
XML	application/xml	Returns a single entry resource in XML format.
PDF	application/pdf	Returns a PDF document of the entry.
HTML	text/html	Uses your template settings to return a confirmation message in HTML format or redirect to the "Redirect URL".

On a successful creation, the "Location" header field will contain the URI of the newly created resource.

Template Settings:

The template used to create the entry must be activated.
It's "Save entries" settings must be enabled on the dashboard.
If you have enabled notifications, they will still function as normal on each successful entry.
If you have disabled PDF download in the templates settings, choosing a representation of PDF will override this.
The Redirect, Redirect URL and Confirmation Message settings only work when the representation is set to HTML, where they will be used as the result of the request.

Parameters: There are multiple ways to send the data to create a new entry, and they corespond to the different content types that can be sent: xml, json and x-www-form-urlencoded. The syntax of each of these is detailed later. The following points are inportant to understand when using this resource:

To create a new entry you need to send through the ID and Value for each element in the template whose readOnly property is false, and for which you wish to change the default value of.
Trying to set the value of an element whose readOnly is true will have no effect.
If you leave out the ID and Value of an element the default value from the template will be used.
You can turn off Resource Security for individual template resources in the API section of your dashboard. Doing this means you will not have to pass through your API Access Secret Key, allowing you to easily make public HTML forms to create new entries for your templates.

All queries to this resource can also set the following parameters in the query string or as form fields if using HTML form.

Name	Type	Description
custom1	String	A Custom value up to 50 characters long stored against the entry.
custom2	String	A Custom value up to 50 characters long stored against the entry.
elements._rows	Integer	How many rows of element data should be returned on a successful creation. Defaults to 0, meaning only the created entry details will be returned.
elements._page	Integer	Which page of element data should be returned on a successful creation. Defaults to 1.

application/xml
You can supply an XML document that maps out all the elements and their values. You must provide the ID and Value of the element in a valid XML document, and set the content-type to application/xml. ie:

<?xml version="1.0" encoding="UTF-8"?>
<elements>
    <element>
        <id>xxxxxxxxxxxxxxxx</id>
        <value>A Text Value</value>
    </element>
    <element>
        <id>yyyyyyyyyyyyyyyy</id>
        <value>false</value>
    </element>     
</elements>

application/json
A JSON object can be sent in the body that contains the ID and Value of each element in a JSON Array, and the content-type of the request set to application/json. ie:

[ 
    {
        "id":"xxxxxxxxxxxxxxxx",
        "value":"A text Value"
    },
    {
        "id":"yyyyyyyyyyyyyyyy",
        "value":"false"
    }
]

application/x-www-form-urlencoded
You can send the element IDs and Values as form fields, allowing you to use a standard HTML form submit to create a new entry. Each element must be a form with an ID/Name equal to the ID of the element you want to update, preceded with the string "df_". The value of the field should be the value you want for that element: ie

df_xxxxxxxxxxxxxxxx=A Text Value
df_yyyyyyyyyyyyyyyy=false

Examples:

HTML
Using your own web form to create a new entry for one of your templates with a UID of ab1234cd5678ef90

<form action="https://api.doculicious.com/entries/ab1234cd5678ef90.xml" method="POST">
    <input type="hidden" id="_apiAccessId" name="_apiAccessId" value="aaabbbcccdddeee">
    <input type="text" id="df_f2bac67467de89ca" name="df_f2bac67467de89ca" value="My Value 1">
    <input type="text" id="df_a3cac964dade4cbb" name="df_a3cac964dade4cbb" value="My Value 2">
    <input type="Submit" id="Submit" name="Submit" value="Submit">
</form>

Please note, that you need to turn off Resource Security for the create entry action in the API settings for the templae. You can do this in under the API link of the template.

Bookmark/Search this post with

Help

Retrieve a list of Entries

Retrieve a single Entry

Retrieve a property of a single entry

Update the properties of a single Entry

Create a new entry