NAV
Python

Welcome

API Endpoint
https://api.platoforms.com

Datetime Format
yyyy-mm-dd’T’HH:MM:SS’Z’
Example: 2017-06-28T04:02:47Z

All APIs and Webhooks payload is in JSON format.

Welcome to PlatoForms Version 3 API documentation.

With our restful APIs, you can do these:

Except for API, we have the submission event Webhook method. By Webhook, you get a web request with the submission metadata once your form got a submission and create the PDF. That means you can synchronise the created PDF into your in-house system on time.

Authentication

The PlatoForms API supports three different authentication methods:

The authenticated API request has the same permission with your form permission settings. You set the form permission from our dashboard -> the form context menu -> Permission.

OAuth2

It has the industrial verified method to protect your API. It is safer but needs extra development effort on OAuth2 implementation.

It allows PlatoForms users to authorise your application to access their PlatoForms account. When a user authorises an application, it will be granted the all APIs access.

To setup OAuth2 application, go to your profile page, open API Access tab, then clicking on “Add Application” to set up the OAuth2 access.

OAuth2 Endpoints

Type Endpoint
Authorize https://api.platoforms.com/v3/oauth2/authorize
Fetch Token https://api.platoforms.com/v3/oauth2/token
Revoke Token https://api.platoforms.com/v3/oauth2/revoke_token
Introspect Token https://api.platoforms.com/v3/oauth2/introspect

Non-expiry Token

You can get a non-expiry token on your profile page, API Access tab. It is less safe as anyone gets that token can execute your API and get your data. But it is the easiest way to access API. With this token, your API request needs the header:

Authorization: Token [your_token_here]

Session

Session authentication is appropriate for AJAX clients that are running in the same session context as your website.

Form

Sample Response (GET):

List all Forms

/v3/forms

[
    {
        "id": "fr3uffwodvi",
        "name": "sample.pdf",
        "is_published": true,
        "published_version": 8,
        "current_version_submission": 1,
        "total_submission": 16,
        "published_url": "http://form.platoforms.com/fr3uffwodvi/",
        "pdf": {
            "id": "pdwdt2zb1rp",
            "filename": "sample.pdf"
        },
        "modified_date": "2018-06-03T06:50:49Z",
        "created_date": "2017-04-19T05:52:17Z"
    },
    {
        "id": "fr1o5n9rs7t",
        "name": "anno-freetext.pdf",
        "is_published": true,
        "published_version": 8,
        "current_version_submission": 12,
        "total_submission": 23,
        "published_url": "http://form.platoforms.com/fr1o5n9rs7t/",
        "pdf": {
            "id": "pdo4yvuoune",
            "filename": "anno-freetext.pdf"
        },
        "modified_date": "2017-12-27T13:35:31Z",
        "created_date": "2017-06-09T09:30:38Z"
    },
]

This group of API are HTTP GET requests. With them, you can list the forms, get a form metadata or get the fields definition of a form.

LIST ALL FORMS

https://api.platoforms.com/v3/forms

Get all available forms in your account.

By default, it only returns published forms. You can append optional parameters ?status=[draft|archived|all] to get the draft (unpublished), archived or all forms. For example, list all your draft forms by GET request to URL https://api.platoforms.com/v3/forms?status=draft.

A SINGLE FORM

https://api.platoforms.com/v3/form/:form_id

Get a form metadata by its ID.

Sample Response (GET):

List Form by ID fr3uffwodvi

/v3/form/fr3uffwodvi/fields

{
    "id": "fr3uffwodvi",
    "name": "sample.pdf",
    "is_published": true,
    "published_version": 8,
    "current_version_submission": 1,
    "total_submission": 16,
    "published_url": "http://form.platoforms.com/fr3uffwodvi/",
    "pdf": {
        "id": "pdwdt2zb1rp",
        "filename": "sample.pdf"
    },
    "modified_date": "2018-06-03T06:50:49Z",
    "created_date": "2017-04-19T05:52:17Z"
}

FORM FIELDS DEFINITION

https://api.platoforms.com/v3/form/:form_id/fields

Get a form definition information.

