---
updatedAt: 2026-05-21T02:59:13.000Z
agentTools:
  projectIndex: https://api.basiq.io/llms.txt
---

# Create an Insight

Creates a new insight for one or more users. Supported insight types are EXPENSE_RATIO_VERIFICATION, BALANCE_VERIFICATION, ACCOUNT_VERIFICATION, IDENTITY_VERIFICATION, and INCOME_VERIFICATION. Multi-user requests (1–10 users) are currently supported only for EXPENSE_RATIO_VERIFICATION.A single insight object is created referencing all users. The self link in the response uses the first userId from the users array.

# OpenAPI definition

```json
{
  "openapi": "3.0.3",
  "info": {
    "title": "Insights",
    "description": "All included utility endpoints for Basiq partners",
    "version": "3.0.0",
    "termsOfService": "https://docs.basiq.io/en/collections/440849-privacy-terms-and-common-questions",
    "license": {
      "name": "Commercial",
      "url": "https://basiq.io"
    }
  },
  "servers": [
    {
      "url": "https://au-api.basiq.io"
    }
  ],
  "paths": {
    "/insights": {
      "post": {
        "tags": [
          "Insights"
        ],
        "summary": "Create an Insight",
        "description": "Creates a new insight for one or more users. Supported insight types are EXPENSE_RATIO_VERIFICATION, BALANCE_VERIFICATION, ACCOUNT_VERIFICATION, IDENTITY_VERIFICATION, and INCOME_VERIFICATION. Multi-user requests (1–10 users) are currently supported only for EXPENSE_RATIO_VERIFICATION.A single insight object is created referencing all users. The self link in the response uses the first userId from the users array.",
        "operationId": "createInsight",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/PostInsightsRequest"
              },
              "examples": {
                "expense_ratio_single_user": {
                  "summary": "Expense Ratio – single user",
                  "value": {
                    "users": [
                      "a9242681-8c49-434c-9eeb-e011fba2a0cc"
                    ],
                    "type": "EXPENSE_RATIO_VERIFICATION",
                    "data": {
                      "expense": "1000"
                    }
                  }
                },
                "expense_ratio_multi_user": {
                  "summary": "Expense Ratio – multiple users",
                  "value": {
                    "users": [
                      "a9242681-8c49-434c-9eeb-e011fba2a0cc",
                      "dda4cd64-356b-4e01-aa44-1713ca95431b"
                    ],
                    "type": "EXPENSE_RATIO_VERIFICATION",
                    "data": {
                      "expense": "1000"
                    }
                  }
                },
                "balance_verification": {
                  "summary": "Balance Verification",
                  "value": {
                    "users": [
                      "a9242681-8c49-434c-9eeb-e011fba2a0cc"
                    ],
                    "type": "BALANCE_VERIFICATION",
                    "data": {
                      "balance": {
                        "min": "1",
                        "max": "2"
                      }
                    }
                  }
                },
                "account_verification": {
                  "summary": "Account Verification",
                  "value": {
                    "users": [
                      "a9242681-8c49-434c-9eeb-e011fba2a0cc"
                    ],
                    "type": "ACCOUNT_VERIFICATION",
                    "data": {
                      "accountNumber": "032096658830",
                      "accountType": "savings"
                    }
                  }
                },
                "identity_verification": {
                  "summary": "Identity Verification",
                  "value": {
                    "users": [
                      "a9242681-8c49-434c-9eeb-e011fba2a0cc"
                    ],
                    "type": "IDENTITY_VERIFICATION",
                    "data": {
                      "name": "Jane Doe",
                      "email": "jane@example.com",
                      "phone": "+61400000000",
                      "address": "123 Main St, Sydney NSW 2000"
                    }
                  }
                },
                "income_verification": {
                  "summary": "Income Verification",
                  "value": {
                    "users": [
                      "a9242681-8c49-434c-9eeb-e011fba2a0cc"
                    ],
                    "type": "INCOME_VERIFICATION",
                    "data": {
                      "income": {
                        "min": "1",
                        "max": "2"
                      }
                    }
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Successfully created insight",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PostInsightsResponse"
                },
                "examples": {
                  "0_to_10_percent_single_user": {
                    "summary": "Expense ratio 0% to 10% (single user)",
                    "value": {
                      "type": "insight",
                      "id": "a2fdfa02-e2a7-461f-ab59-94e0b751f9dc",
                      "created": "2025-12-16T11:32:42Z",
                      "users": [
                        "a9242681-8c49-434c-9eeb-e011fba2a0cc"
                      ],
                      "insightType": "expense-ratio",
                      "data": [
                        {
                          "input": {
                            "expense": "500"
                          },
                          "result": {
                            "range": "0% to 10%"
                          }
                        }
                      ],
                      "links": {
                        "self": "https://au-api.basiq.io/users/a9242681-8c49-434c-9eeb-e011fba2a0cc/insights/a2fdfa02-e2a7-461f-ab59-94e0b751f9dc"
                      }
                    }
                  },
                  "50_to_60_percent_multi_user": {
                    "summary": "Expense ratio 50% to 60% (multiple users)",
                    "value": {
                      "type": "insight",
                      "id": "ed17a3ce-cf15-4ff2-a9e3-26b50602bd61",
                      "created": "2025-12-16T11:32:42Z",
                      "users": [
                        "a9242681-8c49-434c-9eeb-e011fba2a0cc",
                        "dda4cd64-356b-4e01-aa44-1713ca95431b"
                      ],
                      "insightType": "expense-ratio",
                      "data": [
                        {
                          "input": {
                            "expense": "2750"
                          },
                          "result": {
                            "range": "50% to 60%"
                          }
                        }
                      ],
                      "links": {
                        "self": "https://au-api.basiq.io/users/a9242681-8c49-434c-9eeb-e011fba2a0cc/insights/ed17a3ce-cf15-4ff2-a9e3-26b50602bd61"
                      }
                    }
                  },
                  "income_exceeded": {
                    "summary": "Expenses exceed income",
                    "value": {
                      "type": "insight",
                      "id": "xyz789-uvw012-abc345",
                      "created": "2025-12-16T11:32:42Z",
                      "users": [
                        "a9242681-8c49-434c-9eeb-e011fba2a0cc"
                      ],
                      "insightType": "expense-ratio",
                      "data": [
                        {
                          "input": {
                            "expense": "6000"
                          },
                          "result": {
                            "range": "Income Exceeded"
                          }
                        }
                      ],
                      "links": {
                        "self": "https://au-api.basiq.io/users/a9242681-8c49-434c-9eeb-e011fba2a0cc/insights/xyz789-uvw012-abc345"
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Bad Request - Invalid request parameters",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "examples": {
                  "unsupportedType": {
                    "summary": "Unsupported insight type",
                    "value": {
                      "type": "list",
                      "correlationId": "bde1a9ce-75e3-45aa-acf1-1299f03baf03",
                      "data": [
                        {
                          "type": "error",
                          "code": "parameter-not-valid",
                          "title": "Parameter value is not valid",
                          "detail": "The provided type parameter is not supported"
                        }
                      ]
                    }
                  },
                  "tooManyUsers": {
                    "summary": "More than 10 users provided",
                    "value": {
                      "type": "list",
                      "correlationId": "c4ad43f3-703c-4472-9fc3-a31aea7c62eb",
                      "data": [
                        {
                          "type": "error",
                          "code": "parameter-not-valid",
                          "title": "Parameter value is not valid",
                          "detail": "A maximum of 10 users is allowed per request"
                        }
                      ]
                    }
                  },
                  "invalidExpense": {
                    "summary": "Invalid expense value",
                    "value": {
                      "type": "list",
                      "correlationId": "bde1a9ce-75e3-45aa-acf1-1299f03baf04",
                      "data": [
                        {
                          "type": "error",
                          "code": "parameter-not-valid",
                          "title": "Parameter value is not valid",
                          "detail": "The provided expense parameter is in invalid format",
                          "source": {
                            "pointer": "expense-ratio",
                            "parameter": "expense"
                          }
                        }
                      ]
                    }
                  },
                  "userNoTransactions": {
                    "summary": "User without transactions",
                    "value": {
                      "type": "list",
                      "correlationId": "3088f3f9-400d-4417-b8b4-4245e1e5f5f6",
                      "data": [
                        {
                          "type": "error",
                          "code": "invalid-content",
                          "title": "Invalid request content",
                          "detail": "User has no transactions"
                        }
                      ]
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized - Invalid or missing authentication token",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "examples": {
                  "wrongToken": {
                    "summary": "Expired token used",
                    "value": {
                      "type": "list",
                      "correlationId": "25af36e7-c99c-4725-8d9c-eac33fd3ce3e",
                      "data": [
                        {
                          "type": "error",
                          "code": "access-denied",
                          "title": "Access denied.",
                          "detail": "token has expired",
                          "source": null
                        }
                      ]
                    }
                  }
                }
              }
            }
          },
          "403": {
            "description": "Forbidden - Insufficient authorization scopes",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "examples": {
                  "insufficientScopes": {
                    "summary": "Missing required scopes",
                    "value": {
                      "type": "list",
                      "correlationId": "9948dc17-4159-4999-b5d3-97fc0ac0476d",
                      "data": [
                        {
                          "type": "error",
                          "code": "access-denied",
                          "title": "Access denied",
                          "detail": "Required scopes: bank:accounts.basic:read, bank:accounts.detail:read, bank:transactions:read"
                        }
                      ]
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "One or more users not found or no active consent",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "examples": {
                  "userNotFound": {
                    "summary": "User does not exist",
                    "value": {
                      "type": "list",
                      "correlationId": "b35f1203-47b0-49d6-9271-10f594549f7a",
                      "data": [
                        {
                          "type": "error",
                          "code": "resource-not-found",
                          "title": "Requested resource is not found",
                          "detail": "Requested user does not exist."
                        }
                      ]
                    }
                  },
                  "noActiveConsent": {
                    "summary": "User has no active consent",
                    "value": {
                      "type": "list",
                      "correlationId": "73892179-226e-408d-ba3d-0b9e311adad5",
                      "data": [
                        {
                          "type": "error",
                          "code": "resource-not-found",
                          "title": "Requested resource is not found",
                          "detail": "User has no active consent."
                        }
                      ]
                    }
                  }
                }
              }
            }
          },
          "500": {
            "description": "Internal Server Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        },
        "security": [
          {
            "services_token": []
          }
        ]
      }
    }
  },
  "components": {
    "securitySchemes": {
      "services_token": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "JWT"
      }
    },
    "schemas": {
      "PostInsightsRequest": {
        "type": "object",
        "required": [
          "users",
          "type",
          "data"
        ],
        "properties": {
          "users": {
            "type": "array",
            "description": "Array of user IDs to generate the insight for. Minimum 1, maximum 10 users.",
            "minItems": 1,
            "maxItems": 10,
            "items": {
              "type": "string",
              "format": "uuid"
            },
            "example": [
              "a9242681-8c49-434c-9eeb-e011fba2a0cc",
              "dda4cd64-356b-4e01-aa44-1713ca95431b"
            ]
          },
          "type": {
            "type": "string",
            "description": "The type of insight to generate.",
            "enum": [
              "EXPENSE_RATIO_VERIFICATION",
              "BALANCE_VERIFICATION",
              "ACCOUNT_VERIFICATION",
              "IDENTITY_VERIFICATION",
              "INCOME_VERIFICATION"
            ],
            "example": "EXPENSE_RATIO_VERIFICATION"
          },
          "data": {
            "type": "object",
            "description": "Input data for the insight. The required fields vary by `type`.",
            "oneOf": [
              {
                "title": "ExpenseRatioData",
                "description": "Required when type is EXPENSE_RATIO_VERIFICATION.",
                "required": [
                  "expense"
                ],
                "properties": {
                  "expense": {
                    "type": "string",
                    "description": "The expense value (as a numeric string) to calculate the ratio against income (ME040 Average Monthly Credit). Must be a positive numeric string.",
                    "example": "1000"
                  }
                }
              },
              {
                "title": "BalanceVerificationData",
                "description": "Required when type is BALANCE_VERIFICATION.",
                "required": [
                  "balance"
                ],
                "properties": {
                  "balance": {
                    "type": "object",
                    "required": [
                      "min"
                    ],
                    "properties": {
                      "min": {
                        "type": "string",
                        "description": "Minimum balance threshold as a numeric string.",
                        "example": "1"
                      },
                      "max": {
                        "type": "string",
                        "description": "Maximum balance threshold as a numeric string. Optional.",
                        "example": "2"
                      }
                    }
                  }
                }
              },
              {
                "title": "AccountVerificationData",
                "description": "Required when type is ACCOUNT_VERIFICATION.",
                "required": [
                  "accountNumber"
                ],
                "properties": {
                  "accountNumber": {
                    "type": "string",
                    "description": "The account number to verify.",
                    "example": "032096658830"
                  },
                  "accountType": {
                    "type": "string",
                    "description": "The account type to verify. Optional.",
                    "example": "savings"
                  }
                }
              },
              {
                "title": "IdentityVerificationData",
                "description": "Required when type is IDENTITY_VERIFICATION. At least one field must be provided.",
                "properties": {
                  "name": {
                    "type": "string",
                    "description": "Full name to verify.",
                    "example": "Jane Doe"
                  },
                  "email": {
                    "type": "string",
                    "format": "email",
                    "description": "Email address to verify.",
                    "example": "jane@example.com"
                  },
                  "phone": {
                    "type": "string",
                    "description": "Phone number to verify (E.164 format recommended).",
                    "example": "+61400000000"
                  },
                  "address": {
                    "type": "string",
                    "description": "Address to verify.",
                    "example": "123 Main St, Sydney NSW 2000"
                  }
                }
              },
              {
                "title": "IncomeVerificationData",
                "description": "Required when type is INCOME_VERIFICATION.",
                "required": [
                  "income"
                ],
                "properties": {
                  "income": {
                    "type": "object",
                    "required": [
                      "min"
                    ],
                    "properties": {
                      "min": {
                        "type": "string",
                        "description": "Minimum income threshold as a numeric string.",
                        "example": "1"
                      },
                      "max": {
                        "type": "string",
                        "description": "Maximum income threshold as a numeric string. Optional.",
                        "example": "2"
                      }
                    }
                  }
                }
              }
            ]
          }
        }
      },
      "PostInsightsResponse": {
        "type": "object",
        "required": [
          "type",
          "id",
          "created",
          "users",
          "insightType",
          "data",
          "links"
        ],
        "description": "Response for an insight created via POST /insights. Includes a `users` array reflecting the users from the request.",
        "properties": {
          "type": {
            "type": "string",
            "enum": [
              "insight"
            ],
            "description": "Resource type indicator"
          },
          "id": {
            "type": "string",
            "format": "uuid",
            "description": "Unique identifier for this insight"
          },
          "created": {
            "type": "string",
            "format": "date-time",
            "description": "ISO 8601 timestamp of when the insight was created"
          },
          "users": {
            "type": "array",
            "description": "Array of user IDs for whom the insight was generated. Mirrors the `users` field from the request.",
            "items": {
              "type": "string",
              "format": "uuid"
            },
            "example": [
              "a9242681-8c49-434c-9eeb-e011fba2a0cc",
              "dda4cd64-356b-4e01-aa44-1713ca95431b"
            ]
          },
          "insightType": {
            "type": "string",
            "enum": [
              "expense-ratio",
              "balance",
              "account",
              "identity",
              "income"
            ],
            "description": "Type of insight returned"
          },
          "data": {
            "type": "array",
            "description": "Array containing the insight result. Shape varies by insightType.",
            "items": {
              "oneOf": [
                {
                  "$ref": "#/components/schemas/ExpenseRatioInsightDataItem"
                },
                {
                  "$ref": "#/components/schemas/AccountInsightDataItem"
                },
                {
                  "$ref": "#/components/schemas/BalanceInsightDataItem"
                },
                {
                  "$ref": "#/components/schemas/IdentityInsightDataItem"
                }
              ]
            }
          },
          "links": {
            "type": "object",
            "required": [
              "self"
            ],
            "description": "For multi-user insights the self link uses the first userId from the users array.",
            "properties": {
              "self": {
                "type": "string",
                "format": "uri",
                "description": "Self link pointing to /users/{firstUserId}/insights/{insightId}",
                "example": "https://au-api.basiq.io/users/a9242681-8c49-434c-9eeb-e011fba2a0cc/insights/a2fdfa02-e2a7-461f-ab59-94e0b751f9dc"
              }
            }
          }
        }
      },
      "AccountInsightDataItem": {
        "type": "object",
        "required": [
          "accountId"
        ],
        "properties": {
          "accountId": {
            "type": "string",
            "format": "uuid",
            "description": "The account identifier being verified"
          },
          "accountNumber": {
            "$ref": "#/components/schemas/VerificationResult",
            "description": "Account number verification result"
          },
          "accountType": {
            "$ref": "#/components/schemas/VerificationResult",
            "description": "Account type verification result"
          }
        }
      },
      "ErrorResponse": {
        "type": "object",
        "required": [
          "type",
          "correlationId",
          "data"
        ],
        "properties": {
          "type": {
            "type": "string",
            "enum": [
              "list"
            ],
            "description": "Response type for error responses",
            "example": "list"
          },
          "correlationId": {
            "type": "string",
            "format": "uuid",
            "description": "Unique identifier for tracking this request",
            "example": "0cf1a1fe-de4a-4e01-b81e-60790a1e881b"
          },
          "data": {
            "type": "array",
            "description": "Array containing error details",
            "items": {
              "$ref": "#/components/schemas/ErrorDetail"
            }
          }
        }
      },
      "ErrorDetail": {
        "type": "object",
        "required": [
          "type",
          "code",
          "title",
          "detail"
        ],
        "properties": {
          "type": {
            "type": "string",
            "enum": [
              "error"
            ],
            "description": "Type of data object",
            "example": "error"
          },
          "code": {
            "type": "string",
            "description": "Error code identifier",
            "example": "access-denied"
          },
          "title": {
            "type": "string",
            "description": "Human-readable error title",
            "example": "Access denied."
          },
          "detail": {
            "type": "string",
            "description": "Detailed error message",
            "example": "invalid token"
          },
          "source": {
            "oneOf": [
              {
                "type": "object",
                "nullable": true,
                "properties": {
                  "pointer": {
                    "type": "string"
                  },
                  "parameter": {
                    "type": "string"
                  }
                }
              }
            ],
            "description": "Source of the error (optional)",
            "example": null
          }
        }
      },
      "IdentityInsightDataItem": {
        "type": "object",
        "properties": {
          "name": {
            "$ref": "#/components/schemas/VerificationResult",
            "description": "Name verification result"
          },
          "phones": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/VerificationResult"
            },
            "description": "Array of phone number verification results"
          },
          "emails": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/VerificationResult"
            },
            "description": "Array of email verification results"
          },
          "addresses": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/VerificationResult"
            },
            "description": "Array of address verification results"
          }
        }
      },
      "BalanceInsightDataItem": {
        "type": "object",
        "required": [
          "accountId"
        ],
        "properties": {
          "accountId": {
            "type": "string",
            "format": "uuid",
            "description": "The account identifier being verified"
          },
          "balance": {
            "type": "object",
            "description": "Balance verification result",
            "properties": {
              "input": {
                "type": "object",
                "properties": {
                  "min": {
                    "type": "string",
                    "description": "Minimum balance value"
                  },
                  "max": {
                    "type": "string",
                    "description": "Maximum balance value"
                  }
                },
                "required": [
                  "min",
                  "max"
                ]
              },
              "match": {
                "type": "boolean",
                "nullable": true,
                "description": "Whether the balance falls within the specified range"
              },
              "confidence": {
                "type": "number",
                "format": "float",
                "minimum": 0,
                "maximum": 1,
                "description": "Confidence score of the match (0.0 to 1.0)"
              }
            },
            "required": [
              "input",
              "match",
              "confidence"
            ]
          }
        }
      },
      "VerificationResult": {
        "type": "object",
        "required": [
          "input"
        ],
        "properties": {
          "input": {
            "oneOf": [
              {
                "type": "string"
              },
              {
                "type": "object"
              }
            ],
            "description": "The input value being verified"
          },
          "match": {
            "type": "boolean",
            "nullable": true,
            "description": "Whether the input matched the source data. Null if verification could not be completed."
          },
          "confidence": {
            "type": "number",
            "format": "float",
            "minimum": 0,
            "maximum": 1,
            "description": "Confidence score of the match (0.0 to 1.0)"
          },
          "error": {
            "type": "string",
            "description": "Error message if verification could not be completed"
          }
        }
      },
      "ExpenseRatioInsightDataItem": {
        "type": "object",
        "required": [
          "input",
          "result"
        ],
        "properties": {
          "input": {
            "type": "object",
            "required": [
              "expense"
            ],
            "properties": {
              "expense": {
                "type": "string",
                "description": "Echo of the expense value from request"
              }
            },
            "description": "Echo of the input parameters"
          },
          "result": {
            "type": "object",
            "required": [
              "range"
            ],
            "properties": {
              "range": {
                "type": "string",
                "enum": [
                  "0% to 10%",
                  "10% to 20%",
                  "20% to 30%",
                  "30% to 40%",
                  "40% to 50%",
                  "50% to 60%",
                  "60% to 70%",
                  "70% to 80%",
                  "80% to 90%",
                  "90% to 100%",
                  "Income Exceeded"
                ],
                "description": "Expense-to-income ratio range. Calculated as: expense / ME040 (Average Monthly Credit). 'Income Exceeded' indicates ratio greater than 100%."
              }
            },
            "description": "Result containing the expense ratio range"
          }
        }
      }
    }
  }
}
```