All Collections
REST API Reference
Forms API
Forms API

The Forms API allows you to manipulate the forms of your organization in XML or JSON.

Xandy Strydom avatar
Written by Xandy Strydom
Updated over a week ago

Authentication

The API requires you to authenticate each call with your API token. Please see our authentication article for more information.

Base URL

The forms API is RESTful, operating on this base URL (note the HTTPS):

https://api.devicemagic.com/organizations/[organization_id]/forms

where your organization_id is evident from the URL to your dashboard when browsing app.devicemagic.com/organizations/[organization_id]/.

Retrieving All Forms

For an overview of all the forms belonging to your organization, issue an HTTP GET request to the Base URL.

https://api.devicemagic.com/organizations/[organization_id]/forms.(xml|json)

This will return a list of all your forms. e.g.

Request

https://api.devicemagic.com/organizations/1/forms.xml

Response

<?xml version="1.0"?>
<forms>
  <form>
    <id>2</id>
    <name>Sample Form Two</name>
    <namespace>http://www.devicemagic.com/xforms/4859c760-d9eb-012d-2595-123139016cf2</namespace>
    <version>1.04</version>
    <description/>
    <group>Unpublished</group>
   </form>
   <form>
     <id>1</id>
     <name>Simple Form</name>
     <namespace>http://www.devicemagic.com/xforms/simple</namespace>
     <version>1.0</version>
     <description/>
     <group>Unpublished</group>
  </form>
</forms>

And in JSON

Request

https://api.devicemagic.com/organizations/1/forms.json

Response

{
  "forms"=> 
     [ {"id"=>2,
        "namespace"=>"http://www.devicemagic.com/xforms/4859c760-d9eb-012d-2595-123139016cf2", 
        "version"=>"1.04", 
        "description"=>nil, 
        "group"=>"Unpublished"},
       {"id"=>1, 
        "namespace"=>
        "http://www.devicemagic.com/xforms/simple", 
        "version"=>"1.0", 
        "description"=>nil, 
        "group"=>"Unpublished"}
     ]
}

Fetching Form Definition

To fetch a form's definition, issue an HTTP GET request to:

https://api.devicemagic.com/organizations/[organization_id]/forms/[form_id].(xml|json)

This will return either the JSON or the XML body.

You may also optionally provide a version parameter.

For example:

Request:

https://api.devicemagic.com/organizations/1/forms/1.xml?version=1.03

Response:

<?xml version="1.03"?>
<h:html xmlns:h="http://www.w3.org/1999/xhtml" xmlns:dm="http://www.devicemagic.com/XMLSchemaDataTypes" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:ev="http://www.w3.org/2001/xml-events" xmlns="http://www.w3.org/2002/xforms">
  <h:head>
    <h:title>Untitled Form</h:title>
    <model>
      <instance xmlns="http://www.devicemagic.com/xforms/ns">
        <inputs>
          <Untitled_Question/>
        </inputs>
      </instance>
    </model>
  </h:head>
  <h:body>
    <input ref="Untitled_Question">
      <label>Untitled Question</label>
    </input> 
  </h:body>
</h:html>

And in JSON

Request

https://api.devicemagic.com/organizations/1/forms/1.json

Response

{
  "type": "root",
  "children": [{
    "identifier": "Untitled_Question",
    "title": "Untitled Question",
    "autoIdentifier": true,
    "type": "text"
  }],
  "title": "Untitled Form"
}

Creating a New Form

To create a new form, send an HTTP POST with the form definition to:

HTTP POST https://api.devicemagic.com/organizations/[organization_id]/forms

If you’re providing an XML definition for the form, set the content type in the request headers to application/xml :

Content-Type: application/xml

In the POST body, provide the XML definition:

<h:html
    xmlns='http://www.w3.org/2002/xforms'
    xmlns:dm='http://www.devicemagic.com/XMLSchemaDataTypes'
    xmlns:ev='http://www.w3.org/2001/xml-events'
    xmlns:h='http://www.w3.org/1999/xhtml'
    xmlns:xsd='http://www.w3.org/2001/XMLSchema'>
    <h:head>
        <h:title>Dummy Form</h:title>
        <model>
            <instance xmlns='http://www.devicemagic.com/xforms/dummy_form'>
                <untitled_form_1>
                    <alpha/>
                    <bravo/>
                </untitled_form_1>
            </instance>
        </model>
    </h:head>
    <h:body>
        <input ref='alpha'>
            <label>Alpha</label>
        </input>
        <input ref='bravo'>
            <label>Bravo</label>
        </input>
    </h:body>
</h:html>

On success you’ll receive a 201 Created, with a response body similar to this:

<form>
    <id>42</id>
    <namespace>http://www.devicemagic.com/xforms/dummy_form</namespace>
    <name>Dummy Form</name>
