Custom Fields in Records

Custom fields allow you to store additional data on any record type in Nexudus (customers, invoices, bookings, products, and more). You can start using custom fields immediately via the API without any prior setup. If you need the field to be visible in the admin UI or member portal, you can optionally register it via the Custom Fields API.

How it works

Read custom field values from any GET response — the CustomFields object is included in single-record (GET by ID) and list/search results.
Set custom field values by including the CustomFields object in your PUT request body.
Optionally, register a custom field using the /api/crm/customfields endpoints if you need the field to appear in the Nexudus admin UI or member portal. This is not required for API-only usage.

You do not need to pre-register custom fields to use them via the API. You can store and retrieve arbitrary key-value data on any record by simply including a CustomFields object in your PUT requests. Registration is only necessary when you want the field to be visible and editable in the Nexudus UI.

The CustomFields object

Every record that supports custom fields includes a CustomFields property with the following structure:

{
  "CustomFields": {
    "Data": [
      {
        "Name": "1414363299",
        "Value": "ABC1234",
        "JsonValue": null,
        "Type": "string"
      }
    ]
  }
}

array

required

Array of custom field entries for this record.

string

required

The identifier for the custom field. This can be:

Any arbitrary string if you are using the API to store data without registering the field in the UI.
The Id of a registered custom field definition (as a string) if the field was created via GET /api/crm/customfields/{id}. When fields are registered, the UI uses the definition’s Id as the Name.

string

required

The value to store. All values are represented as strings regardless of the field’s FieldType.

string

required

The data type hint. Use "string" for most field types.

object

Read-only. Automatically populated when Type is "json" and Value contains a valid JSON structure. In that case, the field value is returned as a parsed JSON object rather than a string, making it easier to consume directly without additional parsing on the client side.

Reading custom field values

Custom field values are returned automatically in GET responses — both when retrieving a single record by ID and in list/search results.

Example: GET a single invoice

cURL

curl -X GET \
  "https://spaces.nexudus.com/api/billing/coworkerinvoices/1428806532" \
  -H "Authorization: Bearer YOUR_TOKEN"

The response includes the CustomFields property:

{
  "Id": 1428806532,
  "InvoiceNumber": "INV-0107",
  "Description": "HQ Teams (Tech 005)",
  "TotalAmount": 10.00,
  "CustomFields": {
    "Data": [
      {
        "Name": "1414363299",
        "Value": "ABC1234",
        "JsonValue": null,
        "Type": "string"
      }
    ]
  }
}

For registered custom fields, the Name in each entry corresponds to the Id of the custom field definition. Use GET /api/crm/customfields to look up the human-readable name and configuration. For unregistered fields, the Name is whatever string you chose when storing the value.

Setting custom field values

To set or update custom field values, include the CustomFields object in your PUT request body. You must send the full record as part of the PUT request (the API does not support PATCH).

Example: Update an invoice with a custom field value

cURL

curl -X PUT \
  "https://spaces.nexudus.com/api/billing/coworkerinvoices" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "Id": 1428806532,
    "CoworkerId": 1418015221,
    "BusinessId": 1414890114,
    "CustomFields": {
      "Data": [
        {
          "Name": "1414363299",
          "Type": "string",
          "Value": "ABC1234"
        }
      ]
    }
  }'

JavaScript

const response = await fetch(
  'https://spaces.nexudus.com/api/billing/coworkerinvoices',
  {
    method: 'PUT',
    headers: {
      'Authorization': 'Bearer YOUR_TOKEN',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      Id: 1428806532,
      CoworkerId: 1418015221,
      BusinessId: 1414890114,
      CustomFields: {
        Data: [
          {
            Name: '1414363299',
            Type: 'string',
            Value: 'ABC1234'
          }
        ]
      }
    })
  }
);

Python

import requests

response = requests.put(
    'https://spaces.nexudus.com/api/billing/coworkerinvoices',
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
        'Content-Type': 'application/json'
    },
    json={
        'Id': 1428806532,
        'CoworkerId': 1418015221,
        'BusinessId': 1414890114,
        'CustomFields': {
            'Data': [
                {
                    'Name': '1414363299',
                    'Type': 'string',
                    'Value': 'ABC1234'
                }
            ]
        }
    }
)

The Nexudus API does not support PATCH requests. Always read the full record first with a GET request, modify the CustomFields values, and then submit the complete record in your PUT request.

Setting multiple custom field values

Include multiple entries in the Data array to set several custom fields at once:

{
  "CustomFields": {
    "Data": [
      {
        "Name": "1414363299",
        "Type": "string",
        "Value": "ABC1234"
      },
      {
        "Name": "1414363300",
        "Type": "string",
        "Value": "2026-06-01"
      }
    ]
  }
}

Clearing a custom field value

To clear a custom field value, set Value to an empty string:

