Insurance Exchange API n8n Node

This n8n node provides integration with the Insurance Exchange API for submitting home insurance quotes. The node handles authentication, data transformation, and API communication automatically.

Features

• Automatic Authentication: Handles OAuth token acquisition and management
• Data Transformation: Converts JSON input to required XML format
• Error Handling: Comprehensive error handling and validation
• Flexible Input: Accepts data from previous nodes or manual configuration
• Template Support: Configurable template ID (default: 1001633)

Installation

Option 1: Manual Installation

1. Copy the node files to your n8n custom nodes directory:

   cp -r dist/* ~/.n8n/custom/

2. Restart your n8n instance

Option 2: npm Package (if published)

npm install n8n-nodes-insurance-exchange

Development

Prerequisites

• Node.js 16 or higher
• npm or yarn

Setup

1. Clone the repository

2. Install dependencies:

   npm install

3. Build the project:

   npm run build

4. For development with watch mode:

   npm run dev

Code Quality

• Lint the code:

  npm run lint

• Fix linting issues:

  npm run lintfix

• Format code:

  npm run format

Configuration

1. Set up Credentials

Before using the node, you need to configure the API credentials:

1. Go to Settings > Credentials in your n8n interface
2. Click Create New Credential
3. Select Insurance Exchange API
4. Fill in the required fields:

| Field | Description | Default Value | |-------|-------------|---------------| | Base URL | API base URL | https://api.insuranceexchange.com | | Client ID | API client identifier | the_insurance_exchange_api | | Client Secret | API client secret | (required - provided by Insurance Exchange) | | Grant Type | OAuth grant type | vendor_data_access | | Scope | API access scopes | ApplicantApi EzLynxApi openid QAS RatingApi | | Username | API username | tie_userUAT | | Integration Group ID | Integration group identifier | 114 |

5. Click Test to verify the credentials
6. Save the credentials

2. Configure the Node

Add the Insurance Exchange API node to your workflow and configure:

| Parameter | Description | Default | |-----------|-------------|---------| | Operation | Type of operation | Submit Quote | | Template ID | Quote template identifier | 1001633 | | Carrier ID | Insurance carrier ID | 301 | | XRef Key | Optional cross-reference key | (empty) | | Input Data Source | Source of quote data | From Previous Node |

Input Data Format

The node expects input data in the following JSON structure:

{
  "primaryApplicant": {
    "personalInfo": {
      "firstName": "John",
      "middleName": "M",
      "lastName": "Doe",
      "dateOfBirth": "1985-06-15",
      "ssn": "123456789",
      "gender": "Male",
      "maritalStatus": "Married",
      "relation": "Insured",
      "industry": "Technology",
      "occupation": "Software Engineer",
      "yearsWithEmployer": 5,
      "yearsWithPreviousEmployer": 3
    },
    "address": {
      "streetNumber": "123",
      "streetName": "Main Street",
      "unitNumber": "",
      "city": "Dallas",
      "stateCode": "TX",
      "county": "Dallas",
      "zip5": "75201",
      "zip4": "1234",
      "phoneType": "Mobile",
      "phoneNumber": "2145551234",
      "email": "[email protected]",
      "preferredContactMethod": "Phone (Mobile)",
      "yearsAtAddress": 3
    }
  },
  "policyInfo": {
    "policyTerm": "12 Month",
    "policyType": "HO3",
    "package": "No",
    "effectiveDate": "2024-01-01",
    "creditCheckAuth": "Yes"
  },
  "ratingInfo": {
    "propertyInsCancelledLapsed": "No",
    "yearBuilt": 2010,
    "dwelling": "One Family",
    "numberOfOccupants": 2,
    "dwellingUse": "Primary",
    "dwellingOccupancy": "Owner Occupied",
    "construction": "Brick",
    "roofType": "Architectural Shingles",
    "heatingType": "Electric",
    "squareFootage": 2000,
    "purchaseDate": "2020-05-15",
    "numberOfStories": 2,
    "numberOfFullBaths": 2,
    "swimmingPool": "No",
    "dogOnPremises": "No",
    "businessOnPremises": "No"
  },
  "replacementCost": {
    "replacementCost": 400000,
    "dwelling": 400000,
    "lossOfUse": 80000,
    "personalProperty": 200000,
    "personalLiability": 300000,
    "medicalPayments": 5000,
    "deductible": "1000"
  }
}

Output Format

The node returns a structured response:

{
  "success": true,
  "data": {
    "applicantId": "12345",
    "quoteExecutionId": "QE-67890",
    "carrierResults": [
      {
        "carrierId": "301",
        "status": "Success",
        "premium": 1250.00,
        "errors": []
      }
    ]
  },
  "metadata": {
    "timestamp": "2024-01-15T10:30:00Z",
    "templateId": "1001633",
    "carrierId": "301"
  }
}

Usage Examples

Example 1: Basic Quote Submission

1. Set up data source: Use a previous node (e.g., Webhook, Form, Database) to provide quote data
2. Add Insurance Exchange node: Configure with your credentials and template ID
3. Process results: Use the output in subsequent nodes for notifications, storage, etc.

Example 2: Manual Data Entry

1. Configure node: Set "Input Data Source" to "Manual Input"
2. Enter JSON data: Paste your quote data in the "Quote Data (JSON)" field
3. Execute: Run the workflow to submit the quote

Example 3: Workflow Integration

Webhook → Data Transformation → Insurance Exchange API → Email Notification

Error Handling

The node includes comprehensive error handling:

Common Errors

| Error | Cause | Solution | |-------|-------|----------| | Authentication Failed | Invalid credentials | Verify credentials configuration | | Invalid Template ID | Template not found | Check template ID with Insurance Exchange | | Missing Required Data | Incomplete input data | Ensure all required fields are provided | | Network Timeout | API unavailable | Check network connectivity and API status |

Error Response Format

{
  "success": false,
  "error": {
    "message": "Authentication failed",
    "code": "AUTH_ERROR",
    "details": "Invalid client credentials"
  }
}

Troubleshooting

1. Authentication Issues

• Verify all credential fields are correct
• Check that the base URL is accessible
• Ensure the client secret is current and valid
• Test credentials using the built-in test function

2. Data Format Issues

• Validate JSON structure against the expected format
• Check date formats (YYYY-MM-DD)
• Ensure numeric fields contain valid numbers
• Verify required fields are not empty

3. API Response Issues

• Check the Insurance Exchange API status
• Verify template ID is valid and accessible
• Ensure carrier ID is supported
• Review API documentation for any changes

API Reference

Authentication Endpoint

• URL: {baseUrl}/auth/connect/token
• Method: POST
• Content-Type: application/x-www-form-urlencoded

Quote Submission Endpoint

• URL: {baseUrl}/RatingApi/web-services/v1/quotes/home
• Method: POST
• Content-Type: application/xml
• Authorization: Bearer {access_token}

Support

For issues related to:

• Node functionality: Create an issue in the project repository
• API access: Contact Insurance Exchange support
• n8n integration: Refer to n8n documentation

License

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

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests if applicable
5. Submit a pull request

Changelog

Version 1.0.0

• Initial release
• Basic quote submission functionality
• Authentication handling
• Error management
• Documentation