# Structurely Reseller v1 API

## Overview

The Structurely API allows resellers to provide automation for their accounts. It offers various functionalities to streamline account management.

By utilizing this API, integrators can streamline their workflows.

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

## Contents

- [Accounts](/api/reseller/v1/accounts.md)
- [Auth](/api/reseller/v1/auth.md)

## Endpoint files

### Accounts

- [GET /api/reseller/v1/accounts](/api/reseller/v1/accounts/get.md)
- [POST /api/reseller/v1/accounts](/api/reseller/v1/accounts/post.md)
- [PATCH /api/reseller/v1/accounts/{accountId}](/api/reseller/v1/accounts/{accountId}/patch.md)
- [DELETE /api/reseller/v1/accounts/{accountId}](/api/reseller/v1/accounts/{accountId}/delete.md)
- [POST /api/reseller/v1/accounts/{accountId}/access-token](/api/reseller/v1/accounts/{accountId}/access-token/post.md)

### Auth

- [GET /api/reseller/v1/auth/token-info](/api/reseller/v1/auth/token-info/get.md)

## Auth

### GET /api/reseller/v1/auth/token-info

[GET /api/reseller/v1/auth/token-info](/api/reseller/v1/auth/token-info/get.md)

**Summary:** Retrieve account metadata

**Description:**

Retrieve reseller account metadata for an API access token

#### Responses

- `200`: Account Metadata
  - Schema: `AccountInfo`
  ```json
  {
    "type": "object",
    "properties": {
      "accountId": {
        "type": "string"
      },
      "accountName": {
        "type": "string"
      }
    },
    "required": [
      "accountId",
      "accountName"
    ]
  }
  ```
- `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/reseller/v1/auth/token-info' \
  -H "Accept: application/json" \
  -H "Authorization: Bearer $STRUCTURELY_API_TOKEN"
```

## Accounts

### GET /api/reseller/v1/accounts

[GET /api/reseller/v1/accounts](/api/reseller/v1/accounts/get.md)

**Summary:** List accounts

**Description:**

List active brokerage accounts for the authenticated reseller. Results are sorted by ascending account ID and returned in fixed pages of 25. Supply name only on the initial request; the returned cursor binds the normalized filter and must be used alone for continuation.

#### Parameters

- `name` (query, required: no)
  - Case-insensitive literal substring filter for the initial account list request.
  - Schema:
    ```json
    {
      "type": "string"
    }
    ```
- `cursor` (query, required: no)
  - Cursor from a previous account list response. It binds the continuation ID and any normalized name filter, and must be used alone.
  - Schema:
    ```json
    {
      "type": "string"
    }
    ```

#### Responses

- `200`: Cursor-paginated active brokerage accounts.
  - Schema: `AccountListResponse`
  ```json
  {
    "type": "object",
    "properties": {
      "items": {
        "type": "array",
        "description": "Active brokerage accounts for the authenticated reseller.",
        "items": {
          "$ref": "#/components/schemas/Account"
        }
      },
      "cursor": {
        "type": "string",
        "description": "Pagination cursor for the next page, binding the account ID and any normalized name filter.",
        "nullable": true
      },
      "next": {
        "type": "string",
        "description": "Fully-qualified next-page URL containing only the cursor.",
        "nullable": true
      }
    },
    "required": [
      "items"
    ]
  }
  ```
- `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/reseller/v1/accounts' \
  -H "Accept: application/json" \
  -H "Authorization: Bearer $STRUCTURELY_API_TOKEN"
```

### POST /api/reseller/v1/accounts

[POST /api/reseller/v1/accounts](/api/reseller/v1/accounts/post.md)

**Summary:** Create an account

**Description:**

This endpoint will create an account if it does not exist.

Optionally utilize your system's IDs as internal keys, pass IDs from your CRM or database as parameters for:
- externalAccountId: The Account's ID from your CRM or database

#### Request body

New account metadata

Schema: `CreateAccount`

