API Integration Guide

This guide covers the simplified pricing workflow for insurance quotes, ideal for quick premium calculations and pre-qualification scenarios.

Overview

The quick pricing workflow provides streamlined access to:

• Price Quote API - Calculate insurance premium pricing with minimal data
• Vehicle Lookup - Auto-populate vehicle details by registration
• Eircode Lookup - Validate and retrieve address information

This approach is perfect for:

• Initial quote estimates
• Price comparison tools
• Pre-qualification workflows
• Customer self-service portals

Prerequisites

• API credentials (client ID and secret)
• Basic understanding of REST APIs and OAuth 2.0

Need Credentials?

Contact neil.reilly@assistinsurances.ie to obtain your API credentials.

Base URL

https://api.assistinsurances.ie

Quick Start

Complete Integration Example

Shell Script

#!/bin/bash

# Configuration
CLIENT_ID="YOUR_CLIENT_ID"
CLIENT_SECRET="YOUR_CLIENT_SECRET"
BASE_URL="https://api.assistinsurances.ie"
SCOPE="api://1c15f5fa-f434-401b-b4ec-ab3ea75d48bb/assist-api-gateway/.default"

# Step 1: Get access token
echo "Getting access token..."
TOKEN=$(curl -s -X POST "${BASE_URL}/auth/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "client_id=${CLIENT_ID}" \
  -d "client_secret=${CLIENT_SECRET}" \
  -d "scope=${SCOPE}" \
  -d "grant_type=client_credentials" \
  | jq -r '.access_token')

echo "Token obtained: ${TOKEN:0:50}..."

# Step 2: Lookup vehicle
echo -e "\nLooking up vehicle 12-D-12345..."
curl -X GET "${BASE_URL}/vehicle-lookup/12-D-12345" \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "Content-Type: application/json" \
  | jq '.'

# Step 3: Get price quote
echo -e "\nGetting price quote..."
curl -X POST "${BASE_URL}/priceQuote" \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "data": {
      "in_policy.dateInception": "2025-10-02T00:00:00+01:00",
      "in_customer.dateOfBirth": "1987-09-18",
      "in_dts.raterCover": "Comprehensive"
    }
  }' \
  | jq '.'

# Step 4: Lookup eircode
echo -e "\nLooking up eircode D02X285..."
curl -X GET "${BASE_URL}/eircode-lookup/D02X285" \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "Content-Type: application/json" \
  | jq '.'

JavaScript

class QuickPricingClient {
  constructor(clientId, clientSecret) {
    this.clientId = clientId;
    this.clientSecret = clientSecret;
    this.baseUrl = 'https://api.assistinsurances.ie';
    this.token = null;
    this.tokenExpiresAt = null;
  }

  async getAccessToken() {
    // Return cached token if valid
    if (this.token && this.tokenExpiresAt > Date.now() + 300000) {
      return this.token;
    }

    const response = await fetch(`${this.baseUrl}/auth/token`, {
      method: 'POST',
      headers: {
        'Content-Type': 'application/x-www-form-urlencoded',
      },
      body: new URLSearchParams({
        client_id: this.clientId,
        client_secret: this.clientSecret,
        scope: 'api://1c15f5fa-f434-401b-b4ec-ab3ea75d48bb/assist-api-gateway/.default',
        grant_type: 'client_credentials',
      }),
    });

    const data = await response.json();
    this.token = data.access_token;
    this.tokenExpiresAt = Date.now() + (data.expires_in * 1000);

    return this.token;
  }

  async lookupVehicle(vrm) {
    const token = await this.getAccessToken();
    const response = await fetch(
      `${this.baseUrl}/vehicle-lookup/${encodeURIComponent(vrm)}`,
      {
        headers: {
          'Authorization': `Bearer ${token}`,
        },
      }
    );

    if (!response.ok) {
      throw new Error(`Vehicle lookup failed: ${response.statusText}`);
    }

    return response.json();
  }

  async getPriceQuote(quoteData) {
    const token = await this.getAccessToken();
    const response = await fetch(`${this.baseUrl}/priceQuote`, {
      method: 'POST',
      headers: {
        'Authorization': `Bearer ${token}`,
        'Content-Type': 'application/json',
      },
      body: JSON.stringify({ data: quoteData }),
    });

    if (!response.ok) {
      throw new Error(`Price quote failed: ${response.statusText}`);
    }

    return response.json();
  }

