# Structurely Direct v2

## Overview

The Structurely API allows integrators to provide automation for their accounts. It offers various functionalities to streamline lead management, messaging, lead qualification conversations, and retrieval of metadata.

The Structurely API simplifies the integration process and removes the necessity to track additional fields in your system. It is specifically designed to utilize **your system's IDs** as internal keys, enabling you to seamlessly use IDs from your CRM or database as parameters, such as externalLeadId, and externalMessageId.

By utilizing this API, integrators can streamline their workflows, activate enhanced AI qualification conversations, and gain valuable insights into their accounts, leads, and conversations.

### Security

The Structurely API provides secure authentication and authorization mechanisms to ensure controlled access to its endpoints. The authentication system utilizes API tokens to secure interactions with the API.

Types of tokens and keys:

  
- bearer-access-token: Bearer JWT; **valid until deactivated**

**Note:** It is essential to keep your bearer-access-tokens secure and avoid sharing them with unauthorized parties to maintain the integrity and security of your Structurely API integration.

Version: `v3.35.20`

## Custom Properties

- [GET /api/direct/v2/custom-properties](/api/direct/v2/custom-properties/get.md)
- [POST /api/direct/v2/custom-properties](/api/direct/v2/custom-properties/post.md)
- [PATCH /api/direct/v2/custom-properties/{customPropertyId}](/api/direct/v2/custom-properties/{customPropertyId}/patch.md)
- [DELETE /api/direct/v2/custom-properties/{customPropertyId}](/api/direct/v2/custom-properties/{customPropertyId}/delete.md)

### GET /api/direct/v2/custom-properties

[GET /api/direct/v2/custom-properties](/api/direct/v2/custom-properties/get.md)

**Summary:** List custom property definitions

**Description:**

Manage account-level Direct API custom property definitions.
Names are sanitized before storage. JSON schema fragments are validated as custom property schemas,
and schema.required is stripped; use the top-level
required field instead.

usedForLlmContext controls whether this custom property is
included in automatic LLM lead_metadata prompt context. This setting controls whether a custom property is included in automatic LLM lead_metadata prompt context. It does not change extraction behavior, which remains controlled by dataOnly.

Create example:
{
  "name": "Financing Status",
  "description": "How the lead plans to finance the purchase.",
  "schema": {
    "type": "string",
    "enum": ["cash", "financed"],
    "x-enum-descriptions": ["Cash buyer", "Needs financing"]
  },
  "required": false,
  "dataType": "ENUM",
  "dataOnly": false,
  "usedForLlmContext": false
}

Response example:
{
  "id": "650ba6ced07cb5552a2467b0",
  "name": "financingStatus",
  "description": "How the lead plans to finance the purchase.",
  "schema": {
    "type": "string",
    "enum": ["cash", "financed"],
    "x-enum-descriptions": ["Cash buyer", "Needs financing"]
  },
  "required": false,
  "dataType": "ENUM",
  "dataOnly": false,
  "usedForLlmContext": false
}

#### Responses

- `200`: Custom property definitions for the authenticated account.
  - Schema: `CustomPropertyListResponse`
  ```json
  {
    "type": "object",
    "properties": {
      "customProperties": {
        "type": "array",
        "description": "Custom property definitions for the authenticated account.",
        "items": {
          "$ref": "#/components/schemas/CustomProperty"
        }
      }
    },
    "required": [
      "customProperties"
    ]
  }
  ```
- `400`: Invalid request, check response message
  - Schema: `InvalidRequest`
  ```json
  {
    "type": "object",
    "properties": {
      "message": {
        "type": "string",
        "description": "A message describing the error",
        "example": "The parameter leadId must be provided"
      },
      "statusCode": {
        "type": "number",
        "example": 400
      }
    }
  }
  ```
- `401`: Request is not authorized
  - Schema: `NotAuthorized`
  ```json
  {
    "type": "object",
    "properties": {
      "message": {
        "type": "string",
        "description": "A message describing the error",
        "example": "Access Token is not authorized"
      },
      "statusCode": {
        "type": "number",
        "example": 401
      }
    }
  }
  ```
- `500`: Internal server error, check response message
  - Schema: `InternalServerError`
  ```json
  {
    "type": "object",
    "properties": {
      "message": {
        "type": "string",
        "description": "A message describing the error",
        "example": "Internal server error"
      },
      "statusCode": {
        "type": "number",
        "example": 500
      }
    }
  }
  ```

#### Security

- `bearer-access-token`

#### Example request

```bash
curl -sS -X GET 'https://client.structurely.com/api/direct/v2/custom-properties' \
  -H "Accept: application/json" \
  -H "Authorization: Bearer $STRUCTURELY_API_TOKEN"
```

### POST /api/direct/v2/custom-properties

[POST /api/direct/v2/custom-properties](/api/direct/v2/custom-properties/post.md)

**Summary:** Create a custom property definition

**Description:**

Manage account-level Direct API custom property definitions.
Names are sanitized before storage. JSON schema fragments are validated as custom property schemas,
and schema.required is stripped; use the top-level
required field instead.

usedForLlmContext controls whether this custom property is
included in automatic LLM lead_metadata prompt context. This setting controls whether a custom property is included in automatic LLM lead_metadata prompt context. It does not change extraction behavior, which remains controlled by dataOnly.

Create example:
{
  "name": "Financing Status",
  "description": "How the lead plans to finance the purchase.",
  "schema": {
    "type": "string",
    "enum": ["cash", "financed"],
    "x-enum-descriptions": ["Cash buyer", "Needs financing"]
  },
  "required": false,
  "dataType": "ENUM",
  "dataOnly": false,
  "usedForLlmContext": false
}

Response example:
{
  "id": "650ba6ced07cb5552a2467b0",
  "name": "financingStatus",
  "description": "How the lead plans to finance the purchase.",
  "schema": {
    "type": "string",
    "enum": ["cash", "financed"],
    "x-enum-descriptions": ["Cash buyer", "Needs financing"]
  },
  "required": false,
  "dataType": "ENUM",
  "dataOnly": false,
  "usedForLlmContext": false
}

#### Request body

Custom property definition payload.

Schema: `CustomPropertyCreateRequest`

