PlatoForms API API Reference

Welcome to PlatoForms Version 4 API documentation.

With our restful APIs, you can do these:

  • List your forms metadata or fields definition.
  • Get the submission metadata, raw data and generated PDF download URL.
  • Get all raw data of all revision for a submission.
  • Download the generated PDF or attachment files.
  • Submit the form to generate the PDF file.
  • Manage Webhook

Except for API, we have a Webhook for form submission. By Webhook, you get a web request with the submission data 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.

Things worth knowing:

  • Some API requests need the proper form permissions. If you got any permission denied issue only for some particular requests, checking if that form has the correct permission.

  • All the date time format is yyyy-mm-dd'T'HH:MM:SS'Z', for example, 2017-06-28T04:02:47Z.

  • Our API is Swagger compatible; You can directly try our API from its swagger UI

API Endpoint
https://api.platoforms.com/v4
Contact: hello@platoforms.com
Request Content-Types: application/json
Response Content-Types: application/json
Schemes: https
Version: v4

Authentication

NoExpiryToken

in
header
name
Authorization
type
apiKey

Oauth2

authorizationUrl
https://api.platoforms.com/v4/oauth2/authorize
introspectUrl
https://api.platoforms.com/v4/oauth2/introspect
revokeUrl
https://api.platoforms.com/v4/oauth2/revoke_token
scopes
read

Read your forms and submissions

write

Read and Write forms

tokenUrl
https://api.platoforms.com/v4/oauth2/token
type
oauth2

Session

type
HTTPSession

download

Download Attachment

GET /download/submission/attach/{submission_identifier}/{attach_identifier}/

This download request needs the authentication, i.e, OAuth2, API Token or HTTPSession. It needs Submission Viewer permission.

This request needs the Form Submission Viewer Permission.

attach_identifier: string
in path

(no description)

submission_identifier: string
in path

(no description)

200 OK

Download PDF

GET /download/submission/pdf/{submission_identifier}/{pdf_identifier}/

This download request needs the authentication, i.e, OAuth2, API Token or HTTPSession. It needs Submission Viewer permission.

This request needs the Form Submission Viewer Permission.

pdf_identifier: string
in path

(no description)

submission_identifier: string
in path

(no description)

200 OK

Download Signature

GET /download/submission/signature/{submission_identifier}/{fid}/

This download request needs the authentication, i.e, OAuth2, API Token or HTTPSession. It needs Submission Viewer permission.

This request needs the Form Submission Viewer Permission.

fid: string
in path

(no description)

submission_identifier: string
in path

(no description)

200 OK

form

Get a Form Metadata

GET /form/{form_identifier}/

Get a form metadata by ID. The metadata does not include the fields definition.

This request needs the Form Editor Permission.

form_identifier: string
in path

(no description)

200 OK

Form

Response Example (200 OK)
{
  "id": "string",
  "name": "string",
  "is_published": "string",
  "published_version": "string",
  "current_version_submission": "string",
  "total_submission": "string",
  "published_url": "string",
  "pdf": {
    "id": "string",
    "filename": "string"
  },
  "modified_date": "string (date-time)",
  "created_date": "string (date-time)"
}

Get a Form Fields Definition

GET /form/{form_identifier}/fields/

Get all fields definition by form ID.

This request needs the Form Editor Permission.

form_identifier: string
in path

(no description)

200 OK

Form Fields Definitions

Response Example (200 OK)
{
  "id": "string",
  "name": "string",
  "published_version": "string",
  "published_date": "string (date-time)",
  "form_fields": [
    {
      "id": "string",
      "type": "string",
      "label": "string",
      "help_text": "string",
      "placeholder": "string",
      "required": "boolean",
      "pdf_page_number": "integer",
      "format_rules": "string",
      "validators": "string",
      "options": "string"
    }
  ]
}

Get Submissions Metadata for a Form

GET /form/{form_identifier}/submissions/

Return list of all submissions of the specified form. Note, this response doesn't include submission data. If you want to view the submission data, using /submission/:submission_id request to get the details.

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, OAuth2, 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 be duplicated with different forms.

This request needs the Form Submission Viewer Permission.

The result is paginated, using resultsperpage and page in URL to decide how many submissions returned by the given page number. If the parameter has keywords, the result will do searching query. Note, a form does not have any searchable fields by default, you must set the searchable fields from the submission page.