  async lookupEircode(eircode) {
    const token = await this.getAccessToken();
    const response = await fetch(
      `${this.baseUrl}/eircode-lookup/${encodeURIComponent(eircode)}`,
      {
        headers: {
          'Authorization': `Bearer ${token}`,
        },
      }
    );

    if (!response.ok) {
      throw new Error(`Eircode lookup failed: ${response.statusText}`);
    }

    return response.json();
  }
}

// Usage
const client = new QuickPricingClient(
  process.env.ASSIST_CLIENT_ID,
  process.env.ASSIST_CLIENT_SECRET
);

// Lookup vehicle
const vehicle = await client.lookupVehicle('12-D-12345');
console.log('Vehicle:', vehicle);

// Get quote
const quote = await client.getPriceQuote({
  'in_policy.dateInception': '2025-10-02T00:00:00+01:00',
  'in_customer.dateOfBirth': '1987-09-18',
  'in_dts.raterCover': 'Comprehensive',
});
console.log('Quote:', quote);

// Lookup address
const address = await client.lookupEircode('D02X285');
console.log('Address:', address);

Python

import os
import requests
from datetime import datetime, timedelta
from typing import Dict, Optional

class QuickPricingClient:
    def __init__(self, client_id: str, client_secret: str):
        self.client_id = client_id
        self.client_secret = client_secret
        self.base_url = 'https://api.assistinsurances.ie'
        self.token: Optional[str] = None
        self.token_expires_at: Optional[datetime] = None
        self.session = requests.Session()

    def get_access_token(self) -> str:
        """Get cached token or request new one."""
        if self.token and self.token_expires_at:
            if datetime.now() < (self.token_expires_at - timedelta(minutes=5)):
                return self.token

        response = self.session.post(
            f'{self.base_url}/auth/token',
            data={
                'client_id': self.client_id,
                'client_secret': self.client_secret,
                'scope': 'api://1c15f5fa-f434-401b-b4ec-ab3ea75d48bb/assist-api-gateway/.default',
                'grant_type': 'client_credentials',
            },
            timeout=30
        )
        response.raise_for_status()

        data = response.json()
        self.token = data['access_token']
        self.token_expires_at = datetime.now() + timedelta(
            seconds=data['expires_in']
        )

        return self.token

    def lookup_vehicle(self, vrm: str) -> Dict:
        """Look up vehicle details by registration number."""
        token = self.get_access_token()
        response = self.session.get(
            f'{self.base_url}/vehicle-lookup/{vrm}',
            headers={'Authorization': f'Bearer {token}'},
            timeout=30
        )
        response.raise_for_status()
        return response.json()

    def get_price_quote(self, quote_data: Dict) -> Dict:
        """Get insurance price quote."""
        token = self.get_access_token()
        response = self.session.post(
            f'{self.base_url}/priceQuote',
            headers={
                'Authorization': f'Bearer {token}',
                'Content-Type': 'application/json',
            },
            json={'data': quote_data},
            timeout=30
        )
        response.raise_for_status()
        return response.json()

    def lookup_eircode(self, eircode: str) -> Dict:
        """Look up address by eircode."""
        token = self.get_access_token()
        response = self.session.get(
            f'{self.base_url}/eircode-lookup/{eircode}',
            headers={'Authorization': f'Bearer {token}'},
            timeout=30
        )
        response.raise_for_status()
        return response.json()


# Usage
client = QuickPricingClient(
    os.environ['ASSIST_CLIENT_ID'],
    os.environ['ASSIST_CLIENT_SECRET']
)

# Lookup vehicle
vehicle = client.lookup_vehicle('12-D-12345')
print(f'Vehicle: {vehicle}')

# Get quote
quote = client.get_price_quote({
    'in_policy.dateInception': '2025-10-02T00:00:00+01:00',
    'in_customer.dateOfBirth': '1987-09-18',
    'in_dts.raterCover': 'Comprehensive',
})
print(f'Quote: {quote}')

# Lookup address
address = client.lookup_eircode('D02X285')
print(f'Address: {address}')

API Endpoints

1. Get Access Token

POST /auth/token
Content-Type: application/x-www-form-urlencoded

