Unique Fields for Custom Objects in Sparkforge
Unique Fields block duplicate values in Sparkforge custom objects across every entry point: UI, forms, workflows, imports, and API. Up to 10 unique fields per object; supported types are Single Line, Multi Line, Number, and Phone.
Unique Fields stop duplicate values from being saved on a custom object. Mark a field unique and Sparkforge checks every create or update against existing records in the sub-account, blocking any value that already exists. That keeps your reporting clean and saves you from running deduplication projects later.
Rules and limits
- Up to 10 unique fields per object, scoped to the sub-account.
- Enforced across UI, Workflows, Forms, and APIs on both create and update.
- Supported field types: Single Line Text, Multi Line Text, Number, Phone.
- Downgrading a unique field to non-unique is irreversible. Once turned off, you cannot re-enable.
Mark a new field as unique
- Go to Settings → Custom Fields.
- Click + Add Field and select a supported type.
- Enter the field name, object, and group.
- Check Mark Field as Unique.
- Click Save.
Mark a primary field unique while creating a custom object
- Go to Settings → Objects.
- Click + Add Custom Object.
- Define the Object Name and Primary Display Field.
- Check Mark Primary Field as Unique — useful for identifiers like Case No. or VIN Number.
- Click Create Custom Object.
Downgrade a unique field
- Go to Settings → Custom Fields and find the field.
- Select the field and open Bulk Actions → Edit.
- Deselect Mark Field as Unique.
Once downgraded, you cannot mark the same field unique again. Plan field uniqueness early.
Behavior in common scenarios
| Scenario | Action | Result |
|---|---|---|
| Two records save the same value in a primary unique field | Save | Error: "A record with the same value already exists." |
| CSV import contains duplicate values | Import | Partial success — duplicate rows fail with warnings |
| Field marked unique, user attempts to delete it | Delete | Warning — field cannot be deleted |
| API update with a duplicate value | Update call | API returns a validation error |
Best practices
- Use unique fields for stable identifiers — Patient ID, Case No., Employee Code, VIN.
- Avoid marking frequently edited text fields unique.
- Deduplicate data externally before bulk imports to avoid skipped rows.
Frequently Asked Questions
Does uniqueness apply across the whole agency?
No. Uniqueness is enforced per sub-account. Two sub-accounts can hold the same value in the same unique field.
What error message do users see on a duplicate?
"A record with the same value for <fieldName> already exists." The save is blocked on both the UI and the API.
Can I mark a dropdown or email field as unique?
Not yet. Only Single Line Text, Multi Line Text, Number, and Phone fields support the unique flag.
Do uniqueness checks slow down API bulk inserts?
No. Validation runs at the database layer, so the performance hit on large batches is negligible.
What happens to duplicates during a CSV import?
The import finishes, but rows with duplicate unique-field values fail and are reported in the import warnings. Clean the file first to avoid skips.
Was this article helpful?
Thanks for the feedback.