# 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`

## Webhooks

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

### GET /api/direct/v2/webhooks

[GET /api/direct/v2/webhooks](/api/direct/v2/webhooks/get.md)

**Summary:** List webhook subscriptions

**Description:**

List webhook subscriptions for the authenticated account.

#### Responses

- `200`: Webhook subscriptions for the authenticated account
  - Schema: `WebhookListResponse`
  ```json
  {
    "type": "object",
    "properties": {
      "webhooks": {
        "type": "array",
        "description": "Webhook resources for the authenticated account.",
        "items": {
          "$ref": "#/components/schemas/WebhookCreateResponse"
        }
      }
    },
    "required": [
      "webhooks"
    ]
  }
  ```
- `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/webhooks' \
  -H "Accept: application/json" \
  -H "Authorization: Bearer $STRUCTURELY_API_TOKEN"
```

### POST /api/direct/v2/webhooks

[POST /api/direct/v2/webhooks](/api/direct/v2/webhooks/post.md)

**Summary:** Create a new webhook

**Description:**

Create a webhook subscription for lead, call, and message events.

#### Request body

Webhook configuration payload

Schema: `WebhookCreateRequest`

```json
{
  "type": "object",
  "properties": {
    "name": {
      "type": "string",
      "description": "Human-readable webhook name.",
      "example": "my webhook"
    },
    "target": {
      "type": "string",
      "description": "HTTPS URL where webhook events will be delivered.",
      "example": "https://example.com/webhooks"
    },
    "triggers": {
      "type": "array",
      "description": "List of events that should trigger this webhook.",
      "example": [
        "lead:created",
        "message"
      ],
      "items": {
        "type": "string",
        "enum": [
          "lead:created",
          "lead:updated",
          "call:created",
          "call:updated",
          "message",
          "custom-tool"
        ]
      }
    }
  },
  "required": [
    "name",
    "target",
    "triggers"
  ]
}
```

#### Responses

- `200`: The created webhook resource
  - Schema: `WebhookCreateResponse`
  ```json
  {
    "type": "object",
    "properties": {
      "id": {
        "description": "Webhook ID.",
        "example": "650ba6ced07cb5552a2467b0",
        "type": "string",
        "format": "ObjectId"
      },
      "name": {
        "type": "string",
        "description": "Human-readable webhook name.",
        "example": "my webhook"
      },
      "target": {
        "type": "string",
        "description": "HTTPS URL where webhook events are delivered."
      },
      "secret": {
        "type": "string",
        "description": "Webhook signing secret.",
        "example": "A4h5Q8Y3y9D7s2P4n6V1k3R0t8W2x5Z7b9C1d4F6g8H0j2K4"
      },
      "triggers": {
        "type": "array",
        "description": "Events that trigger this webhook.",
        "example": [
          "message"
        ],
        "items": {
          "type": "string",
          "enum": [
            "lead:created",
            "lead:updated",
            "call:created",
            "call:updated",
            "message",
            "custom-tool"
          ]
        }
      },
      "status": {
        "description": "Current webhook status.",
        "example": "active",
        "type": "string",
        "enum": [
          "active",
          "disabled",
          "failed"
        ]
      },
      "consecutiveFailures": {
        "type": "integer",
        "description": "Number of consecutive failed delivery attempts.",
        "example": 0
      },
      "totalSuccessfulRequests": {
        "type": "integer",
        "description": "Total successful webhook delivery attempts.",
        "example": 0
      },
      "totalFailedRequests": {
        "type": "integer",
        "description": "Total failed webhook delivery attempts.",
        "example": 0
      },
      "createdAt": {
        "type": "string",
        "format": "date-time",
        "description": "Webhook creation timestamp."
      },
      "updatedAt": {
        "type": "string",
        "format": "date-time",
        "description": "Webhook last update timestamp."
      }
    },
    "required": [
      "consecutiveFailures",
      "createdAt",
      "id",
      "name",
      "secret",
      "status",
      "target",
      "totalFailedRequests",
      "totalSuccessfulRequests",
      "triggers",
      "updatedAt"
    ]
  }
  ```
