< BACK TO BLOG

FormRead Web API Integration Developers Guide

For enterprise uses the API can be used by generating and Bearer Auth token.

Create the API tokens to allow third-party services to authenticate with our application on your behalf:

Copy the token generated in a secure place (it will only be shown once):

Create New Form

Request

POST /api/forms

curl --location --request POST 'https://formread.org/api/forms' \
    --header 'Accept: application/json' \
    --header 'Authorization: Bearer grqr7w3pZ4u7Kif7CJpICzhBitOFXbq4VvXfGvMA' \
    --form 'form_name="new form"' \
    --form 'custom_css="{ingest custom css to edit FormRead View}"'

Response

{
    id: 8,
    form_name: "new form",
    iframe_token: "6ifvCyEcjB3D5SGqtFmJ5eg0sPYNQfLoWCEgv7bb",
    created_at: "2022-02-28T21:22:55.000000Z",
    updated_at: "2022-02-28T21:22:55.000000Z"
}

Variable custom_css will allow to ingest css rules to edit FormRead look and add custom text, like eg:

#app-title::after{
    content: 'Your Tittle';
    color: white;
}
#app-subtitle::after{
    content: 'Your Custom sub-tittle Your Custom sub-tittle Your Custom sub-tittle';
    color: white;
}
#upload-from-cam{
    display: none;
}
#upload-from-system{
    background: lightblue;
}
#upload-from-csv{
    display: none;
}
#app > div.bg-gray-50.h-screen.overflow-auto > div > div{
    background-color: black;
}

Get Form by Id

Request

GET /api/forms/{form_id}

curl --location --request GET 'https://formread.org/api/forms/8' \
    --header 'Accept: application/json' \
    --header 'Authorization: Bearer kHMwPfhJC9rJyhR7h0L78j1OB9FXErF9JseFCXH9'

Response

{
    "id": 8,
    "form_name": "adsf",
    "thumbnail": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAFoAA...",
    "iframe_token": "po75a0pqut4fa16XWgdEP2qRDwnhgfiqP3H0Dij6",
    "created_at": "2022-02-28T21:22:55.000000Z",
    "updated_at": "2022-03-01T01:40:19.000000Z"
}

the thumbnail a src url that contains general img form:

Edit a Form

After a form is Created or GET it can be displayed in an Iframe using the iframe_token provided in the response (this token variates so make sure you GET your form before rendering the iframe)

Create also a script that listen to the events of the iframe like in the example below:

<!DOCTYPE html>
<html style="height: 100%">
<head>
    <meta charset="UTF-8">
    <title>Title</title>
</head>
<body style="height: 100%">

<iframe src="https://formread.org/{lang}/api/forms/{form_id}/edit/{iframe_token}/{read_only}"
        style="height: 100%; width: 100%"></iframe>

<script>
    window.addEventListener('message', function (e) {
        // if (e.origin !== 'https://formread.org') return;

        console.log(e.data.method)

        if (e.data.method === "editForm") {
            let formData = e.data.formData // data used to saved your form
            let schema = JSON.parse(e.data.schema)
            console.log(schema)
            console.log(formData)
        }
        if (e.data.method === "getResults") {
            let results = JSON.parse(e.data.results)
            console.log(results)
        }
        if (e.data.method === "rowResult") {
            let rowResult = JSON.parse(e.data.rowResult)
            console.log(rowResult)
        }

    });
</script>
</body>
</html>

Set lang variable to display the app commands in the desired language. Currently, we support english (en) , french (fr), spanish (es), brazilian portuguese (pt) or kazakh (kk)

Variable read_only can be set to 1 for disabling form editing or 0 to allow form editing

When users click on the save button, the editForm method will be triggered, there you have access to 2 variables:

formData variable will contain the encoded form attributes that can be sent using the Updateto save the changes made to your form:

the schema variable will let you know the fields created so far:

{
      "file_name": {
          "type": "text"
      },
      "BCR-0": {
          "type": "text"
      },
      "OCR-1": {
          "type": "text"
      },
      "OMR-2-0": {
          "type": "select",
          "options": ["0", "1", "2", "3", "4", "5", "6", "7", "8", "9"],
          "questionIndex": "0"
      },
      "OMR-2-1": {
          "type": "select",
          "options": ["0", "1", "2", "3", "4", "5", "6", "7", "8", "9"],
          "questionIndex": "1"
      },
      "OMR-2-2": {
          "type": "select",
          "options": ["0", "1", "2", "3", "4", "5", "6", "7", "8", "9"],
          "questionIndex": "2"
      }
  }

The schema variable is meant only for you to display some alerts to your users in case you are requiring mandatory area fields to be created:

When a user click on download results, the getResults method will be triggered, there you`ll get the result data in a JSON format so you can store then in your system

Also, you can get the row by row results with the rowResult method, that will be triggered each time a page is processed

Update Form

Request

GET /api/forms/{form_id}?_method=PUT

curl --location --request POST 'https://formread.org/api/forms/8?_method=PUT' \
--header 'Authorization: Bearer kHMwPfhJC9rJyhR7h0L78j1OB9FXErF9JseFCXH9' \
--form 'form_data="eyJ2dWV4X3N0YXRlIjp7ImZvcm1OYW1lIjoiYWRzZiIsImZvcm1zIjp7f
                   Swic2VsZWN0ZWRGb3JtSWQiOiIiLCJmb3JtUmVhZEFyZWFzIjp7IkJDUi
                   0wIjp7ImNvbHVtblBvc2l0aW9uIjoxLCJ3aWR0aCI6MC4xMTQ5NTA0NTM
                   0MDUzNTE2NCwiaGVpZ2h0IjowL...'
--form 'custom_css="{ingest custom css to edit FormRead View}"'

Response

{
    "id": 8,
    "form_name": "adsf",
    "iframe_token": "po75a0pqut4fa16XWgdEP2qRDwnhgfiqP3H0Dij6",
    "thumbnail": "data:image/png;base64,iVBORw0KGgoAAAANSUhEU...",
    "created_at": "2022-02-28T21:22:55.000000Z",
    "updated_at": "2022-03-01T02:30:14.000000Z"
}

Delete Form

Request

GET /api/forms/{form_id}

curl --location --request DELETE 'https://formread.org/api/forms/8' \
    --header 'Accept: application/json' \
    --header 'Authorization: Bearer kHMwPfhJC9rJyhR7h0L78j1OB9FXErF9JseFCXH9'

Response

Postman Collection Link

Click here to open postman link