Skip to main content

Documentation Index

Fetch the complete documentation index at: https://learn.nexudus.com/llms.txt

Use this file to discover all available pages before exploring further.

​
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

  1. Read custom field values from any GET response — the CustomFields object is included in single-record (GET by ID) and list/search results.
  2. Set custom field values by including the CustomFields object in your PUT request body.
  3. 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"
      }
    ]
  }
}
​
CustomFields.Data
array
required
Array of custom field entries for this record.
​
CustomFields.Data[].Name
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.
​
CustomFields.Data[].Value
string
required
The value to store. All values are represented as strings regardless of the field’s FieldType.
​
CustomFields.Data[].Type
string
required
The data type hint. Use "string" for most field types.
​
CustomFields.Data[].JsonValue
string
Reserved for complex values. Typically null.

​
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 valueEntity
1Customer
2Team
3FloorPlanDesk
4CrmOpportunity
5Visitor
6Proposal
7Customer (Internal)
8HelpDeskMessage
9HelpDeskDepartment
10Product
11Booking
12Invoice
13Location
14Contract
15Tariff
16Resource
17FloorPlan
18InventoryAsset
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.

​
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

EntityFilter parameter example
CustomerCoworker_CustomFields_12345=value
BookingBooking_CustomFields_12345=value
InvoiceCoworkerInvoice_CustomFields_12345=value
ProductProduct_CustomFields_12345=value
TeamTeam_CustomFields_12345=value
ContractContractProduct_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.