InsurScan SDK

Name: InsurScan.Sdk
Author: InsurUp

Official .NET SDK for InsurScan API - Convert insurance policy and quote PDFs to structured JSON with zero setup. Stateless, secure, and developer-friendly.

Features

🚀 Zero Setup - No training, no configuration files, just plug and play
📄 PDF to JSON - Convert insurance PDFs to structured, typed data
🏢 Multi-Insurance Support - Works with major Turkish insurance companies
🔒 Stateless & Secure - No data storage, process and forget
🛡️ Type Safe - Full C# type safety with discriminated unions
📊 Structured Logging - Comprehensive logging with structured data
🔄 Resilient - Built-in retry policies and timeout handling
⚡ High Performance - Optimized for speed and efficiency

Installation

Install the NuGet package:

dotnet add package InsurScan.Sdk

Or via Package Manager Console:

Install-Package InsurScan.Sdk

Quick Start

1. Register Services

using InsurScan.Sdk;

// In Program.cs or Startup.cs
builder.Services.AddInsurScan("https://api.insurscan.com");

// Or with configuration
builder.Services.AddInsurScan(builder.Configuration.GetSection("InsurScan"));

2. Configuration (appsettings.json)

{
  "InsurScan": {
    "BaseUrl": "https://api.insurscan.com",
    "Timeout": "00:00:30",
    "MaxFileSize": 5000000,
    "MaxRetryAttempts": 3,
    "BaseDelaySeconds": 1.0
  }
}

3. Use the Client

using InsurScan.Sdk;
using InsurScan.Models;

public class InsuranceService
{
    private readonly IInsurScanClient _insurScanClient;
    private readonly ILogger<InsuranceService> _logger;

    public InsuranceService(IInsurScanClient insurScanClient, ILogger<InsuranceService> logger)
    {
        _insurScanClient = insurScanClient;
        _logger = logger;
    }

    public async Task<KaskoQuoteResult?> ProcessKaskoQuoteAsync(string filePath)
    {
        // Create PDF content from file
        using var pdfContent = PdfContent.FromFile(filePath);

        // Process the PDF
        var result = await _insurScanClient.ReadQuotePdf(
            PdfProductBranch.Kasko,
            pdfContent,
            InsuranceCompany.Auto // Auto-detect insurance company
        );

        // Handle the result
        return result switch
        {
            InsurScanResult<KaskoQuoteResult>.Success success => success.Data,
            InsurScanResult<KaskoQuoteResult>.Failure failure => 
            {
                _logger.LogError("Failed to process PDF: {Error}", failure.Error);
                return null;
            }
        };
    }
}

Usage Examples

Processing from Different Sources

From File Path

using var pdfContent = PdfContent.FromFile("path/to/kasko-quote.pdf");
var result = await client.ReadQuotePdf(PdfProductBranch.Kasko, pdfContent);

From Stream

using var fileStream = File.OpenRead("kasko-quote.pdf");
using var pdfContent = PdfContent.FromStream(fileStream, "kasko-quote.pdf");
var result = await client.ReadQuotePdf(PdfProductBranch.Kasko, pdfContent);

From Byte Array

byte[] pdfBytes = await File.ReadAllBytesAsync("kasko-quote.pdf");
using var pdfContent = PdfContent.FromBytes(pdfBytes, "kasko-quote.pdf");
var result = await client.ReadQuotePdf(PdfProductBranch.Kasko, pdfContent);

From HTTP Upload (ASP.NET Core)

[HttpPost("upload")]
public async Task<IActionResult> UploadKaskoQuote(IFormFile file)
{
    using var stream = file.OpenReadStream();
    using var pdfContent = PdfContent.FromStream(stream, file.FileName);
    
    var result = await _insurScanClient.ReadQuotePdf(
        PdfProductBranch.Kasko, 
        pdfContent,
        InsuranceCompany.Auto
    );

    return result switch
    {
        InsurScanResult<KaskoQuoteResult>.Success success => Ok(success.Data),
        InsurScanResult<KaskoQuoteResult>.Failure failure => BadRequest(failure.Error.ToString())
    };
}

Error Handling

The SDK uses discriminated unions for type-safe error handling:

var result = await client.ReadQuotePdf(PdfProductBranch.Kasko, pdfContent);

