DM Hero Developers
API reference
Menu

Reference

Custom fields

Custom fields: 4 operations (custom_fields.list, custom_fields.create, custom_fields.update, custom_fields.delete).

The definitions of the fields a workspace adds to its leads. How their values are read, written, filtered, set in bulk, exported and reported by webhooks: Custom fields.

MethodPathOperation
GET/v1/custom-fieldscustom_fields.list
POST/v1/custom-fieldscustom_fields.create
PATCH/v1/custom-fields/{key}custom_fields.update
DELETE/v1/custom-fields/{key}custom_fields.delete

custom_fields.list

GET/v1/custom-fields

The workspace's custom fields (at most 5) and how many leads carry each.

Operation idcustom_fields.list
Scopesleads:read
Rate class`read`
IdempotencyNot applicable
KeysDeveloper keys

Response 200

FieldTypeRequiredDescription
dataobject[]yes
maxintegeryes-9007199254740991 to 9007199254740991

Errors

Every operation can also answer the shared errors: authentication, scopes, rate limits and validation.

Example

bash
curl "https://api.dmhero.ai/v1/custom-fields" \
  -H "Authorization: Bearer $DMHERO_API_KEY"
JSON Schema
Response 200
{
  "type": "object",
  "properties": {
    "data": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "key": {
            "type": "string"
          },
          "label": {
            "type": "string"
          },
          "created_at": {
            "type": "string",
            "format": "date-time",
            "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"
          },
          "coverage": {
            "type": "integer",
            "minimum": -9007199254740991,
            "maximum": 9007199254740991,
            "description": "Leads of the workspace that carry a non-blank value for this field."
          }
        },
        "required": [
          "key",
          "label",
          "created_at",
          "coverage"
        ],
        "additionalProperties": false
      }
    },
    "max": {
      "type": "integer",
      "minimum": -9007199254740991,
      "maximum": 9007199254740991
    }
  },
  "required": [
    "data",
    "max"
  ],
  "additionalProperties": false
}

custom_fields.create

POST/v1/custom-fields

Define a custom field. The key is derived from the label unless given, and never changes.

Operation idcustom_fields.create
Scopesleads:write
Rate class`write`
Idempotency`Idempotency-Key` accepted
KeysDeveloper keys

Request body

FieldTypeRequiredDescription
labelstringyes
keystringnoat most 100 characters

Response 201

FieldTypeRequiredDescription
coverageintegeryesLeads of the workspace that carry a non-blank value for this field.. -9007199254740991 to 9007199254740991
created_atdate-timeyes
keystringyes
labelstringyes

Errors

StatusCodeWhen
409`CUSTOM_FIELD_KEY_TAKEN_409`A custom field with this key already exists.
409`CUSTOM_FIELD_LIMIT_409`The workspace already has its 5 custom fields.

Every operation can also answer the shared errors: authentication, scopes, rate limits and validation.

Example

bash
curl -X POST "https://api.dmhero.ai/v1/custom-fields" \
  -H "Authorization: Bearer $DMHERO_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "label": "Deal size"
}'
JSON Schema
Request body
{
  "type": "object",
  "properties": {
    "label": {
      "type": "string"
    },
    "key": {
      "type": "string",
      "maxLength": 100
    }
  },
  "required": [
    "label"
  ]
}
Response 201
{
  "type": "object",
  "properties": {
    "key": {
      "type": "string"
    },
    "label": {
      "type": "string"
    },
    "created_at": {
      "type": "string",
      "format": "date-time",
      "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"
    },
    "coverage": {
      "type": "integer",
      "minimum": -9007199254740991,
      "maximum": 9007199254740991,
      "description": "Leads of the workspace that carry a non-blank value for this field."
    }
  },
  "required": [
    "key",
    "label",
    "created_at",
    "coverage"
  ],
  "additionalProperties": false
}

custom_fields.update

PATCH/v1/custom-fields/{key}

Rename a custom field's label. The key stays.

Operation idcustom_fields.update
Scopesleads:write
Rate class`write`
IdempotencyNot applicable
KeysDeveloper keys

Path parameters

NameTypeRequiredDescription
keystringyes1 to 100 characters

Request body

FieldTypeRequiredDescription
labelstringyes

Response 200

FieldTypeRequiredDescription
coverageintegeryesLeads of the workspace that carry a non-blank value for this field.. -9007199254740991 to 9007199254740991
created_atdate-timeyes
keystringyes
labelstringyes

Errors

StatusCodeWhen
404`CUSTOM_FIELD_NOT_FOUND_404`No custom field with this key exists in this workspace.

Every operation can also answer the shared errors: authentication, scopes, rate limits and validation.

Example

bash
curl -X PATCH "https://api.dmhero.ai/v1/custom-fields/string" \
  -H "Authorization: Bearer $DMHERO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "label": "string"
}'
JSON Schema
Request body
{
  "type": "object",
  "properties": {
    "label": {
      "type": "string"
    }
  },
  "required": [
    "label"
  ]
}
Response 200
{
  "type": "object",
  "properties": {
    "key": {
      "type": "string"
    },
    "label": {
      "type": "string"
    },
    "created_at": {
      "type": "string",
      "format": "date-time",
      "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"
    },
    "coverage": {
      "type": "integer",
      "minimum": -9007199254740991,
      "maximum": 9007199254740991,
      "description": "Leads of the workspace that carry a non-blank value for this field."
    }
  },
  "required": [
    "key",
    "label",
    "created_at",
    "coverage"
  ],
  "additionalProperties": false
}

custom_fields.delete

DELETE/v1/custom-fields/{key}

Delete a custom field and strip its value from every lead of the workspace. Needs confirm=true.

Operation idcustom_fields.delete
Scopesleads:delete
Rate class`write`
IdempotencyNot applicable
KeysDeveloper keys
DestructiveYes: it removes or stops something that cannot be restored by repeating the call

Path parameters

NameTypeRequiredDescription
keystringyes1 to 100 characters

Query parameters

NameTypeRequiredDescription
confirmbooleanno

Response 200

FieldTypeRequiredDescription
keystringyes
values_strippedintegeryes-9007199254740991 to 9007199254740991

Errors

StatusCodeWhen
400`CONFIRM_REQUIRED_400`confirm=true is missing: deleting a field strips its value from every lead.
404`CUSTOM_FIELD_NOT_FOUND_404`No custom field with this key exists in this workspace.

Every operation can also answer the shared errors: authentication, scopes, rate limits and validation.

Example

bash
curl -X DELETE "https://api.dmhero.ai/v1/custom-fields/string?confirm=true" \
  -H "Authorization: Bearer $DMHERO_API_KEY"
JSON Schema
Response 200
{
  "type": "object",
  "properties": {
    "key": {
      "type": "string"
    },
    "values_stripped": {
      "type": "integer",
      "minimum": -9007199254740991,
      "maximum": 9007199254740991
    }
  },
  "required": [
    "key",
    "values_stripped"
  ],
  "additionalProperties": false
}
Custom fields | DM Hero Developers