Sample Response (GET):

List all Forms /v3/form/fr3uffwodvi/fields

{
    "id": "fr3uffwodvi",
    "name": "sample.pdf",
    "published_version": "8",
    "published_date": "2018-06-03T06:34:38Z",
    "form_fields": [
        {
            "id": "fid2",
            "type": "PageSep",
            "label": "Car Rental Checklist",
            "help_text": "",
            "placeholder": null,
            "required": false,
            "pdf_page_number": 0,
            "format_rules": [],
            "validators": []
        },
        {
            "id": "fid14",
            "type": "TextTitle",
            "label": "<h2>Renter's section</h2>",
            "help_text": null,
            "placeholder": null,
            "required": false,
            "pdf_page_number": 0,
            "format_rules": [],
            "validators": []
        },
        {
            "id": "fid3",
            "type": "text",
            "label": "Full name",
            "help_text": "",
            "placeholder": "Full name",
            "required": true,
            "pdf_page_number": 0,
            "format_rules": [],
            "validators": []
        },
        {
            "id": "fid5",
            "type": "date",
            "label": "Date of Birth",
            "help_text": "yyyy/mm/dd",
            "placeholder": "Date of Birth",
            "required": true,
            "pdf_page_number": 0,
            "format_rules": [
                {
                    "content": "YYYY",
                    "input_type": "number",
                    "max_len": 4,
                    "min_len": 4
                },
                {
                    "content": "MM",
                    "input_type": "number",
                    "max_len": 2,
                    "min_len": 2
                },
                {
                    "content": "DD",
                    "input_type": "number",
                    "max_len": 2,
                    "min_len": 2
                }
            ],
            "validators": []
        },
        {
            "id": "fid9",
            "type": "number",
            "label": "Postcode",
            "help_text": "",
            "placeholder": "Postcode",
            "required": true,
            "pdf_page_number": 0,
            "format_rules": [],
            "validators": [
                {
                    "max": 10,
                    "type": "length",
                    "maxCond": "<"
                },
                {
                    "isWholeNumber": true,
                    "type": "number"
                }
            ]
        },
        {
            "id": "fid11",
            "type": "text",
            "label": "Email",
            "help_text": "",
            "placeholder": "Email",
            "required": true,
            "pdf_page_number": 0,
            "format_rules": [],
            "validators": []
        },
        {
            "id": "fid13",
            "type": "Signature",
            "label": "Signature",
            "help_text": "Draw your signature here",
            "placeholder": null,
            "required": true,
            "pdf_page_number": 0,
            "format_rules": [],
            "validators": []
        },
        {
            "id": "fid4",
            "type": "mtext",
            "label": "Visual Inspection",
            "help_text": "Please note any visible rips, stains, or scratches that appear on the carpets, seats, or dashboard.",
            "placeholder": "Visual Inspection",
            "required": true,
            "pdf_page_number": 0,
            "format_rules": [],
            "validators": []
        },
        {
            "id": "fid12",
            "type": "Choice",
            "label": "Inspect",
            "help_text": "",
            "placeholder": null,
            "required": true,
            "pdf_page_number": 0,
            "format_rules": [],
            "validators": [],
            "options": {
                "multiple_selection": true,
                "items": [
                    {
                        "id": 1,
                        "label": "I’ve inspected the car exterior/interior, and noted concerns below."
                    }
                ]
            }
        },
        {
            "id": "fid10",
            "type": "text",
            "label": "Phone",
            "help_text": "",
            "placeholder": "Phone",
            "required": true,
            "pdf_page_number": 0,
            "format_rules": [],
            "validators": []
        },
        {
            "id": "fid6",
            "type": "text",
            "label": "Address",
            "help_text": "",
            "placeholder": "Address",
            "required": true,
            "pdf_page_number": 0,
            "format_rules": [],
            "validators": []
        },
        {
            "id": "fid22",
            "type": "Dropdown",
            "label": "City",
            "help_text": "",
            "placeholder": "Select an Option",
            "required": true,
            "pdf_page_number": 0,
            "format_rules": [],
            "validators": [],
            "options": {
                "multiple_selection": false,
                "items": [
                    {
                        "id": 1,
                        "value": "",
                        "label": "Sydney"
                    },
                    {
                        "id": 2,
                        "value": "",
                        "label": "Melbourne"
                    }
                ]
            }
        },
        {
            "id": "fid8",
            "type": "text",
            "label": "State",
            "help_text": "",
            "placeholder": "State",
            "required": true,
            "pdf_page_number": 0,
            "format_rules": [],
            "validators": [
                {
                    "max": 6,
                    "maxCond": "<",
                    "minCond": "<",
                    "type": "length",
                    "min": 2
                }
            ]
        },
        {
            "id": "fid15",
            "type": "Choice",
            "label": "How to Contact",
            "help_text": "How to contact me",
            "placeholder": null,
            "required": true,
            "pdf_page_number": 0,
            "format_rules": [],
            "validators": [],
            "options": {
                "multiple_selection": false,
                "other": {
                    "placeholder": "Fax Number",
                    "id": 0,
                    "label": "Fax Me"
                },
                "items": [
                    {
                        "id": 1,
                        "label": "Text Message"
                    },
                    {
                        "id": 2,
                        "label": "Phone Call"
                    }
                ]
            }
        },
        {
            "id": "fid19",
            "type": "Captcha",
            "label": "Human Being verify",
            "help_text": "Verify you are a human",
            "placeholder": null,
            "required": true,
            "pdf_page_number": 0,
            "format_rules": [],
            "validators": []
        },
        {
            "id": "fid20",
            "type": "FileUpload",
            "label": "Upload Attachments",
            "help_text": "You can upload one or more files.",
            "placeholder": null,
            "required": true,
            "pdf_page_number": 0,
            "format_rules": [],
            "validators": []
        },
        {
            "id": "fid23",
            "type": "Choice",
            "label": "Source",
            "help_text": "",
            "placeholder": null,
            "required": true,
            "pdf_page_number": 0,
            "format_rules": [],
            "validators": [],
            "options": {
                "multiple_selection": true,
                "items": [
                    {
                        "id": 1,
                        "label": "Google"
                    },
                    {
                        "id": 2,
                        "label": "Flyer"
                    },
                    {
                        "id": 3,
                        "label": "Friends"
                    }
                ]
            }
        }
    ]
}