{
  "CustomFields": {
    "Data": [
      {
        "Name": "1414363299",
        "Type": "string",
        "Value": ""
      }
    ]
  }
}

Supported record types

Every record in the Nexudus REST API supports the CustomFields property — you can read and set custom field values on any record via the API regardless of whether a custom field definition exists for that record type. However, for custom fields to appear and be editable in the Nexudus admin UI, you must create a custom field definition with a matching RecordType. The following record types have UI support when creating a custom field definition:

RecordType value	Entity
1	Customer
2	Team
3	FloorPlanDesk
4	CrmOpportunity
5	Visitor
6	Proposal
7	Customer (Internal)
8	HelpDeskMessage
9	HelpDeskDepartment
10	Product
11	Booking
12	Invoice
13	Location
14	Contract
15	Tariff
16	Resource
17	FloorPlan
18	InventoryAsset

If you only need to store and retrieve data programmatically via the API, you can use the CustomFields array on any record without creating a custom field definition. The definition is only required if you want the field to be visible and editable in the admin dashboard or member portal.

Publishable Custom Fields on Customers

The Customer (Coworker) entity has an additional type of custom field called Publishable Custom Fields. These are distinct from the CustomFields array described above and are unique to the Coworker entity.

Two types of custom fields on Customers

Customers support both types of custom fields:

Feature	CustomFields Array	Custom1 – Custom30
Storage	JSON array in `CustomFields.Data`	Dedicated columns on the Coworker record
Fields available	Unlimited (key-value pairs)	30 fixed fields (`Custom1` to `Custom30`)
Visible in member portal	No (admin UI only when registered)	Yes — can be shown on public profiles
Queryable via filters	Via `Coworker_CustomFields_{id}=value`	Via `Coworker_Custom1=value`, etc.
RecordType for registration	7 (CustomerInternal)	1 (Customer)
API documentation	This page	Search Coworkers

What are Publishable Custom Fields?

Publishable Custom Fields are 30 dedicated string properties (Custom1 through Custom30) that exist directly on the Coworker entity. Unlike the CustomFields array, these are first-class properties of the record — not stored as key-value pairs. In the admin UI, these are referred to as “Publishable Custom Fields” because their values can optionally be displayed on a customer’s public profile in the member portal.

Reading Publishable Custom Fields

These fields are returned as top-level properties in GET responses, just like any other coworker property:

{
  "Id": 1418015221,
  "FullName": "Jane Smith",
  "Email": "jane@example.com",
  "Custom1": "Engineering",
  "Custom2": "Senior Developer",
  "Custom3": "",
  "CustomFields": {
    "Data": [
      {
        "Name": "1414363299",
        "Value": "ABC1234",
        "Type": "string",
        "JsonValue": null
      }
    ]
  }
}

Setting Publishable Custom Fields

Set these fields directly in the PUT request body as top-level properties:

cURL

curl -X PUT \
  "https://spaces.nexudus.com/api/spaces/coworkers" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "Id": 1418015221,
    "FullName": "Jane Smith",
    "Custom1": "Engineering",
    "Custom2": "Senior Developer",
    "Custom3": "Remote-First"
  }'

JavaScript

const response = await fetch(
  'https://spaces.nexudus.com/api/spaces/coworkers',
  {
    method: 'PUT',
    headers: {
      'Authorization': 'Bearer YOUR_TOKEN',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      Id: 1418015221,
      FullName: 'Jane Smith',
      Custom1: 'Engineering',
      Custom2: 'Senior Developer',
      Custom3: 'Remote-First'
    })
  }
);

Filtering by Publishable Custom Fields

Because these are regular properties on the Coworker entity, you can filter by them using standard query parameters:

cURL

curl -X GET \
  "https://spaces.nexudus.com/api/spaces/coworkers?Coworker_Custom1=Engineering" \
  -H "Authorization: Bearer YOUR_TOKEN"

JavaScript

const response = await fetch(
  'https://spaces.nexudus.com/api/spaces/coworkers?Coworker_Custom1=Engineering',
  {
    headers: {
      'Authorization': 'Bearer YOUR_TOKEN'
    }
  }
);

You can combine publishable custom field filters with CustomFields array filters in the same request:

GET /api/spaces/coworkers?Coworker_Custom1=Engineering&Coworker_CustomFields_1414363299=ABC1234

For the complete list of query parameters available when searching coworkers (including all 30 publishable custom fields), see the Search Coworkers API documentation.

Searching and filtering by custom field values

You can filter list/search results by custom field values using query string parameters. The filter parameter follows this pattern:

{EntityName}_CustomFields_{CustomFieldId}={value}

Where:

{EntityName} is the API entity name (e.g. CoworkerInvoice, Coworker, Booking)
{CustomFieldId} is the Name used when storing the custom field value — this is the Id of a registered custom field definition, or any arbitrary name you used when setting the value directly via the API
{value} is the value to filter by