```json
{
  "type": "object",
  "properties": {
    "name": {
      "type": "string",
      "description": "Human-readable custom property name. The stored name is sanitized to the custom property camelCase identifier.",
      "example": "Financing Status"
    },
    "description": {
      "type": "string",
      "description": "Optional human-readable description for this custom property.",
      "example": "How the lead plans to finance the purchase.",
      "nullable": true
    },
    "schema": {
      "type": "object",
      "description": "JSON Schema Draft-07 fragment for the custom property value. Supported fragments are STRING {'type': 'string'}, NUMBER {'type': 'number'}, BOOLEAN {'type': 'boolean'}, ARRAY {'type': 'array', 'items': {'type': 'string'}} with items.type of string, number, or boolean, and ENUM {'type': 'string', 'enum': [...], 'x-enum-descriptions': [...]}. DATE, DATETIME, ANNIVERSARY_DATE, and TIME use a string schema with the semantic dataType; callers do not need to provide format. schema.required is not part of the public Direct API contract and is stripped by custom property validation; use the top-level required field instead.",
      "oneOf": [
        {
          "type": "object",
          "description": "STRING and date/time semantic value schema. Use with dataType STRING, DATE, DATETIME, ANNIVERSARY_DATE, or TIME. DATE, DATETIME, ANNIVERSARY_DATE, and TIME use this same string schema plus semantic dataType; format is optional.",
          "properties": {
            "type": {
              "type": "string",
              "enum": [
                "string"
              ]
            }
          },
          "required": [
            "type"
          ],
          "not": {
            "required": [
              "enum"
            ]
          },
          "example": {
            "type": "string"
          }
        },
        {
          "type": "object",
          "description": "NUMBER value schema. Use with dataType NUMBER.",
          "properties": {
            "type": {
              "type": "string",
              "enum": [
                "number"
              ]
            }
          },
          "required": [
            "type"
          ],
          "example": {
            "type": "number"
          }
        },
        {
          "type": "object",
          "description": "BOOLEAN value schema. Use with dataType BOOLEAN.",
          "properties": {
            "type": {
              "type": "string",
              "enum": [
                "boolean"
              ]
            }
          },
          "required": [
            "type"
          ],
          "example": {
            "type": "boolean"
          }
        },
        {
          "type": "object",
          "description": "ARRAY value schema. items.type supports string, number, or boolean.",
          "properties": {
            "type": {
              "type": "string",
              "enum": [
                "array"
              ]
            },
            "items": {
              "type": "object",
              "properties": {
                "type": {
                  "type": "string",
                  "enum": [
                    "string",
                    "number",
                    "boolean"
                  ]
                }
              },
              "required": [
                "type"
              ]
            }
          },
          "required": [
            "type",
            "items"
          ],
          "example": {
            "type": "array",
            "items": {
              "type": "string"
            }
          }
        },
        {
          "type": "object",
          "description": "ENUM value schema. enum options stay in schema.enum; optional labels stay in x-enum-descriptions.",
          "properties": {
            "type": {
              "type": "string",
              "enum": [
                "string"
              ]
            },
            "enum": {
              "type": "array",
              "items": {
                "type": "string"
              }
            },
            "x-enum-descriptions": {
              "type": "array",
              "items": {
                "type": "string"
              }
            }
          },
          "required": [
            "type",
            "enum"
          ],
          "example": {
            "type": "string",
            "enum": [
              "cash",
              "financed"
            ],
            "x-enum-descriptions": [
              "Cash buyer",
              "Needs financing"
            ]
          }
        }
      ],
      "example": {
        "type": "string",
        "enum": [
          "cash",
          "financed"
        ],
        "x-enum-descriptions": [
          "Cash buyer",
          "Needs financing"
        ]
      },
      "additionalProperties": {}
    },
    "required": {
      "type": "boolean",
      "default": false,
      "description": "Whether this property should be considered required. Use this top-level field instead of schema.required.",
      "example": false,
      "nullable": true
    },
    "dataType": {
      "type": "string",
      "default": "STRING",
      "enum": [
        "DATE",
        "DATETIME",
        "ANNIVERSARY_DATE",
        "TIME",
        "STRING",
        "NUMBER",
        "BOOLEAN",
        "ARRAY",
        "ENUM"
      ],
      "description": "Semantic custom property data type. DATE, DATETIME, ANNIVERSARY_DATE, and TIME use a string schema plus this semantic value.",
      "example": "ENUM"
    },
    "dataOnly": {
      "type": "boolean",
      "default": false,
      "description": "Whether the property is data-only. Data-only properties are not extracted from conversations; they can still be injected into LLM context when usedForLlmContext is enabled.",
      "example": false,
      "nullable": true
    },
    "usedForLlmContext": {
      "type": "boolean",
      "description": "This setting controls whether a custom property is included in automatic LLM lead_metadata prompt context. It does not change extraction behavior, which remains controlled by dataOnly. When omitted, this value is derived from dataOnly after create defaults are applied.",
      "example": false,
      "nullable": true
    }
  },
  "required": [
    "name",
    "schema"
  ]
}
```

#### Responses

