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

Welcome to PlatoForms API documentation.

We have a group of RESTful APIs to retrieve your forms metadata and submissions data. With these APIs, you can download generated PDF and save them into your local or server drive.

We also support webhook method. Once your form gets a new submission, the webhook notification will send to your URL immediately.

All APIs and Webhooks payload are in JSON format.

Authorisation

The PlatoForms API uses OAuth2 for authorisation. This allows PlatoForms users to authorises your application to access their PlatoForms account. When a user authorises an application, it will be granted the all APIs access.

Go to your profile page, open API Access tab, then clicking on “Add Application” to setup the OAuth2 access.

OAuth2 Endpoints

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

Form

Sample Response: GET /v1/forms

{
  "forms": [
    {
      "total_submission": 0, 
      "current_version_submission": 0, 
      "name": "sample.pdf", 
      "modified_date": "2017-06-28T04:02:47Z", 
      "published_version": 1, 
      "published_url": "https://form.platoforms.com/fr3uffwodvi/", 
      "created_date": "2017-04-19T05:52:17Z", 
      "pdf": [
        {
          "id": "pdwdt2zb1rp", 
          "name": "sample.pdf"
        }
      ], 
      "id": "fr3uffwodvi", 
      "is_published": true
    }, 
    {
      "total_submission": 8, 
      "current_version_submission": 1, 
      "name": "anno-freetext.pdf", 
      "modified_date": "2017-06-28T05:24:48Z", 
      "published_version": 7, 
      "published_url": "https://form.platoforms.com/fr1o5n9rs7t/", 
      "created_date": "2017-06-09T09:30:38Z", 
      "pdf": [
        {
          "id": "pdo4yvuoune", 
          "name": "anno-freetext.pdf"
        }
      ], 
      "id": "fr1o5n9rs7t", 
      "is_published": true
    }
  ]
}

GET

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

Get all available forms information.

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

GET

https://api.platoforms.com/v1/forms/:form_id

Get a form detail information.

Submissions

PDF id in submission is only unique against its form. May duplicated in different forms.

Sample Reponse: GET /v1/forms/:form_id/submissions

{
  "id": "fr1o5n9rs7t",
  "name": "anno-freetext.pdf",
  "submissions": [
    {
      "submit_date": "2017-06-20T07:30:41Z",
      "pdf": [
        {
          "url": "https://api.platoforms.com/v1/submissions/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/v1/submissions/pdf/sr76a4a6bc539444abb32798eb9f9f8312/pdo4yvuoune",
          "id": "170629001",
          "template_id": "pdo4yvuoune",
          "name": "anno-freetext.pdf"
        }
      ],
      "published_version": 7,
      "id": "sr76a4a6bc539444abb32798eb9f9f8312",
      "attachments": [
        {
          "url": "/v1/submissions/attach/sfhfu9a2hrj",
          "file_name": "Screen Shot 2017-06-21 at 4.09.24 pm.png",
          "field_name": "fid6",
          "id": "sfhfu9a2hrj",
          "size": 16175
        }
      ]
    }
  ]
}

GET

https://api.platoforms.com/v1/forms/:form_id/submissions

Get form submissions.

Note, pdf[].id 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 good idea to construct an unqiue and meanful file name by id+name if you want to save all generated PDF files of a form into same directory.

Sample Reponse: GET /v1/submissions/:submission_id

{
  "attachments": [
    {
      "url": "https://api.platoforms.com/v1/submissions/attach/sfhfu9a2hrj", 
      "file_name": "Screen Shot 2017-06-21 at 4.09.24 pm.png", 
      "field_name": "fid6", 
      "id": "sfhfu9a2hrj", 
      "size": 16175
    }
  ], 
  "form": {
    "id": "fr1o5n9rs7t", 
    "name": "anno-freetext.pdf"
  }, 
  "submit_date": "2017-06-28T05:25:21Z", 
  "published_version": 7, 
  "pdf": [
    {
      "url": "https://api.platoforms.com/v1/submissions/pdf/sr76a4a6bc539444abb32798eb9f9f8312/pdo4yvuoune", 
      "id": "170629001",
      "template_id": "pdo4yvuoune",
      "name": "anno-freetext.pdf"
    }
  ], 
  "id": "sr76a4a6bc539444abb32798eb9f9f8312"
}

GET

https://api.platoforms.com/v1/submissions/:submission_id

Get a submission metadata.

Submission Webhook Objects

[
  {
    "attachments": [
      {
        "url": "http://localhost:8000/api/v1/submissions/attach/sfhxsndx62c",
        "file_name": "Screen Shot 2017-06-22 at 10.44.16 am.png",
        "field_name": "fid6",
        "id": "sfhxsndx62c",
        "size": 282992
      }
    ],
    "form": {
      "id": "fr1o5n9rs7t",
      "name": "anno-freetext.pdf"
    },
    "submit_date": "2017-06-29T04:38:47Z",
    "published_version": 10,
    "pdf": [
      {
        "url": "http://localhost:8000/api/v1/submissions/pdf/srf0f7ce64a01743e6a1ee19a9424954e6/pdo4yvuoune",
        "id": "170629000",
        "template_id": "pdo4yvuoune",
        "name": "anno-freetext.pdf"
      }
    ],
    "id": "srf0f7ce64a01743e6a1ee19a9424954e6"
  },
  {
    "attachments": [
      {
        "url": "http://localhost:8000/api/v1/submissions/attach/sfacu66foxn",
        "file_name": "Screen Shot 2017-06-22 at 10.44.16 am.png",
        "field_name": "fid6",
        "id": "sfacu66foxn",
        "size": 282992
      }
    ],
    "form": {
      "id": "fr1o5n9rs7t",
      "name": "anno-freetext.pdf"
    },
    "submit_date": "2017-06-29T04:37:59Z",
    "published_version": 10,
    "pdf": [
      {
        "url": "http://localhost:8000/api/v1/submissions/pdf/sr7c37842f07cb488a8202f1d4723940ae/pdo4yvuoune",
        "id": "170629001",
        "template_id": "pdo4yvuoune",
        "name": "anno-freetext.pdf"
      }
    ],
    "id": "sr7c37842f07cb488a8202f1d4723940ae"
  }
]

GET

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

Returns a reverse-chronologically ordered list with same objects in Webhook Submission Event.

Download PDF or Attachment files

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/v1/submissions/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'

At submission JSON payload, you can find URLs to down the generated PDF or the attached files in form submission. The files are also protected by same OAuth2 mechanism.

GET

https://api.platoforms.com/v1/submissions/pdf/:submission_id/:pdf_id

Download generated PDF from a submission.

GET

https://api.platoforms.com/v1/submissions/attach/:attach_id

Download a uploaded attachment from a submission.

Webhooks

Register or Unregister webhook

Sample Request: Subscribe webhook POST (/v1/webhooks/form/:form_id):

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

Sample Response: Get all Webhooks (/v1/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/v1/webhooks/form/:form_id

Register a webhook URL.

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

GET

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

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

GET

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

Get this webhook information.

DELETE

https://api.platoforms.com/v1/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/v1/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/v1/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.