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

Was this page helpful?