client_id=YOUR_CLIENT_ID&client_secret=YOUR_CLIENT_SECRET&scope=api://1c15f5fa-f434-401b-b4ec-ab3ea75d48bb/assist-api-gateway/.default&grant_type=client_credentials

Response:

{
  "access_token": "eyJ0eXAiOiJKV1QiLCJhbGc...",
  "token_type": "Bearer",
  "expires_in": 3599
}

Token Lifetime

Tokens expire after 1 hour. Cache and reuse tokens to avoid unnecessary authentication requests.

2. Price Quote API

Calculate insurance premium based on policy and customer data.

Request:

POST /priceQuote
Authorization: Bearer {access_token}
Content-Type: application/json

{
  "data": {
    "in_policy.dateInception": "2025-10-02T00:00:00+01:00",
    "in_customer.dateOfBirth": "1987-09-18",
    "in_dts.raterCover": "Comprehensive"
  }
}

Response:

{
  "rater.Comp.GrossPrem": 372.5,
  "rater.Comp.PolFee": 60.0,
  "rater.Comp.PremAfterPolFee": 426.0
}

Parameters:

Field	Type	Required	Description
in_policy.dateInception	string	Yes	Policy start date (ISO 8601 format)
in_customer.dateOfBirth	string	Yes	Customer date of birth (YYYY-MM-DD)
in_dts.raterCover	string	Yes	Cover type: Comprehensive, ThirdParty, or ThirdPartyFireAndTheft

Response Fields:

Field	Type	Description
rater.Comp.GrossPrem	number	Base premium amount before fees
rater.Comp.PolFee	number	Policy administration fee
rater.Comp.PremAfterPolFee	number	Total premium including fees

3. Vehicle Lookup API

Retrieve vehicle details using Vehicle Registration Mark (VRM).

Request:

GET /vehicle-lookup/{vrm}
Authorization: Bearer {access_token}

Example:

GET /vehicle-lookup/12-D-12345
Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGc...

Response:

{
  "vrm": "12-D-12345",
  "make": "Toyota",
  "model": "Corolla",
  "year": 2012,
  "engineSize": 1600,
  "fuelType": "Petrol"
}

VRM Format: Irish vehicle registration format: YY-C-NNNNN or YYY-C-NNNNN

• YY/YYY: Year digits
• C: County code (1-2 letters)
• NNNNN: Sequential number

4. Eircode Lookup API

Retrieve address information using Irish postal code (Eircode).

Request:

GET /eircode-lookup/{eircode}
Authorization: Bearer {access_token}

Example:

GET /eircode-lookup/D02X285
Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGc...

Response:

{
  "eircode": "D02X285",
  "addressLine1": "123 Main Street",
  "addressLine2": "",
  "town": "Dublin",
  "county": "Dublin",
  "country": "Ireland"
}

Eircode Format: 7-character alphanumeric code (e.g., D02X285)

Integration Workflow

Typical Quote Flow

sequenceDiagram
    participant C as Client App
    participant A as Assist API

    Note over C,A: Step 1: Authentication
    C->>A: POST /auth/token
    A->>C: access_token

    Note over C,A: Step 2: Vehicle Lookup
    C->>A: GET /vehicle-lookup/{vrm}
    A->>C: Vehicle details

    Note over C,A: Step 3: Address Validation
    C->>A: GET /eircode-lookup/{eircode}
    A->>C: Address details

    Note over C,A: Step 4: Price Quote
    C->>A: POST /priceQuote
    A->>C: Premium pricing

    Note over C: Present quote to customer

Recommended Implementation Steps

1. Initial Setup

   • Store API credentials securely
   • Implement token caching mechanism
   • Set up error handling and logging

2. Pre-Quote Data Collection

   • Use vehicle lookup to auto-populate vehicle details
   • Use eircode lookup to validate customer address
   • Reduce data entry errors

3. Quote Calculation

   • Gather all required customer and policy data
   • Call price quote API with complete information
   • Display pricing to customer

4. Error Handling

   • Implement retry logic for transient failures
   • Handle rate limiting (429 responses)
   • Log errors for debugging

Error Handling

Common Error Responses

401 Unauthorized

{
  "statusCode": 401,
  "message": "Unauthorized. Access token is missing or invalid."
}

Solution: Request a new access token.

404 Not Found