Optional url parameters:

  • ?sort=[id | submitted_date | modified_date | created_date | ... ]; Any fields can add - to indicate sort in descending. For example -modified_date means from latest (higher value) to older (lower value).
  • ?keywords=[some keywords to search fields]
  • ?resultsperpage=[result per page]
  • ?page=[page number]
form_identifier: string
in path

(no description)

Form Submission List

Response Example (200 OK)
{
  "total_count": "integer",
  "page": "integer",
  "total_pages": "integer",
  "results_per_page": "integer",
  "submissions": {
    "id": "string",
    "submit_date": "string (date-time)",
    "submit_revision": "string",
    "published_form_revision": "integer",
    "submit_form_url": "string",
    "form": {
      "id": "string",
      "name": "string"
    },
    "attachments": {
      "id": "string",
      "field_name": "string",
      "file_name": "string",
      "url": "string",
      "sharing_creator_url": "string",
      "size": "string"
    },
    "pdf": {
      "id": "string",
      "template_id": "string",
      "display_name": "string",
      "name": "string",
      "url": "string",
      "sharing_creator_url": "string"
    },
    "submit_data": {
      "id": "string",
      "type": "string",
      "label": "string",
      "value": "string",
      "raw": [
        {
          "id": "string",
          "value": "string"
        }
      ]
    }
  },
  "id": "string",
  "name": "string"
}

Get Webhook Submissions

GET /form/{form_identifier}/webhook/

The response returns a list of specified form submissions. This API has the exact same response with our webhook polling. You can use this API to test your webhook application.

form_identifier: string
in path

(no description)

Form Submission List with Submission Data

Response Example (200 OK)
{
  "id": "string",
  "submit_date": "string (date-time)",
  "submit_revision": "string",
  "published_form_revision": "integer",
  "submit_form_url": "string",
  "form": {
    "id": "string",
    "name": "string"
  },
  "attachments": {
    "id": "string",
    "field_name": "string",
    "file_name": "string",
    "url": "string",
    "sharing_creator_url": "string",
    "size": "string"
  },
  "pdf": {
    "id": "string",
    "template_id": "string",
    "display_name": "string",
    "name": "string",
    "url": "string",
    "sharing_creator_url": "string"
  }
}

forms

Get Forms

GET /forms/

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/v4/forms?status=draft.

This request needs the Form Editor Permission.

200 OK

Form List

type
Response Example (200 OK)
[
  {
    "id": "string",
    "name": "string",
    "is_published": "string",
    "published_version": "string",
    "current_version_submission": "string",
    "total_submission": "string",
    "published_url": "string",
    "pdf": {
      "id": "string",
      "filename": "string"
    },
    "modified_date": "string (date-time)",
    "created_date": "string (date-time)"
  }
]

me

me

Get Login User Information

GET /me/

A helper API to return the API login user name and email.

200 OK

sharing

Create Attachment Sharing URL

GET /sharing/submission/attach/{submission_identifier}/{attach_identifier}/

This request needs Submission Viewer permission.

This request returns a sharing URL which can download Attachment without authentication.

The sharing URL is expired in 24 hours by default. You can change the expiry time with URL parameter ?expired=_time_to_expire_ at the creating sharing URL. The time format is the number plus the unit m, h, d, i.e, minutes, hours or days. For example, ?expired=2h will make the created sharing URL expired in 2 hours. If ?expired=0, the sharing URL never expire.

attach_identifier: string
in path

(no description)

submission_identifier: string
in path

(no description)

200 OK

Create PDF Sharing URL

GET /sharing/submission/pdf/{submission_identifier}/{pdf_identifier}/

This request needs Submission Viewer permission.

This request returns a sharing URL which can download PDF without authentication.

The sharing URL is expired in 24 hours by default. You can change the expiry time with URL parameter ?expired=_time_to_expire_ at the creating sharing URL. The time format is the number plus the unit m, h, d, i.e, minutes, hours or days. For example, ?expired=2h will make the created sharing URL expired in 2 hours. If ?expired=0, the sharing URL never expire.

pdf_identifier: string
in path

(no description)

submission_identifier: string
in path

(no description)

200 OK

submission

Get Submission Revision Detail

GET /submission/rev/{submission_identifier}/

Return list of all Submission Revision detail by submission ID. The detail include the metadata and submission data.

submission_identifier: string
in path

(no description)

200 OK

Submission All Revisions History

