cURL

RUNTIME_URL="${FORMERIE_RUNTIME_URL:-https://forms.formerie.com}"
# Your form. This is the only line that names it.
FORM="${FORMERIE_FORM:-acme/contact}"

curl --silent --show-error --max-time 10 \
  --request POST "$RUNTIME_URL/$FORM/submit" \
  --header "Content-Type: application/json" \
  --data '{
    "fields": {
      "name": "Jane Example",
      "email": "jane@example.com",
      "message": "Hello from my server"
    }
  }'

RUNTIME_URL="${FORMERIE_RUNTIME_URL:-https://forms.formerie.com}"
# Your form. This is the only line that names it.
FORM="${FORMERIE_FORM:-acme/contact}"

# Keep the key out of your scripts. A test is stored apart and emails nobody.
curl --silent --show-error --max-time 10 \
  --request POST "$RUNTIME_URL/$FORM/submit" \
  --header "Content-Type: application/json" \
  --header "X-Formerie-Test-Key: $FORMERIE_TEST_KEY" \
  --data '{
    "fields": {
      "name": "Jane Example",
      "email": "jane@example.com",
      "message": "Just a test"
    }
  }'

RUNTIME_URL="${FORMERIE_RUNTIME_URL:-https://forms.formerie.com}"
# Your form. This is the only line that names it.
FORM="${FORMERIE_FORM:-acme/contact}"

# Stores nothing. Only the fields you send are checked.
curl --silent --show-error --max-time 10 \
  --request POST "$RUNTIME_URL/$FORM/validate" \
  --header "Content-Type: application/json" \
  --data '{
    "mode": "partial",
    "fields": {
      "email": "jane@example.com",
      "message": "hi"
    }
  }'

RUNTIME_URL="${FORMERIE_RUNTIME_URL:-https://forms.formerie.com}"
# Your form. This is the only line that names it.
FORM="${FORMERIE_FORM:-acme/contact}"

# Checks every field of that step, and nothing else.
curl --silent --show-error --max-time 10 \
  --request POST "$RUNTIME_URL/$FORM/validate" \
  --header "Content-Type: application/json" \
  --data '{
    "mode": "step",
    "step": "you",
    "fields": {
      "name": "Jane Example",
      "email": "jane@example.com"
    }
  }'

# $answers holds the visitor's answers as JSON, and $shown is the path of the field to show.
RUNTIME_URL="${FORMERIE_RUNTIME_URL:-https://forms.formerie.com}"
# Your form. This is the only line that names it.
FORM="${FORMERIE_FORM:-acme/contact}"

result=$(curl --silent --show-error --max-time 10 \
  --request POST "$RUNTIME_URL/$FORM/submit" \
  --header "Content-Type: application/json" \
  --data "$(jq -n --argjson fields "$answers" '{fields: $fields}')")

# One line for each problem: the field's path, then its message.
echo "$result" | jq -r '.error.issues[]? | "\(.path): \(.message)"'

# The answer at a path such as contact.email, and its first message, both safe for HTML.
answer=$(echo "$answers" | jq -r --arg path "$shown" 'getpath($path | split(".")) // "" | @html')
message=$(echo "$result" | jq -r --arg path "$shown" '.error.fields[$path][0].message // "" | @html')
html="<input name=\"$shown\" value=\"$answer\"><p class=\"error\">$message</p>"

# Takes a key to reuse as its first argument, and $message holds the answer to send.
RUNTIME_URL="${FORMERIE_RUNTIME_URL:-https://forms.formerie.com}"
# Your form. This is the only line that names it.
FORM="${FORMERIE_FORM:-acme/contact}"
MAX_ATTEMPTS=3
LONGEST_WAIT=30

# One key per submission, the same on every retry. Keep it with the answers if you retry later.
key="${1:-$(cat /proc/sys/kernel/random/uuid 2>/dev/null || uuidgen)}"
body=$(jq -n --arg message "$message" --arg key "$key" '{
  fields: {name: "Jane Example", email: "jane@example.com", message: $message},
  metadata: {idempotencyKey: $key}
}')
headers=$(mktemp)
trap 'rm -f "$headers"' EXIT

answer() { # outcome-and-details as jq arguments
  jq -cn --arg key "$key" --argjson attempts "$attempt" "$@" '$ARGS.named'
}

pause() { # a little longer each time, and not after the last attempt
  if [ "$attempt" -lt "$MAX_ATTEMPTS" ]; then
    sleep "$attempt"
  fi
}