switch (result)
{
    case InsurScanResult<KaskoQuoteResult>.Success success:
        // Process successful result
        var quote = success.Data;
        Console.WriteLine($"Premium: {quote.Premium.TotalPremium}");
        break;

    case InsurScanResult<KaskoQuoteResult>.Failure failure:
        // Handle specific errors
        switch (failure.Error)
        {
            case InsurScanError.EmptyPdf:
                Console.WriteLine("PDF file is empty");
                break;
            case InsurScanError.EncryptedPdf:
                Console.WriteLine("PDF file is encrypted");
                break;
            case InsurScanError.UnsupportedInsuranceCompany:
                Console.WriteLine("Insurance company not supported");
                break;
            case InsurScanError.NetworkError:
                Console.WriteLine("Network error occurred");
                break;
            default:
                Console.WriteLine($"Error: {failure.Error}");
                break;
        }
        break;
}

Configuration Options

InsurScanClientOptions

Property	Type	Default	Description
`BaseUrl`	`string`	Required	The base URL of the InsurScan API
`Timeout`	`TimeSpan`	`00:00:30`	HTTP request timeout
`MaxFileSize`	`long`	`1000000`	Maximum PDF file size in bytes (1MB)
`MaxRetryAttempts`	`int`	`3`	Maximum retry attempts for failed requests
`BaseDelaySeconds`	`double`	`1.0`	Base delay for exponential backoff
`CustomHeaders`	`Dictionary<string, string>`	`{}`	Custom headers for requests
`UserAgent`	`string`	Auto-generated	User agent string

Advanced Configuration

builder.Services.AddInsurScan(options =>
{
    options.BaseUrl = "https://api.insurscan.com";
    options.Timeout = TimeSpan.FromSeconds(60);
    options.MaxFileSize = 5_000_000; // 5MB
    options.MaxRetryAttempts = 5;
    options.BaseDelaySeconds = 2.0;
    options.CustomHeaders.Add("X-API-Key", "your-api-key");
    options.CustomHeaders.Add("X-Client-Version", "1.0.0");
});

Supported Insurance Companies

The SDK supports automatic detection and processing of PDFs from major Turkish insurance companies:

Auto Detection (InsuranceCompany.Auto) - Automatically detects the insurance company
Aksigorta (InsuranceCompany.Ak)
HDI Sigorta (InsuranceCompany.Hdi)
Neova Sigorta (InsuranceCompany.Neova)
Ray Sigorta (InsuranceCompany.Ray)
Sompo Sigorta (InsuranceCompany.Sompo)
Türkiye Katılım Bankası (InsuranceCompany.TurkiyeKatilim)

Error Types

The SDK defines comprehensive error types for different failure scenarios:

Error	Description
`EmptyPdf`	PDF file is empty or has no content
`EncryptedPdf`	PDF file is encrypted and cannot be processed
`InvalidPdf`	PDF file is corrupted or invalid
`FileTooLarge`	PDF file exceeds the maximum size limit
`UnsupportedPdfFormat`	PDF format is not supported
`InsuranceCompanyNotDetected`	Cannot detect insurance company from PDF
`UnsupportedInsuranceCompany`	Insurance company is not supported
`InvalidQuoteFormat`	Quote format in PDF is invalid
`UnsupportedProductBranch`	Product branch is not supported
`NetworkError`	Network error during API request
`Timeout`	Request timeout
`AuthenticationError`	Authentication failed
`AuthorizationError`	Authorization failed
`RateLimitExceeded`	API rate limit exceeded
`ServerError`	Server error
`InvalidResponse`	Invalid response from API
`UnknownError`	Unknown error occurred

Logging

The SDK provides comprehensive structured logging with the InsurScan prefix for easy filtering:

// Configure logging in Program.cs
builder.Logging.AddConsole();
builder.Logging.SetMinimumLevel(LogLevel.Information);

// Example log output:
// [INF] InsurScan starting PDF quote reading for ProductBranch: Kasko, InsuranceCompany: Auto, FileSize: 245760 bytes, FileName: quote.pdf
// [ERR] InsurScan PDF processing failed with error: UnsupportedInsuranceCompany for ProductBranch: Kasko