Form Submissions Metadata

This group HTTP GET API returns the metadata of form submissions. If you only want to download the PDF, these are a good choice. If you want to get the detail of submission data, please check out the next Submission Detail section.

PDF ID of submissions in response is only unique against its form. It may be duplicated in different forms.

Sample Reponse (GET):

List all submissions of a form.

/v3/form/:form_id/submissions

{
  "id": "fr1o5n9rs7t",
  "name": "anno-freetext.pdf",
  "total_count": 8,
  "total_pages": 1,
  "results_per_page": 20,
  "page": 1,
  "submissions": [
    {
      "submit_date": "2017-06-20T07:30:41Z",
      "pdf": [
        {
          "url": "https://api.platoforms.com/v3/submission/pdf/srcd77be84880f4b3f8d6f51c42c35b47b/pdo4yvuoune",
          "id": "170629001",
          "template_id": "pdo4yvuoune",
          "name": "anno-freetext.pdf"
        }
      ],
      "published_version": 4,
      "id": "srcd77be84880f4b3f8d6f51c42c35b47b",
      "attachments": []
    },
    {
      "submit_date": "2017-06-28T05:25:21Z",
      "pdf": [
        {
          "url": "https://api.platoforms.com/v3/submission/pdf/sr76a4a6bc539444abb32798eb9f9f8312/pdo4yvuoune",
          "id": "170629001",
          "template_id": "pdo4yvuoune",
          "name": "anno-freetext.pdf"
        }
      ],
      "published_version": 7,
      "id": "sr76a4a6bc539444abb32798eb9f9f8312",
      "attachments": [
        {
          "url": "https://api.platoforms.com/v3/submission/attach/sfhfu9a2hrj",
          "file_name": "Screen Shot 2017-06-21 at 4.09.24 pm.png",
          "field_name": "fid6",
          "id": "sfhfu9a2hrj",
          "size": 16175
        }
      ]
    }
  ]
}