```json
{
  "type": "object",
  "properties": {
    "externalAccountId": {
      "type": "string",
      "description": "Optionally provide the ID for this account in your CRM or database",
      "example": "b6726f23-1440-4206-962f-8c429f61714c",
      "nullable": true
    },
    "name": {
      "type": "string",
      "example": "Jane Broker"
    },
    "accountName": {
      "type": "string",
      "example": "Acme Brokerage"
    },
    "email": {
      "type": "string",
      "example": "acme@example.com"
    },
    "phone": {
      "type": "string",
      "description": "E.164 formatted number",
      "example": "+13035555555"
    },
    "isFauxUser": {
      "type": "boolean",
      "default": false,
      "description": "Create the primary broker as an active faux user.",
      "example": false
    },
    "integrations": {
      "description": "Optional integration-specific metadata.",
      "example": null,
      "anyOf": [
        {
          "$ref": "#/components/schemas/IntegrationMetadata"
        },
        {
          "type": "object",
          "nullable": true
        }
      ]
    }
  },
  "required": [
    "accountName",
    "email",
    "name",
    "phone"
  ]
}
```

#### Responses

- `200`: Newly created account
  - Schema: `CreateAccountResponse`
  ```json
  {
    "type": "object",
    "properties": {
      "id": {
        "description": "The ID for this account in Structurely",
        "example": "650ba6ced07cb5552a2467b0",
        "type": "string",
        "format": "ObjectId"
      },
      "externalAccountId": {
        "type": "string",
        "description": "Optionally provide the ID for this account in your CRM or database",
        "example": "b6726f23-1440-4206-962f-8c429f61714c",
        "nullable": true
      },
      "name": {
        "type": "string",
        "example": "Acme Widget"
      },
      "email": {
        "type": "string",
        "example": "acme@example.com",
        "nullable": true
      },
      "phone": {
        "type": "string",
        "description": "E.164 formatted number",
        "example": "+13035555555",
        "nullable": true
      },
      "integrations": {
        "readOnly": true,
        "description": "Bonzo, Sierra, and Agent Legend integration status.",
        "allOf": [
          {
            "$ref": "#/components/schemas/AccountIntegrations"
          }
        ]
      },
      "isFauxUser": {
        "type": "boolean",
        "description": "Whether the created primary broker is a faux user."
      },
      "accessToken": {
        "type": "string",
        "description": "A long lived API Access token, used to interact with this account's resources (Enroll Leads, Call Leads, ETC)",
        "example": "XXXXXXXXXXXXXXXXXXX"
      }
    },
    "required": [
      "accessToken",
      "isFauxUser"
    ]
  }
  ```
- `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/reseller/v1/accounts' \
  -H "Accept: application/json" \
  -H "Authorization: Bearer $STRUCTURELY_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "accountName": "Acme Brokerage",
  "email": "acme@example.com",
  "name": "Jane Broker",
  "phone": "+13035555555"
}'
```

### PATCH /api/reseller/v1/accounts/{accountId}

[PATCH /api/reseller/v1/accounts/{accountId}](/api/reseller/v1/accounts/{accountId}/patch.md)

**Summary:** Update Agent Legend integration configuration

**Description:**

Update the write-only Agent Legend auth token and/or API base URL for an active account owned by the authenticated reseller. Requires the reseller bearer token to include write:accounts. Provide at least one update field.

#### Parameters

- `accountId` (path, required: yes)
  - The Account's ID, either the Structurely Account ID, or the externalAccountId you used when creating the account.
  - Schema:
    ```json
    {
      "oneOf": [
        {
          "type": "string"
        },
        {
          "format": "ObjectId",
          "type": "string"
        }
      ]
    }
    ```

#### Request body

Agent Legend auth token and/or API endpoint update. Provide at least one field.

Schema: `PatchAccount`

```json
{
  "type": "object",
  "properties": {
    "integrations": {
      "description": "Agent Legend auth token and/or API endpoint update. Provide at least one field.",
      "allOf": [
        {
          "$ref": "#/components/schemas/PatchAccountIntegrations"
        }
      ]
    }
  },
  "required": [
    "integrations"
  ],
  "additionalProperties": false
}
```

#### Responses

