Custom fields
Discover the custom fields your agency configured, then read and write them safely through the customFields object.
Each agency adds its own fields to clients, contacts, deals, leads and tickets: a segment, a budget, a contract end date. An integration cannot guess them, so the API lets you read their definitions first.
Discover the fields
GET /v1/fields returns every field of each entity: the built-in fields every agency has, and the custom fields your agency configured. Any valid key can call it.
curl "https://api.usedashly.com/v1/fields?entity=account" \
-H "Authorization: Bearer $DASHLY_API_KEY"{
"data": {
"account": [
{
"id": "account.name",
"key": "name",
"label": "Nom",
"type": "text",
"required": true,
"source": "builtin",
"deletable": false,
"options": null,
"location": "attribute"
},
{
"id": "fld_a1b2c3d4e5f6",
"key": "segment",
"label": "Segment",
"type": "select",
"required": false,
"source": "custom",
"deletable": true,
"options": [
{ "value": "smb", "label": "SMB" },
{ "value": "enterprise", "label": "Enterprise" }
],
"location": "customFields"
},
{
"id": "fld_q8w7e6r5t4y3",
"key": "contractEnd",
"label": "Contract end",
"type": "date",
"required": false,
"source": "custom",
"deletable": true,
"options": null,
"location": "customFields"
}
]
}
}The entities are account (clients), contact, deal, lead and ticket. Leave out ?entity= to get all of them. Each resource in the catalogue (GET /v1) says which entity applies to it in its customFields property.
| Property | Meaning |
|---|---|
id | Stable id. <entity>.<key> for a built-in field, fld_… for a custom one. |
key | The name you read and write. |
type | text, long_text, number, date, select, multi_select, checkbox, url, email or user. |
required | Whether a value must always be present. |
options | For select and multi_select: the accepted values. |
location | attribute: a top-level field of the record. customFields: an entry of the record's customFields object. |
Labels are the ones shown in the agency's dashboard and may be in French. Rely on key.
Read custom fields
Records whose resource has custom fields carry a customFields object, keyed by field key:
{
"data": {
"id": "hsbftmp3f5",
"name": "Boudbois",
"status": "active",
"customFields": { "segment": "smb", "contractEnd": "2027-03-31" }
}
}A field with no value is normally absent from the object.
Write custom fields
Send customFields in the body of a POST or PATCH:
curl -X POST https://api.usedashly.com/v1/clients \
-H "Authorization: Bearer $DASHLY_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "Lumen Bakery",
"status": "prospect",
"customFields": { "segment": "smb" }
}'The object is validated against your agency's definitions:
- Values are checked and converted to their type: a number must be numeric, a date parseable, a URL or email valid, a
selectvalue one of itsoptions, amulti_selecta list of them. - A required field without a value is refused with
422 validation_failed,details.reason: "field_required". - An invalid value is refused with
422 validation_failed,details.reason: "invalid_input". - In both cases
details.fieldis the key of the field at fault. - Keys that match no field of the entity are dropped.
PATCH replaces the whole object
PATCH merges the top-level fields you send, except customFields, which it replaces as a whole. Sending customFields with one key erases every other custom value of the record.
To change one custom field, read the record, merge your change into its current customFields, then write the full object back:
# 1. Read the current values
current=$(curl -s https://api.usedashly.com/v1/clients/hsbftmp3f5 \
-H "Authorization: Bearer $DASHLY_API_KEY" | jq '.data.customFields')
# 2. Merge your change
merged=$(echo "$current" | jq '. + { "segment": "enterprise" }')
# 3. Write the whole object back
curl -X PATCH https://api.usedashly.com/v1/clients/hsbftmp3f5 \
-H "Authorization: Bearer $DASHLY_API_KEY" \
-H "Content-Type: application/json" \
-d "{ \"customFields\": $merged }"const headers = {
Authorization: `Bearer ${process.env.DASHLY_API_KEY}`,
"Content-Type": "application/json",
};
const url = "https://api.usedashly.com/v1/clients/hsbftmp3f5";
const { data } = await (await fetch(url, { headers })).json();
const customFields = { ...data.customFields, segment: "enterprise" };
await fetch(url, { method: "PATCH", headers, body: JSON.stringify({ customFields }) });A PATCH that does not include customFields leaves the custom values untouched. To clear one value, merge and send the object without that key.
Because the whole object is validated on every write that includes it, a required custom field must be present in it each time.