GET ALL SUBMISSIONS OF THIS FORM

https://api.platoforms.com/v3/form/:form_id/submissions

Get all submissions of this form. This API response includes the generated PDF link and uploaded files link (if your form has the Upload Form fields). Either PDF or Attachments, they have 2 kinds of URL: url and sharing_creator_url. The former URL is protected by the same mechanism with API authentication, i.e, OAuth3, Token or Sessions. The sharing_creator_url is another way to download file: sending GET request to this sharing_creator_url, it returns a download URL that expires in 24 hours. With that download URL, you can download the files directly without permission. This sharing_creator_url is useful when you want to implement API request on the browser side.

Note, pdf[].id in response is only unique for its form. It may have duplicated ID in different forms. pdf[].name is same with its template PDF name.

It is a good idea to construct a unique and meaningful file name by id+name if you want to save all generated PDF files of a form into the same directory.

The result returns in pages. You can browse particular page or declare how many submissions in a page by these parameters:

page: The page to retrieve

resultsperpage: How many results in the page

LSIT WEBHOOK EVENT OBJECTS

https://api.platoforms.com/v3/forms/:form_id/webhook

Returns a reverse-chronologically ordered list of same objects in Webhook Submission Event of this form.

This group HTTP GET API requests can get the submitted data of a submission, or get all revisions data of a submission

Submission Detail

Sample Reponse (GET)

Get a submission detail submitted data.

/v3/submission/sr96abfc99e9d14d0cadc35143431c1ba5

{
    "attachments": [
        {
            "url": "http://api.platoforms.com/v2/submission/attach/sfoik2i6528",
            "file_name": "prd.sh",
            "sharing_creator_url": "http://api.platoforms.com/v2/sharing/submission/attach/sfoik2i6528",
            "field_name": "fid20",
            "id": "sfoik2i6528",
            "size": 3671
        }
    ],
    "form": {
        "id": "fr3uffwodvi",
        "name": "sample.pdf"
    },
    "submit_revision": 1,
    "submit_date": "2018-06-03T06:50:49Z",
    "submit_data": {
        "fid9": "5787",
        "fid8": "NSW",
        "fid3": "Jone Sabo",
        "fid13": "data:image/png;base64,iVBORw0KG...",
        "fid6": "608 Harris Street Ultimo ",
        "fid5": [
            "1980",
            "-",
            "12",
            "-",
            "09"
        ],
        "fid4": "The back mirror broken",
        "fid22": [
            {
                "1": "Sydney"
            }
        ],
        "fid23": [
            {
                "1": "Google"
            },
            {
                "3": "Friends"
            }
        ],
        "fid20": "sfoik2i6528",
        "fid15": [
            {
                "othertext": "Fax me at 04213113"
            }
        ],
        "fid12": [
            {
                "1": "I’ve inspected the car exterior/interior, and noted concerns below."
            }
        ],
        "fid11": "jone@email.com",
        "fid10": "4432123123"
    },
    "pdf": [
        {
            "url": "http://api.platoforms.com/v2/submission/pdf/sr96abfc99e9d14d0cadc35143431c1ba5/pdwdt2zb1rp",
            "sharing_creator_url": "http://api.platoforms.com/v2/sharing/submission/pdf/sr96abfc99e9d14d0cadc35143431c1ba5/pdwdt2zb1rp",
            "id": "180603016",
            "name": "sample.pdf",
            "template_id": "pdwdt2zb1rp"
        }
    ],
    "published_form_revision": 8,
    "id": "sr96abfc99e9d14d0cadc35143431c1ba5"
}

This group of API are HTTP GET requests. With them, you can list the forms or get the details of a submission.

GET A SUBMISSION DATA

https://api.platoforms.com/v3/submission/:submission_id

Get a submission data.

GET ALL REVISION DATA OF A SUBMISSION

https://api.platoforms.com/v3/submission/rev/:submission_id

It returns a list of revisions of this submission. Every revision has the same data format with a single submission data.

