API

Innoscout support submitting submissions via an API (application programming interface).

API Activation and Key

To activate the API for your account, go to your account settings and click the button "Activate API". You will receive an Organisation ID and API Key that needs to be included with each API request.

You can regenerate your API key any time but all future requests must include the new key (the old key will be rejected).

You can also deactivate the API for your account at any time.

API Base URL

The base url for all API requests is

https://www.innoscout.com/api/v1/<organisation-id>/

Replace the <organisation-id> with the organisation ID from your account settings page.

Authentication

Send a HTTP authorization bearer token with each request with your API Key.

Authorization: Bearer <api-key>

Replace <api-key> with the api key from your account settings page.

Response

All successful responses follow the same base format:

{
   data: [...],
   errors: null
}

An error response may contain data but will contain an error object:

{
   data: {}, // (optional)
   errors: []
}

GET Questionnaires

GET <api-base-url>/questionnaires
Result:
{
    "data": [
        {
            "id": guid-string,
            "slug": string,
            "name": string,
            "description": string
        },
        ...
    ],
    "errors": null
}

GET Questionnaire and Questions

GET <api-base-url>/questionnaires/<questionnaire-id>
Result:

{
    "data": {
        "id": guid-string,
        "slug": string,
        "name": string,
        "description": string,
        "questions": [
            // For all questions types
            {
                "id": guid-string , // the id to reference when posting an answer
                "index": number in the questionnaire,
                "required": boolean,
                "title": string,
                "subtitle": string,
                "type": string, see https://help.innoscout.com/article/10-question-types
            }
            // For number questions
            {
                ... other properties as above,
                "configuration": {
                    "decimalpoints": "2",
                    "minimum": "4",
                    "maximum": "8"
                },
            },
            // For select and multi-select questions
            {
                ... other properties as above,
                "configuration": {
                    // Allowed values as a string seperated by \n
                    "items": "Selection1\nSelection2\nSelection3",
                    // Are other values allowed 
                    "allowother": boolean
                },
            },
        ]
    },
    "errors": null
}

POST Submissions

You can "validate" submissions only or "validate and submit" submissions with the "submit" property.

POST <api-base-url>/questionnaires/<questionnaire-id>/submissions
Payload:
{
    "name": "", // Company Name or Entity Name - Something to identify who submitted
    "email": "", // Email address of submission,
    "submit": false, // true to validate and submit / false to only validate,
    "answers": [
        // for each answer add these common properties
        {
            "question-id": "30efcc0c-4751-47ce-7b55-08da00e0bd17",
        },
	    // for text (short and long) and link question types
        {
	    // ... common properties,
            "text": "API import 1"
        },
        // for number questions split number into before decimal part (number) and after decimal part (decimals). Decimals can be optional.
        {
            // ... common properties,
            "number": "4",
            "decimals": "9"
        },
	    // for single select questions set selection (singular)
	    // if "other" values are allowed in question configuration you can set a different value, otherwise only those provided in property "items" of "question" (see above)
        {
            // ... common properties,
            "selection": "Selection3"
        },
	    // for multi select questions set selections (plurar)
	    // if "other" values are allowed in question configuration you can add any value, otherwise only those provided in property "items" of "question" (see above)
        {
            // ... common properties,
            "selections": [
                "Selection1",
                "Selection2",
                "OtherValue"
            ]
        },
	    // for date question set datetime in format "yyyy-MM-dd". Time is currently not supported.
        {
            // ... common properties,
            "datetime": "2022-12-31"
        }
    ]
}

Result:
{
    "data": {
        "id": guid-string, //
        "entityID": guid-string, // unique id for entity, not used currently
        "entityName": string, // name of the company or submitter
        "email": string, // email of the submitted
        "submitted": true, // always true if data is returned
        "items": [
            // For all questions types these common properties
            {
                "id": guid-string,
                "question-id": "30efcc0c-4751-47ce-7b55-08da00e0bd17"
            },
            // For text (short and long) and link
	        {
                // ... common properties
		        "answer": {
                    "text": "https://example.com"
                },
            },
	        // For number question types
            {
                // ... common properties
		        "answer": {
                    "number": "4",
                    "decimals": "9"
                },
            },
            // For single select question types
            {
                // ... common properties
		        "answer": {
                    "selection": "Selection3",
                    "other": null
                },
            },
            // For multi select question types
            {
                // ... common properties
		        "answer": {
                    "selections": [
                        "Selection1",
                        "Selection2",
                        "OtherValue"
                    ]
                },
            },
            // For date question types
            {
                // ... common properties
		        "answer": {
                    "datetime": "2022-12-31"
                },
            }
        ]
    },
    "errors": [
       "0": "Error 1",
       "1": "Error 2"
    ]
}

Question Types

Innoscout supports different question types. There are generic question types and specific question types that are themselves based on a generic type but have preset configurations. The following table shows which generic type a specific question type maps to. In the API documentation only the generic types are differentiated.