REST API

FormiaのREST APIを使うと、基幹システムや自社のプログラムから、アプリのデータを読んだり、登録・更新したりできます。この記事では、基本の使いかたを説明します。APIを使うには、先にAPIのトークンと権限で鍵を用意してください。

基本

• 入口は、自社のFormiaのアドレスの/api/v1/です（例: https://forms.example.co.jp/api/v1/）
• やりとりはJSON（UTF-8）です。日付は、タイムゾーン付きのISO 8601形式です
• 項目は、内部のIDではなく、**識別子（key）**で指定します
• 認証は、Authorization: Bearer 鍵のヘッダーで行います

API用の鍵（個人トークンとAPIクライアント）は、上の画面（管理 › 連携と外部データ）で作ります。

よく使う道筋

やりたいこと	道筋
アプリのレコードの一覧	GET /apps/{アプリの key}/records
レコードを1件取得	GET /apps/{アプリの key}/records/{id}
レコードを登録	POST /apps/{アプリの key}/records
一部の項目を更新	PATCH /apps/{アプリの key}/records/{id}
フォームの定義を読む	GET /forms/{フォームの key}/schema
条件で探す	POST /forms/{フォームの key}/submissions/search

{id}には、レコードのIDか受付番号を使えます。削除は、フォームのAPI（DELETE /submissions/{id}）を使います。

登録する

POST /api/v1/forms/site_inspection/submissions
Authorization: Bearer pat_...
Idempotency-Key: （一意の文字列）
Content-Type: application/json

{ "status": "submitted",
  "data": { "inspector": "山田 太郎", "recorded_on": "2026-09-17" } }

• dataには、項目のkeyと値を入れます。フォームにないkeyを送ると、422エラーになります。連携先の項目名が変わったことに、気づけるようにするためです
• 計算値は、サーバーが計算した確定値が返ります。送った値は使われません
• 登録のIdempotency-Keyを付けると、同じキーでの再送は、同じ結果が返り、二重に登録されません。24時間記憶されます

更新する

更新には、If-Matchに、取得したときの版（ETag）を付けるのをおすすめします。ほかの人が先に直していたときは、412エラーになり、上書きを防げます。PATCHは、指定した項目だけを更新します。明細（繰り返し）は、配列全体の置き換えです。

ページングとエラー

一覧は、limitとcursorで、続きを順に取ります。offsetはありません。応答のlinks.nextを使います。

状態	意味
401	鍵がない、または無効
403	権限が足りない。必要な権限が示される
404	ない、または見えない（存在を知らせない）
409	受付終了、重複など
412	更新の版が合わない
422	入力内容の誤り。項目ごとに理由が返る
429	回数の上限。Retry-Afterの後に再試行する

回数の上限は、既定で1分に600回（書き込みは120回）です。

フォームごとのOpenAPI

GET /forms/{フォームの key}/openapi.jsonで、そのフォーム専用のOpenAPIの定義が取れます。項目のkeyと型がそのままスキーマになるので、連携を作るときの手がかりになります。

関連する記事

• APIのトークンと権限
• Webhookで通知する
• データを書き出す・取り込む
• 外部サービスとの連携