- `200`: The created custom property definition.
  - Schema: `CustomProperty`
  ```json
  {
    "type": "object",
    "properties": {
      "id": {
        "description": "Custom property definition ID.",
        "example": "650ba6ced07cb5552a2467b0",
        "type": "string",
        "format": "ObjectId"
      },
      "name": {
        "type": "string",
        "description": "Sanitized custom property camelCase identifier.",
        "example": "financingStatus"
      },
      "description": {
        "type": "string",
        "description": "Custom property description, when set.",
        "example": "How the lead plans to finance the purchase.",
        "nullable": true
      },
      "schema": {
        "type": "object",
        "description": "JSON Schema Draft-07 fragment for the custom property value. Supported fragments are STRING {'type': 'string'}, NUMBER {'type': 'number'}, BOOLEAN {'type': 'boolean'}, ARRAY {'type': 'array', 'items': {'type': 'string'}} with items.type of string, number, or boolean, and ENUM {'type': 'string', 'enum': [...], 'x-enum-descriptions': [...]}. DATE, DATETIME, ANNIVERSARY_DATE, and TIME use a string schema with the semantic dataType; callers do not need to provide format. schema.required is not part of the public Direct API contract and is stripped by custom property validation; use the top-level required field instead.",
        "oneOf": [
          {
            "type": "object",
            "description": "STRING and date/time semantic value schema. Use with dataType STRING, DATE, DATETIME, ANNIVERSARY_DATE, or TIME. DATE, DATETIME, ANNIVERSARY_DATE, and TIME use this same string schema plus semantic dataType; format is optional.",
            "properties": {
              "type": {
                "type": "string",
                "enum": [
                  "string"
                ]
              }
            },
            "required": [
              "type"
            ],
            "not": {
              "required": [
                "enum"
              ]
            },
            "example": {
              "type": "string"
            }
          },
          {
            "type": "object",
            "description": "NUMBER value schema. Use with dataType NUMBER.",
            "properties": {
              "type": {
                "type": "string",
                "enum": [
                  "number"
                ]
              }
            },
            "required": [
              "type"
            ],
            "example": {
              "type": "number"
            }
          },
          {
            "type": "object",
            "description": "BOOLEAN value schema. Use with dataType BOOLEAN.",
            "properties": {
              "type": {
                "type": "string",
                "enum": [
                  "boolean"
                ]
              }
            },
            "required": [
              "type"
            ],
            "example": {
              "type": "boolean"
            }
          },
          {
            "type": "object",
            "description": "ARRAY value schema. items.type supports string, number, or boolean.",
            "properties": {
              "type": {
                "type": "string",
                "enum": [
                  "array"
                ]
              },
              "items": {
                "type": "object",
                "properties": {
                  "type": {
                    "type": "string",
                    "enum": [
                      "string",
                      "number",
                      "boolean"
                    ]
                  }
                },
                "required": [
                  "type"
                ]
              }
            },
            "required": [
              "type",
              "items"
            ],
            "example": {
              "type": "array",
              "items": {
                "type": "string"
              }
            }
          },
          {
            "type": "object",
            "description": "ENUM value schema. enum options stay in schema.enum; optional labels stay in x-enum-descriptions.",
            "properties": {
              "type": {
                "type": "string",
                "enum": [
                  "string"
                ]
              },
              "enum": {
                "type": "array",
                "items": {
                  "type": "string"
                }
              },
              "x-enum-descriptions": {
                "type": "array",
                "items": {
                  "type": "string"
                }
              }
            },
            "required": [
              "type",
              "enum"
            ],
            "example": {
              "type": "string",
              "enum": [
                "cash",
                "financed"
              ],
              "x-enum-descriptions": [
                "Cash buyer",
                "Needs financing"
              ]
            }
          }
        ],
        "example": {
          "type": "string",
          "enum": [
            "cash",
            "financed"
          ],
          "x-enum-descriptions": [
            "Cash buyer",
            "Needs financing"
          ]
        },
        "additionalProperties": {}
      },
      "required": {
        "type": "boolean",
        "description": "Whether this property is required.",
        "example": false
      },
      "dataType": {
        "type": "string",
        "enum": [
          "DATE",
          "DATETIME",
          "ANNIVERSARY_DATE",
          "TIME",
          "STRING",
          "NUMBER",
          "BOOLEAN",
          "ARRAY",
          "ENUM"
        ],
        "description": "Semantic custom property data type.",
        "example": "ENUM"
      },
      "dataOnly": {
        "type": "boolean",
        "description": "Whether this property is data-only. Data-only properties are not extracted from conversations; they can still be injected into LLM context when usedForLlmContext is enabled.",
        "example": false
      },
      "usedForLlmContext": {
        "type": "boolean",
        "description": "This setting controls whether a custom property is included in automatic LLM lead_metadata prompt context. It does not change extraction behavior, which remains controlled by dataOnly.",
        "example": false
      }
    },
    "required": [
      "dataOnly",
      "dataType",
      "id",
      "name",
      "required",
      "schema",
      "usedForLlmContext"
    ]
  }
  ```
- `400`: Invalid request, check response message
  - Schema: `InvalidRequest`
  ```json
  {
    "type": "object",
    "properties": {
      "message": {
        "type": "string",
        "description": "A message describing the error",
        "example": "The parameter leadId must be provided"
      },
      "statusCode": {
        "type": "number",
        "example": 400
      }
    }
  }
  ```
- `401`: Request is not authorized
  - Schema: `NotAuthorized`
  ```json
  {
    "type": "object",
    "properties": {
      "message": {
        "type": "string",
        "description": "A message describing the error",
        "example": "Access Token is not authorized"
      },
      "statusCode": {
        "type": "number",
        "example": 401
      }
    }
  }
  ```
- `500`: Internal server error, check response message
  - Schema: `InternalServerError`
  ```json
  {
    "type": "object",
    "properties": {
      "message": {
        "type": "string",
        "description": "A message describing the error",
        "example": "Internal server error"
      },
      "statusCode": {
        "type": "number",
        "example": 500
      }
    }
  }
  ```

#### Security

- `bearer-access-token`

#### Example request

```bash
curl -sS -X POST 'https://client.structurely.com/api/direct/v2/custom-properties' \
  -H "Accept: application/json" \
  -H "Authorization: Bearer $STRUCTURELY_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Financing Status",
  "schema": {
    "type": "string",
    "enum": [
      "cash",
      "financed"
    ],
    "x-enum-descriptions": [
      "Cash buyer",
      "Needs financing"
    ]
  }
}'
```

### PATCH /api/direct/v2/custom-properties/{customPropertyId}

[PATCH /api/direct/v2/custom-properties/{customPropertyId}](/api/direct/v2/custom-properties/{customPropertyId}/patch.md)

**Summary:** Update a custom property definition

**Description:**

Manage account-level Direct API custom property definitions.
Names are sanitized before storage. JSON schema fragments are validated as custom property schemas,
and schema.required is stripped; use the top-level
required field instead.

usedForLlmContext controls whether this custom property is
included in automatic LLM lead_metadata prompt context. This setting controls whether a custom property is included in automatic LLM lead_metadata prompt context. It does not change extraction behavior, which remains controlled by dataOnly.

Create example:
{
  "name": "Financing Status",
  "description": "How the lead plans to finance the purchase.",
  "schema": {
    "type": "string",
    "enum": ["cash", "financed"],
    "x-enum-descriptions": ["Cash buyer", "Needs financing"]
  },
  "required": false,
  "dataType": "ENUM",
  "dataOnly": false,
  "usedForLlmContext": false
}

