Prepare an entry-attachment upload

curl --request POST \
  --url https://formhug.ai/api/v1/f/{form_token}/entry_attachments \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "field_api_code": "field_3",
  "file_name": "design.pdf",
  "content_type": "application/pdf",
  "file_size": 5242880,
  "dimension_api_code": "col_a"
}
'

import requests

url = "https://formhug.ai/api/v1/f/{form_token}/entry_attachments"

payload = {
    "field_api_code": "field_3",
    "file_name": "design.pdf",
    "content_type": "application/pdf",
    "file_size": 5242880,
    "dimension_api_code": "col_a"
}
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({
    field_api_code: 'field_3',
    file_name: 'design.pdf',
    content_type: 'application/pdf',
    file_size: 5242880,
    dimension_api_code: 'col_a'
  })
};

fetch('https://formhug.ai/api/v1/f/{form_token}/entry_attachments', 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/f/{form_token}/entry_attachments",
  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([
    'field_api_code' => 'field_3',
    'file_name' => 'design.pdf',
    'content_type' => 'application/pdf',
    'file_size' => 5242880,
    'dimension_api_code' => 'col_a'
  ]),
  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/f/{form_token}/entry_attachments"

	payload := strings.NewReader("{\n  \"field_api_code\": \"field_3\",\n  \"file_name\": \"design.pdf\",\n  \"content_type\": \"application/pdf\",\n  \"file_size\": 5242880,\n  \"dimension_api_code\": \"col_a\"\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/f/{form_token}/entry_attachments")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"field_api_code\": \"field_3\",\n  \"file_name\": \"design.pdf\",\n  \"content_type\": \"application/pdf\",\n  \"file_size\": 5242880,\n  \"dimension_api_code\": \"col_a\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://formhug.ai/api/v1/f/{form_token}/entry_attachments")

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  \"field_api_code\": \"field_3\",\n  \"file_name\": \"design.pdf\",\n  \"content_type\": \"application/pdf\",\n  \"file_size\": 5242880,\n  \"dimension_api_code\": \"col_a\"\n}"

response = http.request(request)
puts response.read_body

{
  "data": {
    "upload_id": "<string>",
    "upload_url": "<string>",
    "expires_at": "2023-11-07T05:31:56Z",
    "field_api_code": "<string>",
    "dimension_api_code": "<string>"
  }
}

Attachments

Prepare an entry-attachment upload

Prepare an upload for an attachment field. Returns a one-time upload_id and an upload_url.

Send the file to upload_url with an HTTP PUT: the raw file bytes as the request body and the Content-Type header set to the value you declared in content_type (it must match). Use the upload_url exactly as returned.

Then submit the returned upload_id under the attachment field in field_values when creating the entry — the entry-create endpoint registers the attachment. No PAT scope required.

POST

api

{form_token}

entry_attachments

Prepare an entry-attachment upload

curl --request POST \
  --url https://formhug.ai/api/v1/f/{form_token}/entry_attachments \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "field_api_code": "field_3",
  "file_name": "design.pdf",
  "content_type": "application/pdf",
  "file_size": 5242880,
  "dimension_api_code": "col_a"
}
'

import requests

url = "https://formhug.ai/api/v1/f/{form_token}/entry_attachments"

payload = {
    "field_api_code": "field_3",
    "file_name": "design.pdf",
    "content_type": "application/pdf",
    "file_size": 5242880,
    "dimension_api_code": "col_a"
}
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({
    field_api_code: 'field_3',
    file_name: 'design.pdf',
    content_type: 'application/pdf',
    file_size: 5242880,
    dimension_api_code: 'col_a'
  })
};

fetch('https://formhug.ai/api/v1/f/{form_token}/entry_attachments', 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/f/{form_token}/entry_attachments",
  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([
    'field_api_code' => 'field_3',
    'file_name' => 'design.pdf',
    'content_type' => 'application/pdf',
    'file_size' => 5242880,
    'dimension_api_code' => 'col_a'
  ]),
  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/f/{form_token}/entry_attachments"

	payload := strings.NewReader("{\n  \"field_api_code\": \"field_3\",\n  \"file_name\": \"design.pdf\",\n  \"content_type\": \"application/pdf\",\n  \"file_size\": 5242880,\n  \"dimension_api_code\": \"col_a\"\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/f/{form_token}/entry_attachments")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"field_api_code\": \"field_3\",\n  \"file_name\": \"design.pdf\",\n  \"content_type\": \"application/pdf\",\n  \"file_size\": 5242880,\n  \"dimension_api_code\": \"col_a\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://formhug.ai/api/v1/f/{form_token}/entry_attachments")

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  \"field_api_code\": \"field_3\",\n  \"file_name\": \"design.pdf\",\n  \"content_type\": \"application/pdf\",\n  \"file_size\": 5242880,\n  \"dimension_api_code\": \"col_a\"\n}"

response = http.request(request)
puts response.read_body

{
  "data": {
    "upload_id": "<string>",
    "upload_url": "<string>",
    "expires_at": "2023-11-07T05:31:56Z",
    "field_api_code": "<string>",
    "dimension_api_code": "<string>"
  }
}

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

Form token

Body

application/json

field_api_code

string

required

api_code of the target attachment field on this form.

Example:

"field_3"

file_name

string

required

Original file name (with extension).

Example:

"design.pdf"

content_type

string

required

MIME type. Must satisfy the field's media_type configuration and not be in the global blacklist (text/html, text/css, text/javascript, application/x-httpd-php).

Example:

"application/pdf"

file_size

integer

required

File size in bytes. Must be ≤ field.max_size * 1MB.

Example:

5242880

dimension_api_code

string

api_code of the matrix/table dimension when the target field is tabular (e.g. file column inside a table field). Omit for non-tabular attachment fields.

Example:

"col_a"

Response

Init for an attachment field inside a table field (tabular)

data

object

required

Prepare-step response for the 2-step entry-attachment upload. Send the file to upload_url with an HTTP PUT: the raw file bytes as the request body and the Content-Type header set to the value you declared in content_type (it must match). Use upload_url exactly as returned. Then submit the upload_id under the matching attachment field in field_values when creating the entry — the entry-create endpoint registers the attachment. upload_id is a self-describing handle (<form_token>.<field_api_code>[.<dimension_api_code>].<random>).

Show child attributes

Last modified on July 24, 2026

Finalize prepared rich-text image uploads List entries of a form

Overview

Forms

Form Themes

Field Rules

Form Settings

Attachments

Entries

Folders

Published Forms

Published Form Entries

Participated Forms

Me

Webhooks

OAuth

Prepare an entry-attachment upload

Authorizations

Path Parameters

Body

Response