Response Example (200 OK)
{
  "id": "string",
  "total_revision": "integer",
  "histories": {
    "id": "string",
    "submit_date": "string (date-time)",
    "submit_revision": "string",
    "published_form_revision": "integer",
    "submit_form_url": "string",
    "form": {
      "id": "string",
      "name": "string"
    },
    "attachments": {
      "id": "string",
      "field_name": "string",
      "file_name": "string",
      "url": "string",
      "sharing_creator_url": "string",
      "size": "string"
    },
    "pdf": {
      "id": "string",
      "template_id": "string",
      "display_name": "string",
      "name": "string",
      "url": "string",
      "sharing_creator_url": "string"
    }
  }
}

Get Submission Detail

GET /submission/{submission_identifier}/

Return Submission Detail by submission ID. The detail include the metadata and submission data.

submission_identifier: string
in path

(no description)

Submission

Response Example (200 OK)
{
  "id": "string",
  "submit_date": "string (date-time)",
  "submit_revision": "string",
  "published_form_revision": "integer",
  "submit_form_url": "string",
  "form": {
    "id": "string",
    "name": "string"
  },
  "attachments": {
    "id": "string",
    "field_name": "string",
    "file_name": "string",
    "url": "string",
    "sharing_creator_url": "string",
    "size": "string"
  },
  "pdf": {
    "id": "string",
    "template_id": "string",
    "display_name": "string",
    "name": "string",
    "url": "string",
    "sharing_creator_url": "string"
  }
}

submissions

Get Submissions Detail for Custom Field

GET /submissions/custom/{custom_field}/{form_identifier}/

When you open a form, you can declare a Custom Field in URL. For example, https://form.platoforms.com/frcvsafq9?custom-field=my_value. For embedded script, you need to add data-custom-field attribute in

tag.

By this API request, you can get all submissions with this custom-field value, i.e, my_value.

This request needs the Form Submission Viewer Permission.

The result is paginated, using resultsperpage and page in URL to decide how many submissions returned by the given page number. If the parameter has keywords, the result will do searching query. Note, a form does not have any searchable fields by default, you must set the searchable fields from the submission page.

Optional url path parameter /:form_id/ if there is no form Id declared, it returns all submissions for this custom field.

Optional URL parameter:

  • ?sort=[id | submitted_date | modified_date | created_date | ... ]; Any fields can add - to indicate sort in descending. For example -modified_date means from latest (higher value) to older (lower value).
  • ?keywords=[the keywords to search fields]
  • ?resultsperpage=[result per page]
  • ?page=[page number]
custom_field: string
in path

(no description)

form_identifier: string
in path

(no description)

Custom Submission List

Response Example (200 OK)
{
  "total_count": "integer",
  "page": "integer",
  "total_pages": "integer",
  "results_per_page": "integer",
  "submissions": {
    "id": "string",
    "submit_date": "string (date-time)",
    "submit_revision": "string",
    "published_form_revision": "integer",
    "submit_form_url": "string",
    "form": {
      "id": "string",
      "name": "string"
    },
    "attachments": {
      "id": "string",
      "field_name": "string",
      "file_name": "string",
      "url": "string",
      "sharing_creator_url": "string",
      "size": "string"
    },
    "pdf": {
      "id": "string",
      "template_id": "string",
      "display_name": "string",
      "name": "string",
      "url": "string",
      "sharing_creator_url": "string"
    },
    "submit_data": {
      "id": "string",
      "type": "string",
      "label": "string",
      "value": "string",
      "raw": [
        {
          "id": "string",
          "value": "string"
        }
      ]
    }
  }
}

submit

Submit Form

POST /submit/form/{form_identifier}/

