Cascade

    Surveys

    GET /surveys

    List the review surveys sent out by the organization's flows, newest first by default. Supports search, filtering and cursor pagination.

    Requires the surveys:read permission.

    Query Parameters

    limitnumber

    The number of records to return.

    cursorstring

    A pagination cursor. Fetch the next page by passing the nextCursor value from the previous response.

    sortcreatedAt | -createdAt | nextActionAt | -nextActionAt

    The sort order. Prefix a field with - to sort descending. Defaults to -createdAt.

    searchstring

    A free-text search term, matched case-insensitively against the record's most identifying fields. Combined with filter using AND.

    filterstring

    A JSON-encoded filter document, for example {"createdAt":{"$gte":"2025-01-01T00:00:00Z"}}. Filterable fields: id, surveyFlowId, token, orderId, createdAt, customer.id, customer.email, customer.firstName, customer.lastName, customer.metadata, customer.emailOptOut, customer.emailOptOutSource, customer.createdAt, product.id, product.slug, product.title, product.metadata, product.createdAt. See Filtering for the syntax.

    includestring

    A comma-separated list of extra fields to compute and return. Each one costs an additional query, so ask only for what you need. Available: order, customer.

    Request
    curl \
  "https://api.cascade.dev/surveys" \
  -H "Authorization: Bearer sk_YOUR_SECRET_KEY"
    Response
    {
  "data": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "surveyFlowId": "550e8400-e29b-41d4-a716-446655440000",
      "orderId": "550e8400-e29b-41d4-a716-446655440000",
      "token": "string",
      "includedProducts": ["..."],
      "lastFlowStepId": "550e8400-e29b-41d4-a716-446655440000",
      "nextActionAt": "2025-01-15T09:30:00Z",
      "error": "string",
      "status": "scheduled",
      "metadata": "...",
      "createdAt": "2025-01-15T09:30:00Z",
      "updatedAt": "2025-01-15T09:30:00Z",
      "order": {
        "id": "...",
        "siteId": "...",
        "customerId": "...",
        "remoteId": "...",
        "number": "...",
        "totalCents": "...",
        "subtotalCents": "...",
        "shippingCents": "...",
        "taxCents": "...",
        "currencyCode": "...",
        "shippedAt": "...",
        "deliveredAt": "...",
        "cancelledAt": "...",
        "metadata": "...",
        "notes": "...",
        "createdAt": "...",
        "updatedAt": "..."
      },
      "customer": {
        "id": "...",
        "email": "...",
        "phone": "...",
        "firstName": "...",
        "lastName": "...",
        "country": "...",
        "birthday": "...",
        "metadata": "...",
        "notes": "...",
        "emailOptOut": "...",
        "emailOptOutAt": "...",
        "emailOptOutSource": "...",
        "createdAt": "...",
        "updatedAt": "..."
      }
    }
  ],
  "nextCursor": "string"
}

    GET /surveys/{id}

    Get a single survey by ID.

    Requires the surveys:read permission.

    Path Parameters

    idstring (uuid)required

    The ID of the survey.

    Query Parameters

    includestring

    A comma-separated list of extra fields to compute and return. Each one costs an additional query, so ask only for what you need. Available: order, customer.

    Request
    curl \
  "https://api.cascade.dev/surveys/550e8400-e29b-41d4-a716-446655440000" \
  -H "Authorization: Bearer sk_YOUR_SECRET_KEY"
    Response
    {
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "surveyFlowId": "550e8400-e29b-41d4-a716-446655440000",
  "orderId": "550e8400-e29b-41d4-a716-446655440000",
  "token": "string",
  "includedProducts": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "title": "string"
    }
  ],
  "lastFlowStepId": "550e8400-e29b-41d4-a716-446655440000",
  "nextActionAt": "2025-01-15T09:30:00Z",
  "error": "string",
  "status": "scheduled",
  "metadata": "...",
  "createdAt": "2025-01-15T09:30:00Z",
  "updatedAt": "2025-01-15T09:30:00Z",
  "order": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "siteId": "550e8400-e29b-41d4-a716-446655440000",
    "customerId": "550e8400-e29b-41d4-a716-446655440000",
    "remoteId": "string",
    "number": "string",
    "totalCents": 0,
    "subtotalCents": 0,
    "shippingCents": 0,
    "taxCents": 0,
    "currencyCode": "string",
    "shippedAt": "2025-01-15T09:30:00Z",
    "deliveredAt": "2025-01-15T09:30:00Z",
    "cancelledAt": "2025-01-15T09:30:00Z",
    "metadata": "...",
    "notes": "string",
    "createdAt": "2025-01-15T09:30:00Z",
    "updatedAt": "2025-01-15T09:30:00Z"
  },
  "customer": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "email": "[email protected]",
    "phone": "string",
    "firstName": "string",
    "lastName": "string",
    "country": "string",
    "birthday": "string",
    "metadata": "...",
    "notes": "string",
    "emailOptOut": true,
    "emailOptOutAt": "2025-01-15T09:30:00Z",
    "emailOptOutSource": "customer",
    "createdAt": "2025-01-15T09:30:00Z",
    "updatedAt": "2025-01-15T09:30:00Z"
  }
}

    DELETE /surveys/{id}

    Delete a survey before it goes out, so no steps run for it. A survey that has already been sent, or that has collected a review, is part of the audit trail and can't be deleted: those requests answer with a 409. Triggers the survey.deleted webhook.

    Requires the surveys:write permission.

    Path Parameters

    idstring (uuid)required

    The ID of the survey to delete.

    Request
    curl \
  -X DELETE \
  "https://api.cascade.dev/surveys/550e8400-e29b-41d4-a716-446655440000" \
  -H "Authorization: Bearer sk_YOUR_SECRET_KEY"
    Response
    {
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "surveyFlowId": "550e8400-e29b-41d4-a716-446655440000",
  "orderId": "550e8400-e29b-41d4-a716-446655440000",
  "token": "string",
  "includedProducts": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "title": "string"
    }
  ],
  "lastFlowStepId": "550e8400-e29b-41d4-a716-446655440000",
  "nextActionAt": "2025-01-15T09:30:00Z",
  "error": "string",
  "status": "scheduled",
  "metadata": "...",
  "createdAt": "2025-01-15T09:30:00Z",
  "updatedAt": "2025-01-15T09:30:00Z"
}