- `200`: Updated account metadata.
  - Schema: `Account`
  ```json
  {
    "type": "object",
    "properties": {
      "id": {
        "description": "The ID for this account in Structurely",
        "example": "650ba6ced07cb5552a2467b0",
        "type": "string",
        "format": "ObjectId"
      },
      "externalAccountId": {
        "type": "string",
        "description": "Optionally provide the ID for this account in your CRM or database",
        "example": "b6726f23-1440-4206-962f-8c429f61714c",
        "nullable": true
      },
      "name": {
        "type": "string",
        "example": "Acme Widget"
      },
      "email": {
        "type": "string",
        "example": "acme@example.com",
        "nullable": true
      },
      "phone": {
        "type": "string",
        "description": "E.164 formatted number",
        "example": "+13035555555",
        "nullable": true
      },
      "integrations": {
        "readOnly": true,
        "description": "Bonzo, Sierra, and Agent Legend integration status.",
        "allOf": [
          {
            "$ref": "#/components/schemas/AccountIntegrations"
          }
        ]
      }
    }
  }
  ```
- `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
      }
    }
  }
  ```
- `409`: The account does not have a configured Agent Legend integration.
  - 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
      }
    }
  }
  ```
- `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/reseller/v1/accounts/{accountId}' \
  -H "Accept: application/json" \
  -H "Authorization: Bearer $STRUCTURELY_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "integrations": {
    "agentLegend": {
      "authToken": {}
    }
  }
}'
```

### DELETE /api/reseller/v1/accounts/{accountId}

[DELETE /api/reseller/v1/accounts/{accountId}](/api/reseller/v1/accounts/{accountId}/delete.md)

**Summary:** Archive an account

**Description:**

This endpoint will deactivate an account, this operation is not recoverable, it will disable the AI and account access.

Optionally utilize your system's IDs as internal keys, pass IDs from your CRM or database as parameters for:
- externalAccountId: The Account's ID from your CRM or database

#### Parameters

- `accountId` (path, required: yes)
  - The Account's ID, either the Structurely Account ID, or the externalAccountId you used when creating the account.
  - Schema:
    ```json
    {
      "oneOf": [
        {
          "type": "string"
        },
        {
          "format": "ObjectId",
          "type": "string"
        }
      ]
    }
    ```
- `reason` (query, required: yes)
  - The reason for archiving the account.
  - Schema:
    ```json
    {
      "type": "string"
    }
    ```

#### Responses

- `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/reseller/v1/accounts/{accountId}?reason={reason}' \
  -H "Accept: application/json" \
  -H "Authorization: Bearer $STRUCTURELY_API_TOKEN"
```

### POST /api/reseller/v1/accounts/{accountId}/access-token

[POST /api/reseller/v1/accounts/{accountId}/access-token](/api/reseller/v1/accounts/{accountId}/access-token/post.md)

**Summary:** Create a Direct API access token

**Description:**

Create a new long-lived Direct API token for an active account owned by the authenticated reseller. Requires the reseller bearer token to include write:accounts.

#### Parameters

- `accountId` (path, required: yes)
  - The Account's ID, either the Structurely Account ID, or the externalAccountId you used when creating the account.
  - Schema:
    ```json
    {
      "oneOf": [
        {
          "type": "string"
        },
        {
          "format": "ObjectId",
          "type": "string"
        }
      ]
    }
    ```

#### Request body

Optional Direct API token scopes.

Schema: `CreateAccessToken`

```json
{
  "type": "object",
  "properties": {
    "scopes": {
      "type": "array",
      "default": [
        "read:conversations",
        "write:conversations",
        "read:users",
        "write:users",
        "read:account",
        "write:account"
      ],
      "minItems": 1,
      "description": "Direct API scopes for the new token. When omitted, scopes default to exactly: read:conversations, write:conversations, read:users, write:users, read:account, write:account. Duplicate scopes are rejected.",
      "example": [
        "read:conversations",
        "write:conversations",
        "read:users",
        "write:users",
        "read:account",
        "write:account"
      ],
      "uniqueItems": true,
      "items": {
        "type": "string",
        "enum": [
          "read:conversations",
          "write:conversations",
          "read:users",
          "write:users",
          "read:account",
          "write:account"
        ]
      }
    }
  },
  "additionalProperties": false
}
```

#### Responses

- `200`: New Direct API access token and its effective scopes.
  - Schema: `CreateAccessTokenResponse`
  ```json
  {
    "type": "object",
    "properties": {
      "accessToken": {
        "type": "string",
        "description": "A long-lived Direct API access token.",
        "example": "XXXXXXXXXXXXXXXXXXX"
      },
      "scopes": {
        "type": "array",
        "description": "Effective Direct API scopes for the new token.",
        "items": {
          "type": "string",
          "enum": [
            "read:conversations",
            "write:conversations",
            "read:users",
            "write:users",
            "read:account",
            "write:account"
          ]
        }
      }
    },
    "required": [
      "accessToken",
      "scopes"
    ]
  }
  ```
- `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
      }
    }
  }
  ```
- `409`: The account has no broker available to own the token.
  - Schema: `AccountHasNoBrokerError`
  ```json
  {
    "type": "object",
    "properties": {
      "message": {
        "type": "string",
        "description": "A message describing why access-token provisioning failed.",
        "example": "Account has no broker"
      },
      "statusCode": {
        "type": "number",
        "example": 409
      }
    },
    "required": [
      "message",
      "statusCode"
    ]
  }
  ```
- `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/reseller/v1/accounts/{accountId}/access-token' \
  -H "Accept: application/json" \
  -H "Authorization: Bearer $STRUCTURELY_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{}'
