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.


Terminology #

  • ClientAuthorization: base64-encoded string containing client id and client secret separated by ‘:’ (colon)
  • AccessToken: token used for the Authorization header, Retrieved from the access_token endpoint.
  • Rest API principles: Responses are in JSON format. The input data is usually expected as standard GET or POST parameters (application/x-www-form-urlencoded)
    • GET: Getting the list or detail of the items.
    • POST: Inserting new items into the database.
    • PUT: Updating existing items in the database.
    • DELETE: Removing items from the database.

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
  • scope is a comma separated list of the scopes required for your application - see the full list of scopes available.
  • 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.


Same URL is also used for acquiring new Access Token (using the Refresh Token) - Refreshing the Access token

Send the POST request with following parameters: 

  • redirect_uri: YOUR REDIRECT URL
  • client_id: Client ID downloaded from the NestForms back end
  • client_secret: Client Secret downloaded from the NestForms back end
  • grant_type: refresh_token
  • refresh_token: Currently active refresh token

OAuth Access Token Example - from received Code

OAuth Access Token Example - from Refresh Token


Scopes #

Scopes are defining permissions that the API will allow to perform. A list of scopes need to be specified when authenticating into the NestForms API.

  • forms_access: main permission that enables displaying the form details, including a list of the related members, related brand and related images
  • reports_read: permission that will enable the display of responses
  • customdb_read: required to read CustomDB data
  • customdb_write: permission required to modify any CustomDB group and item data
  • remote_login: permission that enables your client to log into NestForms and then for example display the NestForms interface within an iFrame inside your intranet.



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.

Forms List example


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

Report example


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

Relations example


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.

CustomDB Tables list Example


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

CustomDB Tables Group List example

CustomDB Table Group Create example

CustomDB Table Group Edit example


Remote Login #

URL: https://www.nestforms.com/api/v2/members/me/remote_login_create

Generates a remote login token that can be used for one time login into your NestForms profile.


This endpoint returns an object with the following properties:

  • token: Remote login token that can be used for authentication using the following URL https://www.nestforms.com/remote-login/{token} 
    A Remote login token is valid for 24 minutes. Each token can be used only once.
  • link: Prepared link with the token

When using a remote login URL, the following REQUEST parameters can be used:

  • location: Controls where the user will be redirected to after login, the default is Dashboard.
  • allow_iframes: Allows the loading of NestForms inside the iframe, the default is false.
  • remove_page_header: Removes the NestForms header, the default is false.


Standard use case for the intranet.

Creating a second profile on NestForms with which you can share admin rights to your selected forms. The second profile should be used because of limited rights for security purposes.

Inside your intranet settings create an oAuth Token (which will require you to login to the second profile). 

And then when the iframe to your client is to be displayed - call the remote_login_create nestforms endpoint (using your backend scripts) and display the frame using the URL received from the call.

Remote Login Example


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.