Heading image
Heading icon Help

Applications - Technical Details for NestForms API

The following endpoints are currently available:

Authentication - Used to authenticate the member.

Access Token - Used to generate Access token out of the Code (after a successful authentication) or a Refresh Token.

Forms list - List of all member forms.

Report - Report detail for one form.

List of Relations - List of the members that are connected within your account.

Custom DB Tables - List of all Custom DB Tables within your account.

Custom DB Groups - List of all Custom DB rows including the data.

All API calls described on this page (excluding the Authentication and Access Token) requires the access token submitted in the authorization header.

 

OAuth Authentication #

URL: https://www.nestforms.com/api/authorize

This endpoint contains the following mandatory URL parameters:

client_id, response_type, state, scope and redirect_uri

  • client_id is the setting gathered from the Application Edit Page > Keys tab,
  • response_type is always a string 'code',
  • state is an oAuth2 random generated parameter
  • redirect_uri is where the page should return after a successful authentication or after rejection

When you redirect the visitor to this endpoint, the visitor is required to login first and then is asked to approve your request to access some parts of their account. After they make the decision, they are redirected back to the redirect_uri. Your website will receive a 'code' (used to retrieve the access token) and the original 'state' parameter.

 

OAuth Access Token #

URL: https://www.nestforms.com/api/access_token

This endpoint is used for acquiring an access token out of a received 'code' after redirection back to redirect_uri.

It also refreshes expired access tokens using a refresh token.

 

Forms List #

URL: https://www.nestforms.com/api/forms_list

Retrieves all non-archived forms the member has in their account.

This endpoint returns an array with objects containing following properties (empty properties won't be present):

  • form_id: The unique identifier of the form (int), used for all endpoints requiring a form,
  • name: The name of the form,
  • form_description: Text description for the form,
  • is_public: true if the form is set to be public (coming soon),
  • is_frequent: true if the form is set to be frequent,
  • reports_count: How many responses are present for the form,
  • awaiting_approval_count: How many responses are waiting for approval,
  • approved_count: How many approved reponses the form contain,
  • not_viewed_count: How many responses were not viewed yet,
  • brand: an object with some styling definition:
    • name: Name of the branding,
    • color_style: The style selected for the branding.
 

Report #

URL: https://www.nestforms.com/api/report/{form_id}

Retrieve all responses for the specified form. The maximum number of responses allowed in one request is 5000, you can use the query parameter 'page' to view older responses.

This endpoint returns an object with the following properties:

  • form: Same details as the Forms List returns for a single form,
  • form_items: Array of objects, definition of the form fields, each form field can contain the following details:
    • The key of the object is the form_item_id (used in the data),
    • name: The name of the field,
    • field_type: Type of the input,
    • options: Object with configuration (depends on the type of field),
    • page_num: Number of the page, where the form item should appear,
    • page_name: Name of the page,
    • pos: Position within the page (or within the form)
    • items: Array of objects with items to choose from:
      • name: The title for the option,
      • opts: Object with additional options for the item, 'opts' may be omitted if empty, can contain for example:
        • conditional: Array of values that applies to skip logic. Can contain p2 (stands for page2) or 12345 (plain number, stands for form_item_id 12345),
        • default: Array with one item of '1' if the answer is supposed to be the default option,
        • file_id: Array with the file ID associated with this answer
  • data: An array ot the responses themselves:
    • event_name: The name of the response,
    • last_modified: Response of the last modification time (UTC),
    • member_label: The member whom submitted this response,
    • <int>, <int>_<int>: The data itself, the first <int> is form_item_id, the possible second <int> is a subpage, starting with 0, where the data should appear (forms with repeatable sections only):
      • value: The filled-in value (may not be present for some form item types),
      • files: The images, audio or signature feature type - contains an array of objects with the following details:
        • file_url: How to access the file,
        • thumbnail_url: The preview image URL (not applicable for audio feature type)
      • comments: Comments & Images feature type only, contains an array of strings,
      • modified: The data modification date
    • subpages: Defines how many times a page was copied (forms with repeatable sections only):
      • The key is the page_num of form_item,
      • The value is how many copies exist
  • has_more_pages: True when there are further results after each page.
  • pages: Total number of pages in the form
 

List of Relations #

URL: https://www.nestforms.com/api/members

Retrieves all your relations.

This endpoint returns an object with the following properties:

  • member_id: The id of the relation
  • username: The member username
  • email: The member email address
  • forename: Member forename
  • surname: Member surname
  • relation_status: enum of the current status of the members connection to your account with the following values:
    • connected - the relation is set up correctly
    • invitation_sent - you have sent an invitation to the member
    • invitation_pending - the other member sent an invitation to you
    • ignored_sent - you clicked ignore relation
    • Ignored_recieved - the other member ignored you
 

Custom DB Tables #

URL: https://www.nestforms.com/api/customdb

Retrieves a list of Custom DB Tables within your account.

This endpoint returns an object with the following properties:

  • customdb_table_id: The ID of the Custom DB Table
  • member_id: The owner member id
  • name: Name of the table
  • import_settings: Some settings used during import (EG whether the Excel file contains data or headers in the first row)
  • options_json: Other options NestForms stores for internal operations - eg data for dispatch, some column definitions, etc)
  • created: The date and time of creation
  • modified: The date and time of last modification
  • columns: List of columns in this table with the following properties:
    • customdb_column_id: The Custom DB Column ID
    • customdb_handle_id: The Custom DB Handle ID
    • index: Column position
    • name: Column name
  • handles: List of handles in this table with following properties:
    • customdb_handle_id: The Custom DB Handle ID
    • level: The handle depth level
    • name: The handle name

URL: https://www.nestforms.com/api/customdb/:customdb_table_id (GET)

Retrieves a single Custom DB Table, with the same properties as above.

 

Custom DB Groups #

URL: https://www.nestforms.com/api/customdb/:customdb_table_id/groups (GET, POST)

Retrieves a list of Custom DB tables within your account. You can use the optional ‘listing_start’ parameter to start at a chosen item (each request returns 50 groups).

You can also POST to this endpoint, creating new Custom DB Groups.

This endpoint returns an object(s) with the following properties:

    • customdb_group_id: The Custom DB Group ID
    • customdb_table_id: The Custom DB Table ID
    • customdb_handle_id: The Custom DB Handle ID
    • parent_id: The Custom DB Group ID of the parent group
    • group_level: Level of the group
    • group_status: enum of the following possible status: 'visit','visited','approved','revisit' 
    • is_active: 0: deleted, 1: active
    • has_members_mapping: comma delimited list of Relation IDs
    • map_lat: GPS Latitude
    • map_lng: GPS Longitude
    • planned_datetime: The datetime for the next response
    • last_visit: The datetime of the last response
    • created: The date and time of creation
    • modified: The date and time of last modification
    • Items
      • customdb_item_id: The Custom DB Item ID
      • customdb_column_id: The Custom DB Column ID
      • value: The cell value 

API Custom DB Groups Modify:

URL: https://www.nestforms.com/api/customdb/:customdb_table_id/groups/:customdb_group_id (GET, PUT, DELETE)

GET: Retrieves a single group. Retrieves the same object structure as the API Custom DB Groups endpoint described above.

PUT: Modifies an existing group. Retrieves the same object structure as the API Custom DB Groups endpoint described above.

DELETE: deletes the group. Retrieves simple object with 

  • result: ‘success’
  • affected_rows: Number of changed items
 

Error responses #

In case any of the API calls result in an error, there is always an explanation of the error in the content and the call returns a HTTP response code 4XX.