Log Levels

Debug: Detailed flow information, internal operations
Information: Normal operations, successful processing
Warning: Validation failures, recoverable errors
Error: Processing failures, network errors, exceptions

Best Practices

1. Use Dependency Injection

// ✅ Good - Use DI
public class QuoteService
{
    private readonly IInsurScanClient _client;
    
    public QuoteService(IInsurScanClient client) => _client = client;
}

// ❌ Bad - Don't create instances manually
var client = new InsurScanClient(/* ... */);

2. Dispose PDF Content

// ✅ Good - Use using statements
using var pdfContent = PdfContent.FromFile("quote.pdf");
var result = await client.ReadQuotePdf(PdfProductBranch.Kasko, pdfContent);

// ❌ Bad - Memory leaks
var pdfContent = PdfContent.FromFile("quote.pdf");
var result = await client.ReadQuotePdf(PdfProductBranch.Kasko, pdfContent);
// pdfContent not disposed

3. Handle All Error Cases

// ✅ Good - Comprehensive error handling
var result = await client.ReadQuotePdf(PdfProductBranch.Kasko, pdfContent);
return result switch
{
    InsurScanResult<KaskoQuoteResult>.Success success => success.Data,
    InsurScanResult<KaskoQuoteResult>.Failure failure => HandleError(failure.Error)
};

// ❌ Bad - Ignoring errors
var result = await client.ReadQuotePdf(PdfProductBranch.Kasko, pdfContent);
return ((InsurScanResult<KaskoQuoteResult>.Success)result).Data; // Can throw!

4. Use Cancellation Tokens

// ✅ Good - Support cancellation
public async Task<KaskoQuoteResult?> ProcessAsync(string filePath, CancellationToken cancellationToken)
{
    using var pdfContent = PdfContent.FromFile(filePath);
    var result = await _client.ReadQuotePdf(PdfProductBranch.Kasko, pdfContent, cancellationToken: cancellationToken);
    // ...
}

5. Configure Appropriate Timeouts

// ✅ Good - Set reasonable timeouts based on file sizes
builder.Services.AddInsurScan(options =>
{
    options.Timeout = TimeSpan.FromMinutes(2); // For large files
    options.MaxFileSize = 10_000_000; // 10MB
});

Performance Considerations

File Size: Keep PDF files under 5MB for optimal performance
Concurrent Requests: The client is thread-safe and supports concurrent requests
Memory Usage: Always dispose IPdfContent instances to prevent memory leaks
Retry Policy: Built-in exponential backoff handles transient failures automatically
Connection Pooling: Uses HttpClientFactory for efficient connection management

Troubleshooting

Common Issues

"PDF file is encrypted"
- Ensure the PDF is not password-protected
- Remove encryption before processing
"Insurance company not detected"
- Verify the PDF is from a supported insurance company
- Check if the PDF format is standard
"Network error"
- Check internet connectivity
- Verify the API endpoint URL
- Check firewall settings
"Request timeout"
- Increase the timeout value in configuration
- Check file size limits

Debug Logging

Enable debug logging to see detailed operation flow:

builder.Logging.SetMinimumLevel(LogLevel.Debug);

Support

Documentation: https://docs.insurscan.com
API Reference: https://api.insurscan.com/docs
Issues: GitHub Issues
Email: support@insurup.com

License

This project is licensed under the MIT License - see the LICENSE file for details.

Contributing

We welcome contributions! Please see our Contributing Guide for details.

Made with ❤️ by InsurUp

InsurScan SDK

Official .NET SDK for InsurScan API - Convert insurance policy and quote PDFs to structured JSON with zero setup. Stateless, secure, and developer-friendly.

Features

🚀 Zero Setup - No training, no configuration files, just plug and play
📄 PDF to JSON - Convert insurance PDFs to structured, typed data
🏢 Multi-Insurance Support - Works with major Turkish insurance companies
🔒 Stateless & Secure - No data storage, process and forget
🛡️ Type Safe - Full C# type safety with discriminated unions
📊 Structured Logging - Comprehensive logging with structured data
🔄 Resilient - Built-in retry policies and timeout handling
⚡ High Performance - Optimized for speed and efficiency

Installation

Install the NuGet package:

dotnet add package InsurScan.Sdk

Or via Package Manager Console:

Install-Package InsurScan.Sdk

Quick Start

1. Register Services

using InsurScan.Sdk;

// In Program.cs or Startup.cs
builder.Services.AddInsurScan("https://api.insurscan.com");

// Or with configuration
builder.Services.AddInsurScan(builder.Configuration.GetSection("InsurScan"));

2. Configuration (appsettings.json)

{
  "InsurScan": {
    "BaseUrl": "https://api.insurscan.com",
    "Timeout": "00:00:30",
    "MaxFileSize": 5000000,
    "MaxRetryAttempts": 3,
    "BaseDelaySeconds": 1.0
  }
}

3. Use the Client

using InsurScan.Sdk;
using InsurScan.Models;

public class InsuranceService
{
    private readonly IInsurScanClient _insurScanClient;
    private readonly ILogger<InsuranceService> _logger;

    public InsuranceService(IInsurScanClient insurScanClient, ILogger<InsuranceService> logger)
    {
        _insurScanClient = insurScanClient;
        _logger = logger;
    }

    public async Task<KaskoQuoteResult?> ProcessKaskoQuoteAsync(string filePath)
    {
        // Create PDF content from file
        using var pdfContent = PdfContent.FromFile(filePath);

        // Process the PDF
        var result = await _insurScanClient.ReadQuotePdf(
            PdfProductBranch.Kasko,
            pdfContent,
            InsuranceCompany.Auto // Auto-detect insurance company
        );

        // Handle the result
        return result switch
        {
            InsurScanResult<KaskoQuoteResult>.Success success => success.Data,
            InsurScanResult<KaskoQuoteResult>.Failure failure => 
            {
                _logger.LogError("Failed to process PDF: {Error}", failure.Error);
                return null;
            }
        };
    }
}

Usage Examples

Processing from Different Sources

From File Path

using var pdfContent = PdfContent.FromFile("path/to/kasko-quote.pdf");
var result = await client.ReadQuotePdf(PdfProductBranch.Kasko, pdfContent);

From Stream

using var fileStream = File.OpenRead("kasko-quote.pdf");
using var pdfContent = PdfContent.FromStream(fileStream, "kasko-quote.pdf");
var result = await client.ReadQuotePdf(PdfProductBranch.Kasko, pdfContent);

From Byte Array

byte[] pdfBytes = await File.ReadAllBytesAsync("kasko-quote.pdf");
using var pdfContent = PdfContent.FromBytes(pdfBytes, "kasko-quote.pdf");
var result = await client.ReadQuotePdf(PdfProductBranch.Kasko, pdfContent);

From HTTP Upload (ASP.NET Core)

[HttpPost("upload")]
public async Task<IActionResult> UploadKaskoQuote(IFormFile file)
{
    using var stream = file.OpenReadStream();
    using var pdfContent = PdfContent.FromStream(stream, file.FileName);
    
    var result = await _insurScanClient.ReadQuotePdf(
        PdfProductBranch.Kasko, 
        pdfContent,
        InsuranceCompany.Auto
    );

    return result switch
    {
        InsurScanResult<KaskoQuoteResult>.Success success => Ok(success.Data),
        InsurScanResult<KaskoQuoteResult>.Failure failure => BadRequest(failure.Error.ToString())
    };
}

Error Handling

The SDK uses discriminated unions for type-safe error handling:

var result = await client.ReadQuotePdf(PdfProductBranch.Kasko, pdfContent);

switch (result)
{
    case InsurScanResult<KaskoQuoteResult>.Success success:
        // Process successful result
        var quote = success.Data;
        Console.WriteLine($"Premium: {quote.Premium.TotalPremium}");
        break;

    case InsurScanResult<KaskoQuoteResult>.Failure failure:
        // Handle specific errors
        switch (failure.Error)
        {
            case InsurScanError.EmptyPdf:
                Console.WriteLine("PDF file is empty");
                break;
            case InsurScanError.EncryptedPdf:
                Console.WriteLine("PDF file is encrypted");
                break;
            case InsurScanError.UnsupportedInsuranceCompany:
                Console.WriteLine("Insurance company not supported");
                break;
            case InsurScanError.NetworkError:
                Console.WriteLine("Network error occurred");
                break;
            default:
                Console.WriteLine($"Error: {failure.Error}");
                break;
        }
        break;
}

