--- updatedAt: 2026-06-08T19:57:45.000Z agentTools: projectIndex: https://docs.inscribe.ai/llms.txt --- # Retrieve Income Insights (Customer) Returns income insights derived from submitted customer documents and transactions. # OpenAPI definition ```json { "openapi": "3.0.0", "info": { "description": "Inscribe Fraud Detection API Documentation\n", "version": "2.0.0", "title": "Core Resources", "termsOfService": "http://swagger.io/terms/", "contact": { "email": "api@inscribe.ai" }, "license": { "name": "Apache 2.0", "url": "http://www.apache.org/licenses/LICENSE-2.0.html" } }, "servers": [ { "url": "https://api.inscribe.ai/api/v2" } ], "security": [ { "ApiKeyAuth": [] } ], "tags": [ { "name": "Credit Insights", "description": "Credit Insights provides inferred creditworthiness datapoints relating to a specific customer or bank account." } ], "externalDocs": { "description": "Find out more about Swagger", "url": "http://swagger.io" }, "paths": { "/customers/{customer_id}/credit_analysis/income_insights": { "get": { "tags": [ "Credit Insights" ], "summary": "Retrieve Income Insights (Customer)", "description": "Returns income insights derived from submitted customer documents and transactions.", "operationId": "getCustomerCreditAnalysisIncomeInsights", "parameters": [ { "name": "customer_id", "in": "path", "description": "The id of the customer to return.", "example": "0efae611-b3eb-4b84-8ed0-a4e92ad3bf4b", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "$ref": "#/components/parameters/start_date" }, { "$ref": "#/components/parameters/end_date" }, { "$ref": "#/components/parameters/document_ids" }, { "$ref": "#/components/parameters/include_unreconciled_documents" } ], "responses": { "200": { "description": "Successfully retrieved customer income insights.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreditAnalysisIncomeInsights" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "403": { "$ref": "#/components/responses/PermissionDenied" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } } }, "components": { "securitySchemes": { "ApiKeyAuth": { "type": "apiKey", "in": "header", "name": "Authorization", "x-default": "Inscribe " } }, "parameters": { "include_unreconciled_documents": { "name": "include_unreconciled_documents", "in": "query", "description": "Unreconciled bank statements are statements where the difference between the parsed opening and closing balances is not explained by the sum of the parsed transaction amounts. Statements are typically unreconciled if the uploaded document has poor quality or is missing some of its original pages. It can also happen when the parsing models fail to parse and extract all relevant data. If this parameter is set to False, unreconciled bank statements will be excluded from the credit insights. This parameter defaults to True, keeping all documents included.", "required": false, "example": true, "schema": { "type": "boolean" } }, "start_date": { "name": "start_date", "in": "query", "description": "Specifies the start date for data retrieval. Only data with a date on or after this will be considered. This helps in filtering the data to a specific time frame of interest.", "required": false, "example": "2024-01-01", "schema": { "type": "string", "format": "date" } }, "end_date": { "name": "end_date", "in": "query", "description": "Specifies the end date for data retrieval. Only data with a date before this will be considered. This helps in filtering data to a specific time frame of interest.", "required": false, "example": "2024-12-31", "schema": { "type": "string", "format": "date" } }, "document_ids": { "name": "document_ids", "in": "query", "description": "A comma separated list of document UUIDs. Only data from these documents will be considered (as well as open banking data). This helps in filtering data to include/exclude certain documents.", "required": false, "example": "3616baa9-9caf-434e-b4d0-8a32c644dfd4,3616baa9-9caf-434e-b4d0-8a32c644dfe5", "schema": { "type": "string" } } }, "schemas": { "Error": { "type": "object", "properties": { "message": { "type": "string", "example": "error message" } }, "required": [ "message" ] }, "metadata_insights": { "type": "object", "description": "Additional data which provides context about Inscribe's Credit Insights response.", "properties": { "confidence_score": { "type": "number", "format": "float", "description": "The confidence score represents the degree of certainty for the accuracy of the Credit Insights outputs. We calculate this score using a weighted combination of parsing and transaction categorization certainties. Confidence scores above 0.5 represent high confidence.", "example": 0.99 }, "customer_contains_low_trust_score_documents": { "type": "boolean", "description": "This value will be set to True if the customer contains any documents under a trust score threshold of 50. Else, this will be set to False.", "example": false }, "included_data_sources": { "type": "object", "description": "Lists all documents and open banking data which were used to create the Inscribe Credit Insights.", "properties": { "documents": { "type": "array", "items": { "type": "object", "properties": { "document_id": { "type": "string", "format": "uuid", "example": "b3de84cf-97aa-4321-a223-51640d5d8fca" } } } }, "open_banking": { "type": "array", "items": { "type": "object", "properties": { "open_banking_data_id": { "type": "string", "format": "uuid", "example": "e959ed48-a9e4-44f3-a6f8-b9dddd21f27c" } } } } } }, "excluded_data_sources": { "type": "object", "description": "Lists all documents and open banking data which were excluded from the Inscribe Credit Insights. Documents can be excluded if they are duplicate documents, or when the include_unreconciled_documents query parameter is set to False.", "properties": { "documents": { "type": "array", "items": { "type": "object", "properties": { "document_id": { "type": "string", "format": "uuid", "example": "fd7abd7d-5d62-42d0-b49e-62eae1fd4e22" }, "exclusion_reason": { "format": "string", "example": "UNRECONCILED_BANK_ACCOUNT" } } } }, "open_banking": { "type": "array", "items": { "type": "object", "properties": { "open_banking_data_id": { "type": "string", "format": "uuid", "example": "920b148f-db30-46fe-8da9-3de2c9e55b04" } } } } } }, "query_parameters": { "type": "object", "description": "Lists the query parameters which were used in the original endpoint request." } } }, "CreditAnalysisIncomeInsights": { "type": "object", "properties": { "personal_income": { "type": "object", "description": "Insights relating to personal income data.", "properties": { "transaction_data": { "type": "object", "description": "Personal income insights relating to transaction data (bank statements and open banking data).", "properties": { "estimated_annual_net": { "type": "integer", "description": "Estimated annual net income (in cents).", "example": 8866968 }, "period_net": { "type": "integer", "description": "Net income over the period (in cents). The term `period` refers to the time interval covering the earliest date to the latest date found in the submitted data.", "example": 753085 }, "count_deposits": { "type": "integer", "description": "Number of income deposit transactions.", "example": 24 }, "average_deposit_amount": { "type": "integer", "description": "The average deposit amount across all uploaded personal income transactions.", "example": 10000 }, "streams": { "type": "object", "description": "List of all income streams relating to transaction data.", "properties": { "sample_payer_1": { "type": "array", "description": "Income insights relating to income received from sample_payer_1.", "items": { "type": "object", "properties": { "frequency": { "type": "string", "description": "The frequency of this income stream, either `daily`, `weekly`, `fortnightly`, `monthly`, `irregular`, or `unknown`.", "example": "monthly" }, "estimated_annual_net": { "type": "integer", "description": "Estimated annual net income for this income stream (in cents).", "example": 7495769 }, "period_net": { "type": "integer", "description": "Net income over the period for this income stream (in cents). The term `period` refers to the time interval covering the earliest date to the latest date found in the submitted data.", "example": 636627 }, "transaction_ids": { "type": "array", "description": "List of transaction IDs relating to this income stream.", "items": { "type": "string", "format": "uuid" }, "example": [ "0efae611-b3eb-4b84-8ed0-a4e92ad3bf4b", "d0734cb2-eb23-11ed-a05b-0242ac120004" ] }, "category": { "type": "string", "description": "The Inscribe category that this revenue stream belongs to. The Inscribe category that this income stream belongs to. Options here include the top-level category `income`, or one of the subcategories `salary`, `retirement`, `social_security`, `commission_received`, or `interest_received`.", "example": "salary" } } } } } }, "personal_income_by_payment_processor": { "type": "object", "description": "List of all income streams relating to transaction data split by payment processor.", "properties": { "sample_processor_1": { "type": "array", "description": "Income insights relating to personal income received via sample_processor_1.", "items": { "type": "object", "properties": { "frequency": { "type": "string", "description": "The frequency of this income stream, either `daily`, `weekly`, `fortnightly`, `monthly`, `irregular`, or `unknown`.", "example": "monthly" }, "estimated_annual_net": { "type": "integer", "description": "Estimated annual net income for this income stream (in cents).", "example": 7495769 }, "period_net": { "type": "integer", "description": "Net income over the period for this income stream (in cents). The term `period` refers to the time interval covering the earliest date to the latest date found in the submitted data.", "example": 636627 }, "transaction_ids": { "type": "array", "description": "List of transaction IDs relating to this income stream.", "items": { "type": "string", "format": "uuid" }, "example": [ "0efae611-b3eb-4b84-8ed0-a4e92ad3bf4b", "d0734cb2-eb23-11ed-a05b-0242ac120004" ] }, "category": { "type": "string", "description": "The Inscribe category that this revenue stream belongs to. The Inscribe category that this income stream belongs to. Options here include the top-level category `income`, or one of the subcategories `salary`, `retirement`, `social_security`, `commission_received`, or `interest_received`.", "example": "salary" } } } } } } } }, "payslip_data": { "type": "object", "description": "Personal income insights relating to payslips.", "properties": { "estimated_annual_net": { "type": "integer", "description": "Estimated annual net income (in cents).", "example": 8866968 }, "period_net": { "type": "integer", "description": "Net income over the period (in cents). The term `period` refers to the time interval covering the earliest date to the latest date found in the submitted data.", "example": 753085 }, "estimated_annual_gross": { "type": "integer", "description": "Estimated annual gross income (in cents).", "example": 9866968 }, "period_gross": { "type": "integer", "description": "Gross income over the period (in cents). The term `period` refers to the time interval covering the earliest date to the latest date found in the submitted data.", "example": 783085 }, "streams": { "type": "object", "description": "List of all income streams relating to payslip data.", "properties": { "sample_payer_1": { "type": "array", "description": "Income insights relating to income received from sample_payer_1.", "items": { "type": "object", "properties": { "frequency": { "type": "string", "description": "The frequency of this income stream, either `daily`, `weekly`, `fortnightly`, `monthly`, `irregular`, or `unknown`.", "example": "monthly" }, "estimated_annual_net": { "type": "integer", "description": "Estimated annual net income for this income stream (in cents).", "example": 7495769 }, "period_net": { "type": "integer", "description": "Net income over the period for this income stream (in cents). The term `period` refers to the time interval covering the earliest date to the latest date found in the submitted data.", "example": 636627 }, "estimated_annual_gross": { "type": "integer", "description": "Estimated annual gross income for this income stream (in cents).", "example": 8495769 }, "period_gross": { "type": "integer", "description": "Gross income over the period for this income stream (in cents). The term `period` refers to the time interval covering the earliest date to the latest date found in the submitted data.", "example": 736627 }, "payslip_document_ids": { "type": "array", "description": "List of payslip document IDs related to this income stream.", "items": { "type": "integer", "example": 25017 } } } } } } } } } } }, "revenue": { "type": "object", "description": "Insights relating to revenue data.", "properties": { "transaction_data": { "type": "object", "description": "Revenue insights relating to transaction data (bank statements and open banking data).", "properties": { "estimated_annual_gross": { "type": "integer", "description": "Estimated annual gross revenue (in cents).", "example": 8866968 }, "period_gross": { "type": "integer", "description": "Gross revenue over the period (in cents). The term `period` refers to the time interval covering the earliest date to the latest date found in the submitted data.", "example": 753085 }, "count_deposits": { "type": "integer", "description": "Number of revenue deposit transactions.", "example": 24 }, "average_deposit_amount": { "type": "integer", "description": "The average deposit amount across all uploaded revenue transactions.", "example": 10000 }, "streams": { "type": "object", "description": "List of all revenue streams relating to transaction data.", "properties": { "sample_payer_1": { "type": "array", "description": "Revenue insights relating to income received from sample_payer_1.", "items": { "type": "object", "properties": { "frequency": { "type": "string", "description": "The frequency of this revenue stream, either `daily`, `weekly`, `fortnightly`, `monthly`, `irregular`, or `unknown`.", "example": "monthly" }, "estimated_annual_gross": { "type": "integer", "description": "Estimated annual gross revenue for this stream (in cents).", "example": 7495769 }, "period_gross": { "type": "integer", "description": "Gross revenue over the period for this stream (in cents). The term `period` refers to the time interval covering the earliest date to the latest date found in the submitted data.", "example": 636627 }, "transaction_ids": { "type": "array", "description": "List of transaction IDs for this revenue stream.", "items": { "type": "string", "format": "uuid" }, "example": [ "0efae611-b3eb-4b84-8ed0-a4e92ad3bf4b", "160d1f86-eb24-11ed-a05b-0242ac120003" ] }, "category": { "type": "string", "description": "The Inscribe category that this revenue stream belongs to. The Inscribe category that this income stream belongs to. Options here include the top-level category `income`, or one of the subcategories `revenue`, `retirement`, `social_security`, `commission_received`, or `interest_received`.", "example": "revenue" } } } } } }, "revenue_by_payment_processor": { "type": "object", "description": "List of all revenue streams relating to transaction data.", "properties": { "sample_processor_1": { "type": "array", "description": "Revenue insights relating to income received via sample_processor_1.", "items": { "type": "object", "properties": { "frequency": { "type": "string", "description": "The frequency of this revenue stream, either `daily`, `weekly`, `fortnightly`, `monthly`, `irregular`, or `unknown`.", "example": "monthly" }, "estimated_annual_gross": { "type": "integer", "description": "Estimated annual gross revenue for this stream (in cents).", "example": 7495769 }, "period_gross": { "type": "integer", "description": "Gross revenue over the period for this stream (in cents). The term `period` refers to the time interval covering the earliest date to the latest date found in the submitted data.", "example": 636627 }, "transaction_ids": { "type": "array", "description": "List of transaction IDs for this revenue stream.", "items": { "type": "string", "format": "uuid" }, "example": [ "0efae611-b3eb-4b84-8ed0-a4e92ad3bf4b", "160d1f86-eb24-11ed-a05b-0242ac120003" ] }, "category": { "type": "string", "description": "The Inscribe category that this revenue stream belongs to. The Inscribe category that this income stream belongs to. Options here include the top-level category `income`, or one of the subcategories `revenue`, `retirement`, `social_security`, `commission_received`, or `interest_received`.", "example": "revenue" } } } } } } } } } }, "metadata": { "$ref": "#/components/schemas/metadata_insights" }, "confidence_score": { "type": "number", "deprecated": true, "format": "float", "description": "The confidence score represents the degree of certainty for the accuracy of the Credit Insights outputs. We calculate this score using a weighted combination of parsing and transaction categorization certainties. Confidence scores above 0.5 represent high confidence.", "example": 0.99 } } } }, "responses": { "BadRequest": { "description": "You have provided incorrect data.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "PermissionDenied": { "description": "You do not have permission to access this resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "TooManyRequests": { "description": "Too many requests. The request has been rate limited. For more information, visit our [documentation on rate limiting](https://docs.inscribe.ai/docs/are-the-endpoints-rate-limited).", "content": { "text/plain": { "example": "Requests are limited to 200 requests over a 5 minute period. Please try again in 30 seconds" } }, "headers": { "Retry-After": { "description": "The number of seconds to wait before retrying the request.", "schema": { "type": "integer", "example": 30 } } } } } }, "x-explorer-enabled": false, "x-samples-enabled": false, "x-samples-languages": [ "curl", "python", "node" ] } ```