Form submissions

Use POST /v1/form_submissions when your backend handles form submissions server-side. Standard browser forms should use website form tracking instead; never expose a business API key in client-side code.

Submit once, retry with the same ID

When your server first receives a form submission, generate a unique UUID for it and store that UUID alongside the submission. Include a non-empty fields array where each item has a name and a string value (you can also pass optional label, type, and autocomplete metadata to describe each field):

curl --fail-with-body --request POST \
  --header "Authorization: Bearer $NMC_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{
    "id":"c7b3c74e-6628-4cd2-bcb4-0477b8cf911e",
    "fields":[
      {"name":"name","value":"Jane Example","autocomplete":"name"},
      {"name":"email","value":"jane@example.com","type":"email"},
      {"name":"message","value":"Please quote a heat pump installation."}
    ]
  }' \
  https://api.nomissedconversions.com/v1/form_submissions

Generate a fresh UUID for every new submission rather than reusing the example UUID above, and keep both id and the request body identical whenever you retry:

• Payload conflicts: Sending a different request body with an id NMC has already seen returns 409 (form_submission_conflict).
• Size and billing: Request bodies are capped at 64 KiB, and live submissions are deducted from the account’s balance when received.
• Paused tracking or stopped plan: If the account’s plan isn’t running (ended, past due past its grace period, or a stopped free trial), every /v1 endpoint, including read endpoints, returns 403 (plan_inactive). If tracking is paused because the balance is $0 or below, NMC rejects the submission with 409 (tracking_paused). Hold the submission in your queue and resend it with the same id once the plan or tracking resumes.

Check the result

NMC processes form submissions asynchronously:

• 202: NMC saved the submission (received status) and queued it to group into a contact and lead. Follow the Location response header or call GET /form_submissions/{submission_id} to check its status (received or processed).
• 200: Once the submission reaches processed, its record includes the resulting contact, lead, and activity IDs, and retrying the original POST returns 200 right away.

Link a website visit

To tie a server-side submission to a visitor session recorded by NMC’s tracking code, pass website_page_view_id for a page view belonging to the same business. If you include anonymous_visitor_id, you must also include website_page_view_id.

• With website_page_view_id: A new lead gets its channel, source, website visit history, and Google Ads click from that browser’s recorded visits, just like a tracked website form. See Where a lead came from.
• Without website_page_view_id: You can pass standalone attribution fields instead, which NMC stores on the activity and uses to set a new lead’s channel and source. Including a gclid, gbraid, or wbraid marks a new lead as Google Ads (a campaign name on its own does not). Because NMC didn’t record the visit itself and can’t verify the click’s age, NMC uploads that click ID to Google Ads on its own without the form’s contact details. Submissions without a linked page view won’t show the visitor’s website visits.