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": "john.doe@example.com",
      "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