With this API, you can submit payload to the form. It is exactly the 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 /v4/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 the same format with /v4/submission/:submission_id response, except the uploaded file(Our API don't support upload attachment yet). If you cannot decide the data format how to submit a form, you can fill the form in a browser first, and retrieve that submission data by request /v4/submission/:submission_id. At last, you can simply copy its submit_data section as the payload to submit a new form.

In submit_data list, if the fields have raw field, it only accept data from this raw field and its value field will be ignored. This is true for Choice, Dropdown and text with form rules (e.g, date field). For Choice and Dropdown, only the id field is used as submitted data, i.e, the selected options in that choice or items in that dropdown. If the Choice field has other option, its ID is 0 and value is the other text input. For format rules fields, using the same id with field definition and value is the input text. Its placeholders are optional and ignored.

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 seconds delay. So, if an immediately submission listing request v4/form/:form_id/submissions may not contain this submission. To get its generated PDF, you can try a few seconds later, or the best way is set up a Webhook URL to monitor the submission event where can guarantee the PDF is created.

This request needs the Form Submitter Permission. If the form submitter permission is public user(default settings), to avoid any abuse use, this API permission falls back to form editor permission that means this API never can be used by anonymous users.

form_identifier: string
in path

(no description)

201 Created

webhooks

Get Form Webhooks

GET /webhooks/form/{form_identifier}/

Get all Webhooks by Form ID

form_identifier: string
in path

(no description)

200 OK

Register Webhook

POST /webhooks/form/{form_identifier}/

Create a Webhook

form_identifier: string
in path

(no description)

201 Created

Get Webhook

GET /webhooks/{web_hooks_id}/

Get Webhook by ID

web_hooks_id: string
in path

(no description)

200 OK

Unregister Webhook

DELETE /webhooks/{web_hooks_id}/

Delete Webhook by ID

web_hooks_id: string
in path

(no description)

204 No Content

Schema Definitions

FromPDF: object

id: string (at least 1 chars)
filename: string (1 to 128 chars)
Example
{
  "id": "string",
  "filename": "string"
}

From: object

id: string (at least 1 chars)
name: string
is_published: string
published_version: string
current_version_submission: string
total_submission: string
published_url: string
pdf: FromPDF
modified_date: string (date-time)
created_date: string (date-time)
Example
{
  "id": "string",
  "name": "string",
  "is_published": "string",
  "published_version": "string",
  "current_version_submission": "string",
  "total_submission": "string",
  "published_url": "string",
  "pdf": {
    "id": "string",
    "filename": "string"
  },
  "modified_date": "string (date-time)",
  "created_date": "string (date-time)"
}

Field: object

id: string (at least 1 chars)
type: string (at least 1 chars)
label: string
help_text: string
placeholder: string
required: boolean
pdf_page_number: integer
format_rules: string
validators: string
options: string
Example
{
  "id": "string",
  "type": "string",
  "label": "string",
  "help_text": "string",
  "placeholder": "string",
  "required": "boolean",
  "pdf_page_number": "integer",
  "format_rules": "string",
  "validators": "string",
  "options": "string"
}

FromField: object

id: string
name: string
published_version: string (at least 1 chars)
published_date: string (date-time)
form_fields: Field
Field
Example
{
  "id": "string",
  "name": "string",
  "published_version": "string",
  "published_date": "string (date-time)",
  "form_fields": [
    {
      "id": "string",
      "type": "string",
      "label": "string",
      "help_text": "string",
      "placeholder": "string",
      "required": "boolean",
      "pdf_page_number": "integer",
      "format_rules": "string",
      "validators": "string",
      "options": "string"
    }
  ]
}

FormInfo: object

id: string (at least 1 chars)
name: string
Example
{
  "id": "string",
  "name": "string"
}

SubmissionAttachment: object

id: string (at least 1 chars)
field_name: string (at least 1 chars)
file_name: string (at least 1 chars)
url: string
sharing_creator_url: string
size: string (at least 1 chars)
Example
{
  "id": "string",
  "field_name": "string",
  "file_name": "string",
  "url": "string",
  "sharing_creator_url": "string",
  "size": "string"
}

SubmissioPdf: object

id: string (at least 1 chars)
template_id: string (at least 1 chars)
display_name: string (at least 1 chars)
name: string (at least 1 chars)
url: string (at least 1 chars)
sharing_creator_url: string (at least 1 chars)
Example
{
  "id": "string",
  "template_id": "string",
  "display_name": "string",
  "name": "string",
  "url": "string",
  "sharing_creator_url": "string"
}

SubmissionRawData: object

id: string (at least 1 chars)
value: string
Example
{
  "id": "string",
  "value": "string"
}

SubmissionData: object

id: string (at least 1 chars)
type: string (at least 1 chars)
label: string | null
value: string | null
raw: SubmissionRawData | null
SubmissionRawData
Example
{
  "id": "string",
  "type": "string",
  "label": "string",
  "value": "string",
  "raw": [
    {
      "id": "string",
      "value": "string"
    }
  ]
}

SubmissionDataDetail: object

id: string (at least 1 chars)
submit_date: string (date-time)
submit_revision: string
published_form_revision: integer
submit_form_url: string | null
form: FormInfo
attachments: SubmissionAttachment
pdf: SubmissioPdf
submit_data: SubmissionData
Example
{
  "id": "string",
  "submit_date": "string (date-time)",
  "submit_revision": "string",
  "published_form_revision": "integer",
  "submit_form_url": "string",
  "form": {
    "id": "string",
    "name": "string"
  },
  "attachments": {
    "id": "string",
    "field_name": "string",
    "file_name": "string",
    "url": "string",
    "sharing_creator_url": "string",
    "size": "string"
  },
  "pdf": {
    "id": "string",
    "template_id": "string",
    "display_name": "string",
    "name": "string",
    "url": "string",
    "sharing_creator_url": "string"
  },
  "submit_data": {
    "id": "string",
    "type": "string",
    "label": "string",
    "value": "string",
    "raw": [
      {
        "id": "string",
        "value": "string"
      }
    ]
  }
}

FormSubmissionList: object

total_count: integer
page: integer
total_pages: integer
results_per_page: integer
submissions: SubmissionDataDetail
id: string (at least 1 chars)
name: string (at least 1 chars)
Example
{
  "total_count": "integer",
  "page": "integer",
  "total_pages": "integer",
  "results_per_page": "integer",
  "submissions": {
    "id": "string",
    "submit_date": "string (date-time)",
    "submit_revision": "string",
    "published_form_revision": "integer",
    "submit_form_url": "string",
    "form": {
      "id": "string",
      "name": "string"
    },
    "attachments": {
      "id": "string",
      "field_name": "string",
      "file_name": "string",
      "url": "string",
      "sharing_creator_url": "string",
      "size": "string"
    },
    "pdf": {
      "id": "string",
      "template_id": "string",
      "display_name": "string",
      "name": "string",
      "url": "string",
      "sharing_creator_url": "string"
    },
    "submit_data": {
      "id": "string",
      "type": "string",
      "label": "string",
      "value": "string",
      "raw": [
        {
          "id": "string",
          "value": "string"
        }
      ]
    }
  },
  "id": "string",
  "name": "string"
}

SubmissionDetail: object

id: string (at least 1 chars)
submit_date: string (date-time)
submit_revision: string
published_form_revision: integer
submit_form_url: string | null
form: FormInfo
attachments: SubmissionAttachment
pdf: SubmissioPdf
Example
{
  "id": "string",
  "submit_date": "string (date-time)",
  "submit_revision": "string",
  "published_form_revision": "integer",
  "submit_form_url": "string",
  "form": {
    "id": "string",
    "name": "string"
  },
  "attachments": {
    "id": "string",
    "field_name": "string",
    "file_name": "string",
    "url": "string",
    "sharing_creator_url": "string",
    "size": "string"
  },
  "pdf": {
    "id": "string",
    "template_id": "string",
    "display_name": "string",
    "name": "string",
    "url": "string",
    "sharing_creator_url": "string"
  }
}

SubmissionRev: object

id: string (at least 1 chars)
total_revision: integer
histories: SubmissionDetail
Example
{
  "id": "string",
  "total_revision": "integer",
  "histories": {
    "id": "string",
    "submit_date": "string (date-time)",
    "submit_revision": "string",
    "published_form_revision": "integer",
    "submit_form_url": "string",
    "form": {
      "id": "string",
      "name": "string"
    },
    "attachments": {
      "id": "string",
      "field_name": "string",
      "file_name": "string",
      "url": "string",
      "sharing_creator_url": "string",
      "size": "string"
    },
    "pdf": {
      "id": "string",
      "template_id": "string",
      "display_name": "string",
      "name": "string",
      "url": "string",
      "sharing_creator_url": "string"
    }
  }
}

CustomSubmissionList: object

total_count: integer
page: integer
total_pages: integer
results_per_page: integer
submissions: SubmissionDataDetail
Example
{
  "total_count": "integer",
  "page": "integer",
  "total_pages": "integer",
  "results_per_page": "integer",
  "submissions": {
    "id": "string",
    "submit_date": "string (date-time)",
    "submit_revision": "string",
    "published_form_revision": "integer",
    "submit_form_url": "string",
    "form": {
      "id": "string",
      "name": "string"
    },
    "attachments": {
      "id": "string",
      "field_name": "string",
      "file_name": "string",
      "url": "string",
      "sharing_creator_url": "string",
      "size": "string"
    },
    "pdf": {
      "id": "string",
      "template_id": "string",
      "display_name": "string",
      "name": "string",
      "url": "string",
      "sharing_creator_url": "string"
    },
    "submit_data": {
      "id": "string",
      "type": "string",
      "label": "string",
      "value": "string",
      "raw": [
        {
          "id": "string",
          "value": "string"
        }
      ]
    }
  }
}