Forms

Forms are the core element of Forms Live — they allow you to create, manage, and share document templates with your contacts and clients. On this page, we'll dive into the different form endpoints you can use to manage forms programmatically. We'll look at how to query, create, update, and delete forms.

The form model

The form model contains all the information about your forms, including template version, name, status, and associated user details.

Properties

  • Name
    id
    Type
    integer
    Description

    Unique identifier for the form.

  • Name
    template_version_id
    Type
    integer
    Description

    Unique identifier for the template version associated with the form.

  • Name
    agency_id
    Type
    integer
    Description

    Unique identifier for the agency associated with the form.

  • Name
    user_id
    Type
    integer
    Description

    Unique identifier for the user who created the form.

  • Name
    name
    Type
    string
    Description

    The name of the form.

  • Name
    template
    Type
    boolean
    Description

    Indicates whether the form is a template.

  • Name
    finalised
    Type
    boolean
    Description

    Indicates whether the form has been finalised.

  • Name
    private
    Type
    boolean
    Description

    Indicates whether the form is private.

  • Name
    created
    Type
    timestamp
    Description

    Timestamp of when the form was created.

  • Name
    updated
    Type
    timestamp
    Description

    Timestamp of when the form was last updated.

  • Name
    given_name
    Type
    string
    Description

    First name of the form owner.

  • Name
    surname
    Type
    string
    Description

    Last name of the form owner.

  • Name
    template_cost
    Type
    integer
    Description

    The cost of the template in cents.

  • Name
    template_id
    Type
    integer
    Description

    Unique identifier for the template used.

  • Name
    template_name
    Type
    string
    Description

    The name of the template used.

  • Name
    template_code
    Type
    string
    Description

    The code identifier for the template.

  • Name
    template_instruction_pages
    Type
    integer
    Description

    Number of instruction pages in the template.

GET/forms/

List all forms

This endpoint allows you to retrieve a paginated list of all your forms. By default, a maximum of one page of forms is shown.

Optional attributes

  • Name
    page
    Type
    integer
    Description

    Page number for pagination. Default is 1 if not specified.

  • Name
    query
    Type
    string
    Description

    Filter forms by name based on the passed query value.

Request

GET
/forms/
curl https://app-api.reiformslive.com.au/forms/ \
  --request GET \
  --header "Authorization: Basic YTlkOWIwYItNGY4Yi1hYTQxLTI5NzZmMTcyZmEyMQ=="

Response

[
  {
    "id": 1,
    "template_version_id": 1,
    "agency_id": 1,
    "user_id": 1,
    "name": "Important form",
    "template": false,
    "finalised": true,
    "private": false,
    "created": 1350966273,
    "updated": 1350966303,
    "given_name": "John",
    "surname": "Doe",
    "template_cost": 80,
    "template_id": 144,
    "template_name": "Agency Template",
    "template_code": "T1000",
    "template_instruction_pages": 1
  },
  {
    "id": 2,
    // ...
  }
]
GET/forms/:id

Retrieve a form

This endpoint allows you to retrieve a specific form by providing the form id. Refer to the list at the top of this page to see which properties are included with form objects.

Request

GET
/forms/1
curl https://app-api.reiformslive.com.au/forms/1 \
  --request GET \
  --header "Authorization: Basic YTlkOWIwYItNGY4Yi1hYTQxLTI5NzZmMTcyZmEyMQ=="

Response

{
  "id": 1,
  "template_version_id": 1,
  "agency_id": 1,
  "user_id": 1,
  "name": "Important form",
  "template": false,
  "finalised": true,
  "private": false,
  "created": 1350966273,
  "updated": 1350966303,
  "given_name": "John",
  "surname": "Doe",
  "template_cost": 80,
  "template_id": 144,
  "template_name": "Agency Template",
  "template_code": "T1000",
  "template_instruction_pages": 1
}
PUT/forms/:id

Update a form name

This endpoint allows you to update the name of a form by providing the form id.

Required attributes

  • Name
    name
    Type
    string
    Description

    The new name for the form.

Request

PUT
/forms/1
curl https://app-api.reiformslive.com.au/forms/1 \
  --request PUT \
  --header "Authorization: Basic YTlkOWIwYItNGY4Yi1hYTQxLTI5NzZmMTcyZmEyMQ==" \
  --data '{"name":"Updated Important Form"}'

Response

{
  "id": 1,
  "template_version_id": 1,
  "agency_id": 1,
  "user_id": 1,
  "name": "Updated Important Form",
  "template": false,
  "finalised": true,
  "private": false,
  "created": 1350966273,
  "updated": 1350966450,
  "given_name": "John",
  "surname": "Doe",
  "template_cost": 80,
  "template_id": 144,
  "template_name": "Agency Template",
  "template_code": "T1000",
  "template_instruction_pages": 1
}
POST/forms/

Create a form

This endpoint allows you to create a new form from a template.

Required attributes

  • Name
    template_id
    Type
    integer
    Description

    The identifier for the template to use.

  • Name
    name
    Type
    string
    Description

    The name for the new form.

Request

POST
/forms/
curl https://app-api.reiformslive.com.au/forms/ \
  --request POST \
  --header "Authorization: Basic YTlkOWIwYItNGY4Yi1hYTQxLTI5NzZmMTcyZmEyMQ==" \
  --data '{"template_id":144,"name":"New Important Form"}'

Response

