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

- [GET /api/direct/v2/custom-reports](/api/direct/v2/custom-reports/get.md)
- [GET /api/direct/v2/custom-reports/{category}/latest](/api/direct/v2/custom-reports/{category}/latest/get.md)
- [GET /api/direct/v2/custom-reports/{category}/{id}](/api/direct/v2/custom-reports/{category}/{id}/get.md)

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

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

**Summary:** List custom reports

**Description:**

List every S3 object for the authenticated account's client-accessible custom reports. The response is unpaginated.

#### Responses

- `200`: Custom report objects for the authenticated account
  - Schema: `CustomReportListResponse`
  ```json
  {
    "type": "object",
    "properties": {
      "items": {
        "type": "array",
        "description": "Custom report objects for the authenticated account.",
        "items": {
          "$ref": "#/components/schemas/CustomReport"
        }
      }
    },
    "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/direct/v2/custom-reports' \
  -H "Accept: application/json" \
  -H "Authorization: Bearer $STRUCTURELY_API_TOKEN"
```

### GET /api/direct/v2/custom-reports/{category}/latest

[GET /api/direct/v2/custom-reports/{category}/latest](/api/direct/v2/custom-reports/{category}/latest/get.md)

**Summary:** Download the latest custom report in a category

**Description:**

Redirect to a 1-hour presigned S3 GET URL for the most recently modified object in the category. Ties are broken by higher file name.

#### Parameters

- `category` (path, required: yes)
  - Custom report category (DirectPlatformCustomReport.name).
  - Schema:
    ```json
    {
      "oneOf": [
        {
          "type": "string"
        }
      ]
    }
    ```

#### Responses

- `302`: Redirect to a 1-hour presigned S3 GET URL. The Location header contains the same URL as downloadReport.
  - Schema: `CustomReportDownloadResponse`
  ```json
  {
    "type": "object",
    "properties": {
      "downloadReport": {
        "type": "string",
        "description": "1-hour presigned S3 GET URL for the custom report object."
      }
    },
    "required": [
      "downloadReport"
    ]
  }
  ```
- `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 GET 'https://client.structurely.com/api/direct/v2/custom-reports/{category}/latest' \
  -H "Accept: application/json" \
  -H "Authorization: Bearer $STRUCTURELY_API_TOKEN"
```

### GET /api/direct/v2/custom-reports/{category}/{id}

[GET /api/direct/v2/custom-reports/{category}/{id}](/api/direct/v2/custom-reports/{category}/{id}/get.md)

**Summary:** Download a custom report by id

**Description:**

Redirect to a 1-hour presigned S3 GET URL for the matching custom report object.

#### Parameters

- `category` (path, required: yes)
  - Custom report category (DirectPlatformCustomReport.name).
  - Schema:
    ```json
    {
      "oneOf": [
        {
          "type": "string"
        }
      ]
    }
    ```
- `id` (path, required: yes)
  - SHA-256 hex digest of the report file name.
  - Schema:
    ```json
    {
      "oneOf": [
        {
          "type": "string"
        }
      ]
    }
    ```

#### Responses

- `302`: Redirect to a 1-hour presigned S3 GET URL. The Location header contains the same URL as downloadReport.
  - Schema: `CustomReportDownloadResponse`
  ```json
  {
    "type": "object",
    "properties": {
      "downloadReport": {
        "type": "string",
        "description": "1-hour presigned S3 GET URL for the custom report object."
      }
    },
    "required": [
      "downloadReport"
    ]
  }
  ```
- `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 GET 'https://client.structurely.com/api/direct/v2/custom-reports/{category}/{id}' \
  -H "Accept: application/json" \
  -H "Authorization: Bearer $STRUCTURELY_API_TOKEN"
```

## Schemas

### `CustomReport`

```json
{
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "description": "SHA-256 hex digest of the report file name.",
      "example": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855"
    },
    "name": {
      "type": "string",
      "description": "S3 object file name relative to the report prefix.",
      "example": "weekly-2026-08-21.csv"
    },
    "category": {
      "type": "string",
      "description": "Custom report category (DirectPlatformCustomReport.name).",
      "example": "weekly"
    },
    "date": {
      "type": "string",
      "format": "date-time",
      "description": "S3 LastModified timestamp in UTC ISO-8601."
    },
    "downloadReport": {
      "type": "string",
      "description": "Direct API URL to download this custom report object.",
      "example": "https://api.structurely.com/api/direct/v2/custom-reports/weekly/e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855"
    }
  },
  "required": [
    "category",
    "date",
    "downloadReport",
    "id",
    "name"
  ]
}
```

### `CustomReportDownloadResponse`

```json
{
  "type": "object",
  "properties": {
    "downloadReport": {
      "type": "string",
      "description": "1-hour presigned S3 GET URL for the custom report object."
    }
  },
  "required": [
    "downloadReport"
  ]
}
```

### `CustomReportListResponse`

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

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