Example: Find invoices by custom field value

cURL

curl -X GET \
  "https://spaces.nexudus.com/api/billing/coworkerinvoices?CoworkerInvoice_CustomFields_1414363299=ABC1234" \
  -H "Authorization: Bearer YOUR_TOKEN"

JavaScript

const response = await fetch(
  'https://spaces.nexudus.com/api/billing/coworkerinvoices?CoworkerInvoice_CustomFields_1414363299=ABC1234',
  {
    headers: {
      'Authorization': 'Bearer YOUR_TOKEN'
    }
  }
);

Python

import requests

response = requests.get(
    'https://spaces.nexudus.com/api/billing/coworkerinvoices',
    params={
        'CoworkerInvoice_CustomFields_1414363299': 'ABC1234'
    },
    headers={
        'Authorization': 'Bearer YOUR_TOKEN'
    }
)

More examples by entity type

Entity	Filter parameter example
Customer	`Coworker_CustomFields_12345=value`
Booking	`Booking_CustomFields_12345=value`
Invoice	`CoworkerInvoice_CustomFields_12345=value`
Product	`Product_CustomFields_12345=value`
Team	`Team_CustomFields_12345=value`
Contract	`ContractProduct_CustomFields_12345=value`

The filter performs a case-insensitive string match on the custom field value. You can combine custom field filters with any other standard query filters on the same request.

Registered vs unregistered custom fields

There are two ways to use custom fields:

Unregistered fields (API-only)

You can store custom data on any record without pre-registering the field. Simply choose a meaningful name and include it in your PUT request:

{
  "CustomFields": {
    "Data": [
      {
        "Name": "purchase_order_ref",
        "Type": "string",
        "Value": "PO-2026-001"
      }
    ]
  }
}

Unregistered fields are stored and returned in API responses, but they will not appear anywhere in the Nexudus admin UI or member portal.

Registered fields (visible in the UI)

To make a custom field visible and editable in the UI, create a custom field definition via the /api/crm/customfields endpoint. Once registered, the field’s Id is used as the Name when reading and writing values:

cURL

curl -X GET \
  "https://spaces.nexudus.com/api/crm/customfields?CustomField_RecordType=12" \
  -H "Authorization: Bearer YOUR_TOKEN"

This returns all registered custom field definitions for invoices (RecordType 12). Use the Id from each result as the Name value in your CustomFields.Data entries.

When you register a custom field, the Nexudus UI uses the field definition’s Id as the Name stored on each record. This is why registered fields have numeric names (e.g. "1414363299") rather than human-readable ones.

Overview

Apps & Marketplace

Billing

Collaboration

Community

Content

CRM

Security

Spaces

Support

System

Custom Fields in Records

Custom Fields in Records

How it works

The CustomFields object

Reading custom field values

Example: GET a single invoice

Setting custom field values

Example: Update an invoice with a custom field value

Setting multiple custom field values

Clearing a custom field value

Supported record types

Publishable Custom Fields on Customers

Two types of custom fields on Customers

What are Publishable Custom Fields?

Reading Publishable Custom Fields

Setting Publishable Custom Fields

Filtering by Publishable Custom Fields

Searching and filtering by custom field values

Example: Find invoices by custom field value

More examples by entity type

Registered vs unregistered custom fields

Unregistered fields (API-only)

Registered fields (visible in the UI)

​Custom Fields in Records

​How it works

​The CustomFields object

​Reading custom field values

​Example: GET a single invoice

​Setting custom field values

​Example: Update an invoice with a custom field value

​Setting multiple custom field values

​Clearing a custom field value

​Supported record types

​Publishable Custom Fields on Customers

​Two types of custom fields on Customers

​What are Publishable Custom Fields?

​Reading Publishable Custom Fields

​Setting Publishable Custom Fields

​Filtering by Publishable Custom Fields

​Searching and filtering by custom field values

​Example: Find invoices by custom field value

​More examples by entity type

​Registered vs unregistered custom fields

​Unregistered fields (API-only)

​Registered fields (visible in the UI)

Custom Fields in Records

How it works

The CustomFields object

Reading custom field values

Example: GET a single invoice

Setting custom field values

Example: Update an invoice with a custom field value

Setting multiple custom field values

Clearing a custom field value

Supported record types

Publishable Custom Fields on Customers

Two types of custom fields on Customers

What are Publishable Custom Fields?

Reading Publishable Custom Fields

Setting Publishable Custom Fields

Filtering by Publishable Custom Fields

Searching and filtering by custom field values

Example: Find invoices by custom field value

More examples by entity type

Registered vs unregistered custom fields

Unregistered fields (API-only)

Registered fields (visible in the UI)