for attempt in $(seq 1 "$MAX_ATTEMPTS"); do
  if ! response=$(curl --silent --max-time 10 --dump-header "$headers" --write-out '\n%{http_code}' \
    --request POST "$RUNTIME_URL/$FORM/submit" \
    --header "Content-Type: application/json" \
    --data "$body"); then
    reason="network"
    pause
    continue
  fi

  status="${response##*$'\n'}"
  result="${response%$'\n'*}"
  after=$(tr -d '\r' <"$headers" | awk 'tolower($1) == "retry-after:" { print $2 }')

  # Only the short-term limit sends Retry-After. A form's own limit can last an hour, so don't wait for it.
  if [ "$status" = "429" ]; then
    reason="rate-limited"
    if [ -n "$after" ] && [ "$after" -le "$LONGEST_WAIT" ] && [ "$attempt" -lt "$MAX_ATTEMPTS" ]; then
      sleep "$after"
      continue
    fi
    answer --arg outcome retry-later --arg reason "$reason" --arg after "$after"
    exit 0
  fi

  # Something in front of Formerie may answer without JSON.
  if ! code=$(echo "$result" | jq -er 'if .ok then "OK" else .error.code end' 2>/dev/null); then
    reason="bad-response"
    case "$status" in
      502 | 503 | 504) pause; continue ;;
    esac
    answer --arg outcome retry-later --arg reason "$reason"
    exit 0
  fi

  case "$code" in
    OK)
      answer --arg outcome accepted --arg id "$(echo "$result" | jq -r .submissionUid)"
      exit 0
      ;;
    DUPLICATE_SUBMISSION)
      # The first send worked, and only its answer was lost.
      answer --arg outcome accepted --argjson duplicate true
      exit 0
      ;;
    FORM_MAINTENANCE | QUEUE_FAILED | INTERNAL_ERROR)
      reason="$code"
      pause
      continue
      ;;
    VALIDATION_FAILED)
      answer --arg outcome invalid --arg code "$code" --argjson issues "$(echo "$result" | jq -c .error.issues)"
      exit 0
      ;;
    *)
      answer --arg outcome rejected --arg code "$code" --arg message "$(echo "$result" | jq -r .error.message)"
      exit 0
      ;;
  esac
done

attempt=$MAX_ATTEMPTS
answer --arg outcome retry-later --arg reason "$reason"

# $token is what your form sent as cf-turnstile-response, and $origin is the visitor's Origin header.
RUNTIME_URL="${FORMERIE_RUNTIME_URL:-https://forms.formerie.com}"
# Your form. This is the only line that names it.
FORM="${FORMERIE_FORM:-acme/contact}"

# The token goes apart from the fields. Without the visitor's Origin, the provider's hostname can't match.
origin_header=()
if [ -n "$origin" ]; then
  origin_header=(--header "Origin: $origin")
fi

curl --silent --show-error --max-time 10 \
  --request POST "$RUNTIME_URL/$FORM/submit" \
  --header "Content-Type: application/json" \
  "${origin_header[@]}" \
  --data "$(jq -n --arg token "$token" '{
    fields: {name: "Jane Example", email: "jane@example.com", message: "Hello from my server"},
    verificationToken: $token
  }')"

# $started_at is an ISO 8601 time, such as 2026-11-01T12:00:00Z, and $visitor_id is your own ID for the visitor.
RUNTIME_URL="${FORMERIE_RUNTIME_URL:-https://forms.formerie.com}"
# Your form. This is the only line that names it.
FORM="${FORMERIE_FORM:-acme/contact}"

# startedAt: when the visitor opened the form, for the minimum submit time check.
# deviceToken: your own visitor ID, for a limit rule with the deviceToken scope.
curl --silent --show-error --max-time 10 \
  --request POST "$RUNTIME_URL/$FORM/submit" \
  --header "Content-Type: application/json" \
  --data "$(jq -n \
    --arg key "$(cat /proc/sys/kernel/random/uuid 2>/dev/null || uuidgen)" \
    --arg started_at "$started_at" \
    --arg visitor_id "$visitor_id" '{
      fields: {name: "Jane Example", email: "jane@example.com", message: "Hello from my server"},
      metadata: {
        idempotencyKey: $key,
        startedAt: $started_at,
        pageUrl: "https://www.example.com/contact",
        deviceToken: $visitor_id
      }
    }')"