> ## Documentation Index
> Fetch the complete documentation index at: https://docs.decisionly.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Custom Fields

> Associate additional metadata with your cases

Custom fields allow you to associate additional data with your cases using key-value pairs. This feature provides flexibility to include additional information that isn't covered by Decisionly's standard fields.

## Custom Field Requirements

Custom fields must adhere to the following requirements:

* **Field limit:** Maximum of 25 key-value pairs per case
* **Key constraints:** Each key must be 50 characters or fewer
* **Value types:** Values must be strings only
* **String values:** Maximum length of 250 characters

## Using Custom Fields

When creating or updating a case, you can include custom fields in your request body. These fields can be used to:

* Store internal reference IDs
* Include category or classification data
* Trigger workflow rules for automated case handling
* Store any other relevant case metadata

## Managing Custom Fields

You can create, update, and remove custom fields as needed:

* **Create/Update:** Set a value for the field in your request
* **Remove:** Set the field value to `null` to completely remove the key-value pair from the case

## Example

<CodeGroup>
  ```json Creating a case with custom fields theme={null}
  // POST /v2/issuer/cases
  {
    "cardholder": {
      "issuer_id": "9529456289",
      "name": "Jane Smith",
      "email": "jane@example.com",
      "type": "individual"
    },
    "merchant": {
      "name": "FoodHub",
      "category_code": "5812"
    },
    "transaction": {
      "arn": "48162855246353338636162",
      "date": "2026-03-01T00:00:00.000Z",
      "amount": 2990,
      "currency": "USD",
      "card": {
        "network": "mastercard",
        "type": "credit",
        "last4": "4242",
        "expiry_month": 12,
        "expiry_year": 2028
      }
    },
    "dispute": {
      "amount": 2990,
      "currency": "USD",
      "date": "2026-04-01T00:00:00.000Z",
      "raised_by": "cardholder",
      "reason": "fraud"
    },
    "custom_fields": {
      "internal_reference_id": "REF-12345",
      "wallet_type": "mobile",
      "customer_category": "platinum",
      "card_program": "CardHub"
    }
  }
  ```

  ```json Updating custom fields theme={null}
  // PUT /v2/issuer/cases/case_abc123
  {
    "custom_fields": {
      "internal_reference_id": "REF-67890",
      "priority": "high"
    }
  }
  ```
</CodeGroup>

## Custom Fields with Workflow Rules

Custom fields can power Decisionly's workflow rules, enabling automated actions based on field values. When using custom fields for workflow automation:

* **Maintain consistency:** Use identical string values across cases (e.g., always use "high\_priority" instead of mixing with "High Priority")
* **Document conventions:** Maintain internal documentation of your custom field naming and value conventions