Updated March 2026
Upsert means update-or-insert. If a record matching your key already exists, update it. If not, create it. One operation, two possible outcomes.
This matters when the same entity submits data more than once and you want the latest version, not duplicates. CRM sync: a lead fills out your form, then comes back a week later with updated info. Survey re-submission: a participant changes their mind and resubmits. Status tracking: an order form where the status field changes over time.
Sutrena implements upsert through PUT /api/forms/:id/submissions/upsert. You send an externalId (your unique key for the record) and a payload (the field data). If a submission with that externalId exists, Sutrena replaces the payload. If not, it creates a new submission. The response tells you which happened: created (201) or updated (200).
The externalId is your identifier. It can be anything: an email address, a user ID from your system, an order number. You control the uniqueness semantics.
Upsert is available on Builder ($9/month) and above. Free plan does not include it. This is intentional -- upsert is a production feature for systems that need idempotent writes.
Common patterns: sync a CRM contact list by upserting with the CRM record ID. Track application status by upserting with the applicant email. Update inventory counts by upserting with the SKU. Each call is a clean, atomic operation.
Dashboards and webhooks work the same with upserted data. The submission is the latest version. Charts update. Webhooks fire on both create and update.
# Upsert a submission (Builder/Pro/Scale plans)
curl -X PUT https://sutrena.com/api/forms/FORM_ID/submissions/upsert \
-H "Authorization: Bearer st_live_your_key" \
-H "Content-Type: application/json" \
-d '{
"externalId": "lead-42",
"payload": {
"email": "[email protected]",
"company": "Acme Corp",
"status": "qualified"
}
}'
# Response (201 if created, 200 if updated):
# { "id": "sub_abc", "created": true, "externalId": "lead-42", ... }
# Update the same record later:
curl -X PUT https://sutrena.com/api/forms/FORM_ID/submissions/upsert \
-H "Authorization: Bearer st_live_your_key" \
-H "Content-Type: application/json" \
-d '{
"externalId": "lead-42",
"payload": {
"email": "[email protected]",
"company": "Acme Corp",
"status": "closed-won"
}
}'
# Response: { "id": "sub_abc", "created": false, "externalId": "lead-42", ... }