Configuration Options

InsurScanClientOptions

Property	Type	Default	Description
`BaseUrl`	`string`	Required	The base URL of the InsurScan API
`Timeout`	`TimeSpan`	`00:00:30`	HTTP request timeout
`MaxFileSize`	`long`	`1000000`	Maximum PDF file size in bytes (1MB)
`MaxRetryAttempts`	`int`	`3`	Maximum retry attempts for failed requests
`BaseDelaySeconds`	`double`	`1.0`	Base delay for exponential backoff
`CustomHeaders`	`Dictionary<string, string>`	`{}`	Custom headers for requests
`UserAgent`	`string`	Auto-generated	User agent string

Advanced Configuration

builder.Services.AddInsurScan(options =>
{
    options.BaseUrl = "https://api.insurscan.com";
    options.Timeout = TimeSpan.FromSeconds(60);
    options.MaxFileSize = 5_000_000; // 5MB
    options.MaxRetryAttempts = 5;
    options.BaseDelaySeconds = 2.0;
    options.CustomHeaders.Add("X-API-Key", "your-api-key");
    options.CustomHeaders.Add("X-Client-Version", "1.0.0");
});

Supported Insurance Companies

The SDK supports automatic detection and processing of PDFs from major Turkish insurance companies:

Auto Detection (InsuranceCompany.Auto) - Automatically detects the insurance company
Aksigorta (InsuranceCompany.Ak)
HDI Sigorta (InsuranceCompany.Hdi)
Neova Sigorta (InsuranceCompany.Neova)
Ray Sigorta (InsuranceCompany.Ray)
Sompo Sigorta (InsuranceCompany.Sompo)
Türkiye Katılım Bankası (InsuranceCompany.TurkiyeKatilim)

Error Types

The SDK defines comprehensive error types for different failure scenarios:

Error	Description
`EmptyPdf`	PDF file is empty or has no content
`EncryptedPdf`	PDF file is encrypted and cannot be processed
`InvalidPdf`	PDF file is corrupted or invalid
`FileTooLarge`	PDF file exceeds the maximum size limit
`UnsupportedPdfFormat`	PDF format is not supported
`InsuranceCompanyNotDetected`	Cannot detect insurance company from PDF
`UnsupportedInsuranceCompany`	Insurance company is not supported
`InvalidQuoteFormat`	Quote format in PDF is invalid
`UnsupportedProductBranch`	Product branch is not supported
`NetworkError`	Network error during API request
`Timeout`	Request timeout
`AuthenticationError`	Authentication failed
`AuthorizationError`	Authorization failed
`RateLimitExceeded`	API rate limit exceeded
`ServerError`	Server error
`InvalidResponse`	Invalid response from API
`UnknownError`	Unknown error occurred

Logging

The SDK provides comprehensive structured logging with the InsurScan prefix for easy filtering:

// Configure logging in Program.cs
builder.Logging.AddConsole();
builder.Logging.SetMinimumLevel(LogLevel.Information);

// Example log output:
// [INF] InsurScan starting PDF quote reading for ProductBranch: Kasko, InsuranceCompany: Auto, FileSize: 245760 bytes, FileName: quote.pdf
// [ERR] InsurScan PDF processing failed with error: UnsupportedInsuranceCompany for ProductBranch: Kasko

Log Levels

Debug: Detailed flow information, internal operations
Information: Normal operations, successful processing
Warning: Validation failures, recoverable errors
Error: Processing failures, network errors, exceptions

Best Practices

1. Use Dependency Injection

// ✅ Good - Use DI
public class QuoteService
{
    private readonly IInsurScanClient _client;
    
    public QuoteService(IInsurScanClient client) => _client = client;
}

// ❌ Bad - Don't create instances manually
var client = new InsurScanClient(/* ... */);

2. Dispose PDF Content

// ✅ Good - Use using statements
using var pdfContent = PdfContent.FromFile("quote.pdf");
var result = await client.ReadQuotePdf(PdfProductBranch.Kasko, pdfContent);