Response example:
{
  "id": "650ba6ced07cb5552a2467b0",
  "name": "financingStatus",
  "description": "How the lead plans to finance the purchase.",
  "schema": {
    "type": "string",
    "enum": ["cash", "financed"],
    "x-enum-descriptions": ["Cash buyer", "Needs financing"]
  },
  "required": false,
  "dataType": "ENUM",
  "dataOnly": false,
  "usedForLlmContext": false
}

Omitted fields preserve existing values. Explicit null for nullable optional fields (description, required, dataType, dataOnly, and usedForLlmContext) leaves those fields unchanged. When usedForLlmContext is omitted or null, the existing effective value is preserved even if dataOnly changes in the same request.

#### Parameters

- `customPropertyId` (path, required: yes)
  - The custom property definition ID.
  - Schema:
    ```json
    {
      "oneOf": [
        {
          "format": "ObjectId",
          "type": "string"
        }
      ]
    }
    ```

#### Request body

Custom property definition fields to update.

Schema: `CustomPropertyPatchRequest`

```json
{
  "type": "object",
  "properties": {
    "name": {
      "type": "string",
      "description": "New custom property name. When omitted, the current sanitized name is preserved.",
      "example": "Updated Financing Status"
    },
    "description": {
      "type": "string",
      "description": "Updated description. Explicit null leaves the current value unchanged.",
      "example": "Updated financing details.",
      "nullable": true
    },
    "schema": {
      "type": "object",
      "description": "JSON Schema Draft-07 fragment for the custom property value. Supported fragments are STRING {'type': 'string'}, NUMBER {'type': 'number'}, BOOLEAN {'type': 'boolean'}, ARRAY {'type': 'array', 'items': {'type': 'string'}} with items.type of string, number, or boolean, and ENUM {'type': 'string', 'enum': [...], 'x-enum-descriptions': [...]}. DATE, DATETIME, ANNIVERSARY_DATE, and TIME use a string schema with the semantic dataType; callers do not need to provide format. schema.required is not part of the public Direct API contract and is stripped by custom property validation; use the top-level required field instead.",
      "oneOf": [
        {
          "type": "object",
          "description": "STRING and date/time semantic value schema. Use with dataType STRING, DATE, DATETIME, ANNIVERSARY_DATE, or TIME. DATE, DATETIME, ANNIVERSARY_DATE, and TIME use this same string schema plus semantic dataType; format is optional.",
          "properties": {
            "type": {
              "type": "string",
              "enum": [
                "string"
              ]
            }
          },
          "required": [
            "type"
          ],
          "not": {
            "required": [
              "enum"
            ]
          },
          "example": {
            "type": "string"
          }
        },
        {
          "type": "object",
          "description": "NUMBER value schema. Use with dataType NUMBER.",
          "properties": {
            "type": {
              "type": "string",
              "enum": [
                "number"
              ]
            }
          },
          "required": [
            "type"
          ],
          "example": {
            "type": "number"
          }
        },
        {
          "type": "object",
          "description": "BOOLEAN value schema. Use with dataType BOOLEAN.",
          "properties": {
            "type": {
              "type": "string",
              "enum": [
                "boolean"
              ]
            }
          },
          "required": [
            "type"
          ],
          "example": {
            "type": "boolean"
          }
        },
        {
          "type": "object",
          "description": "ARRAY value schema. items.type supports string, number, or boolean.",
          "properties": {
            "type": {
              "type": "string",
              "enum": [
                "array"
              ]
            },
            "items": {
              "type": "object",
              "properties": {
                "type": {
                  "type": "string",
                  "enum": [
                    "string",
                    "number",
                    "boolean"
                  ]
                }
              },
              "required": [
                "type"
              ]
            }
          },
          "required": [
            "type",
            "items"
          ],
          "example": {
            "type": "array",
            "items": {
              "type": "string"
            }
          }
        },
        {
          "type": "object",
          "description": "ENUM value schema. enum options stay in schema.enum; optional labels stay in x-enum-descriptions.",
          "properties": {
            "type": {
              "type": "string",
              "enum": [
                "string"
              ]
            },
            "enum": {
              "type": "array",
              "items": {
                "type": "string"
              }
            },
            "x-enum-descriptions": {
              "type": "array",
              "items": {
                "type": "string"
              }
            }
          },
          "required": [
            "type",
            "enum"
          ],
          "example": {
            "type": "string",
            "enum": [
              "cash",
              "financed"
            ],
            "x-enum-descriptions": [
              "Cash buyer",
              "Needs financing"
            ]
          }
        }
      ],
      "example": {
        "type": "number"
      },
      "additionalProperties": {}
    },
    "required": {
      "type": "boolean",
      "description": "Updated required flag. Explicit null leaves the current value unchanged.",
      "example": true,
      "nullable": true
    },
    "dataType": {
      "type": "string",
      "enum": [
        "DATE",
        "DATETIME",
        "ANNIVERSARY_DATE",
        "TIME",
        "STRING",
        "NUMBER",
        "BOOLEAN",
        "ARRAY",
        "ENUM"
      ],
      "description": "Updated semantic custom property data type. Explicit null leaves the current value unchanged.",
      "example": "NUMBER"
    },
    "dataOnly": {
      "type": "boolean",
      "description": "Updated data-only flag. Data-only properties are not extracted from conversations; they can still be injected into LLM context when usedForLlmContext is enabled. Explicit null leaves the current value unchanged.",
      "example": false,
      "nullable": true
    },
    "usedForLlmContext": {
      "type": "boolean",
      "description": "This setting controls whether a custom property is included in automatic LLM lead_metadata prompt context. It does not change extraction behavior, which remains controlled by dataOnly. Omitted or null values preserve the existing effective setting, even when dataOnly changes in the same request.",
      "example": false,
      "nullable": true
    }
  }
}
```

#### Responses