- `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/webhooks' \
  -H "Accept: application/json" \
  -H "Authorization: Bearer $STRUCTURELY_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "my webhook",
  "target": "https://example.com/webhooks",
  "triggers": [
    "lead:created",
    "message"
  ]
}'
```

### PATCH /api/direct/v2/webhooks/{webhook_id}

[PATCH /api/direct/v2/webhooks/{webhook_id}](/api/direct/v2/webhooks/{webhook_id}/patch.md)

**Summary:** Update an existing webhook

**Description:**

Update mutable webhook fields. This endpoint currently supports status updates only.

#### Parameters

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

#### Request body

Webhook update payload.

Schema: `WebhookPatchRequest`

```json
{
  "type": "object",
  "properties": {
    "status": {
      "type": "string",
      "enum": [
        "active",
        "disabled"
      ],
      "description": "Webhook status to apply.",
      "example": "active"
    }
  },
  "required": [
    "status"
  ]
}
```

#### Responses

- `200`: The updated webhook resource
  - Schema: `WebhookCreateResponse`
  ```json
  {
    "type": "object",
    "properties": {
      "id": {
        "description": "Webhook ID.",
        "example": "650ba6ced07cb5552a2467b0",
        "type": "string",
        "format": "ObjectId"
      },
      "name": {
        "type": "string",
        "description": "Human-readable webhook name.",
        "example": "my webhook"
      },
      "target": {
        "type": "string",
        "description": "HTTPS URL where webhook events are delivered."
      },
      "secret": {
        "type": "string",
        "description": "Webhook signing secret.",
        "example": "A4h5Q8Y3y9D7s2P4n6V1k3R0t8W2x5Z7b9C1d4F6g8H0j2K4"
      },
      "triggers": {
        "type": "array",
        "description": "Events that trigger this webhook.",
        "example": [
          "message"
        ],
        "items": {
          "type": "string",
          "enum": [
            "lead:created",
            "lead:updated",
            "call:created",
            "call:updated",
            "message",
            "custom-tool"
          ]
        }
      },
      "status": {
        "description": "Current webhook status.",
        "example": "active",
        "type": "string",
        "enum": [
          "active",
          "disabled",
          "failed"
        ]
      },
      "consecutiveFailures": {
        "type": "integer",
        "description": "Number of consecutive failed delivery attempts.",
        "example": 0
      },
      "totalSuccessfulRequests": {
        "type": "integer",
        "description": "Total successful webhook delivery attempts.",
        "example": 0
      },
      "totalFailedRequests": {
        "type": "integer",
        "description": "Total failed webhook delivery attempts.",
        "example": 0
      },
      "createdAt": {
        "type": "string",
        "format": "date-time",
        "description": "Webhook creation timestamp."
      },
      "updatedAt": {
        "type": "string",
        "format": "date-time",
        "description": "Webhook last update timestamp."
      }
    },
    "required": [
      "consecutiveFailures",
      "createdAt",
      "id",
      "name",
      "secret",
      "status",
      "target",
      "totalFailedRequests",
      "totalSuccessfulRequests",
      "triggers",
      "updatedAt"
    ]
  }
  ```
- `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 PATCH 'https://client.structurely.com/api/direct/v2/webhooks/{webhook_id}' \
  -H "Accept: application/json" \
  -H "Authorization: Bearer $STRUCTURELY_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "status": "active"
}'
```

### DELETE /api/direct/v2/webhooks/{webhook_id}

[DELETE /api/direct/v2/webhooks/{webhook_id}](/api/direct/v2/webhooks/{webhook_id}/delete.md)

**Summary:** Delete an existing webhook

**Description:**

Delete a webhook subscription.

#### Parameters

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

#### Responses

