Skip to main content
POST
/
api
/
v1
/
f
/
{form_token}
/
entries
Submit an entry to a published form
curl --request POST \
  --url https://formhug.ai/api/v1/f/{form_token}/entries \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "field_values": {
    "field_1": "Jane Doe",
    "field_2": "Welcome!"
  },
  "password": "<string>"
}
'
{
  "data": {
    "serial_number": 42,
    "token": "aB2cD9eF",
    "created_at": "2023-11-07T05:31:56Z",
    "updated_at": "2023-11-07T05:31:56Z"
  }
}

Documentation Index

Fetch the complete documentation index at: https://formhug.ai/docs/llms.txt

Use this file to discover all available pages before exploring further.

Authorizations

​
Authorization
string
header
required

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.

Path Parameters

​
form_token
string
required

Token of a published form

Body

application/json
​
field_values
object
required

Map keyed by field api_code; unknown keys are dropped silently

Example:
{
  "field_1": "Jane Doe",
  "field_2": "Welcome!"
}
​
password
string

Required if the form is password-protected

Response

Submitted

​
data
object
required

A submitted entry. In addition to the fixed fields below, every field of the parent form appears as a top-level key on the entry under its api_code. The JSON value type for each such key is determined by the corresponding field's type.

Field value shapes

Each field of the parent form appears as a top-level key on the entry, keyed by its api_code. The JSON shape of the value depends on the field's type:

Field type (type)Submitted value
short_textString. The submitted text.
long_textString. Multi-line text.
radioObject { value, other_text?, extended_text? }, or null when unset. value is the api_code of the selected choice. other_text carries the respondent's free-text input and is only present when the selected choice has is_other: true. extended_text carries the free-text input for a choice that has allow_extended_text: true. The two text keys are mutually exclusive per choice (an is_other choice cannot also enable allow_extended_text) and both are omitted when blank. On write, a bare string is accepted as shorthand for { value: <string> }; null clears the field; text keys that don't match the selected choice's configuration are ignored.
checkboxArray of { value, other_text?, extended_text? } objects with the same per-choice semantics as radio. Empty array when nothing is selected. At most one element may carry other_text (the element whose value corresponds to the is_other choice). On write, null clears the field; bare strings in the array are accepted as shorthand for { value: <string> }.
dropdownObject { value, other_text? }, or null when unset. Same value and other_text semantics as radio. dropdown does not support extended_text.
numberNumber. Stored as a float; integer-looking values may serialize without a decimal point.
emailString — an email address.
phoneObject { country_id, country_code, number }. country_id is an ISO 3166-1 alpha-2 country code (e.g. "CN", "US") and is required; country_code is the dialing code without + (e.g. "86", "1") and is optional on write — when omitted it is derived from country_id; number is the local number without the dialing-code prefix.
dateNaive wall-clock string formatted per the field's precision: "YYYY-MM" (month), "YYYY-MM-DD" (day), "YYYY-MM-DD HH:mm" (minute), "YYYY-MM-DD HH:mm:ss" (second). Values are interpreted in the form's timezone setting. Forms created via V1 default to UTC when no timezone is supplied at creation time.
nameString — the submitted name.
urlString — a URL.
addressObject { address_line1, address_line2, city, state, postal_code, country }. country is an ISO 3166-1 alpha-2 country code; state is an ISO 3166-2 subdivision code (e.g. "CA", "NY"), not a localized label.
ratingInteger — the chosen rating level (1..rating_max).
npsInteger — the selected score (0..10).
attachmentArray of objects { id: string, name: string, url: string, file_size: integer, content_type: string }. url is a signed download link valid for 24 hours — refetch the entry to get a fresh link rather than caching it; name is the original filename.
cascadeObject { level_1: <api_code>, level_2: <api_code>, ... } — one key per level (the field's levels setting, default 2). Each value is the api_code of the choice selected at that level.
rankingObject { <choice_api_code>: <rank> } — rank is a positive integer, contiguous starting at 1 for the highest-ranked choice. Unranked choices are omitted.
matrixNested object { <statement_api_code>: { <dimension_api_code>: <cell_value> }, ... }. The inner cell value type depends on the matrix cell field type.
likertObject { <statement_api_code>: [<choice_api_code>, ...] }. The value is always an array — a single-choice answer is wrapped in a one-element array.
timeObject { hour: string, minute: string }, plus second: string when the field has include_second enabled. The pieces are decimal strings without zero padding (e.g. "9", "05").
locationObject { longitude: number, latitude: number, address: string }.
signatureString — a signed download URL for the signature image, valid for 24 hours. Refetch the entry to obtain a fresh link rather than caching it.
matrix_ratingNested object { <statement_api_code>: { <dimension_api_code>: <integer> } }. The inner integer is the chosen rating level (1..rating_max).
tableArray of row objects [{ <dimension_api_code>: <cell_value>, ... }]. The inner cell value type depends on each dimension's field type.
productArray [{ api_code, number, specification? }]. specification is present when the goods item has dimensions; it is an object of { <dim_api_code>: <option_api_code> }.
bookingArray [{ api_code, scheduled_at, end_at?, number, item_name, time_range_code }]. scheduled_at / end_at are ISO8601 date-time strings.
linked_formOn write: string — the entry_token of an entry in the associated form, or null to clear. The server resolves the token against associated_form_token; an unknown token yields 422. On read: one of three shapes — (1) null if not linked; (2) { "deleted": true } if the linked entry has been deleted; (3) Object { entry_token, serial_number, associated_fields, display_fields } describing the linked entry, where associated_fields / display_fields map each api_code (from associated_field_api_codes / display_field_api_codes respectively) to that field's value, formatted per the linked field's own type (recursive — e.g. a date field renders as its naive wall-clock string, an attachment field renders as its array of file objects).
Last modified on May 21, 2026