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). In PHP you might use: base64_encode(CLIENT_ID.":".CLIENT_SECRET)
  • 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.

Most of the datetime fields in NestForms are stored in UTC format within our database and they are also in UTC when displayed within the API. The only exception is the datetime component where we keep the data exactly the way it was captured by the device (in device local time).

 

Authenticate using oAuth2 guide #

  1. Create the Client ID, Client Secret and valid Redirect URLs in the back of NestForms Applications.
  2. Create a page in your website that will contain link to NestForms OAuth Authentication.
  3. Let the user click to the link (in their browser).
  4. User is authenticated in the NestForms platform (in their browser).
  5. User is redirected back to your website (based on the redirect_uri part of the request which is also checked against the settings in the back of NestForms).
  6. Your application in the background send the POST request to the OAuth Access Token where you receive the access token (and refresh token) as a result.
  7. Now your application is authorised in the background and you are able to access further data.
    E.g. try this on GET request for
    Forms list https://www.nestforms.com/api/forms_list (in the background). Do not forget to include the Authorization header.
  8. Note: Once the access token is nearing its end of life (or after its end of life), you can send a request to the same OAuth Access Token with refresh token received. When refresh token is used, the current access and refresh tokens are invalidated, you will receive a new set of the access and refresh token that should be used next time.

The lifespan of the access token is 1 Hour. The lifespan of the refresh token is 1 Month.

Authenticate using CURL

 

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 space 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 an original 'state' parameter that you have sent with request as well as the 'code' parameter that you need to send to the OAuth Access Token endpoint to generate an Access Token.

OAuth Authentication Example

 

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.

Same URL is also used for acquiring new Access Token using the Refresh Token.

This request expects following header:

Send the POST request with following parameters: 

  • redirect_uri: YOUR REDIRECT URL
  • grant_type: authorization_code or refresh_token
  • refresh_token: Currently active refresh token. Required for grant type refresh_token.
  • code: String received from OAuth Authentication. Required for grant type authorization_code.

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 returned in one request is 1000. If there are more pages, you will receive a has_more_pages: true in the response. You can then send the same request with added the query parameter 'page' to view older responses (eg, ?page=1 will display the responses from 1001 to 2000, ?page=2 will display responses from 2000 to 2999, etc).

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),
    • modified_local: Time (UTC) when the response was modified in the application (not reliable),
    • event_status: It is automatically set by the NestForms system based on the actions that happen with the response and defining the current state of the Response. Following options are available: 
      • new - when using the events eg on the website fill
      • finished - (most standard) when the user clicks to the “Finish” button within the app.
      • partial - when the user submits the data using the save.

    • 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.

 

Credits #

We thank Harsh Shah, De Montfort University for providing Python examples.