- `200`: The updated custom property definition.
  - Schema: `CustomProperty`
  ```json
  {
    "type": "object",
    "properties": {
      "id": {
        "description": "Custom property definition ID.",
        "example": "650ba6ced07cb5552a2467b0",
        "type": "string",
        "format": "ObjectId"
      },
      "name": {
        "type": "string",
        "description": "Sanitized custom property camelCase identifier.",
        "example": "financingStatus"
      },
      "description": {
        "type": "string",
        "description": "Custom property description, when set.",
        "example": "How the lead plans to finance the purchase.",
        "nullable": true
      },
      "schema": {
        "type": "object",
        "description": "JSON Schema Draft-07 fragment for the custom property value. Supported fragments are STRING {'type': 'string'}, NUMBER {'type': 'number'}, BOOLEAN {'type': 'boolean'}, ARRAY {'type': 'array', 'items': {'type': 'string'}} with items.type of string, number, or boolean, and ENUM {'type': 'string', 'enum': [...], 'x-enum-descriptions': [...]}. DATE, DATETIME, ANNIVERSARY_DATE, and TIME use a string schema with the semantic dataType; callers do not need to provide format. schema.required is not part of the public Direct API contract and is stripped by custom property validation; use the top-level required field instead.",
        "oneOf": [
          {
            "type": "object",
            "description": "STRING and date/time semantic value schema. Use with dataType STRING, DATE, DATETIME, ANNIVERSARY_DATE, or TIME. DATE, DATETIME, ANNIVERSARY_DATE, and TIME use this same string schema plus semantic dataType; format is optional.",
            "properties": {
              "type": {
                "type": "string",
                "enum": [
                  "string"
                ]
              }
            },
            "required": [
              "type"
            ],
            "not": {
              "required": [
                "enum"
              ]
            },
            "example": {
              "type": "string"
            }
          },
          {
            "type": "object",
            "description": "NUMBER value schema. Use with dataType NUMBER.",
            "properties": {
              "type": {
                "type": "string",
                "enum": [
                  "number"
                ]
              }
            },
            "required": [
              "type"
            ],
            "example": {
              "type": "number"
            }
          },
          {
            "type": "object",
            "description": "BOOLEAN value schema. Use with dataType BOOLEAN.",
            "properties": {
              "type": {
                "type": "string",
                "enum": [
                  "boolean"
                ]
              }
            },
            "required": [
              "type"
            ],
            "example": {
              "type": "boolean"
            }
          },
          {
            "type": "object",
            "description": "ARRAY value schema. items.type supports string, number, or boolean.",
            "properties": {
              "type": {
                "type": "string",
                "enum": [
                  "array"
                ]
              },
              "items": {
                "type": "object",
                "properties": {
                  "type": {
                    "type": "string",
                    "enum": [
                      "string",
                      "number",
                      "boolean"
                    ]
                  }
                },
                "required": [
                  "type"
                ]
              }
            },
            "required": [
              "type",
              "items"
            ],
            "example": {
              "type": "array",
              "items": {
                "type": "string"
              }
            }
          },
          {
            "type": "object",
            "description": "ENUM value schema. enum options stay in schema.enum; optional labels stay in x-enum-descriptions.",
            "properties": {
              "type": {
                "type": "string",
                "enum": [
                  "string"
                ]
              },
              "enum": {
                "type": "array",
                "items": {
                  "type": "string"
                }
              },
              "x-enum-descriptions": {
                "type": "array",
                "items": {
                  "type": "string"
                }
              }
            },
            "required": [
              "type",
              "enum"
            ],
            "example": {
              "type": "string",
              "enum": [
                "cash",
                "financed"
              ],
              "x-enum-descriptions": [
                "Cash buyer",
                "Needs financing"
              ]
            }
          }
        ],
        "example": {
          "type": "string",
          "enum": [
            "cash",
            "financed"
          ],
          "x-enum-descriptions": [
            "Cash buyer",
            "Needs financing"
          ]
        },
        "additionalProperties": {}
      },
      "required": {
        "type": "boolean",
        "description": "Whether this property is required.",
        "example": false
      },
      "dataType": {
        "type": "string",
        "enum": [
          "DATE",
          "DATETIME",
          "ANNIVERSARY_DATE",
          "TIME",
          "STRING",
          "NUMBER",
          "BOOLEAN",
          "ARRAY",
          "ENUM"
        ],
        "description": "Semantic custom property data type.",
        "example": "ENUM"
      },
      "dataOnly": {
        "type": "boolean",
        "description": "Whether this property is data-only. Data-only properties are not extracted from conversations; they can still be injected into LLM context when usedForLlmContext is enabled.",
        "example": false
      },
      "usedForLlmContext": {
        "type": "boolean",
        "description": "This setting controls whether a custom property is included in automatic LLM lead_metadata prompt context. It does not change extraction behavior, which remains controlled by dataOnly.",
        "example": false
      }
    },
    "required": [
      "dataOnly",
      "dataType",
      "id",
      "name",
      "required",
      "schema",
      "usedForLlmContext"
    ]
  }
  ```
- `400`: Invalid request, check response message
  - Schema: `InvalidRequest`
  ```json
  {
    "type": "object",
    "properties": {
      "message": {
        "type": "string",
        "description": "A message describing the error",
        "example": "The parameter leadId must be provided"
      },
      "statusCode": {
        "type": "number",
        "example": 400
      }
    }
  }
  ```
- `401`: Request is not authorized
  - Schema: `NotAuthorized`
  ```json
  {
    "type": "object",
    "properties": {
      "message": {
        "type": "string",
        "description": "A message describing the error",
        "example": "Access Token is not authorized"
      },
      "statusCode": {
        "type": "number",
        "example": 401
      }
    }
  }
  ```
- `404`: Resource was not found, check response message
  - Schema: `NotFound`
  ```json
  {
    "type": "object",
    "properties": {
      "message": {
        "type": "string",
        "description": "A message describing the error",
        "example": "Lead not found"
      },
      "statusCode": {
        "type": "number",
        "example": 404
      }
    }
  }
  ```
- `500`: Internal server error, check response message
  - Schema: `InternalServerError`
  ```json
  {
    "type": "object",
    "properties": {
      "message": {
        "type": "string",
        "description": "A message describing the error",
        "example": "Internal server error"
      },
      "statusCode": {
        "type": "number",
        "example": 500
      }
    }
  }
  ```

#### Security

- `bearer-access-token`

#### Example request

```bash
curl -sS -X PATCH 'https://client.structurely.com/api/direct/v2/custom-properties/{customPropertyId}' \
  -H "Accept: application/json" \
  -H "Authorization: Bearer $STRUCTURELY_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{}'
```

### DELETE /api/direct/v2/custom-properties/{customPropertyId}

[DELETE /api/direct/v2/custom-properties/{customPropertyId}](/api/direct/v2/custom-properties/{customPropertyId}/delete.md)

**Summary:** Delete a custom property definition

**Description:**

Delete only the custom property definition. Existing lead customProperties values are not cleared.

