Custom Fields, Values & Tags

Custom fields, custom values, and tags let you extend and label the data in your SMBcrm account without changing your data model. Custom fields attach structured data, like a referral source or preferred contact method, to records such as contacts. Custom values are reusable snippets you can drop into templates and messages. Tags are simple labels you can filter and automate on.

Base URL: https://services.smbcrm.com · Version header: v3 · Scopes: locations/customFields.readonly, locations/customFields.write, locations/customValues.readonly, locations/customValues.write, locations/tags.readonly, locations/tags.write. See Scopes.

Custom values and tags take your account/location ID as a path segment, as described in Base URL & Headers. Custom field endpoints vary — some take locationId as a query parameter, some as a body field, and looking up or deleting a field by ID doesn’t need it at all. Each endpoint below shows exactly where it goes.

Custom fields

A custom field belongs to an object type, such as contact, and can be grouped into a folder you manage in your account’s custom field settings.

Tip

The id returned for a custom field is the same value you send back in a contact’s customFields array when creating or updating a contact. See Contacts for the full contact shape.

GET/custom-fields/object-key/{objectKey}

List custom fields (and folders) defined for an object, such as contact.

scope locations/customFields.readonlyauth Location token or PIT

curl "https://services.smbcrm.com/custom-fields/object-key/contact?locationId=<location_id>" \
  -H "Authorization: Bearer <token>" \
  -H "Version: v3"

200 OK

{
  "fields": [
    {
      "id": "<field_id>",
      "name": "Referral Source",
      "fieldKey": "contact.referral_source",
      "dataType": "TEXT",
      "objectKey": "contact",
      "showInForms": true
    },
    {
      "id": "<field_id_2>",
      "name": "Preferred Contact Method",
      "fieldKey": "contact.preferred_contact_method",
      "dataType": "SINGLE_OPTIONS",
      "objectKey": "contact",
      "showInForms": true,
      "options": [
        { "key": "email", "label": "Email" },
        { "key": "phone", "label": "Phone" },
        { "key": "sms", "label": "SMS" }
      ]
    }
  ],
  "folders": []
}

GET/custom-fields/{id}

Get one custom field by ID.

scope locations/customFields.readonlyauth Location token or PIT

curl https://services.smbcrm.com/custom-fields/<field_id> \
  -H "Authorization: Bearer <token>" \
  -H "Version: v3"

200 OK

{
  "field": {
    "id": "<field_id>",
    "locationId": "<location_id>",
    "name": "Referral Source",
    "fieldKey": "contact.referral_source",
    "dataType": "TEXT",
    "objectKey": "contact",
    "parentId": "<parent_id>",
    "showInForms": true,
    "dateAdded": "2026-07-08T15:04:00.000Z",
    "dateUpdated": "2026-07-08T15:04:00.000Z"
  }
}

POST/custom-fields/

Create a custom field (body: locationId, dataType, fieldKey, objectKey, parentId, showInForms).

scope locations/customFields.writeauth Location token or PIT

Send locationId, dataType, fieldKey, objectKey, parentId, and showInForms — all six are required. dataType is one of TEXT, LARGE_TEXT, NUMERICAL, PHONE, MONETORY (the API’s own spelling), CHECKBOX, SINGLE_OPTIONS, or MULTIPLE_OPTIONS. Choice-type fields — SINGLE_OPTIONS and MULTIPLE_OPTIONS — also take an options array of { key, label, url } objects; other data types ignore it. parentId places the field in a folder in your account’s custom field settings.

curl -X POST https://services.smbcrm.com/custom-fields/ \
  -H "Authorization: Bearer <token>" \
  -H "Version: v3" \
  -H "Content-Type: application/json" \
  -d '{
    "locationId": "<location_id>",
    "name": "Preferred Contact Method",
    "dataType": "SINGLE_OPTIONS",
    "fieldKey": "contact.preferred_contact_method",
    "objectKey": "contact",
    "parentId": "<parent_id>",
    "showInForms": true,
    "options": [
      { "key": "email", "label": "Email" },
      { "key": "phone", "label": "Phone" },
      { "key": "sms", "label": "SMS" }
    ]
  }'

201 Created

{
  "field": {
    "id": "<field_id>",
    "locationId": "<location_id>",
    "name": "Preferred Contact Method",
    "fieldKey": "contact.preferred_contact_method",
    "dataType": "SINGLE_OPTIONS",
    "objectKey": "contact",
    "parentId": "<parent_id>",
    "showInForms": true,
    "options": [
      { "key": "email", "label": "Email" },
      { "key": "phone", "label": "Phone" },
      { "key": "sms", "label": "SMS" }
    ],
    "dateAdded": "2026-07-08T15:04:00.000Z",
    "dateUpdated": "2026-07-08T15:04:00.000Z"
  }
}

PUT/custom-fields/{id}

Update a custom field (body: locationId, showInForms).

scope locations/customFields.writeauth Location token or PIT

locationId and showInForms are required; dataType, fieldKey, objectKey, and parentId can’t be changed after creation.

curl -X PUT https://services.smbcrm.com/custom-fields/<field_id> \
  -H "Authorization: Bearer <token>" \
  -H "Version: v3" \
  -H "Content-Type: application/json" \
  -d '{
    "locationId": "<location_id>",
    "name": "Preferred Contact Method",
    "showInForms": true,
    "options": [
      { "key": "email", "label": "Email" },
      { "key": "phone", "label": "Phone" },
      { "key": "sms", "label": "SMS" },
      { "key": "mail", "label": "Mail" }
    ]
  }'