Search Form Submission

Sample Reponse (GET)

Search form submissions.

/v3/form/search/:form_id/submissions?keywords=:keywords

{
    "name": "anno-freetext.pdf",
    "total_count": 1,
    "total_pages": 1,
    "id": "frhs87s5crr",
    "results_per_page": 20,
    "submissions": [
        {
            "attachments": [],
            "submit_revision": 1,
            "submit_date": "2018-01-24T00:59:04Z",
            "pdf": [
                {
                    "url": "https://myform1.selectist.com/api/v3/submission/pdf/srfe9f4ff6450b422387fe69cab49c123a/pduvtxvwwem",
                    "sharing_creator_url": "https://myform1.selectist.com/api/v3/sharing/submission/pdf/srfe9f4ff6450b422387fe69cab49c123a/pduvtxvwwem",
                    "id": "180124003",
                    "name": "anno-freetext.pdf",
                    "template_id": "pduvtxvwwem"
                }
            ],
            "published_form_revision": 1,
            "id": "srfe9f4ff6450b422387fe69cab49c123a"
        }
    ],
    "page": 1
}

With this Get request, you can search the submission for a particular form. This request returns the metadata of form submissions that are in the same format with that form submissions request.

The result returns in pages. You can browse particular page or declare how many submissions in a page by these parameters:

page: The page to retrieve

resultsperpage: How many results in the page

The form searching is not enabled by default. You must login to your Dashboard and set up the searchable fields in the submission page.

Download the PDF

Sample code to download a generated PDF in the submission.

from requests_oauthlib import OAuth2Session

def submission_download():
    oauth = OAuth2Session(client_id, redirect_uri=redirect_uri, scope=['read', 'write'])
    authorization_url, state = oauth.authorization_url(auth_uri)
    print 'Please go to %s and authorize access.' % authorization_url

    authorization_response = raw_input('Enter the full callback URL')
    token = oauth.fetch_token(token_uri, authorization_response=authorization_response, client_secret=client_secret)

    r = oauth.get('https://api.platoforms.com/v3/submission/pdf/sr76a4a6bc539444abb32798eb9f9f8312/pdo4yvuoune')
    if r.status_code == 200:
        with open('/my_path/my.pdf', 'w') as f:
            for chunk in r.iter_content(1024*10):
                f.write(chunk)
        print 'done'

In submission request, it contains a URL of generated PDF. If your form has the Upload File field, it also has a list URL of attachment files. These URLs are also protected by our authorisation mechanism, i.e, OAuth2, Token or Session.

These requests are HTTP GET method.

DOWNLOAD PDF URL

https://api.platoforms.com/v3/submission/pdf/:submission_id/:pdf_id

Download generated PDF from a submission.

DOWNLOAD ATTACHMENT URL

https://api.platoforms.com/v3/submission/attach/:attach_id

Download an uploaded attachment from a submission.

Submit a Form

Payload to submit a form (POST)

/v3/submit/form/:form_id

{	
    "submit_data": {
        "fid9": "5787",
        "fid8": "NSW",
        "fid3": "Jone Sabo",
        "fid13": "data:image/png;base64,iVBORw....",
        "fid6": "608 Harris Street Ultimo ",
        "fid5": [
            "1980",
            "-",
            "12",
            "-",
            "09"
        ],
        "fid4": "The back mirror broken",
        "fid22": [
            {
                "1": "Sydney"
            }
        ],
        "fid23": [
            {
                "1": "Google"
            },
            {
                "3": "Friends"
            }
        ],
        "fid20": "data:plain/text;base64,iGxsq5....",
        "fid15": [
            {
                "othertext": "Fax me at 04213113"
            }
        ],
        "fid12": [
            {
                "1": "I’ve inspected the car exterior/interior, and noted concerns below."
            }
        ],
        "fid11": "jone@email.com",
        "fid10": "4432123123"
    }
}

POST

/v3/submit/form/:form_id

With this API, you can submit payload to the form. It is exactly same as a web form submission. You got the generated PDF notification email; The data is searchable on our submission CMS page; The submission has the revision, etc.

