Skip to content
SMBcrmSMBcrm Developers

Forms

Forms are built visually in the SMBcrm UI. The form builder, field layout, and styling all live there. The API gives you read access to the forms in your account and the submissions they’ve collected, plus a way to upload files to a contact’s custom fields.

Base URL: https://services.smbcrm.com · Version header: v3 · Scopes: forms.readonly (list forms and submissions), forms.write (upload files). See Scopes.

List forms

Section titled “List forms”
GET/forms/

List the forms built in your SMBcrm account.

scope forms.readonlyauth Location token or PIT

locationId is required. The default page size is 10, so use limit (up to 50) and skip to page through accounts with many forms. Keep paging until you’ve collected total forms.

Terminal window
curl "https://services.smbcrm.com/forms/?locationId=<location_id>&limit=20&skip=0" \
  -H "Authorization: Bearer <token>" \
  -H "Version: v3"
200 OK
{
  "forms": [
    {
      "id": "<form_id>",
      "name": "Contact Us",
      "locationId": "<location_id>"
    }
  ],
  "total": 1
}
Query param Type Required Description
locationId string Yes Your SMBcrm account/location ID.
limit number No Number of forms to return per page. Maximum 50, default 10.
skip number No Number of forms to skip, for pagination.
type string No Filter by item type, for example folder.

List form submissions

Section titled “List form submissions”
GET/forms/submissions

List submissions for one form or all forms in your account, within a date range (the last month by default).

scope forms.readonlyauth Location token or PIT

locationId is required. Add formId to scope results to a single form, and startAt / endAt to set the date range. Without them you get the last month of submissions.

Terminal window
curl "https://services.smbcrm.com/forms/submissions?locationId=<location_id>&formId=<form_id>&startAt=2026-01-01&endAt=2026-10-08&limit=20&page=1" \
  -H "Authorization: Bearer <token>" \
  -H "Version: v3"
200 OK
{
  "submissions": [
    {
      "id": "<submission_id>",
      "contactId": "<contact_id>",
      "createdAt": "2026-07-08T15:04:00.000Z",
      "formId": "<form_id>",
      "name": "Jordan Lee",
      "email": "jordan@example.com",
      "others": {
        "full_name": "Jordan Lee",
        "email": "jordan@example.com",
        "eventData": {
          "type": "page-visit",
          "page": {
            "url": "https://example.com/contact",
            "title": "Contact Us"
          },
          "domain": "example.com",
          "medium": "form",
          "source": "Direct traffic",
          "referrer": "https://example.com/",
          "pageVisitType": "form"
        },
        "fieldsOriSequance": ["full_name", "email"]
      }
    }
  ],
  "meta": {
    "total": 1,
    "currentPage": 1,
    "nextPage": null,
    "prevPage": null
  }
}

others holds the submitted field values, keyed by field key or custom field ID, plus two metadata entries:

  • eventData: attribution and page-visit details such as the page URL, referrer, and traffic source. Use it for lead-source reporting.
  • fieldsOriSequance: the original order of the form’s fields. The key is spelled this way in the response.
Query param Type Required Description
locationId string Yes Your SMBcrm account/location ID.
formId string No Limit results to submissions for one form.
limit number No Number of submissions to return per page. Maximum 100, default 20.
page number No Page number. Default 1.
q string No Filter by contact ID, name, email address, or phone number.
startAt string No Return submissions on or after this date, formatted YYYY-MM-DD. Defaults to the same date one month ago.
endAt string No Return submissions on or before this date, formatted YYYY-MM-DD. Defaults to today.

Upload files to a contact’s custom fields

Section titled “Upload files to a contact’s custom fields”
POST/forms/upload-custom-files

Upload a file and attach it to a contact's custom field.

scope forms.writeauth Location token or PIT

locationId and contactId are required query parameters. Send the files as multipart/form-data, not JSON: drop the Content-Type: application/json header and let your HTTP client set the multipart boundary for you.

Name each form field <custom_field_id>_<file_id>, where <custom_field_id> is the ID of the contact custom field the file belongs to and <file_id> is any unique value you generate (a UUID works). To upload several files in one request, add one field per file in the same format.

Terminal window
curl -X POST "https://services.smbcrm.com/forms/upload-custom-files?locationId=<location_id>&contactId=<contact_id>" \
  -H "Authorization: Bearer <token>" \
  -H "Version: v3" \
  -F "<custom_field_id>_<file_id>=@/path/to/resume.pdf" \
  -F "<other_custom_field_id>_<other_file_id>=@/path/to/photo.png"

A successful upload returns 200 OK with the updated contact object. To read the stored files later, fetch the contact with Retrieve a contact.

Limits

  • Maximum file size: 50 MB.
  • Allowed file types: PDF, DOC, DOCX, JPG, JPEG, PNG, GIF, CSV, XLS, XLSX, MP4, MPEG, ZIP, RAR, TXT, SVG.
Query param Type Required Description
locationId string Yes Your SMBcrm account/location ID.
contactId string Yes The contact to attach the uploaded file to.
Section titled “Related”