{
  "id": 2,
  "template_version_id": 1,
  "agency_id": 1,
  "user_id": 1,
  "name": "New Important Form",
  "template": false,
  "finalised": false,
  "private": false,
  "created": 1350967000,
  "updated": 1350967000,
  "given_name": "John",
  "surname": "Doe",
  "template_cost": 80,
  "template_id": 144,
  "template_name": "Agency Template",
  "template_code": "T1000",
  "template_instruction_pages": 1
}
DELETE/forms/:id

Delete a form

This endpoint allows you to delete a form by providing the form id.

Request

DELETE
/forms/2
curl https://app-api.reiformslive.com.au/forms/2 \
  --request DELETE \
  --header "Authorization: Basic YTlkOWIwYItNGY4Yi1hYTQxLTI5NzZmMTcyZmEyMQ=="

Response

{
  "status": "success",
  "message": "Form deleted successfully"
}
GET/forms/:id/download/

Get form download token

This endpoint allows you to retrieve a unique download token for a form. This token is required to download the form as a PDF.

Request

GET
/forms/1/download/
curl https://app-api.reiformslive.com.au/forms/1/download/ \
  --request GET \
  --header "Authorization: Basic YTlkOWIwYItNGY4Yi1hYTQxLTI5NzZmMTcyZmEyMQ=="

Response

{
  "id": 1,
  "agency_id": 1,
  "ip": "127.0.0.1",
  "token": "00000000-0000-0000-0000-000000000000"
}
GET/download/:token/attach/

Download a form

This endpoint allows you to download a form as a PDF file using the download token obtained from the Get form download token endpoint.

URI Parameters

  • Name
    token
    Type
    string
    Description

    The unique download token for the form.

  • Name
    attach
    Type
    boolean
    Description

    If supplied, the PDF file will be downloaded instead of opened in the browser.

Request

GET
/download/00000000-0000-0000-0000-000000000000/attach/
curl https://app-api.reiformslive.com.au/download/00000000-0000-0000-0000-000000000000/attach/ \
  --request GET \
  --output "form.pdf"

// Returns a PDF file
POST/forms/:id/finalise

Finalise a form

This endpoint allows you to finalise a form by providing the form id. Once a form is finalised, it is locked and can no longer be edited.

Request

POST
/forms/1/finalise
curl https://app-api.reiformslive.com.au/forms/1/finalise \
  --request POST \
  --header "Content-Type: application/json" \
  --header "Authorization: Basic YTlkOWIwYItNGY4Yi1hYTQxLTI5NzZmMTcyZmEyMQ=="

Response

{
  "message": "The form has been finalised"
}
POST/forms/:id/duplicate

Duplicate a form

This endpoint allows you to duplicate a form by providing the form ID. You can specify a new name for the duplicated form and set whether it should be private.

Required attributes

  • Name
    name
    Type
    string
    Description

    Name of the duplicated form.

Optional attributes

  • Name
    private
    Type
    boolean
    Description

    Whether the form is private or not. If this property is not passed, the user's default preference will be used.

Returns

  • Name
    id
    Type
    integer
    Description

    Unique ID of the duplicated form.

  • Name
    template_version_id
    Type
    integer
    Description

    Unique ID of the template version of the template the form is made from.

  • Name
    agency_id
    Type
    integer
    Description

    Unique ID of the agency the form belongs to.

  • Name
    user_id
    Type
    integer
    Description

    Unique ID of the user that created the form.

  • Name
    name
    Type
    string
    Description

    Name of the duplicated form.

  • Name
    template
    Type
    boolean
    Description

    Returns true if the form is a template.

  • Name
    deleted
    Type
    boolean
    Description

    Returns true if the form is deleted.

  • Name
    finalised
    Type
    boolean
    Description

    Returns true if the form is finalised.

  • Name
    private
    Type
    boolean
    Description

    Returns true if the form is private.

  • Name
    created
    Type
    timestamp
    Description

    Unix timestamp of when form was created.

  • Name
    updated
    Type
    timestamp
    Description

    Unix timestamp of when form was updated.

Request

POST
/forms/1/duplicate
curl https://app-api.reiformslive.com.au/forms/1/duplicate \
  --request POST \
  --header "Content-Type: application/json" \
  --header "Authorization: Basic YTlkOWIwYItNGY4Yi1hYTQxLTI5NzZmMTcyZmEyMQ==" \
  --data '{
    "name": "Duplicated Form",
    "private": false
  }'

Response

{
  "id": 8454,
  "template_version_id": 83,
  "agency_id": 1,
  "user_id": 2,
  "name": "Duplicated Form",
  "template": false,
  "deleted": false,
  "finalised": false,
  "private": false,
  "created": 1354671153,
  "updated": 1354671153
}

Display and edit forms in an iframe

You can embed the Forms Live form editor within your own application using an iframe. This allows users to view and edit forms without leaving your workflow.

You must first use a deep-link token to authenticate before displaying a form in an iframe. See the Session documentation for details on obtaining deep-link tokens.

Controlling the toolbar

Use the allow parameter to control which toolbar buttons are displayed in the iframe. The minimum required buttons are:

  • save - Save form changes
  • close - Close the form editor
  • zoom-in - Zoom in on the form
  • zoom-out - Zoom out on the form

Additional recommended buttons:

  • finalise - Finalise the form
  • annexures - Manage form annexures
  • files - Manage form files
  • toggle-menu - Toggle the sidebar menu

Listening to iframe events

The iframe communicates with its parent window using window.postMessage(). Currently, the close event is supported, which fires when the user closes the form editor.

Embedding a form

<iframe 
  src="https://app.formslive.com.au/?x-token=<deep-link-token>#form/1234?allow=save,close,zoom-in,zoom-out,finalise,annexures,files,toggle-menu"
  width="100%"
  height="800px"
  frameborder="0">
</iframe>