```

## Schemas

### `BonzoIntegration`

```json
{
  "type": "object",
  "properties": {
    "accountId": {
      "type": "string",
      "description": "Bonzo's Unique ID for the account",
      "example": "b6726f23-1440-4206-962f-8c429f61714c"
    },
    "apiToken": {
      "type": "string",
      "description": "A Bonzo access token allowing Structurely to access resources for this account",
      "example": "XXXXXXXXXXXXXXXXXXX"
    }
  },
  "required": [
    "accountId",
    "apiToken"
  ]
}
```

### `SierraIntegration`

```json
{
  "type": "object",
  "properties": {
    "accountId": {
      "type": "string",
      "description": "Sierra's unique account ID",
      "example": "sierra-account-12345"
    },
    "accessToken": {
      "type": "string",
      "description": "A Sierra access token allowing Structurely to access resources for this account",
      "example": "XXXXXXXXXXXXXXXXXXX"
    }
  },
  "required": [
    "accessToken",
    "accountId"
  ]
}
```

### `AgentLegendIntegration`

```json
{
  "type": "object",
  "properties": {
    "accountId": {
      "type": "string",
      "description": "Agent Legend's unique account ID",
      "example": "agent-legend-account-12345"
    },
    "authToken": {
      "type": "string",
      "description": "An Agent Legend auth token allowing Structurely to access resources for this account",
      "example": "XXXXXXXXXXXXXXXXXXX"
    },
    "apiEndpoint": {
      "type": "string",
      "format": "uri",
      "description": "Optional HTTPS Agent Legend API base URL override.",
      "example": "https://tenant.agentlegend.example/api",
      "nullable": true
    }
  },
  "required": [
    "accountId",
    "authToken"
  ]
}
```

### `IntegrationMetadata`

```json
{
  "type": "object",
  "properties": {
    "bonzo": {
      "description": "Bonzo integration metadata",
      "anyOf": [
        {
          "$ref": "#/components/schemas/BonzoIntegration"
        },
        {
          "type": "object",
          "nullable": true
        }
      ]
    },
    "sierra": {
      "description": "Sierra integration metadata",
      "anyOf": [
        {
          "$ref": "#/components/schemas/SierraIntegration"
        },
        {
          "type": "object",
          "nullable": true
        }
      ]
    },
    "agentLegend": {
      "description": "Agent Legend integration metadata",
      "anyOf": [
        {
          "$ref": "#/components/schemas/AgentLegendIntegration"
        },
        {
          "type": "object",
          "nullable": true
        }
      ]
    }
  }
}
```

### `CreateAccount`

```json
{
  "type": "object",
  "properties": {
    "externalAccountId": {
      "type": "string",
      "description": "Optionally provide the ID for this account in your CRM or database",
      "example": "b6726f23-1440-4206-962f-8c429f61714c",
      "nullable": true
    },
    "name": {
      "type": "string",
      "example": "Jane Broker"
    },
    "accountName": {
      "type": "string",
      "example": "Acme Brokerage"
    },
    "email": {
      "type": "string",
      "example": "acme@example.com"
    },
    "phone": {
      "type": "string",
      "description": "E.164 formatted number",
      "example": "+13035555555"
    },
    "isFauxUser": {
      "type": "boolean",
      "default": false,
      "description": "Create the primary broker as an active faux user.",
      "example": false
    },
    "integrations": {
      "description": "Optional integration-specific metadata.",
      "example": null,
      "anyOf": [
        {
          "$ref": "#/components/schemas/IntegrationMetadata"
        },
        {
          "type": "object",
          "nullable": true
        }
      ]
    }
  },
  "required": [
    "accountName",
    "email",
    "name",
    "phone"
  ]
}
```

### `AccountIntegrationStatus`

```json
{
  "type": "object",
  "properties": {
    "status": {
      "type": "string",
      "enum": [
        "NotConfigured",
        "Healthy",
        "NotHealthy"
      ],
      "readOnly": true,
      "description": "Integration configuration status.",
      "example": "NotConfigured"
    },
    "error": {
      "type": "string",
      "readOnly": true,
      "description": "Integration error message, if any.",
      "example": null,
      "nullable": true
    }
  },
  "required": [
    "error",
    "status"
  ]
}
```

### `AccountIntegrations`

```json
{
  "type": "object",
  "properties": {
    "bonzo": {
      "readOnly": true,
      "description": "Bonzo integration status.",
      "allOf": [
        {
          "$ref": "#/components/schemas/AccountIntegrationStatus"
        }
      ]
    },
    "sierra": {
      "readOnly": true,
      "description": "Sierra integration status.",
      "allOf": [
        {
          "$ref": "#/components/schemas/AccountIntegrationStatus"
        }
      ]
    },
    "agentLegend": {
      "readOnly": true,
      "description": "Agent Legend integration status.",
      "allOf": [
        {
          "$ref": "#/components/schemas/AccountIntegrationStatus"
        }
      ]
    }
  },
  "required": [
    "agentLegend",
    "bonzo",
    "sierra"
  ]
}
```

### `CreateAccountResponse`

```json
{
  "type": "object",
  "properties": {
    "id": {
      "description": "The ID for this account in Structurely",
      "example": "650ba6ced07cb5552a2467b0",
      "type": "string",
      "format": "ObjectId"
    },
    "externalAccountId": {
      "type": "string",
      "description": "Optionally provide the ID for this account in your CRM or database",
      "example": "b6726f23-1440-4206-962f-8c429f61714c",
      "nullable": true
    },
    "name": {
      "type": "string",
      "example": "Acme Widget"
    },
    "email": {
      "type": "string",
      "example": "acme@example.com",
      "nullable": true
    },
    "phone": {
      "type": "string",
      "description": "E.164 formatted number",
      "example": "+13035555555",
      "nullable": true
    },
    "integrations": {
      "readOnly": true,
      "description": "Bonzo, Sierra, and Agent Legend integration status.",
      "allOf": [
        {
          "$ref": "#/components/schemas/AccountIntegrations"
        }
      ]
    },
    "isFauxUser": {
      "type": "boolean",
      "description": "Whether the created primary broker is a faux user."
    },
    "accessToken": {
      "type": "string",
      "description": "A long lived API Access token, used to interact with this account's resources (Enroll Leads, Call Leads, ETC)",
      "example": "XXXXXXXXXXXXXXXXXXX"
    }
  },
  "required": [
    "accessToken",
    "isFauxUser"
  ]
}
```

### `Account`

```json
{
  "type": "object",
  "properties": {
    "id": {
      "description": "The ID for this account in Structurely",
      "example": "650ba6ced07cb5552a2467b0",
      "type": "string",
      "format": "ObjectId"
    },
    "externalAccountId": {
      "type": "string",
      "description": "Optionally provide the ID for this account in your CRM or database",
      "example": "b6726f23-1440-4206-962f-8c429f61714c",
      "nullable": true
    },
    "name": {
      "type": "string",
      "example": "Acme Widget"
    },
    "email": {
      "type": "string",
      "example": "acme@example.com",
      "nullable": true
    },
    "phone": {
      "type": "string",
      "description": "E.164 formatted number",
      "example": "+13035555555",
      "nullable": true
    },
    "integrations": {
      "readOnly": true,
      "description": "Bonzo, Sierra, and Agent Legend integration status.",
      "allOf": [
        {
          "$ref": "#/components/schemas/AccountIntegrations"
        }
      ]
    }
  }
}
```

### `PatchAgentLegendIntegration`

```json
{
  "anyOf": [
    {
      "required": [
        "authToken"
      ]
    },
    {
      "required": [
        "apiEndpoint"
      ]
    }
  ],
  "type": "object",
  "properties": {
    "authToken": {
      "type": "string",
      "description": "Write-only Agent Legend auth token replacement.",
      "writeOnly": true
    },
    "apiEndpoint": {
      "type": "string",
      "format": "uri",
      "description": "HTTPS Agent Legend API base URL override, or null to clear it.",
      "example": "https://tenant.agentlegend.example/api",
      "nullable": true
    }
  },
  "additionalProperties": false
}
```

### `PatchAccountIntegrations`

```json
{
  "type": "object",
  "properties": {
    "agentLegend": {
      "description": "Agent Legend auth token and/or API endpoint update. Provide at least one field.",
      "allOf": [
        {
          "$ref": "#/components/schemas/PatchAgentLegendIntegration"
        }
      ]
    }
  },
  "required": [
    "agentLegend"
  ],
  "additionalProperties": false
}
```

### `PatchAccount`

```json
{
  "type": "object",
  "properties": {
    "integrations": {
      "description": "Agent Legend auth token and/or API endpoint update. Provide at least one field.",
      "allOf": [
        {
          "$ref": "#/components/schemas/PatchAccountIntegrations"
        }
      ]
    }
  },
  "required": [
    "integrations"
  ],
  "additionalProperties": false
}
```

### `CreateAccessToken`

```json
{
  "type": "object",
  "properties": {
    "scopes": {
      "type": "array",
      "default": [
        "read:conversations",
        "write:conversations",
        "read:users",
        "write:users",
        "read:account",
        "write:account"
      ],
      "minItems": 1,
      "description": "Direct API scopes for the new token. When omitted, scopes default to exactly: read:conversations, write:conversations, read:users, write:users, read:account, write:account. Duplicate scopes are rejected.",
      "example": [
        "read:conversations",
        "write:conversations",
        "read:users",
        "write:users",
        "read:account",
        "write:account"
      ],
      "uniqueItems": true,
      "items": {
        "type": "string",
        "enum": [
          "read:conversations",
          "write:conversations",
          "read:users",
          "write:users",
          "read:account",
          "write:account"
        ]
      }
    }
  },
  "additionalProperties": false
}
```

### `CreateAccessTokenResponse`

```json
{
  "type": "object",
  "properties": {
    "accessToken": {
      "type": "string",
      "description": "A long-lived Direct API access token.",
      "example": "XXXXXXXXXXXXXXXXXXX"
    },
    "scopes": {
      "type": "array",
      "description": "Effective Direct API scopes for the new token.",
      "items": {
        "type": "string",
        "enum": [
          "read:conversations",
          "write:conversations",
          "read:users",
          "write:users",
          "read:account",
          "write:account"
        ]
      }
    }
  },
  "required": [
    "accessToken",
    "scopes"
  ]
}
```

### `AccountHasNoBrokerError`

```json
{
  "type": "object",
  "properties": {
    "message": {
      "type": "string",
      "description": "A message describing why access-token provisioning failed.",
      "example": "Account has no broker"
    },
    "statusCode": {
      "type": "number",
      "example": 409
    }
  },
  "required": [
    "message",
    "statusCode"
  ]
}
```

### `AccountListResponse`

```json
{
  "type": "object",
  "properties": {
    "items": {
      "type": "array",
      "description": "Active brokerage accounts for the authenticated reseller.",
      "items": {
        "$ref": "#/components/schemas/Account"
      }
    },
    "cursor": {
      "type": "string",
      "description": "Pagination cursor for the next page, binding the account ID and any normalized name filter.",
      "nullable": true
    },
    "next": {
      "type": "string",
      "description": "Fully-qualified next-page URL containing only the cursor.",
      "nullable": true
    }
  },
  "required": [
    "items"
  ]
}
```

### `AccountInfo`

```json
{
  "type": "object",
  "properties": {
    "accountId": {
      "type": "string"
    },
    "accountName": {
      "type": "string"
    }
  },
  "required": [
    "accountId",
    "accountName"
  ]
}
```

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

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

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