Skip to main content

Customer Attributes

Customer Attributes are flexible key-value pairs that can be attached to any customer record to store custom metadata, configuration settings, or business-specific information that doesn't fit into standard customer fields.

For visual customer categorization and clickable links, see Customer Tags <administration_tags>. For basic customer information, see Customers, Contacts, Sites & Services <basics_customers>.

Unlike fixed database fields, attributes allow you to dynamically extend customer records without modifying the database schema. This makes them ideal for storing deployment-specific data, integration parameters, or custom business logic flags.

Purpose and Use Cases​

Common use cases for Customer Attributes include:

1. Integration Data

Store external system identifiers or API keys specific to this customer:

  • external_crm_id = "SF-12345" (Salesforce customer ID)
  • legacy_system_id = "OLD-CRM-789" (Migration reference)
  • hubspot_contact_id = "12345678" (HubSpot integration)

2. Custom Business Logic

Store flags or settings that control customer-specific behavior:

  • billing_method = "quarterly" (Override default monthly billing)
  • auto_provision = "true" (Enable automatic service provisioning)
  • support_tier = "premium" (Custom support level)
  • credit_limit = "10000" (Customer-specific credit limit)

3. Compliance and Regulatory Data

Track compliance-related metadata:

  • gdpr_consent_date = "2025-01-01" (Data processing consent)
  • tax_exempt = "true" (Tax exemption status)
  • regulatory_entity = "FCC-123456" (Regulatory identifier)

4. Operational Metadata

Store operational information:

  • preferred_contact_method = "email" (Communication preference)
  • account_manager = "<john.smith@company.com>" (Assigned account manager)
  • onboarding_date = "2025-01-15" (Customer lifecycle tracking)
  • churn_risk_score = "0.23" (Predictive analytics)

5. Provisioning Parameters

Store provisioning-specific configuration:

  • radius_username_format = "email" (Custom RADIUS format)
  • vlan_id = "100" (Network configuration)
  • ipv6_enabled = "true" (Feature flags)

Attributes vs. Standard Fields​

Use Attributes When:

  • Data is deployment-specific or varies by installation
  • Requirements change frequently
  • Storing integration-specific metadata
  • Prototyping new features before adding database fields
  • Data doesn't need complex querying or joins

Use Standard Fields When:

  • Data is core to the customer model (name, email, address)
  • Frequent searching, filtering, or reporting required
  • Data has referential integrity constraints
  • Performance is critical for large-scale queries

Managing Attributes via the UI​

Viewing Customer Attributes​

To view attributes for a customer:

  1. Navigate to the customer's overview page
  2. Click on the Attributes tab
  3. You will see a table of all attributes for this customer, showing:
    • Attribute Name (key)
    • Attribute Value
    • Created date
    • Last Modified date

Creating a New Attribute​

To create a new attribute for a customer:

  1. Navigate to the customer's overview page
  2. Click on the Attributes tab
  3. Click the Add Attribute button
  4. Fill in the required fields:
    • Attribute Name (required): The key/name for this attribute (e.g., external_crm_id)
    • Attribute Value (required): The value to store (e.g., SF-12345)
  5. Click Create Attribute

Naming Conventions:

  • Use lowercase with underscores: external_system_id ✓
  • Avoid spaces: external system id ✗
  • Keep names descriptive but concise
  • Use consistent naming across customers for same attribute types

Editing an Attribute​

To edit an existing attribute:

  1. Navigate to the customer's overview page
  2. Click on the Attributes tab
  3. Find the attribute you want to edit in the table
  4. Click the Edit (pencil) button
  5. Modify the attribute name or value
  6. Click Update Attribute

Note

Changing an attribute name creates a new key-value pair. Ensure this doesn't break integrations that depend on the original attribute name.

Deleting an Attribute​

To delete an attribute:

  1. Navigate to the customer's overview page
  2. Click on the Attributes tab
  3. Find the attribute you want to delete in the table
  4. Click the Delete (trash) button
  5. Confirm the deletion in the popup

Warning

Deleting attributes used by integrations, provisioning workflows, or billing logic may cause failures. Verify dependencies before deletion.

Attribute Field Reference​

API Integration​

Attributes can be managed programmatically via the API:

Create or Update an Attribute​

Endpoint: PUT /crm/attribute/

Required Permission: create_customer_attribute

Request Body:

{
  "customer_id": 123,
  "attribute_name": "external_crm_id",
  "attribute_value": "SF-12345"
}

Response:

{
  "attribute_id": 456,
  "customer_id": 123,
  "attribute_name": "external_crm_id",
  "attribute_value": "SF-12345",
  "created": "2025-01-04 10:30:00",
  "last_modified": "2025-01-04 10:30:00"
}

Update an Existing Attribute​

Endpoint: PATCH /crm/attribute/attribute_id/{attribute_id}

Required Permission: update_customer_attribute

Request Body:

{
  "attribute_value": "SF-54321"
}

Get Attribute by ID​

Endpoint: GET /crm/attribute/attribute_id/{attribute_id}

Required Permission: view_customer_attribute

Response:

{
  "attribute_id": 456,
  "customer_id": 123,
  "attribute_name": "external_crm_id",
  "attribute_value": "SF-12345",
  "created": "2025-01-04 10:30:00",
  "last_modified": "2025-01-04 10:30:00"
}

