---
title: "Save a recipe: one JSON that a person or an agent can read, edit, dry-run and run the same way every time"
method: POST
path: "/api/v1/recipes"
tags: ["Automation"]
---

# Save a recipe: one JSON that a person or an agent can read, edit, dry-run and run the same way every time

`POST /api/v1/recipes`

## Request

- Base URL: `https://philforms.com`
- URL: `https://philforms.com/api/v1/recipes`
- Auth: HTTP bearer

## Request body

- object
  - `name` string
  - `form_id` string, required
  - `row_mode` 'each' | 'total': each = one form per row (default); total = one form for the whole sheet
  - `total_parameter` string[]: With row_mode total: parameters summed over the rows
  - `source` object: { type: "url", url, header? } (JSON or CSV) | { type: "csv", text } | { type: "static", row: [...] } — optional: a run may send its own rows
  - `mapping` object[]: column → parameter; left out: your saved mapping for the header row, else exact parameter names, else a proposal
    - `header` string
    - `parameter` string
  - `join` object[]
    - `parameter` string
    - `header` string[]
    - `separator` string
  - `constant` object: Values on every document (a blank cell never overrides one)
  - `transform` object[]
    - `parameter` string
    - `step` string[]: trim, upper, lower, collapse_space, digit, number, date, date:<format> (e.g. date:DD/MM/YYYY), zip, default:<value>, prefix:<text>, slice:<start>,<end>
  - `file_name_field` string
  - `deliver` object
    - `webhook_url` string
  - `as_of` string: The documents' date (YYYY-MM-DD = midnight Asia/Manila); default: the run's day

## Response `201`

{ recipe }

## Other responses

- `400`: Bad recipe, source URL or webhook URL
- `404`: Unknown form

---

[API](https://skmtc.dev/philforms/apis/philforms-api.md) · [All operations](https://skmtc.dev/philforms/apis/philforms-api/llms.txt) · [OpenAPI document](https://skmtc.dev/philforms/apis/philforms-api/revisions/a43bf313729c?raw)