Reference
REST API
Read your forms and submissions over HTTPS with a Bearer API key. JSON in, JSON out. Read-only for now; available on paid plans.
Authentication
Create a key in Settings → API keys (it's shown once). Send it as a Bearer token on every request. Call the API from your server — never ship a key to the browser.
terminal
curl https://shipmyform.com/api/v1/forms \
-H "Authorization: Bearer smf_your_key_here"Base URL: All endpoints live under
https://shipmyform.com/api/v1. Responses are JSON; errors use { "ok": false, "error": "<code>", "message": "…" }.List forms
GET /forms— every form in the key's workspace.
GET /forms
{
"forms": [
{ "id": "frm_8Kx2mQ9pL4vN", "name": "Contact", "submissions": 42, "createdAt": "2026-08-01T10:00:00.000Z" }
]
}List a form's submissions
GET /forms/{formId}/submissions. Query params: status (ok, spam, or flagged), page (default 1), and limit (default 25, max 100).
terminal
curl "https://shipmyform.com/api/v1/forms/frm_8Kx2mQ9pL4vN/submissions?status=ok&page=1&limit=25" \
-H "Authorization: Bearer smf_your_key_here"response
{
"submissions": [
{
"id": "sub_1a2b3c",
"formId": "frm_8Kx2mQ9pL4vN",
"createdAt": "2026-08-20T14:03:00.000Z",
"status": "ok",
"spamScore": 0,
"subject": null,
"country": "US",
"data": { "email": "[email protected]", "message": "Hello!" }
}
],
"page": 1,
"limit": 25,
"total": 42,
"hasMore": true
}Get one submission
GET /submissions/{id}— a single submission, scoped to the key's workspace.
GET /submissions/{id}
{
"submission": {
"id": "sub_1a2b3c",
"formId": "frm_8Kx2mQ9pL4vN",
"createdAt": "2026-08-20T14:03:00.000Z",
"status": "ok",
"spamScore": 0,
"subject": null,
"country": "US",
"data": { "email": "[email protected]", "message": "Hello!" }
}
}Errors
| Status | error | When |
|---|---|---|
| 401 | unauthorized | Missing or invalid API key. |
| 403 | plan | The key's workspace is not on a plan with API access. |
| 400 | bad_request | An invalid query parameter (e.g. an unknown status). |
| 404 | not_found | No form or submission matches that id in this workspace. |
| 429 | rate_limited | Over 120 requests per minute for this key (see Retry-After). |
Keys are secret: Send keys only from server-side code over HTTPS. They're stored as a hash (shown once), so create a replacement if one is lost, and revoke any key instantly in Settings.