- `200`: Webhook deletion result
  ```json
  {
    "example": "OK",
    "type": "string"
  }
  ```
- `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 DELETE 'https://client.structurely.com/api/direct/v2/webhooks/{webhook_id}' \
  -H "Accept: application/json" \
  -H "Authorization: Bearer $STRUCTURELY_API_TOKEN"
```

## Schemas

### `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
    }
  }
}
```

### `WebhookCreateRequest`

```json
{
  "type": "object",
  "properties": {
    "name": {
      "type": "string",
      "description": "Human-readable webhook name.",
      "example": "my webhook"
    },
    "target": {
      "type": "string",
      "description": "HTTPS URL where webhook events will be delivered.",
      "example": "https://example.com/webhooks"
    },
    "triggers": {
      "type": "array",
      "description": "List of events that should trigger this webhook.",
      "example": [
        "lead:created",
        "message"
      ],
      "items": {
        "type": "string",
        "enum": [
          "lead:created",
          "lead:updated",
          "call:created",
          "call:updated",
          "message",
          "custom-tool"
        ]
      }
    }
  },
  "required": [
    "name",
    "target",
    "triggers"
  ]
}
```

### `WebhookCreateResponse`

```json
{
  "type": "object",
  "properties": {
    "id": {
      "description": "Webhook ID.",
      "example": "650ba6ced07cb5552a2467b0",
      "type": "string",
      "format": "ObjectId"
    },
    "name": {
      "type": "string",
      "description": "Human-readable webhook name.",
      "example": "my webhook"
    },
    "target": {
      "type": "string",
      "description": "HTTPS URL where webhook events are delivered."
    },
    "secret": {
      "type": "string",
      "description": "Webhook signing secret.",
      "example": "A4h5Q8Y3y9D7s2P4n6V1k3R0t8W2x5Z7b9C1d4F6g8H0j2K4"
    },
    "triggers": {
      "type": "array",
      "description": "Events that trigger this webhook.",
      "example": [
        "message"
      ],
      "items": {
        "type": "string",
        "enum": [
          "lead:created",
          "lead:updated",
          "call:created",
          "call:updated",
          "message",
          "custom-tool"
        ]
      }
    },
    "status": {
      "description": "Current webhook status.",
      "example": "active",
      "type": "string",
      "enum": [
        "active",
        "disabled",
        "failed"
      ]
    },
    "consecutiveFailures": {
      "type": "integer",
      "description": "Number of consecutive failed delivery attempts.",
      "example": 0
    },
    "totalSuccessfulRequests": {
      "type": "integer",
      "description": "Total successful webhook delivery attempts.",
      "example": 0
    },
    "totalFailedRequests": {
      "type": "integer",
      "description": "Total failed webhook delivery attempts.",
      "example": 0
    },
    "createdAt": {
      "type": "string",
      "format": "date-time",
      "description": "Webhook creation timestamp."
    },
    "updatedAt": {
      "type": "string",
      "format": "date-time",
      "description": "Webhook last update timestamp."
    }
  },
  "required": [
    "consecutiveFailures",
    "createdAt",
    "id",
    "name",
    "secret",
    "status",
    "target",
    "totalFailedRequests",
    "totalSuccessfulRequests",
    "triggers",
    "updatedAt"
  ]
}
```

### `WebhookListResponse`

```json
{
  "type": "object",
  "properties": {
    "webhooks": {
      "type": "array",
      "description": "Webhook resources for the authenticated account.",
      "items": {
        "$ref": "#/components/schemas/WebhookCreateResponse"
      }
    }
  },
  "required": [
    "webhooks"
  ]
}
```

### `WebhookPatchRequest`

```json
{
  "type": "object",
  "properties": {
    "status": {
      "type": "string",
      "enum": [
        "active",
        "disabled"
      ],
      "description": "Webhook status to apply.",
      "example": "active"
    }
  },
  "required": [
    "status"
  ]
}
```

## Security

### `bearer-access-token`

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