</form>

If the request fails, check the response header ‘Message’ for the reason. (Common issues include an invalid XML definition, or providing a namespace that is already in use.) For more information regarding common API responses, see this article.
​
JSON forms work similarly. Send the POST to the same URL, with content type application/json :

HTTP POST https://api.devicemagic.com/organizations/[organization_id]/forms
Content-Type: application/json

A JSON form definition as the POST body:

{
    "type": "root",
    "children": [
    {
        "identifier": "Free_Text_Question",
        "title": "Free Text Question",
        "autoIdentifier": true,
        "type": "text"
    },
    {
        "identifier": "Sketch_Question",
        "title": "Sketch Question",
        "autoIdentifier": true,
        "type": "sketch"
    } ],
    "title": "Dummy Form",
    "description": "Testing sample"
}   

And the 201 Created on success will include a body like:

{
    "id": 129,
    "namespace": "http://www.devicemagic.com/xforms/dummy_sample",
    "name": "Test Form"
}

As with XML, check the response header ‘Message’ for reasons if the creation fails.

Question Types

"text"
"boolean"
"select"
"date"
"time"
"datetime"
"decimal"
"integer"
"location"
"email"
"phone_number"
"image"
"signature"
"barcode"
"sketch"
"password"
"calculated"
"resource"

Updating an Existing Form

To update an existing form, send an HTTP PUT with the form definition to:

HTTP PUT https://api.devicemagic.com/organizations/[organization_id]/forms/[form_id]

If you’re providing an XML definition for the form, set the content type in the request headers to application/xml :

Content-Type: application/xml

In the PUT request body, provide the updated XML definition:

<h:html
    xmlns='http://www.w3.org/2002/xforms'
    xmlns:dm='http://www.devicemagic.com/XMLSchemaDataTypes'
    xmlns:ev='http://www.w3.org/2001/xml-events'
    xmlns:h='http://www.w3.org/1999/xhtml'
    xmlns:xsd='http://www.w3.org/2001/XMLSchema'>
    <h:head>
        <h:title>Some Form</h:title>
        <model>
            <instance xmlns='http://www.devicemagic.com/xforms/dummy_form'>
                <untitled_form_1>
                    <alpha/>
                    <bravo/>
                </untitled_form_1>
            </instance>
        </model>
    </h:head>
    <h:body>
        <input ref='alpha'>
            <label>Alpha</label>
        </input>
        <input ref='bravo'>
            <label>Bravo</label>
        </input>
    </h:body>
</h:html>

Use the same form namespace in the updated definition as was in the original.

On success you’ll receive a 202 Accepted, with a response body similar to this:

<form>
    <id>42</id>
    <namespace>http://www.devicemagic.com/xforms/dummy_form</namespace>
    <name>Some Form</name>
    <version>1.1</version>
</form>

If the request fails, check the response header ‘Message’ for the reason.

JSON forms work similarly. Send the PUT to the same URL, with content type application/json :

HTTP PUT https://api.devicemagic.com/organizations/[organization_id]/forms/[form_id]

Content-Type: application/json

A JSON form definition as the PUT body:

{
    "type": "root",
    "children": [
    {
        "identifier": "Free_Text_Question",
        "title": "Free Text Question",
        "autoIdentifier": true,
        "type": "text"
    },
    {
        "identifier": "Sketch_Question",
        "title": "Sketch Question",
        "autoIdentifier": true,
        "type": "sketch"
    } ],
    "title": "Dummy Form",
    "description": "Testing sample"
}   

And the 202 Accepted on success will include a body like:

{
    "id": 129,
    "namespace": "http://www.devicemagic.com/xforms/dummy_sample",
    "name": "Test Form",
    "version": "1.1"
}

As with XML, check the response header ‘Message’ for reasons if the update fails.

Deleting a Form

To delete a form, you need to send an HTTP DELETE to:

HTTP DELETE https://api.devicemagic.com/organizations/[organization_id]/forms/[form_id]

You’ll receive a 200 OK if the delete succeeded.

Updating a Form’s Group

To change the group to which a form belongs (e.g. publish/unpublished), send an HTTP POST to:

HTTP POST https://api.devicemagic.com/organizations/[organization_id]/forms/[form_id]/properties

You can update either via JSON or XML.

If you use XML, set the content type in the request headers to application/xml :

Content-Type: application/xml

And provide an XML body, with the required group name (which is case sensitive), as below:

<form_properties>
    <group>Unpublished</group>
</form_properties>

If you prefer JSON, set the content type in the request headers to application/json :

Content-Type: application/json

And use a JSON body as below:

{
    "group": "Unpublished"
}

Please note that the group name is case sensitive, and must exist within your organization.

On success you’ll receive a 200 OK. If the request fails, check the response header ‘Message’ for the reason.

Did this answer your question?