{
  "statusCode": 404,
  "message": "Vehicle not found"
}

Solution: Verify the VRM/Eircode format and try again. Some records may not exist in the database.

429 Rate Limit Exceeded

{
  "statusCode": 429,
  "message": "Rate limit exceeded"
}

Solution: Wait and retry with exponential backoff. Rate limit is 100 requests per minute.

Error Handling Best Practices

JavaScript

async function makeRequestWithRetry(requestFn, maxRetries = 3) {
  for (let attempt = 0; attempt <= maxRetries; attempt++) {
    try {
      const response = await requestFn();

      // Handle rate limiting
      if (response.status === 429) {
        if (attempt < maxRetries) {
          const delay = Math.pow(2, attempt) * 1000; // Exponential backoff
          console.log(`Rate limited. Retrying in ${delay}ms...`);
          await new Promise(resolve => setTimeout(resolve, delay));
          continue;
        }
        throw new Error('Rate limit exceeded - max retries reached');
      }

      // Handle auth errors
      if (response.status === 401) {
        // Clear cached token and retry once
        this.token = null;
        if (attempt === 0) continue;
        throw new Error('Authentication failed');
      }

      if (!response.ok) {
        throw new Error(`Request failed: ${response.statusText}`);
      }

      return response.json();

    } catch (error) {
      if (attempt === maxRetries) {
        throw error;
      }
      console.log(`Attempt ${attempt + 1} failed. Retrying...`);
    }
  }
}

Python

import time
from typing import Callable, Any

def make_request_with_retry(
    request_fn: Callable,
    max_retries: int = 3
) -> Any:
    """Make HTTP request with exponential backoff retry."""
    for attempt in range(max_retries + 1):
        try:
            response = request_fn()

            # Handle rate limiting
            if response.status_code == 429:
                if attempt < max_retries:
                    delay = (2 ** attempt)  # Exponential backoff
                    print(f'Rate limited. Retrying in {delay}s...')
                    time.sleep(delay)
                    continue
                raise Exception('Rate limit exceeded - max retries reached')

            # Handle auth errors
            if response.status_code == 401:
                # Clear cached token and retry once
                self.token = None
                if attempt == 0:
                    continue
                raise Exception('Authentication failed')

            response.raise_for_status()
            return response.json()

        except Exception as e:
            if attempt == max_retries:
                raise
            print(f'Attempt {attempt + 1} failed. Retrying...')

Testing

Test Checklist

• Authentication works and tokens are cached
• Vehicle lookup handles valid and invalid VRMs
• Eircode lookup handles valid and invalid codes
• Price quote calculation works with all cover types
• Rate limiting is handled gracefully
• Token expiry is handled automatically
• Errors are logged for debugging
• Retries work for transient failures

Sample Test Data

Valid Test Vehicle:

VRM: 12-D-12345
Expected: Toyota Corolla, 2012

Valid Test Eircode:

Eircode: D02X285
Expected: Dublin address

Test Quote Data:

{
  "in_policy.dateInception": "2025-10-02T00:00:00+01:00",
  "in_customer.dateOfBirth": "1987-09-18",
  "in_dts.raterCover": "Comprehensive"
}

Performance Optimization

Best Practices

1. Token Caching

   • Cache tokens for their full lifetime (1 hour)
   • Refresh automatically before expiry
   • Use a single token for all concurrent requests

2. Connection Pooling

   • Reuse HTTP connections
   • Configure appropriate timeout values
   • Use persistent sessions

3. Parallel Requests

   • Vehicle and eircode lookups can be done in parallel
   • Use Promise.all() or similar for concurrent requests

4. Caching Lookup Results

   • Cache vehicle lookup results by VRM
   • Cache eircode results by postal code
   • Implement appropriate TTL (e.g., 24 hours)

Support

Getting Help

• Technical Support: neil.reilly@assistinsurances.ie
• API Documentation: Full API Reference
• Authentication Guide: OAuth 2.0 Details

SLA and Service Status

• Uptime Target: 99.9%
• Support Hours: Monday-Friday, 9:00-17:00 IST
• Response Time: Within 4 business hours

Next Steps

• Authentication Guide - Deep dive into OAuth 2.0
• Error Handling - Comprehensive error handling patterns
• API Reference - Complete endpoint documentation
• Full Quote Lifecycle - Complete quote management workflow