Create a public query
curl --request POST \
--url https://formhug.ai/api/v1/opensearch/queries \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"form_token": "<string>",
"name": "Exam results",
"search_field_rules": [
{
"fields": [
{
"field": "field_1",
"label": "<string>",
"fuzzy": false
}
]
}
],
"display_field_rules": [
{
"field": "field_2",
"label": "<string>",
"editable": false,
"protected": false,
"highlight": {
"color": "<string>",
"position": 123
}
}
],
"description": "<string>",
"enabled": true,
"allow_to_export_results": true,
"search_button": {
"text": "<string>",
"color": "<string>"
},
"messages": {
"has_result": "<string>",
"no_result": "<string>"
},
"header": {
"background_image": {
"id": "<string>",
"upload_id": "<string>",
"position_x": 123,
"position_y": 123
}
},
"scope_conditions": [
{
"field": "field_1",
"operator": "eq",
"value": "Alice"
}
]
}
'import requests
url = "https://formhug.ai/api/v1/opensearch/queries"
payload = {
"form_token": "<string>",
"name": "Exam results",
"search_field_rules": [{ "fields": [
{
"field": "field_1",
"label": "<string>",
"fuzzy": False
}
] }],
"display_field_rules": [
{
"field": "field_2",
"label": "<string>",
"editable": False,
"protected": False,
"highlight": {
"color": "<string>",
"position": 123
}
}
],
"description": "<string>",
"enabled": True,
"allow_to_export_results": True,
"search_button": {
"text": "<string>",
"color": "<string>"
},
"messages": {
"has_result": "<string>",
"no_result": "<string>"
},
"header": { "background_image": {
"id": "<string>",
"upload_id": "<string>",
"position_x": 123,
"position_y": 123
} },
"scope_conditions": [
{
"field": "field_1",
"operator": "eq",
"value": "Alice"
}
]
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({
form_token: '<string>',
name: 'Exam results',
search_field_rules: [{fields: [{field: 'field_1', label: '<string>', fuzzy: false}]}],
display_field_rules: [
{
field: 'field_2',
label: '<string>',
editable: false,
protected: false,
highlight: {color: '<string>', position: 123}
}
],
description: '<string>',
enabled: true,
allow_to_export_results: true,
search_button: {text: '<string>', color: '<string>'},
messages: {has_result: '<string>', no_result: '<string>'},
header: {
background_image: {id: '<string>', upload_id: '<string>', position_x: 123, position_y: 123}
},
scope_conditions: [{field: 'field_1', operator: 'eq', value: 'Alice'}]
})
};
fetch('https://formhug.ai/api/v1/opensearch/queries', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://formhug.ai/api/v1/opensearch/queries",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'form_token' => '<string>',
'name' => 'Exam results',
'search_field_rules' => [
[
'fields' => [
[
'field' => 'field_1',
'label' => '<string>',
'fuzzy' => false
]
]
]
],
'display_field_rules' => [
[
'field' => 'field_2',
'label' => '<string>',
'editable' => false,
'protected' => false,
'highlight' => [
'color' => '<string>',
'position' => 123
]
]
],
'description' => '<string>',
'enabled' => true,
'allow_to_export_results' => true,
'search_button' => [
'text' => '<string>',
'color' => '<string>'
],
'messages' => [
'has_result' => '<string>',
'no_result' => '<string>'
],
'header' => [
'background_image' => [
'id' => '<string>',
'upload_id' => '<string>',
'position_x' => 123,
'position_y' => 123
]
],
'scope_conditions' => [
[
'field' => 'field_1',
'operator' => 'eq',
'value' => 'Alice'
]
]
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://formhug.ai/api/v1/opensearch/queries"
payload := strings.NewReader("{\n \"form_token\": \"<string>\",\n \"name\": \"Exam results\",\n \"search_field_rules\": [\n {\n \"fields\": [\n {\n \"field\": \"field_1\",\n \"label\": \"<string>\",\n \"fuzzy\": false\n }\n ]\n }\n ],\n \"display_field_rules\": [\n {\n \"field\": \"field_2\",\n \"label\": \"<string>\",\n \"editable\": false,\n \"protected\": false,\n \"highlight\": {\n \"color\": \"<string>\",\n \"position\": 123\n }\n }\n ],\n \"description\": \"<string>\",\n \"enabled\": true,\n \"allow_to_export_results\": true,\n \"search_button\": {\n \"text\": \"<string>\",\n \"color\": \"<string>\"\n },\n \"messages\": {\n \"has_result\": \"<string>\",\n \"no_result\": \"<string>\"\n },\n \"header\": {\n \"background_image\": {\n \"id\": \"<string>\",\n \"upload_id\": \"<string>\",\n \"position_x\": 123,\n \"position_y\": 123\n }\n },\n \"scope_conditions\": [\n {\n \"field\": \"field_1\",\n \"operator\": \"eq\",\n \"value\": \"Alice\"\n }\n ]\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://formhug.ai/api/v1/opensearch/queries")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"form_token\": \"<string>\",\n \"name\": \"Exam results\",\n \"search_field_rules\": [\n {\n \"fields\": [\n {\n \"field\": \"field_1\",\n \"label\": \"<string>\",\n \"fuzzy\": false\n }\n ]\n }\n ],\n \"display_field_rules\": [\n {\n \"field\": \"field_2\",\n \"label\": \"<string>\",\n \"editable\": false,\n \"protected\": false,\n \"highlight\": {\n \"color\": \"<string>\",\n \"position\": 123\n }\n }\n ],\n \"description\": \"<string>\",\n \"enabled\": true,\n \"allow_to_export_results\": true,\n \"search_button\": {\n \"text\": \"<string>\",\n \"color\": \"<string>\"\n },\n \"messages\": {\n \"has_result\": \"<string>\",\n \"no_result\": \"<string>\"\n },\n \"header\": {\n \"background_image\": {\n \"id\": \"<string>\",\n \"upload_id\": \"<string>\",\n \"position_x\": 123,\n \"position_y\": 123\n }\n },\n \"scope_conditions\": [\n {\n \"field\": \"field_1\",\n \"operator\": \"eq\",\n \"value\": \"Alice\"\n }\n ]\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://formhug.ai/api/v1/opensearch/queries")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"form_token\": \"<string>\",\n \"name\": \"Exam results\",\n \"search_field_rules\": [\n {\n \"fields\": [\n {\n \"field\": \"field_1\",\n \"label\": \"<string>\",\n \"fuzzy\": false\n }\n ]\n }\n ],\n \"display_field_rules\": [\n {\n \"field\": \"field_2\",\n \"label\": \"<string>\",\n \"editable\": false,\n \"protected\": false,\n \"highlight\": {\n \"color\": \"<string>\",\n \"position\": 123\n }\n }\n ],\n \"description\": \"<string>\",\n \"enabled\": true,\n \"allow_to_export_results\": true,\n \"search_button\": {\n \"text\": \"<string>\",\n \"color\": \"<string>\"\n },\n \"messages\": {\n \"has_result\": \"<string>\",\n \"no_result\": \"<string>\"\n },\n \"header\": {\n \"background_image\": {\n \"id\": \"<string>\",\n \"upload_id\": \"<string>\",\n \"position_x\": 123,\n \"position_y\": 123\n }\n },\n \"scope_conditions\": [\n {\n \"field\": \"field_1\",\n \"operator\": \"eq\",\n \"value\": \"Alice\"\n }\n ]\n}"
response = http.request(request)
puts response.read_body{
"data": {
"token": "aB3dE",
"form_token": "<string>",
"url": "<string>",
"status": "active",
"name": "<string>",
"enabled": true,
"search_field_rules": [
{
"operand": "and",
"fields": [
{
"field": "field_1",
"label": "<string>",
"fuzzy": false
}
]
}
],
"display_field_rules": [
{
"field": "field_2",
"label": "<string>",
"editable": false,
"protected": false,
"highlight": {
"color": "<string>",
"position": 123
}
}
],
"scope_conditions": [
{
"field": "field_1",
"operator": "eq",
"value": "Alice"
}
],
"created_at": "2023-11-07T05:31:56Z",
"updated_at": "2023-11-07T05:31:56Z",
"description": "<string>",
"allow_to_export_results": true,
"search_button": {
"text": "<string>",
"color": "<string>"
},
"messages": {
"has_result": "<string>",
"no_result": "<string>"
},
"header": {
"background_image": {
"id": "<string>",
"image_url": "<string>",
"position_x": 123,
"position_y": 123
}
},
"searches_count": 123,
"views_count": 123
}
}Public Queries
Create a public query
Required scope: form:write. You must be able to manage the form.
POST
/
api
/
v1
/
opensearch
/
queries
Create a public query
curl --request POST \
--url https://formhug.ai/api/v1/opensearch/queries \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"form_token": "<string>",
"name": "Exam results",
"search_field_rules": [
{
"fields": [
{
"field": "field_1",
"label": "<string>",
"fuzzy": false
}
]
}
],
"display_field_rules": [
{
"field": "field_2",
"label": "<string>",
"editable": false,
"protected": false,
"highlight": {
"color": "<string>",
"position": 123
}
}
],
"description": "<string>",
"enabled": true,
"allow_to_export_results": true,
"search_button": {
"text": "<string>",
"color": "<string>"
},
"messages": {
"has_result": "<string>",
"no_result": "<string>"
},
"header": {
"background_image": {
"id": "<string>",
"upload_id": "<string>",
"position_x": 123,
"position_y": 123
}
},
"scope_conditions": [
{
"field": "field_1",
"operator": "eq",
"value": "Alice"
}
]
}
'import requests
url = "https://formhug.ai/api/v1/opensearch/queries"
payload = {
"form_token": "<string>",
"name": "Exam results",
"search_field_rules": [{ "fields": [
{
"field": "field_1",
"label": "<string>",
"fuzzy": False
}
] }],
"display_field_rules": [
{
"field": "field_2",
"label": "<string>",
"editable": False,
"protected": False,
"highlight": {
"color": "<string>",
"position": 123
}
}
],
"description": "<string>",
"enabled": True,
"allow_to_export_results": True,
"search_button": {
"text": "<string>",
"color": "<string>"
},
"messages": {
"has_result": "<string>",
"no_result": "<string>"
},
"header": { "background_image": {
"id": "<string>",
"upload_id": "<string>",
"position_x": 123,
"position_y": 123
} },
"scope_conditions": [
{
"field": "field_1",
"operator": "eq",
"value": "Alice"
}
]
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({
form_token: '<string>',
name: 'Exam results',
search_field_rules: [{fields: [{field: 'field_1', label: '<string>', fuzzy: false}]}],
display_field_rules: [
{
field: 'field_2',
label: '<string>',
editable: false,
protected: false,
highlight: {color: '<string>', position: 123}
}
],
description: '<string>',
enabled: true,
allow_to_export_results: true,
search_button: {text: '<string>', color: '<string>'},
messages: {has_result: '<string>', no_result: '<string>'},
header: {
background_image: {id: '<string>', upload_id: '<string>', position_x: 123, position_y: 123}
},
scope_conditions: [{field: 'field_1', operator: 'eq', value: 'Alice'}]
})
};
fetch('https://formhug.ai/api/v1/opensearch/queries', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://formhug.ai/api/v1/opensearch/queries",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'form_token' => '<string>',
'name' => 'Exam results',
'search_field_rules' => [
[
'fields' => [
[
'field' => 'field_1',
'label' => '<string>',
'fuzzy' => false
]
]
]
],
'display_field_rules' => [
[
'field' => 'field_2',
'label' => '<string>',
'editable' => false,
'protected' => false,
'highlight' => [
'color' => '<string>',
'position' => 123
]
]
],
'description' => '<string>',
'enabled' => true,
'allow_to_export_results' => true,
'search_button' => [
'text' => '<string>',
'color' => '<string>'
],
'messages' => [
'has_result' => '<string>',
'no_result' => '<string>'
],
'header' => [
'background_image' => [
'id' => '<string>',
'upload_id' => '<string>',
'position_x' => 123,
'position_y' => 123
]
],
'scope_conditions' => [
[
'field' => 'field_1',
'operator' => 'eq',
'value' => 'Alice'
]
]
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://formhug.ai/api/v1/opensearch/queries"
payload := strings.NewReader("{\n \"form_token\": \"<string>\",\n \"name\": \"Exam results\",\n \"search_field_rules\": [\n {\n \"fields\": [\n {\n \"field\": \"field_1\",\n \"label\": \"<string>\",\n \"fuzzy\": false\n }\n ]\n }\n ],\n \"display_field_rules\": [\n {\n \"field\": \"field_2\",\n \"label\": \"<string>\",\n \"editable\": false,\n \"protected\": false,\n \"highlight\": {\n \"color\": \"<string>\",\n \"position\": 123\n }\n }\n ],\n \"description\": \"<string>\",\n \"enabled\": true,\n \"allow_to_export_results\": true,\n \"search_button\": {\n \"text\": \"<string>\",\n \"color\": \"<string>\"\n },\n \"messages\": {\n \"has_result\": \"<string>\",\n \"no_result\": \"<string>\"\n },\n \"header\": {\n \"background_image\": {\n \"id\": \"<string>\",\n \"upload_id\": \"<string>\",\n \"position_x\": 123,\n \"position_y\": 123\n }\n },\n \"scope_conditions\": [\n {\n \"field\": \"field_1\",\n \"operator\": \"eq\",\n \"value\": \"Alice\"\n }\n ]\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://formhug.ai/api/v1/opensearch/queries")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"form_token\": \"<string>\",\n \"name\": \"Exam results\",\n \"search_field_rules\": [\n {\n \"fields\": [\n {\n \"field\": \"field_1\",\n \"label\": \"<string>\",\n \"fuzzy\": false\n }\n ]\n }\n ],\n \"display_field_rules\": [\n {\n \"field\": \"field_2\",\n \"label\": \"<string>\",\n \"editable\": false,\n \"protected\": false,\n \"highlight\": {\n \"color\": \"<string>\",\n \"position\": 123\n }\n }\n ],\n \"description\": \"<string>\",\n \"enabled\": true,\n \"allow_to_export_results\": true,\n \"search_button\": {\n \"text\": \"<string>\",\n \"color\": \"<string>\"\n },\n \"messages\": {\n \"has_result\": \"<string>\",\n \"no_result\": \"<string>\"\n },\n \"header\": {\n \"background_image\": {\n \"id\": \"<string>\",\n \"upload_id\": \"<string>\",\n \"position_x\": 123,\n \"position_y\": 123\n }\n },\n \"scope_conditions\": [\n {\n \"field\": \"field_1\",\n \"operator\": \"eq\",\n \"value\": \"Alice\"\n }\n ]\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://formhug.ai/api/v1/opensearch/queries")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"form_token\": \"<string>\",\n \"name\": \"Exam results\",\n \"search_field_rules\": [\n {\n \"fields\": [\n {\n \"field\": \"field_1\",\n \"label\": \"<string>\",\n \"fuzzy\": false\n }\n ]\n }\n ],\n \"display_field_rules\": [\n {\n \"field\": \"field_2\",\n \"label\": \"<string>\",\n \"editable\": false,\n \"protected\": false,\n \"highlight\": {\n \"color\": \"<string>\",\n \"position\": 123\n }\n }\n ],\n \"description\": \"<string>\",\n \"enabled\": true,\n \"allow_to_export_results\": true,\n \"search_button\": {\n \"text\": \"<string>\",\n \"color\": \"<string>\"\n },\n \"messages\": {\n \"has_result\": \"<string>\",\n \"no_result\": \"<string>\"\n },\n \"header\": {\n \"background_image\": {\n \"id\": \"<string>\",\n \"upload_id\": \"<string>\",\n \"position_x\": 123,\n \"position_y\": 123\n }\n },\n \"scope_conditions\": [\n {\n \"field\": \"field_1\",\n \"operator\": \"eq\",\n \"value\": \"Alice\"\n }\n ]\n}"
response = http.request(request)
puts response.read_body{
"data": {
"token": "aB3dE",
"form_token": "<string>",
"url": "<string>",
"status": "active",
"name": "<string>",
"enabled": true,
"search_field_rules": [
{
"operand": "and",
"fields": [
{
"field": "field_1",
"label": "<string>",
"fuzzy": false
}
]
}
],
"display_field_rules": [
{
"field": "field_2",
"label": "<string>",
"editable": false,
"protected": false,
"highlight": {
"color": "<string>",
"position": 123
}
}
],
"scope_conditions": [
{
"field": "field_1",
"operator": "eq",
"value": "Alice"
}
],
"created_at": "2023-11-07T05:31:56Z",
"updated_at": "2023-11-07T05:31:56Z",
"description": "<string>",
"allow_to_export_results": true,
"search_button": {
"text": "<string>",
"color": "<string>"
},
"messages": {
"has_result": "<string>",
"no_result": "<string>"
},
"header": {
"background_image": {
"id": "<string>",
"image_url": "<string>",
"position_x": 123,
"position_y": 123
}
},
"searches_count": 123,
"views_count": 123
}
}Authorizations
Personal Access Token prefixed with fh_. Sent as Authorization: Bearer fh_xxx.
The scope required by each endpoint is listed in that endpoint's description.
Body
application/json
Form to query; you must be able to manage it.
Example:
"Exam results"
Search field groups; every group must be satisfied. Replaces the existing groups. A field may appear only once across all groups.
Searchable fields (fields[].field):
- Form fields of type short_text, long_text, name, phone, email, number, date, radio, dropdown, cascade and linked_form.
- The two sub-fields of a booking field:
<booking_api_code>_attribute_api_code(booked item) and<booking_api_code>_attribute_date_time(booked time). - System fields:
serial_number;exam_score(exam forms);gen_code(forms with verification codes). - Linked-form sub-fields that are publicly displayable and searchable by the rules above, including the linked form's
serial_number, as<linked_form_api_code>_associated_<sub_field_api_code>.
A field outside this set is rejected with 422, and the error message lists the allowed api_codes for the form.
Minimum array length:
1Show child attributes
Show child attributes
Fields shown on each result. Replaces the existing list. A field may appear only once.
Displayable fields (field):
- Form fields of type short_text, long_text, name, phone, email, number, date, time, radio, checkbox, image_radio, image_checkbox, dropdown, cascade, url, address, rating, nps, attachment, audio, signature, ranking, matrix, matrix_rating, likert, location, product, booking and linked_form.
- System fields:
serial_number,created_at,updated_at,info_filling_duration;total_priceandpreferential_price(forms with products);reservation_status_fsf_field(booking status, forms with bookings);exam_score(exam forms);x_field_certificate(forms with certificates);gen_code(forms with verification codes);evaluation_report(evaluation forms). - Linked-form sub-fields that are publicly displayable, as
<linked_form_api_code>_associated_<sub_field_api_code>.
A field outside this set is rejected with 422, and the error message lists the allowed api_codes for the form.
Minimum array length:
1Show child attributes
Show child attributes
Whether the public page accepts searches.
Show child attributes
Show child attributes
Show child attributes
Show child attributes
Show child attributes
Show child attributes
Limit which entries visitors can find, using the entries filter syntax (all ANDed). [] removes the limit. Requires a plan with scoped data.
Show child attributes
Show child attributes
Response
Created
Show child attributes
Show child attributes
Last modified on October 9, 2026
Was this page helpful?