DELETE/custom-fields/{id}

Delete a custom field.

scope locations/customFields.writeauth Location token or PIT

curl -X DELETE https://services.smbcrm.com/custom-fields/<field_id> \
  -H "Authorization: Bearer <token>" \
  -H "Version: v3"

200 OK

{ "succeded": true, "id": "<field_id>", "key": "contact.preferred_contact_method" }

The response uses the API’s own spelling, succeded, not succeeded.

Custom values

Custom values are named snippets you define once in your account and reuse by name across templates and messages. Typical examples are a business phone number, a support email address, or a shipping cutoff time.

GET/locations/{locationId}/customValues

List custom values.

scope locations/customValues.readonlyauth Location token or PIT

curl https://services.smbcrm.com/locations/<location_id>/customValues \
  -H "Authorization: Bearer <token>" \
  -H "Version: v3"

200 OK

{
  "customValues": [
    { "id": "<value_id>", "name": "Business Phone", "fieldKey": "business_phone", "value": "+15125550100" },
    { "id": "<value_id_2>", "name": "Support Email", "fieldKey": "support_email", "value": "support@example.com" }
  ]
}

GET/locations/{locationId}/customValues/{id}

Get one custom value.

scope locations/customValues.readonlyauth Location token or PIT

curl https://services.smbcrm.com/locations/<location_id>/customValues/<value_id> \
  -H "Authorization: Bearer <token>" \
  -H "Version: v3"

200 OK

{
  "customValue": {
    "id": "<value_id>",
    "name": "Business Phone",
    "fieldKey": "business_phone",
    "value": "+15125550100"
  }
}

POST/locations/{locationId}/customValues

Create a custom value (body: name, value).

scope locations/customValues.writeauth Location token or PIT

curl -X POST https://services.smbcrm.com/locations/<location_id>/customValues \
  -H "Authorization: Bearer <token>" \
  -H "Version: v3" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Business Phone",
    "value": "+15125550100"
  }'

201 Created

{
  "customValue": {
    "id": "<value_id>",
    "name": "Business Phone",
    "fieldKey": "business_phone",
    "value": "+15125550100"
  }
}

PUT/locations/{locationId}/customValues/{id}

Update a custom value (body: name, value).

scope locations/customValues.writeauth Location token or PIT

Both name and value are required — this endpoint replaces the custom value, it doesn’t patch a single field.

curl -X PUT https://services.smbcrm.com/locations/<location_id>/customValues/<value_id> \
  -H "Authorization: Bearer <token>" \
  -H "Version: v3" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Business Phone", "value": "+15125550199" }'

DELETE/locations/{locationId}/customValues/{id}

Delete a custom value.

scope locations/customValues.writeauth Location token or PIT

curl -X DELETE https://services.smbcrm.com/locations/<location_id>/customValues/<value_id> \
  -H "Authorization: Bearer <token>" \
  -H "Version: v3"

Tags

Tags are short labels you attach to contacts to segment lists and trigger automations. This section manages the tag definitions for your account; to add or remove a tag on a specific contact, use the tag endpoints on the Contacts API instead.

GET/locations/{locationId}/tags

List tags.

scope locations/tags.readonlyauth Location token or PIT

curl https://services.smbcrm.com/locations/<location_id>/tags \
  -H "Authorization: Bearer <token>" \
  -H "Version: v3"

200 OK

{
  "tags": [
    { "id": "<tag_id>", "name": "website-lead" },
    { "id": "<tag_id_2>", "name": "vip" }
  ]
}

GET/locations/{locationId}/tags/{tagId}

Get one tag.

scope locations/tags.readonlyauth Location token or PIT

curl https://services.smbcrm.com/locations/<location_id>/tags/<tag_id> \
  -H "Authorization: Bearer <token>" \
  -H "Version: v3"

200 OK

{
  "tag": { "id": "<tag_id>", "name": "website-lead" }
}

POST/locations/{locationId}/tags

Create a tag (body: name).

scope locations/tags.writeauth Location token or PIT

curl -X POST https://services.smbcrm.com/locations/<location_id>/tags \
  -H "Authorization: Bearer <token>" \
  -H "Version: v3" \
  -H "Content-Type: application/json" \
  -d '{ "name": "webinar-2026" }'

201 Created

{
  "tag": { "id": "<tag_id>", "name": "webinar-2026" }
}

PUT/locations/{locationId}/tags/{tagId}

Update a tag.

scope locations/tags.writeauth Location token or PIT

curl -X PUT https://services.smbcrm.com/locations/<location_id>/tags/<tag_id> \
  -H "Authorization: Bearer <token>" \
  -H "Version: v3" \
  -H "Content-Type: application/json" \
  -d '{ "name": "webinar-2026-replay" }'

DELETE/locations/{locationId}/tags/{tagId}

Delete a tag.

scope locations/tags.writeauth Location token or PIT

curl -X DELETE https://services.smbcrm.com/locations/<location_id>/tags/<tag_id> \
  -H "Authorization: Bearer <token>" \
  -H "Version: v3"

Related

• Contacts: the customFields array you send when creating or updating a contact matches the fields you define here, and contacts carry the tags you define here.
• Locations: other account-level settings for your SMBcrm location.
• Scopes: the full list of scopes your token can request.