Forms: fetching definitions and submitting responses

Your integration can fetch a published form, render its questions and submit the answers to Gorilla Dash. These endpoints use the standalone Forms module. They save responses under that form’s Responses screen; they do not create website enquiries.

Before you start

Create the form in Forms and set its status to Published — accepting responses. Draft, paused and deleted forms cannot be fetched or submitted through these endpoints. A tribe is one location, branch or business unit inside your organisation. A tribe API key can access that tribe’s own forms and organisation forms shared with tribes. An organisation key can access published forms throughout its own organisation.

REST API

Use the API base URL https://api.gorilladash.com/api/v1 and send your existing GorillaDash-Api-Key and GorillaDash-Api-Secret headers. Keep those credentials on your server. The organisation’s REST API access must be enabled.

Successful REST requests return HTTP 201 with the result inside data. Each field definition has a stable key, a label and a type, plus any required flag or options. Build the answers object using those keys. For example, if your form defines full_name and email, send the following body.

{"answers":{"full_name":"Alex","email":"alex@example.com"}}

With a tribe key, a response to a shared form is attributed to that tribe. An organisation key attributes a tribe-owned form to its owner, and an organisation-owned form to the organisation. Do not send organisation_id or tribe_id in the body: credentials and form ownership determine the scope.

GraphQL

Use the existing authenticated website GraphQL endpoint. The website determines the organisation. The forms query lists published forms, and form(slug: ...) returns one definition. Both accept an optional tribe_slug within that organisation. The list accepts page and itemsPerPage, with the same default page size and maximum of 100.

{ forms(page: 1, itemsPerPage: 25) { id name slug } form(slug: "customer-survey") { heading message fields submit_label accepts_files } }

Submit a response with submitFormResponse. Send the answers as a JSON object in GraphQL variables. Add tribe_slug when a shared organisation form should record the response against a particular tribe. A tribe context can access only that tribe’s own forms and shared organisation forms.

mutation Submit($slug: String!, $answers: JsonParser!) { submitFormResponse(slug: $slug, answers: $answers) { id thankyou redirect_url } }

{"slug":"customer-survey","answers":{"full_name":"Alex","email":"alex@example.com"}}

Validation, contacts and files

Required questions and field types are checked before a response is saved. Unknown answer keys are discarded. Optional first_name, last_name, email and phone values can be sent alongside answers; otherwise the form’s mapped fields provide contact details. Contacts are matched only when the form’s Save people who respond as contacts setting is on, and tribe responses match within that tribe. Leave the website honeypot field empty or omit it.

For a file-upload question, upload each file first through POST /api/form-uploads/{organisation-slug}/{form-slug} on the Gorilla Dash app host, sending a multipart field named file. Place the returned descriptor in the answer array for that question. The response submission checks that each descriptor belongs to the same form before committing it. Invalid file descriptors are discarded while the other answers are saved.