Get All Attributes by Customer ID​

Endpoint: GET /crm/attribute/customer_id/{customer_id}

Required Permission: view_customer_attribute

Response:

[
  {
    "attribute_id": 456,
    "customer_id": 123,
    "attribute_name": "external_crm_id",
    "attribute_value": "SF-12345",
    "created": "2025-01-04 10:30:00",
    "last_modified": "2025-01-04 10:30:00"
  },
  {
    "attribute_id": 457,
    "customer_id": 123,
    "attribute_name": "billing_method",
    "attribute_value": "quarterly",
    "created": "2025-01-04 10:35:00",
    "last_modified": "2025-01-04 10:35:00"
  }
]

Delete an Attribute​

Endpoint: DELETE /crm/attribute/attribute_id/{attribute_id}

Required Permission: delete_customer_attribute

Response:

{
  "result": "success"
}

Bulk Attribute Operations​

Managing Multiple Attributes​

To set multiple attributes for a customer at once (e.g., during onboarding or integration sync):

import requests

customer_id = 123
attributes = [
    {"attribute_name": "external_crm_id", "attribute_value": "SF-12345"},
    {"attribute_name": "billing_method", "attribute_value": "quarterly"},
    {"attribute_name": "support_tier", "attribute_value": "premium"}
]

for attr in attributes:
    attr["customer_id"] = customer_id
    requests.put(
        "https://api.example.com/crm/attribute/",
        json=attr,
        headers={"Authorization": "Bearer YOUR_TOKEN"}
    )

Querying Customers by Attribute​

While attributes don't have built-in search endpoints, you can filter customers by attribute using the customer search API with custom filtering:

# Get all customers, then filter by attribute in application code
customers = requests.get("https://api.example.com/crm/customer/").json()

for customer in customers:
    attributes = requests.get(
        f"https://api.example.com/crm/attribute/customer_id/{customer['customer_id']}"
    ).json()

    # Find customers with specific attribute
    for attr in attributes:
        if attr['attribute_name'] == 'support_tier' and attr['attribute_value'] == 'premium':
            print(f"Premium customer: {customer['customer_name']}")

Note

For frequent attribute-based queries, consider adding indexed database fields or implementing a dedicated search endpoint.

Best Practices​

1. Naming Conventions

  • Use snake_case: external_system_id ✓
  • Be descriptive: billing_method ✓ vs method ✗
  • Avoid reserved keywords or special characters
  • Document attribute meanings in your deployment guide

2. Data Types

  • Attributes store values as strings (max 150 characters)
  • For booleans, use "true"/"false" (lowercase)
  • For dates, use ISO 8601 format: "2025-01-04 10:30:00"
  • For large JSON data, consider dedicated database fields instead

3. Validation

  • Validate attribute values in application code before saving
  • Use consistent value formats across customers
  • Document expected values for each attribute name

4. Documentation

  • Maintain a registry of attribute names and purposes
  • Document which systems/integrations depend on specific attributes
  • Include examples of valid values

5. Migration and Cleanup

  • Regularly audit unused attributes
  • Remove obsolete attributes after system migrations
  • Version attribute names when changing schemas (e.g., api_key_v2)

Example Workflows​

Onboarding Integration​

When migrating customers from a legacy system:

# Store legacy system reference for debugging
PUT /crm/attribute/
{
  "customer_id": 123,
  "attribute_name": "legacy_crm_id",
  "attribute_value": "OLD-12345"
}

# Track migration date
PUT /crm/attribute/
{
  "customer_id": 123,
  "attribute_name": "migrated_date",
  "attribute_value": "2025-01-04"
}

Custom Billing Rules​

Override default billing cycle for specific customer:

# Set quarterly billing
PUT /crm/attribute/
{
  "customer_id": 123,
  "attribute_name": "billing_cycle",
  "attribute_value": "quarterly"
}

# Then in billing code, check for attribute before processing
attributes = GET /crm/attribute/customer_id/123
billing_cycle = next(
    (a['attribute_value'] for a in attributes if a['attribute_name'] == 'billing_cycle'),
    'monthly'  # default
)

Feature Flags​

Enable beta features for specific customers:

# Enable IPv6 provisioning
PUT /crm/attribute/
{
  "customer_id": 123,
  "attribute_name": "feature_ipv6_enabled",
  "attribute_value": "true"
}

Permissions​

Attribute operations require the following permissions:

  • view_customer_attribute - View attributes
  • create_customer_attribute - Create new attributes
  • update_customer_attribute - Modify existing attributes
  • delete_customer_attribute - Remove attributes

See rbac for role-based access control configuration.

Troubleshooting​

Attribute Not Appearing in UI

  • Verify attribute was created (check API response)
  • Refresh the page to reload customer data
  • Check user has view_customer_attribute permission

Cannot Update Attribute

  • Ensure you have update_customer_attribute permission
  • Verify attribute_id is correct
  • Check attribute belongs to specified customer

Integration Failing After Attribute Deletion

  • Restore attribute with previous value
  • Update integration code to handle missing attributes gracefully
  • Audit attribute dependencies before deletion

Attribute Value Truncated

  • Attribute values have 150 character limit
  • For longer data, split into multiple attributes or use customer notes field
  • Consider storing large data in dedicated database fields
Last updated on