// ❌ Bad - Memory leaks
var pdfContent = PdfContent.FromFile("quote.pdf");
var result = await client.ReadQuotePdf(PdfProductBranch.Kasko, pdfContent);
// pdfContent not disposed

3. Handle All Error Cases

// ✅ Good - Comprehensive error handling
var result = await client.ReadQuotePdf(PdfProductBranch.Kasko, pdfContent);
return result switch
{
    InsurScanResult<KaskoQuoteResult>.Success success => success.Data,
    InsurScanResult<KaskoQuoteResult>.Failure failure => HandleError(failure.Error)
};

// ❌ Bad - Ignoring errors
var result = await client.ReadQuotePdf(PdfProductBranch.Kasko, pdfContent);
return ((InsurScanResult<KaskoQuoteResult>.Success)result).Data; // Can throw!

4. Use Cancellation Tokens

// ✅ Good - Support cancellation
public async Task<KaskoQuoteResult?> ProcessAsync(string filePath, CancellationToken cancellationToken)
{
    using var pdfContent = PdfContent.FromFile(filePath);
    var result = await _client.ReadQuotePdf(PdfProductBranch.Kasko, pdfContent, cancellationToken: cancellationToken);
    // ...
}

5. Configure Appropriate Timeouts

// ✅ Good - Set reasonable timeouts based on file sizes
builder.Services.AddInsurScan(options =>
{
    options.Timeout = TimeSpan.FromMinutes(2); // For large files
    options.MaxFileSize = 10_000_000; // 10MB
});

Performance Considerations

File Size: Keep PDF files under 5MB for optimal performance
Concurrent Requests: The client is thread-safe and supports concurrent requests
Memory Usage: Always dispose IPdfContent instances to prevent memory leaks
Retry Policy: Built-in exponential backoff handles transient failures automatically
Connection Pooling: Uses HttpClientFactory for efficient connection management

Troubleshooting

Common Issues

"PDF file is encrypted"
- Ensure the PDF is not password-protected
- Remove encryption before processing
"Insurance company not detected"
- Verify the PDF is from a supported insurance company
- Check if the PDF format is standard
"Network error"
- Check internet connectivity
- Verify the API endpoint URL
- Check firewall settings
"Request timeout"
- Increase the timeout value in configuration
- Check file size limits

Debug Logging

Enable debug logging to see detailed operation flow:

builder.Logging.SetMinimumLevel(LogLevel.Debug);

Support

Documentation: https://docs.insurscan.com
API Reference: https://api.insurscan.com/docs
Issues: GitHub Issues
Email: support@insurup.com

License

This project is licensed under the MIT License - see the LICENSE file for details.

Contributing

We welcome contributions! Please see our Contributing Guide for details.

Made with ❤️ by InsurUp

InsurUp/InsurScan.Sdkv0.1.23

Get Started

Readme

InsurScan SDK

Features

Installation

Quick Start

1. Register Services

2. Configuration (appsettings.json)

3. Use the Client

Usage Examples

Processing from Different Sources

From File Path

From Stream

From Byte Array

From HTTP Upload (ASP.NET Core)

Error Handling

Configuration Options

InsurScanClientOptions

Advanced Configuration

Supported Insurance Companies

Error Types

Logging

Log Levels

Best Practices

1. Use Dependency Injection

2. Dispose PDF Content

3. Handle All Error Cases

4. Use Cancellation Tokens

5. Configure Appropriate Timeouts

Performance Considerations

Troubleshooting

Common Issues

Debug Logging

Support

License

Contributing

InsurUp/InsurScan.Sdkv0.1.23

Get Started

Readme

InsurScan SDK

Features

Installation

Quick Start

1. Register Services

2. Configuration (appsettings.json)

3. Use the Client

Usage Examples

Processing from Different Sources

From File Path

From Stream

From Byte Array

From HTTP Upload (ASP.NET Core)

Error Handling

Configuration Options

InsurScanClientOptions

Advanced Configuration

Supported Insurance Companies

Error Types

Logging

Log Levels

Best Practices

1. Use Dependency Injection

2. Dispose PDF Content

3. Handle All Error Cases

4. Use Cancellation Tokens

5. Configure Appropriate Timeouts

Performance Considerations

Troubleshooting

Common Issues

Debug Logging

Support

License

Contributing