Update if exists, insert if not. One endpoint.
Updated March 2026
Sometimes you want to update an existing submission instead of creating a new one. A user changes their survey answer. An agent updates a status record. A CRM sync overwrites the latest data. Sutrena's upsert endpoint handles this. PUT /api/forms/:id/submissions/upsert matches on a key field (like email or user_id). If a submission with that value exists, it updates. If not, it inserts. One call, no need to check first.
1. Create a form with a unique field
The upsert matches on the field specified in uniqueBy. Set this when creating the form.
curl -X POST https://sutrena.com/api/forms -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" -d '{"name": "CRM Sync", "fields": [{"name": "email", "label": "Email", "type": "email", "required": true}, {"name": "status", "label": "Status", "type": "text"}], "uniqueBy": ["email"]}'2. Upsert a submission
PUT to the upsert endpoint with the submission data. If a submission with the matching uniqueBy value exists, it gets updated. Otherwise, a new submission is created.
curl -X PUT https://sutrena.com/api/forms/FORM_ID/submissions/upsert -H "Content-Type: application/json" -d '{"email": "[email protected]", "status": "active"}'3. Use upsert from an AI agent or script
Upsert is useful for agents that sync data periodically. The agent does not need to check whether a record exists first -- just call upsert and let Sutrena handle the logic.
const res = await fetch(
"https://sutrena.com/api/forms/FORM_ID/submissions/upsert",
{
method: "PUT",
headers: { "Content-Type": "application/json" },
body: JSON.stringify({ email: "[email protected]", status: "renewed" }),
}
);
const data = await res.json();
console.log(data.created ? "Inserted" : "Updated");The field specified in uniqueBy when you created the form. Usually email or user_id. The form must have uniqueBy set for upsert to work.
The upsert endpoint is public, like the regular submit endpoint. No API key needed. The form ID in the URL identifies which form the data belongs to.
Upsert requires uniqueBy. Without it, the endpoint returns a 400 error. Use the regular submit endpoint instead if you do not need upsert.
Yes. Both inserts and updates trigger webhooks. The payload includes a created boolean so your webhook handler knows which it was.
Yes. Use the presigned upload flow for files, then include the file reference in the upsert body. The file replaces any previous file on update.
Sutrena is the web runtime for AI agents. Three primitives — pages, forms, and dashboards — accessible through one API. Your agent creates web artifacts, humans interact with them, and your agent gets the data back. Framework-agnostic. Works from any MCP client or HTTP client.
1. Get a trial key (no auth, no signup)
curl -X POST https://sutrena.com/api/trial2. Create a form + dashboard from a template
curl -X POST https://sutrena.com/api/forms \
-H "Authorization: Bearer st_trial_xxx" \
-H "Content-Type: application/json" \
-d '{"templateId": "waitlist", "createDashboard": true}'Get a trial API key instantly with no signup, or create an account for the full experience.