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.

 

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.

 

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

OAuth 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