#### Parameters

- `customPropertyId` (path, required: yes)
  - The custom property definition ID.
  - Schema:
    ```json
    {
      "oneOf": [
        {
          "format": "ObjectId",
          "type": "string"
        }
      ]
    }
    ```

#### Responses

- `200`: Custom property deletion result.
  - Schema: `CustomPropertyDeleteResponse`
  ```json
  {
    "type": "object",
    "properties": {
      "ok": {
        "type": "boolean",
        "description": "True when the custom property definition was deleted.",
        "example": true
      }
    },
    "required": [
      "ok"
    ]
  }
  ```
- `400`: Invalid request, check response message
  - Schema: `InvalidRequest`
  ```json
  {
    "type": "object",
    "properties": {
      "message": {
        "type": "string",
        "description": "A message describing the error",
        "example": "The parameter leadId must be provided"
      },
      "statusCode": {
        "type": "number",
        "example": 400
      }
    }
  }
  ```
- `401`: Request is not authorized
  - Schema: `NotAuthorized`
  ```json
  {
    "type": "object",
    "properties": {
      "message": {
        "type": "string",
        "description": "A message describing the error",
        "example": "Access Token is not authorized"
      },
      "statusCode": {
        "type": "number",
        "example": 401
      }
    }
  }
  ```
- `404`: Resource was not found, check response message
  - Schema: `NotFound`
  ```json
  {
    "type": "object",
    "properties": {
      "message": {
        "type": "string",
        "description": "A message describing the error",
        "example": "Lead not found"
      },
      "statusCode": {
        "type": "number",
        "example": 404
      }
    }
  }
  ```
- `500`: Internal server error, check response message
  - Schema: `InternalServerError`
  ```json
  {
    "type": "object",
    "properties": {
      "message": {
        "type": "string",
        "description": "A message describing the error",
        "example": "Internal server error"
      },
      "statusCode": {
        "type": "number",
        "example": 500
      }
    }
  }
  ```

#### Security

- `bearer-access-token`

#### Example request

```bash
curl -sS -X DELETE 'https://client.structurely.com/api/direct/v2/custom-properties/{customPropertyId}' \
  -H "Accept: application/json" \
  -H "Authorization: Bearer $STRUCTURELY_API_TOKEN"
```

## Schemas

### `CustomProperty`

```json
{
  "type": "object",
  "properties": {
    "id": {
      "description": "Custom property definition ID.",
      "example": "650ba6ced07cb5552a2467b0",
      "type": "string",
      "format": "ObjectId"
    },
    "name": {
      "type": "string",
      "description": "Sanitized custom property camelCase identifier.",
      "example": "financingStatus"
    },
    "description": {
      "type": "string",
      "description": "Custom property description, when set.",
      "example": "How the lead plans to finance the purchase.",
      "nullable": true
    },
    "schema": {
      "type": "object",
      "description": "JSON Schema Draft-07 fragment for the custom property value. Supported fragments are STRING {'type': 'string'}, NUMBER {'type': 'number'}, BOOLEAN {'type': 'boolean'}, ARRAY {'type': 'array', 'items': {'type': 'string'}} with items.type of string, number, or boolean, and ENUM {'type': 'string', 'enum': [...], 'x-enum-descriptions': [...]}. DATE, DATETIME, ANNIVERSARY_DATE, and TIME use a string schema with the semantic dataType; callers do not need to provide format. schema.required is not part of the public Direct API contract and is stripped by custom property validation; use the top-level required field instead.",
      "oneOf": [
        {
          "type": "object",
          "description": "STRING and date/time semantic value schema. Use with dataType STRING, DATE, DATETIME, ANNIVERSARY_DATE, or TIME. DATE, DATETIME, ANNIVERSARY_DATE, and TIME use this same string schema plus semantic dataType; format is optional.",
          "properties": {
            "type": {
              "type": "string",
              "enum": [
                "string"
              ]
            }
          },
          "required": [
            "type"
          ],
          "not": {
            "required": [
              "enum"
            ]
          },
          "example": {
            "type": "string"
          }
        },
        {
          "type": "object",
          "description": "NUMBER value schema. Use with dataType NUMBER.",
          "properties": {
            "type": {
              "type": "string",
              "enum": [
                "number"
              ]
            }
          },
          "required": [
            "type"
          ],
          "example": {
            "type": "number"
          }
        },
        {
          "type": "object",
          "description": "BOOLEAN value schema. Use with dataType BOOLEAN.",
          "properties": {
            "type": {
              "type": "string",
              "enum": [
                "boolean"
              ]
            }
          },
          "required": [
            "type"
          ],
          "example": {
            "type": "boolean"
          }
        },
        {
          "type": "object",
          "description": "ARRAY value schema. items.type supports string, number, or boolean.",
          "properties": {
            "type": {
              "type": "string",
              "enum": [
                "array"
              ]
            },
            "items": {
              "type": "object",
              "properties": {
                "type": {
                  "type": "string",
                  "enum": [
                    "string",
                    "number",
                    "boolean"
                  ]
                }
              },
              "required": [
                "type"
              ]
            }
          },
          "required": [
            "type",
            "items"
          ],
          "example": {
            "type": "array",
            "items": {
              "type": "string"
            }
          }
        },
        {
          "type": "object",
          "description": "ENUM value schema. enum options stay in schema.enum; optional labels stay in x-enum-descriptions.",
          "properties": {
            "type": {
              "type": "string",
              "enum": [
                "string"
              ]
            },
            "enum": {
              "type": "array",
              "items": {
                "type": "string"
              }
            },
            "x-enum-descriptions": {
              "type": "array",
              "items": {
                "type": "string"
              }
            }
          },
          "required": [
            "type",
            "enum"
          ],
          "example": {
            "type": "string",
            "enum": [
              "cash",
              "financed"
            ],
            "x-enum-descriptions": [
              "Cash buyer",
              "Needs financing"
            ]
          }
        }
      ],
      "example": {
        "type": "string",
        "enum": [
          "cash",
          "financed"
        ],
        "x-enum-descriptions": [
          "Cash buyer",
          "Needs financing"
        ]
      },
      "additionalProperties": {}
    },
    "required": {
      "type": "boolean",
      "description": "Whether this property is required.",
      "example": false
    },
    "dataType": {
      "type": "string",
      "enum": [
        "DATE",
        "DATETIME",
        "ANNIVERSARY_DATE",
        "TIME",
        "STRING",
        "NUMBER",
        "BOOLEAN",
        "ARRAY",
        "ENUM"
      ],
      "description": "Semantic custom property data type.",
      "example": "ENUM"
    },
    "dataOnly": {
      "type": "boolean",
      "description": "Whether this property is data-only. Data-only properties are not extracted from conversations; they can still be injected into LLM context when usedForLlmContext is enabled.",
      "example": false
    },
    "usedForLlmContext": {
      "type": "boolean",
      "description": "This setting controls whether a custom property is included in automatic LLM lead_metadata prompt context. It does not change extraction behavior, which remains controlled by dataOnly.",
      "example": false
    }
  },
  "required": [
    "dataOnly",
    "dataType",
    "id",
    "name",
    "required",
    "schema",
    "usedForLlmContext"
  ]
}
```

