Formula Fields
A Formula field computes its value at read time from other fields on the same record. Formulas are read-only.
Create a Formula Field
POST /api/3.0/entity/EntityField
Authorization: Bearer <token>
Content-Type: application/json
Accept: application/json
{
"EntityId": "7NS0000000000A50001",
"Name": "DaysActive",
"Label": "Days Active",
"FieldTypeId": "7NY00000000000m0000",
"RelatedToFieldId": "7NY00000000000b0000",
"DefaultValue": "TODAY() - StartDate__c",
"DecimalPlaces": 0
}
Payload Reference
| Property | Notes |
|---|
FieldTypeId | 7NY00000000000m0000 (Formula). |
DefaultValue | The formula expression. Reference other fields by their API name (with __c suffix for custom fields). |
RelatedToFieldId | Required. The formula's return type, expressed as a FieldType ID (from Field Type Reference) — not a reference to another field. |
DecimalPlaces | For a numeric return type, sets the precision (for example, DecimalPlaces = 2 when returning Currency). Length is not accepted on a Formula field. |
Return Type → RelatedToFieldId
Set RelatedToFieldId to the FieldType ID of the type your formula evaluates to:
| Return type | RelatedToFieldId |
|---|
| Text | 7NY0000000000000000 |
| Number | 7NY00000000000b0000 |
| Currency | 7NY00000000000a0000 |
| Percent | 7NY00000000000c0000 |
| Date | 7NY0000000000070000 |
| DateTime | 7NY0000000000020000 |
| Checkbox (boolean) | 7NY0000000000050000 |
If the expression does not evaluate to the declared return type, the API returns an HTTP 406 with the parser's error message identifying the mismatch.
Behavior
- Formula fields are read-only. Attempting to write to one on a record CRUD call returns an error.
IsRequired is not allowed on Formula fields.IsUnique is not allowed on Formula fields.- Referencing a Formula's field name inside another Formula is allowed; cyclic references are rejected at save time.
- Changing a Formula's expression is done via PATCH on
DefaultValue. Changing the return type (RelatedToFieldId) is generally rejected if any other field depends on the current type.
Constraints on Length Changes
If a Text field is used inside a formula, that field's Length cannot be increased above 4,000 — the platform blocks the update to protect the formula's validity. Remove the formula's reference first, resize the Text field, then re-add the formula.
Formula Grammar and Function Reference
Formula syntax, operators, and the full function library (date functions, string functions, conditionals, aggregations) are documented separately. See Configuring Magentrix Entity Formula Fields for the complete grammar and function reference.
Common Examples
| Purpose | Return type | Expression |
|---|
| Days since a date | Number | TODAY() - StartDate__c |
| Full name concatenation | Text | FirstName + " " + LastName |
| Discounted total | Currency | Amount__c * (1 - DiscountPct__c / 100) |
| Is overdue | Checkbox | DueDate__c < TODAY() && !IsPaid__c |
| Priority label | Text | IF(Amount__c > 100000, "Enterprise", IF(Amount__c > 10000, "Mid", "SMB")) |
Field names in expressions are case-sensitive. Custom-field references must include the __c suffix.
<< Rollup Summary Fields | Entity Management API Overview