To get what the fields are in your form, using our Get Form Fields API request /v3/form/:form_id/fields which returns all fields ID, type, options(choice or drop-down), format rules(text fields), etc. With this information, you can construct what the submit form API payload.

TIP: This request uses same format with /v3/submission/:submission_id response, except the uploaded file. If you cannot decide the data format how to submit a form, you can fill the form in a browser first, and try to retrieve that submission data by request /v3/submission/:submission_id. At last, you can simply copy its submit_data section as the payload to submit a new form.

Except for text field, which is simply a "field_id": "text_value" pair, some particular format describe here:

All inputs are validated by this form validators which you set in our form designer. If any validations are failed, the submit request will return a response with the detail error message.

Note, for success response, you get the submission ID. However, as our PDF generation is an asychronised service, that means, the generation of PDF usually has a few of seconds delay. So, if a immediately submission listing request v3/form/:form_id/submissions may not contain this submission. To get its generated PDF, you can try a few of seconds later, or the best way is set up a Webhook URL to monitor the submission event where can guarantee the PDF is created.

Webhooks

Register or Unregister webhook

Sample Request (POST)

Subscribe webhook

/v3/webhooks/form/:form_id

{
    "name": "my webhook",
    "hook_url": "http://my.server/platoforms/hook"
}

Sample Response: Get all Webhooks (/v3/webhooks/form/*/):

{
  "webhooks": [
    {
      "id": 1, 
      "name": "hook1", 
      "hook_url": "http://hook.url.com", 
      "created_date": "2017-06-28T05:12:42Z"
    }, 
    {
      "id": 2, 
      "name": "my webhook", 
      "hook_url": "http://my.server/platoforms/hook", 
      "form": {
        "id": "fr1o5n9rs7t", 
        "name": "anno-freetext.pdf"
      }, 
      "created_date": "2017-06-28T05:18:03Z"
    }
  ]
}

To register a webhook, you can either

POST

https://api.platoforms.com/v3/webhooks/form/:form_id

Register a webhook URL.

:form_id can be * that means subscribe all forms submissions, e.g, https://api.platoforms.com/v3/webhooks/form/*/ will listen to the submissions to any of your forms.

GET

https://api.platoforms.com/v3/webhooks/form/:form_id

Get all webhooks on this form or all forms if :form_id is *.

GET

https://api.platoforms.com/v3/webhooks/:webhook_id

Get this webhook information.

DELETE

https://api.platoforms.com/v3/webhooks/:webhook_id

Remove this webhook.

You also can do this from your profile API Access page.

Webhook Submission Event

Sample webhook message:

[
  {
    "attachments": [
      {
        "field_name": "fid6",
        "file_name": "Screen Shot 2017-06-22 at 10.44.16 am.png",
        "id": "sflchuodyqe",
        "size": 282992,
        "url": "http://localhost:8000/api/v3/submissions/attach/sflchuodyqe"
      }
    ],
    "form": {
      "id": "fr1o5n9rs7t",
      "name": "anno-freetext.pdf"
    },
    "id": "sr29b6e5b677ff4da79df529cfdda5e51b",
    "pdf": [
      {
        "id": "170629002",
        "name": "anno-freetext.pdf",
        "template_id": "pdo4yvuoune",
        "url": "http://localhost:8000/api/v3/submissions/pdf/sr29b6e5b677ff4da79df529cfdda5e51b/pdo4yvuoune"
      }
    ],
    "published_version": 10,
    "submit_date": "2017-06-29T07:12:25Z"
  }
]

Sample Django Code listening the hook event:

import json
from django.http import HttpResponse
from django.views.decorators.csrf import csrf_exempt

@csrf_exempt
def submission_monitor(request):
    if request.method == 'POST':
        payload = json.loads(request.body)
        # here just simply print the webhook message in console
        print json.dumps(payload, sort_keys=True, indent=4, separators=(',', ': '))
        # Your application can response any content with the `HTTP 200` code.
        return HttpResponse('ok')

This webhook JSON message sends to you register URL immediately once a submission and its PDF are created. The message is a list of submission data.