### `CustomPropertyCreateRequest`

```json
{
  "type": "object",
  "properties": {
    "name": {
      "type": "string",
      "description": "Human-readable custom property name. The stored name is sanitized to the custom property camelCase identifier.",
      "example": "Financing Status"
    },
    "description": {
      "type": "string",
      "description": "Optional human-readable description for this custom property.",
      "example": "How the lead plans to finance the purchase.",
      "nullable": true
    },
    "schema": {
      "type": "object",
      "description": "JSON Schema Draft-07 fragment for the custom property value. Supported fragments are STRING {'type': 'string'}, NUMBER {'type': 'number'}, BOOLEAN {'type': 'boolean'}, ARRAY {'type': 'array', 'items': {'type': 'string'}} with items.type of string, number, or boolean, and ENUM {'type': 'string', 'enum': [...], 'x-enum-descriptions': [...]}. DATE, DATETIME, ANNIVERSARY_DATE, and TIME use a string schema with the semantic dataType; callers do not need to provide format. schema.required is not part of the public Direct API contract and is stripped by custom property validation; use the top-level required field instead.",
      "oneOf": [
        {
          "type": "object",
          "description": "STRING and date/time semantic value schema. Use with dataType STRING, DATE, DATETIME, ANNIVERSARY_DATE, or TIME. DATE, DATETIME, ANNIVERSARY_DATE, and TIME use this same string schema plus semantic dataType; format is optional.",
          "properties": {
            "type": {
              "type": "string",
              "enum": [
                "string"
              ]
            }
          },
          "required": [
            "type"
          ],
          "not": {
            "required": [
              "enum"
            ]
          },
          "example": {
            "type": "string"
          }
        },
        {
          "type": "object",
          "description": "NUMBER value schema. Use with dataType NUMBER.",
          "properties": {
            "type": {
              "type": "string",
              "enum": [
                "number"
              ]
            }
          },
          "required": [
            "type"
          ],
          "example": {
            "type": "number"
          }
        },
        {
          "type": "object",
          "description": "BOOLEAN value schema. Use with dataType BOOLEAN.",
          "properties": {
            "type": {
              "type": "string",
              "enum": [
                "boolean"
              ]
            }
          },
          "required": [
            "type"
          ],
          "example": {
            "type": "boolean"
          }
        },
        {
          "type": "object",
          "description": "ARRAY value schema. items.type supports string, number, or boolean.",
          "properties": {
            "type": {
              "type": "string",
              "enum": [
                "array"
              ]
            },
            "items": {
              "type": "object",
              "properties": {
                "type": {
                  "type": "string",
                  "enum": [
                    "string",
                    "number",
                    "boolean"
                  ]
                }
              },
              "required": [
                "type"
              ]
            }
          },
          "required": [
            "type",
            "items"
          ],
          "example": {
            "type": "array",
            "items": {
              "type": "string"
            }
          }
        },
        {
          "type": "object",
          "description": "ENUM value schema. enum options stay in schema.enum; optional labels stay in x-enum-descriptions.",
          "properties": {
            "type": {
              "type": "string",
              "enum": [
                "string"
              ]
            },
            "enum": {
              "type": "array",
              "items": {
                "type": "string"
              }
            },
            "x-enum-descriptions": {
              "type": "array",
              "items": {
                "type": "string"
              }
            }
          },
          "required": [
            "type",
            "enum"
          ],
          "example": {
            "type": "string",
            "enum": [
              "cash",
              "financed"
            ],
            "x-enum-descriptions": [
              "Cash buyer",
              "Needs financing"
            ]
          }
        }
      ],
      "example": {
        "type": "string",
        "enum": [
          "cash",
          "financed"
        ],
        "x-enum-descriptions": [
          "Cash buyer",
          "Needs financing"
        ]
      },
      "additionalProperties": {}
    },
    "required": {
      "type": "boolean",
      "default": false,
      "description": "Whether this property should be considered required. Use this top-level field instead of schema.required.",
      "example": false,
      "nullable": true
    },
    "dataType": {
      "type": "string",
      "default": "STRING",
      "enum": [
        "DATE",
        "DATETIME",
        "ANNIVERSARY_DATE",
        "TIME",
        "STRING",
        "NUMBER",
        "BOOLEAN",
        "ARRAY",
        "ENUM"
      ],
      "description": "Semantic custom property data type. DATE, DATETIME, ANNIVERSARY_DATE, and TIME use a string schema plus this semantic value.",
      "example": "ENUM"
    },
    "dataOnly": {
      "type": "boolean",
      "default": false,
      "description": "Whether the property is data-only. Data-only properties are not extracted from conversations; they can still be injected into LLM context when usedForLlmContext is enabled.",
      "example": false,
      "nullable": true
    },
    "usedForLlmContext": {
      "type": "boolean",
      "description": "This setting controls whether a custom property is included in automatic LLM lead_metadata prompt context. It does not change extraction behavior, which remains controlled by dataOnly. When omitted, this value is derived from dataOnly after create defaults are applied.",
      "example": false,
      "nullable": true
    }
  },
  "required": [
    "name",
    "schema"
  ]
}
```

### `CustomPropertyDeleteResponse`

```json
{
  "type": "object",
  "properties": {
    "ok": {
      "type": "boolean",
      "description": "True when the custom property definition was deleted.",
      "example": true
    }
  },
  "required": [
    "ok"
  ]
}
```

### `CustomPropertyListResponse`

```json
{
  "type": "object",
  "properties": {
    "customProperties": {
      "type": "array",
      "description": "Custom property definitions for the authenticated account.",
      "items": {
        "$ref": "#/components/schemas/CustomProperty"
      }
    }
  },
  "required": [
    "customProperties"
  ]
}
```

### `CustomPropertyPatchRequest`

```json
{
  "type": "object",
  "properties": {
    "name": {
      "type": "string",
      "description": "New custom property name. When omitted, the current sanitized name is preserved.",
      "example": "Updated Financing Status"
    },
    "description": {
      "type": "string",
      "description": "Updated description. Explicit null leaves the current value unchanged.",
      "example": "Updated financing details.",
      "nullable": true
    },
    "schema": {
      "type": "object",
      "description": "JSON Schema Draft-07 fragment for the custom property value. Supported fragments are STRING {'type': 'string'}, NUMBER {'type': 'number'}, BOOLEAN {'type': 'boolean'}, ARRAY {'type': 'array', 'items': {'type': 'string'}} with items.type of string, number, or boolean, and ENUM {'type': 'string', 'enum': [...], 'x-enum-descriptions': [...]}. DATE, DATETIME, ANNIVERSARY_DATE, and TIME use a string schema with the semantic dataType; callers do not need to provide format. schema.required is not part of the public Direct API contract and is stripped by custom property validation; use the top-level required field instead.",
      "oneOf": [
        {
          "type": "object",
          "description": "STRING and date/time semantic value schema. Use with dataType STRING, DATE, DATETIME, ANNIVERSARY_DATE, or TIME. DATE, DATETIME, ANNIVERSARY_DATE, and TIME use this same string schema plus semantic dataType; format is optional.",
          "properties": {
            "type": {
              "type": "string",
              "enum": [
                "string"
              ]
            }
          },
          "required": [
            "type"
          ],
          "not": {
            "required": [
              "enum"
            ]
          },
          "example": {
            "type": "string"
          }
        },
        {
          "type": "object",
          "description": "NUMBER value schema. Use with dataType NUMBER.",
          "properties": {
            "type": {
              "type": "string",
              "enum": [
                "number"
              ]
            }
          },
          "required": [
            "type"
          ],
          "example": {
            "type": "number"
          }
        },
        {
          "type": "object",
          "description": "BOOLEAN value schema. Use with dataType BOOLEAN.",
          "properties": {
            "type": {
              "type": "string",
              "enum": [
                "boolean"
              ]
            }
          },
          "required": [
            "type"
          ],
          "example": {
            "type": "boolean"
          }
        },
        {
          "type": "object",
          "description": "ARRAY value schema. items.type supports string, number, or boolean.",
          "properties": {
            "type": {
              "type": "string",
              "enum": [
                "array"
              ]
            },
            "items": {
              "type": "object",
              "properties": {
                "type": {
                  "type": "string",
                  "enum": [
                    "string",
                    "number",
                    "boolean"
                  ]
                }
              },
              "required": [
                "type"
              ]
            }
          },
          "required": [
            "type",
            "items"
          ],
          "example": {
            "type": "array",
            "items": {
              "type": "string"
            }
          }
        },
        {
          "type": "object",
          "description": "ENUM value schema. enum options stay in schema.enum; optional labels stay in x-enum-descriptions.",
          "properties": {
            "type": {
              "type": "string",
              "enum": [
                "string"
              ]
            },
            "enum": {
              "type": "array",
              "items": {
                "type": "string"
              }
            },
            "x-enum-descriptions": {
              "type": "array",
              "items": {
                "type": "string"
              }
            }
          },
          "required": [
            "type",
            "enum"
          ],
          "example": {
            "type": "string",
            "enum": [
              "cash",
              "financed"
            ],
            "x-enum-descriptions": [
              "Cash buyer",
              "Needs financing"
            ]
          }
        }
      ],
      "example": {
        "type": "number"
      },
      "additionalProperties": {}
    },
    "required": {
      "type": "boolean",
      "description": "Updated required flag. Explicit null leaves the current value unchanged.",
      "example": true,
      "nullable": true
    },
    "dataType": {
      "type": "string",
      "enum": [
        "DATE",
        "DATETIME",
        "ANNIVERSARY_DATE",
        "TIME",
        "STRING",
        "NUMBER",
        "BOOLEAN",
        "ARRAY",
        "ENUM"
      ],
      "description": "Updated semantic custom property data type. Explicit null leaves the current value unchanged.",
      "example": "NUMBER"
    },
    "dataOnly": {
      "type": "boolean",
      "description": "Updated data-only flag. Data-only properties are not extracted from conversations; they can still be injected into LLM context when usedForLlmContext is enabled. Explicit null leaves the current value unchanged.",
      "example": false,
      "nullable": true
    },
    "usedForLlmContext": {
      "type": "boolean",
      "description": "This setting controls whether a custom property is included in automatic LLM lead_metadata prompt context. It does not change extraction behavior, which remains controlled by dataOnly. Omitted or null values preserve the existing effective setting, even when dataOnly changes in the same request.",
      "example": false,
      "nullable": true
    }
  }
}
```

### `InternalServerError`

```json
{
  "type": "object",
  "properties": {
    "message": {
      "type": "string",
      "description": "A message describing the error",
      "example": "Internal server error"
    },
    "statusCode": {
      "type": "number",
      "example": 500
    }
  }
}
```

### `InvalidRequest`

```json
{
  "type": "object",
  "properties": {
    "message": {
      "type": "string",
      "description": "A message describing the error",
      "example": "The parameter leadId must be provided"
    },
    "statusCode": {
      "type": "number",
      "example": 400
    }
  }
}
```

### `NotAuthorized`

```json
{
  "type": "object",
  "properties": {
    "message": {
      "type": "string",
      "description": "A message describing the error",
      "example": "Access Token is not authorized"
    },
    "statusCode": {
      "type": "number",
      "example": 401
    }
  }
}
```

### `NotFound`

```json
{
  "type": "object",
  "properties": {
    "message": {
      "type": "string",
      "description": "A message describing the error",
      "example": "Lead not found"
    },
    "statusCode": {
      "type": "number",
      "example": 404
    }
  }
}
```

## Security

### `bearer-access-token`

```json
{
  "type": "http",
  "scheme": "bearer",
  "bearerFormat": "JWT"
}
```