ACORD Standards Converter API (AL3, ACORD XML, ELabels)  

API Base URL: https://apis.winsurtech.com/al3/v2  

API Site URL: https://developer.winsurtech.com

Terms and Conditions: https://winsurtech.com/terms-and-conditions

SLA: https://winsurtech.com/winsurtech-rest-apis-service-level-agreement

Supported Lines of Business:

Personal Line Of Business (use these codes while creating the template)

Dwelling Fire- DFIREP

Homeowners- HOMEP

Inland Marine- INMARP

Mobile Home- MHOMEP

Watercraft- WATERCRAFTP

Automobile- AUTOP

Umbrella- UMBP

Flood (Personal or Commercial)- FLOODP

Personal Package- PKGP

Header Groups- HEADER_GROUPS

Commercial Line Of Business (use these codes while creating the template)

Direct Bill Commission - DBC

Business Automobile - AUTOC

Worker’s Compensation - WCC

Commercial General Liability - LIABC

Property - PROPC

Crime - CRIMEC

Inland Marine - INMARC

Garage & Dealers- GARAGEC

Umbrella - UMBC

Commercial Package- PKGC

Business Owner’s Policy (BOP)-BOPC

Commercial Package with BOP- PKGC_BOPC

Agriculture/Farm Package- AGRIC

  • Agriculture/Farm Property- AGPR
  • Agriculture/Farm Scheduled & Unscheduled Personal Property- AGPP
  • Agriculture/Farm Liability- AGLIA
  • Commercial General Liability - LIABC
  • Business Automobile - AUTOC
  • Umbrella - UMBC
  • Inland Marine - INMARC
  • Homeowners- HOMEP

Boiler & Machinery- BMC

Header Groups- HEADER_GROUPS

Introduction

WinsurTech AL3 API  makes it very easy to accomplish the following:

  1. Download Files from IVANS mailbox
  2. Convert AL3 files to JSON/CSV
  3. Create AL3 files from CSV templates
  4. Extract data and attachememnts from Claim Files

The API endpoints work for both Policy Transaction files and Direct Bill Commission Files. In addition, there are endpoints to fetch all the valid values (according to ACORD) for code lists and map NAIC code to the Carrier.

Download Files from IVANS mailbox set of endpoints allow you to login to IVANS with your mailbox credentials (IVANS Secret Key, IVANS Client Id, Mailbox Account Name, Mailbox User Id, Mailbox Password). After login, you can fetch the information of all the files available in your mailbox account and then fetch each available file from the mailbox.

AL3 to JSON/CSV Endpoints make it very easy to extract different types of Policy data and Direct Bill Commission data from the AL3 file.

An AL3 file can contain various types of information, like:

  • Transaction Information
  • Insured Information
  • Basic Policy Information
  • What is covered (location and covered items)
  • Coverages, limits, deductibles, options, etc
  • Additional interests, their types, related amounts
  • Other and Prior Policy Information
  • Forms, Remarks, and Attachments
  • Carrier Questions
  • Claim History and Violations
  • Commission Summary and Details

Using the set of endpoints available in our API, you can extract each of the above information one by one as required.

In addition, for Direct Bill commission files you can extract:

  • Commission Summary Data
  • Commission Details Data

Convert CSV to ACORD AL3 Endpoints take a CSV file as an input and convert it to an ACORD AL3 file or DAT file.   There is one endpoint to generate a CSV template for different lines of business and another endpoint to convert this template to an AL3 file. All you have to do is fill available values in the “Value” column and upload the CSV back into our AL3 Creation endpoint to create the AL3 file. No need to fill values for the rows not applicable in your case.

There are Code list endpoints and Carrier Name endpoints to help you further during the process of preparing the CSV.

Code List Names endpoint generates all the code list names as a response and contains al3_reference_id along with a description. You can copy the reference id from here and paste that to the Code List Values endpoint and use the required code from the output to add it to the Value column in the CSV Template for the AL3 file.

The Carrier Details endpoint will help you to get the information of the Carrier. The generated output contains the Carrier Name and NAIC Code for the carrier that matches the substring entered.

 

Claims/ACORD XML to Elabels Endpoints make it feasible to extract data from Claim downloads in JSON format where eLabels are JSON keys, and also to extract images and documents embedded inside the Claim files. Claim files are also downloaded from your IVANS mailbox.

How to view AL3 file contents on UI?

To view the AL3 files on screen, you can use WinsurTech  AL3 Viewer or WinsurTech  Web Viewer.

Links:

WinsurTech AL3 Viewer: https://winsurtech.com/al3-desktop-viewer

WinsurTech  Web Viewer: https://products.winsurtech.com

Some important points:

  1. AL3 / DAT files are created by Carriers and they may have any extension although the most common extensions are .DAT and .AL3. Sometimes the files      may have extensions like .001, .002, etc or even .ZIP. Our API examines each file irrespective of its extension.
  2. AL3 format is ACORD’s proprietary format to pack Policy and Direct Bill commission data into this format and the files are sent from Carriers to their      agencies (mostly view IVANS).
  3. Although Claim Download files also have .DAT or .AL3 extension but these files are in ACORD XML format not in AL3 format. Claim data is parsed by a      separate product of ours. Contact us at contact@winsurtech.com  for that.
  4. AL3 files for Policies can contain a variable amount of data. Some files contain only a single policy but some files can contain a large number of policies.      Each policy in an AL3 file can be of a different line of business.
  5. Most of the AL3 files are in KBs in their size, not in MBs. But “initial load” files from IVANS can be larger, like 2 MB or more. Our main /conversion      endpoint can convert max up to 1 MB sized AL3 file. For a larger file use our / callBack-conversion endpoint.
  6. Files with 10 to 200 KB size can be converted in less than 5 seconds but files that are 200+Kb and up to 1 Mb can take anywhere between 5 seconds to      40 seconds for conversion depending on the exact file size and traffic.
  7. / callBack-conversion  is not a real-time endpoint. It converts the data in the background and POSTS the response back to the CALLBACK URL you      provide of your own application. Make sure the URL works, is open for the external traffic and you have written the code to receive JSON and process that.
  8. / callBack-conversion  can be used with any sized file. There are no restrictions related to file size in it.
  9. To make it easy to extract data of specific nature like Additional Interests, Coverages, What is Covered, etc, we provide per-policy  endpoints. We call  them per-policy because you can use these endpoints to get data of a single policy from the AL3 file based on the policy number, although you can make  use of per-policy endpoints to fetch data of multiple policies also that match different types of criteria - like all policies having the same transaction type, all    policies having the same line of business, etc.
  10. We store JSON output for a 2 hour period so as to serve per-policy endpoints. We do not store any AL3 files on our server. The JSON data is removed   after a 2 hour period and the transaction id expires after this.
  11. You need the User Secret  to call the API endpoints. Check the steps given below to find your User Secret.

Key points about “per-policy” endpoints:

  1. Always call /al3/conversion endpoint before calling the “per-policy” endpoints
  2. Per-policy endpoints are not applicable to the Direct Bill Commission AL3 files ( /al3/conversion endpoint is applicable in this case which will give you the  entire output or DB Commission Endpoints which will give you commission summary and commission details).
  3. “Transaction_id” that you got in response to the /conversion  endpoint is always required for calling any per-policy endpoint
  4. From the other 3 parameters (transaction type, policy number, LOB type) the output will depend on what parameter values are passed.
  1. When none of the three parameters is passed, then it will return data corresponding to the endpoint for all the policies included in the AL3 file.
  2. When the only lob_type is passed, it will return the data for all the policies that have the matching LOB type.
  3. When the only transaction_type is passed, it will return the data for all the policies that have the matching Transaction type.
  4. When only policy number is passed, it will return the data for the policy that has the matching Policy Number
  5. If multiple parameter values are passed, then it will return the data for all the policies that match all the passed parameter values.

How to download postman collection and reset User Secret Key


  • Import this collection to Postman. The secret key is automatically included in the postman collection.
  • To reset your secret key click on Click to reset


**Click over the eye icon to view the secret key, you will need this key to call the Endpoints**

  • Update this key in postman under the authorization tab.


  1. Download Files from IVANS mailbox

Description

These endpoints allow you to login to IVANS with your mailbox credentials and fetch the information of all the files available in your mailbox account and then fetch each available file from the mailbox one by one. Both policy transaction files and direct bill commission files can be downloaded and fetched.

Endpoint Information

User Authentication:  Each Endpoint needs USER_SECRET parameter in the HEADER while making the request

IVANS login

Request Method: POST
Endpoint: BaseURL /ivans/login

Description

This endpoint allows you to login to IVANS with your mailbox credentials. You need to provide IVANS Secret Key, IVANS Client Id, Mailbox Account Name, Mailbox User Id, Mailbox Password. By providing these details, an access_token  is generated which is used to pull files and their content from the mailbox.

Input Parameters

Key (Body Parameter)

Value

mailbox_account

Example: XX88B

mailbox_user_id

Example: AB112YZ

mailbox_password

Example: Summer2010!

ivans_api_client_id

Example: 11AB1234-2345-12D2-A235-2AC05A12B345

ivans_api_client_secret

Example: 1233d254f-6e98-2df2-aa62-jc1234a2b121

In the Body Parameters (all required):

  • mailbox_account: User mailbox account provided by IVANS
  • mailbox_user_id: User mailbox user id provided by IVANS
  • mailbox_password: User mailbox password provided by IVANS
  • ivans_api_client_id: User API client id provided by IVANS
  • ivans_api_client_secret: User API client secret key provided by IVANS

Postman Screenshot


Copy this access token in the pre-request script and using this you can pull files and file content from the other two endpoints.

Pull Files Information

Request Method: GET
Endpoint: BaseURL /ivans/pull-files-info

Description

This endpoint is used to get information about all the files available in the IVANS mailbox. Information of the available files is returned with details like file id, original name, remote name, status date, etc. File id returned here is used to call the next endpoint to fetch the file.

Input Parameters

Key (Params Parameter)

Value

mailbox_account

Example: XX99A

mailbox_user_id

Example: AB111XY

Postman Screenshot


Pull File Content

Request Method: GET
Endpoint: BaseURL /ivans/pull-file

Description

This endpoint is used to download a particular file by providing its file_id received in the output of pull-files-info endpoint.

In mark_as_received ,enter the value as true if you want to mark the file as received and not to show in file_info list of "Pull Files Information" endpoint in future. The default value is assumed to be false.

Input Parameters

Key (Params Parameter)

Value

file_id

Example: 3374be83-c57f-4b97-b4c6-16fde72f6e6f

mark_as_received

Example: false


Postman Screenshot


  • The file content is returned back in the output.
  • Save the file_content within " " to a notepad file on your disk with .al3 or .dat extension.
  • The Al3 file created can now be viewed in any AL3 viewer, links to our AL3 viewers are below:

WinsurTech AL3 Viewer: https://winsurtech.com/al3-desktop-viewer

WinsurTech  Web Viewer: https://products.winsurtech.com


  1. Convert AL3 files to JSON/CSV

With AL3 to JSON/AMS_MAP/CSV API endpoints, we make it very easy to extract different types of Policy and Direct Bill Commission data from the AL3 file.

Endpoint Information

AL3 to JSON endpoints are comprised of three sets that are discussed below:

  1. Conversion & Policy Transaction Endpoints
  2. Per-Policy Information Endpoints
  3. DB Commission Endpoints

User Authentication:  Each Endpoint needs the USER_SECRET parameter in the HEADER while making the request

The suggested flow for Policy transaction files is this:

  1. Conversion - To convert al3 to JSON/AMS_MAP as well as CSV file with Zip extension and get the transaction id back in case of   JSON/AMS_MAP.
  2. Transaction Summary - To get the summary of all the transactions contained within the AL3 file based on the transaction id obtained   through Conversion API.
  3. Per Policy Endpoints - Using the output of Transaction Summary Endpoint call these per-policy endpoints to fetch policy specific data.

The suggested flow for DB Commission files is this:

  1. Conversion - To convert al3 to JSON/AMS_MAP and get the transaction id back.
  2. DB Commission endpoints- To see the summary and details of DB Commission files.

Conversion & Policy Transaction Endpoints

AL3 to JSON/CSV Conversion

Request Method: POST
Endpoint: BaseURL /conversion

Description

This is the main endpoint that converts AL3 to JSON. This must be called before calling other endpoints. This call gives you a unique transaction id for your request that you need for the subsequent calls. It also gives you the entire JSON output together and you can use it if you do not prefer to call subsequent endpoints. After making this call, note down the transaction id you get back in the JSON output and use that to call the per-policy endpoints to extract specific pieces of information. Note that per-policy calls are supported only for Policy Transaction AL3 files.
For package policies where multiple LOBs are packed within the same AL3 file, the output in CSV format is a zip file where each CSV has data of one sub-policy contained within the package.


Input Parameters for Al3 to CSV conversion

Key (Body Parameter)

Value

input_file

example: AUTOP_4_masked.al3

output_format

CSV/ams_map/JSON

omit_blank_values

false/true

  • In the Body Parameter input_file: Upload the AL3 file you want to convert.
  • In output_format: Enter the format you want the al3 to convert to i.e CSV, ams_map or JSON.
  • In omit_blank_values: Enter the value as true if you want to omit the blank values from the output else enter false . The default value is assumed to be true .

Postman Screenshot

Sample Output

 

Policy Transaction Summary

Request Method: POST
Endpoint: BaseURL /all-transaction-summary
**Use this API endpoint only for Policy Transaction AL3 files, not for Direct Bill Commission files. Before calling this API call the /al3/conversion API only then it will work**

Description
This endpoint is to fetch the summary of all the policy transactions contained within the AL3 file which you just converted. From “summary“ the meaning is, only the following parameters for each policy transaction will be returned in the JSON output:

  • Policy Number
  • LOB type
  • Transaction Type

Input Parameters

Key (Body Parameter)

Value

transaction_id

Transaction id value from conversion endpoint output

eg: 81881af4-3199-4b3a-bad2-4367aabf6c5f

Sample Output

 

Callback Conversion

Request Method: POST
Endpoint: BaseURL /callBack-conversion

Description

To convert files greater than 1MB, this endpoint is used. It is not a real-time endpoint. It converts the data in the background and POSTS the response back to the CALLBACK URL you provide of your own application. Make sure the URL works, is open for the external traffic and you have written the code to receive JSON and process that.

Input Parameters

Key (Body Parameter)

Value

input_file

example: MHOME.al3

output_format

ams_map/JSON

callback_url

https://yourwebsite.com/AL3JSONHandler

omit_blank_values

true/false

  • In the Body Parameter input_file: Upload the AL3 file you want to convert
  • In output_format: Enter the format you want the al3 to convert to i.e ams_map or JSON.
  • In callback_url: Enter the URL hosted on your server where you want the output to be posted back.
  • In omit_blank_values: Enter the value as true if you want to omit the blank values from the output else enter false . The default value is      assumed to be true .

Postman Screenshot

Per-Policy Endpoints

Using the transaction id obtained in the output of the Conversion API call, and the transaction summary parameters, call any endpoint in this group in any order to fetch the specific details.

**Note that our server does not store the AL3 file and the JSON output is retained only for 2 hours duration. After that transaction id expires and you need to call the conversion API again to convert the file again**

From the Transaction Summary API, you will get the following parameters for each transaction contained in the AL3 file:

  • Policy Number
  • LOB type
  • Transaction Type

For the per-policy API endpoints, use a combination of these 3 parameters as required. The output will depend on what parameter values are passed.

  • When none of three parameters is passed, then it will return data corresponding to the endpoint for all the policies included in the AL3 file
  • When only lob_type is passed, it will return the data for all the policies that have the matching LOB type
  • When only transaction_type is passed, it will return the data for all the policies that have the matching Transaction type
  • When only a policy number is passed, it will return the data for the policy that has the matching Policy Number.

If multiple parameter values are passed, then it will return the data for all the policies that match all the passed parameter value

**Use these API endpoints only for Policy Transaction AL3 files, not for Direct Bill Commission files. Before calling this API call the /al3/conversion API only then it will work**

Input Parameters:  

Input Parameters remain the same for every per-policy endpoint hence mentioned only once here.

Parameter Name

Data Type

Is Mandatory

Description

transaction_id

text

true

Use the transaction id returned by the conversion API

lob_type

text

false

Enter the valid lob_type. You can use any Lob_type value returned by the Policy transaction Summary API output.

policy_Number

text

false

Enter the valid policy number. You can use any policy_number returned by the Policy transaction Summary API output.

transaction_type

text

false

Enter the valid transaction_type. You can use any transaction_type returned by the Policy transaction Summary API output.

omit_blank_values

boolean

false

true or false


Note- if for conversion endpoint you passed
omit_blank_values: true

Then the output of per policy endpoint will not be affected.

flatten

boolean

false

true or false


Note- if for conversion endpoint you passed
flatten: false

Then the output of per policy endpoint will not be affected.

Insured Details

Request Method: POST
EndPoint: BaseURL /per-policy/insured

Description
This endpoint is to retrieve the Insured data contained within the AL3 file, like Insured Name, Address, Country Name, City Name, Insured's Date of Birth, etc.


Postman Screenshot for Insured Details

Sample Output

 

Policy Summary

Request Method: POST
Endpoint: BaseURL /per-policy/current-policy

Description
This endpoint is to fetch Policy summary data contained within the AL3 file. Policy summary comprises the details like Policy Number, Policy Effective Date, Policy Expiration Date, Carrier NAIC Code, etc.

Sample Output

 

Covered Items with Locations

Request Method: POST
Endpoint: BaseURL /per-policy/location-covered-items

Description:
This endpoint is to retrieve all the details of Covered items (Risks) along with their locations contained within the AL3 file. The details include Location Number, State/Province Code, Zip Code, Covered item’s Type, Model, Description, Construction Year, Year of Occupancy, etc.

Sample Output

 

Coverages

Request Method: POST
Endpoint:
BaseURL /per-policy/coverage

Description
This endpoint is to retrieve the data of coverages, limits, deductibles, options, etc. contained within the AL3 file. The data in it includes Coverage Code, Full Term Premium, Limit Amount, Liabilities, etc

Sample Output

 

Additional Interests

Request Method: POST
Endpoint: BaseURL /per-policy/additional-interests

Description
This endpoint is used to retrieve the data of additional interests and their types contained within the AL3 file. The details in it comprises Additional Interest Name, Address, Zip Code, Nature of Interest Code, etc.

Sample Output

 

Remarks and Attachments

Request Method: POST
Endpoint: BaseURL /per-policy/remarks-and-attachments

Description
This endpoint is to fetch the data of available remarks and names of the attachments (if any) contained within the AL3 file. The details in it will be like Remark Number, Remark Text, Attachment Type Code, Attachment Description.


Sample Output

 

Forms

Request Method: POST
Endpoint: BaseURL /per-policy/forms

Description
This endpoint is to retrieve the data of all the related forms contained within the AL3 file. The form data includes the details like Form Name, Form Number, Form Edition Date, etc.

Sample Output

 

Carrier Questions

Request Method: POST
Endpoint: BaseURL /per-policy/general

Description
This endpoint is to retrieve data of the questionnaire (carrier questions) contained within the AL3 file.

Sample Output

 

Claim History and Violations

Request Method: POST
Endpoint: BaseURL /per-policy/claim-history

Description
This endpoint is to retrieve the history of all the previous claims and violations contained within the AL3 file. The data includes Loss Date, Loss Type, Loss Description, Claim Settled Indicator, etc.

Sample Output

 

Prior Policy Information

Request Method: POST
Endpoint: BaseURL /per-policy/prior-policy

Description
This endpoint is to retrieve the data of Prior policy contained within the AL3 file. Here the Prior policy means, if a policy existed before the current policy then this endpoint will give the details accordingly. The details in it will be like Line of Business of Prior Policy, Policy Number, Carrier Name, Policy Expiration Date, etc.

Sample Output

 

Other Policy Information

Request Method: POST
Endpoint: BaseURL /per-policy/other-policy

Description
This endpoint is to retrieve the data of other policies contained within the AL3 file. Here the other policy means, if Insured is having one or more policies from the same or any other company then this endpoint will give the details accordingly. For example Other Policy Number, Line of Business, Carrier Name, etc.

Sample Output

 

Commission Summary

Request Method: POST
Endpoint: BaseURL /commission-summary

Description

This endpoint is to retrieve the data of the Commissionary Summary contained within the DBC AL3 file. For example Total Gross Amount, Total Commission Amount, Total number of items/policies, Agency Contract Number, etc.

Sample Output

 

Commission Details

Request Method: POST
Endpoint: BaseURL /commission-details

Description

This endpoint is to retrieve the data of the Commissionary Details contained within the AL3 file. For example Policy Number, Commission Rate, Commission Amount, Policy Binder Number,  etc.

Sample Output

 

  1. Convert CSV to ACORD AL3

Description

CSV to ACORD AL3 or DAT File Conversion takes a CSV file as input and converts it to an ACORD AL3 file. There is an endpoint to get the CSV format for different lines of business. Fill data in the CSV and upload it back to create the AL3 file. One CSV template can also contain data of multiple transactions but not of different LOBs. For packing multiple transactions of more than one LOB in the same AL3 file, upload a zip file containing all the CSV files packed in this ZIP. You can also optionally upload a HEADER file that contains the header groups only which are needed only once even if you pack multiple transactions in the same AL3 file. For generating the template (CSV file) for the HEADER groups use the LOB = HEADER_GROUPS with the Generate CSV Template API. You can add the coded values to the CSV file as input by using Code List Names and Code List Values API calls. NAIC Codes of carriers and their names can be retrieved by using Carrier Search API.

AL3 Creation Process is comprised of two steps:

  1. Template Generation & AL3 Creation:  By using the endpoint (Template Generation) available in this collection you can get the CSV    template for the Line of Business relevant to your Policy Transaction (or for DB Commission). Each CSV template contains one row per  element (like for Policy Number, Effective Date, etc). Templates are available in a shorter & simpler format of important elements only, as well  as in FULL format (which means all the possible elements for the LOB are shown in the template). You can also specify the count of  transactions for the passed LOB while generating the template (by default it is 1).

  1. Create AL3 File:  Add values in the template that you have against the matching rows in the template. If you have fewer data fill only that  and leave the other rows blank. Then upload the data-filled CSV to AL3 Creation endpoint and the resulting AL3 file comes back in the  output.Your programmer can easily access the AL3 content in the JSON response and save it into a file with the extension of .AL3 or .DAT. If  you test the API in Postman you can manually copy and paste the content (excluding double quotes) into notepad and save it with .AL3 or .DAT  file extension to test.

Supported Lines of Business:

Personal Line Of Business (use these codes while creating the template)

Dwelling Fire- DFIREP

Homeowners- HOMEP

Inland Marine- INMARP

Mobile Home- MHOMEP

Watercraft- WATERCRAFTP

Automobile- AUTOP

Umbrella- UMBP

Flood (Personal or Commercial)- FLOODP

Personal Package- PKGP

Header Groups- HEADER_GROUPS

Commercial Line Of Business (use these codes while creating the template)

Direct Bill Commission - DBC

Business Automobile - AUTOC

Worker’s Compensation - WCC

Commercial General Liability - LIABC

Property - PROPC

Crime - CRIMEC

Inland Marine - INMARC

Garage & Dealers- GARAGEC

Umbrella - UMBC

Commercial Package- PKGC

Business Owner’s Policy (BOP)-BOPC

Commercial Package with BOP- PKGC_BOPC

Agriculture/Farm Package- AGRIC

  • Agriculture/Farm Property- AGPR
  • Agriculture/Farm Scheduled & Unscheduled Personal Property- AGPP
  • Agriculture/Farm Liability- AGLIA
  • Commercial General Liability - LIABC
  • Business Automobile - AUTOC
  • Umbrella - UMBC
  • Inland Marine - INMARC
  • Homeowners- HOMEP

Boiler & Machinery- BMC

Header Groups- HEADER_GROUPS

Endpoint Information

User Authentication:  Each Endpoint needs the USER_SECRET parameter in the HEADER while making the request

Template Generation & AL3 Creation

Generate CSV Template

Request Method: GET
Endpoint:  BaseURL /template

Description

This endpoint helps you to get the Template for the Line of Business you want. For e.g. if you have to create an AL3 file for Personal Homeowners (HOMEP) transactions the pass HOME P  in the LOB parameter. By default, CSV is generated for a single transaction, but you can pass any value for the Transaction Count input variable (max 50 for generating the template although you can manually extend the template file contents if you need more no. of transactions in the same AL3 file. Alternatively, you can create multiple copies of the same template file and pack all in a zip file to put all the transactions in the same AL3).

By default, full_format is set to false which gives a shorter and simpler template of the most common elements for each LOB. If you want the full format, pass full_format= yes. The AL3 file also contains some Header Groups which surround the actual data. If you are not comfortable with the AL3 structure then keep the header_groups parameter to blank or false as our code can automatically add the header groups & elements with blank values. If you want to set data in header group elements also then pass header_groups=true and it will work only if full_format is set to true. A better way to specify the header is to generate the header groups template separately with Templates API using LOB = HEADER_GROUPS as input for the LOB parameter. This single header file can be uploaded as input to the AL3 Creation API endpoint for the input_header_file parameter. header_groups=true is useful only when full_format is set to true and it is the case of a single CSV file upload to create the AL3 file. In the case of ZIP upload, a separate header file is always required (header elements from inside the data file are ignored in this case, a separate file is always expected).

Line of Business codes:

Personal Line Of Business (use these codes while creating the template)

Dwelling Fire- DFIREP

Homeowners- HOMEP

Inland Marine- INMARP

Mobile Home- MHOMEP

Watercraft- WATERCRAFTP

Automobile- AUTOP

Umbrella- UMBP

Flood (Personal or Commercial)- FLOODP

Personal Package- PKGP

Header Groups- HEADER_GROUPS

Commercial Line Of Business (use these codes while creating the template)

Direct Bill Commission - DBC

Business Automobile - AUTOC

Worker’s Compensation - WCC

Commercial General Liability - LIABC

Property - PROPC

Crime - CRIMEC

Inland Marine - INMARC

Garage & Dealers- GARAGEC

Umbrella - UMBC

Commercial Package- PKGC

Business Owner’s Policy (BOP)-BOPC

Commercial Package with BOP- PKGC_BOPC

Agriculture/Farm Package- AGRIC

  • Agriculture/Farm Property- AGPR
  • Agriculture/Farm Scheduled & Unscheduled Personal Property- AGPP
  • Agriculture/Farm Liability- AGLIA
  • Commercial General Liability - LIABC
  • Business Automobile - AUTOC
  • Umbrella - UMBC
  • Inland Marine - INMARC
  • Homeowners- HOMEP

Boiler & Machinery- BMC

Header Groups- HEADER_GROUPS

Input Parameters

Parameter Name

Data type

Is Mandatory

Description

LOB

text

true

Input the Line of Business Code to generate a template.

transaction_count

text

false

No. of transactions required in a single Al3 file.

header_groups

text

false

If passed true, it will add the header group elements also to the generated template.

full_format

text

false

If passed true, the full format of the template will be generated, i.e. a template including all the possible AL3 elements for the passed LOB.

  • By default, transaction_count is set to 1. You can add a value of upto 50.
  • By default, header_groups is false (No).

**header_groups parameter will only work for full format template**

  • By default, full_format  is false (No).

Sample Output


  • In the above screenshot, the CSV template is generated for the Personal Homeowners Line of Business (HOMEP) with 2 transactions.
  • In postman, save this response by clicking on Save Response  → Save to a file   and save it to your disk with .csv extension or .zip  extension in case of package policies.
  • Add values to the CSV template and save it. This file can be uploaded in the next endpoint “Create Al3 File” to create an Al3 File.

Create AL3 File

Request Method: POST
Endpoint: BaseURL /creation

Description

Fill data in the template generated from our Generate API Template endpoint call (fill whatever data you have and leave the rest of it blank. Don’t change the template columns but you can remove the rows you do not need. Note that all the mandatory fields are auto-filled with question marks at AL3 generation time according to the width of the element, but if you want to explicitly keep the field value blank then type {Blank}  in the CSV cell for it. One CSV template can also contain data of multiple transactions but not of different LOBs. For packing multiple transactions of different LOBs in the same AL3 file, upload a zip file containing all the CSV files packed in this ZIP. You can also optionally upload a HEADER file that contains the header groups which are needed only once even if you pack multiple transactions in the same AL3 file.

Upload the data-filled CSV file to this API endpoint and save the response with the .al3 extension, thus creating the al3 file. The resulting AL3 file comes back in the output. Your programmer can easily access the AL3 content in the JSON response and save it into a file with the extension of .AL3 or .DAT. If you test the API over Postman you can manually copy and paste the output (excluding " ") into notepad and save it with .AL3 or .DAT file extension to test.

Input Parameters

Parameter Name

Data type

Is Mandatory

Description

input_file

binary

true

.csv file or .zip file that needs to be converted.

input_header_file

binary

false

.csv header file.

contains_pkg_or_bopc

text

false

Enter 'yes' if the uploaded zip file is either a Package file or a Business Owner's file.

Sample Output:

  • Here the HOMEP Template.csv is given as an input file and the data in the file is converted to an AL3 file.
  • Save the output within “ “ to a notepad file on your disk with .al3 or .dat extension.
  • The Al3 file created can now be viewed in any AL3 viewer, links to our AL3 viewers are mentioned above in the document.

Code List Names & Values

Code List Names

Request Method: GET
Endpoint: BaseURL /code-list-names

Description

This API call will generate all the code list names, the response contains al3_reference_id along with a description. You can copy the reference id from here and paste that to the next API (Code List Values).

Sample Output

Code List Values

Request Method: GET
Endpoint: BaseURL /code-list-values

Description

This API call will generate all the code list values under the specific reference id (code list name) that you have entered and you can use the required code from the output to add it to the Value column in the CSV Template for the AL3 file. Also, the value "null" is not a code value, it only depicts that the value can be left blank if needed.

Input Parameters

Parameter Name

Data type

Is Mandatory

Description

reference_id

text

true

Use the valid reference id (code list name) to get all the related code list values under that code list name.

Sample Output

Here “CBPUR” is passed as input and all the codes that can be used are returned.

Carrier Details

Carrier Information

Request Method: GET
Endpoint: BaseURL /carrier-search

Description:
This endpoint will help you to get the information of the Carrier. The generated output contains the Carrier Name and NAIC Code for the carrier that matches the substring entered.

Sample Output

  • Here the information of all the carriers matching the substring “123” is returned as an output.


  1. Convert Claims/ACORD XML to Elabels

Conversion to elabels

Request Method: POST
Endpoint: BaseURL /acord-xml/conversion-to-elabels

Description

This endpoint is used to convert Claims/ACORD XML file to ACORD Form Elabels/json output and also provide a unique attachment_id for attachments present in Claims/ACORD XML file. These attachment_id can be further used to fetch attachment files using the Pull Attachment endpoint.

Input Parameters

Key (Body Parameter)

Value

input_file

Example: xyz.dat

    In the Body Parameters (all required):
  • Input_file: A valid Claims/ACORD XML file.

Sample JSON for ActivityNoteRs file:

 

Sample JSON for AlertDownloadRs file:

 

Sample JSON for ClaimDownloadRs file:

 

Pull Attachment

Request Method: GET
Endpoint: BaseURL /acord-xml/attachment

Description

This endpoint is used to extract a particular attachment file from a Claims/ACORD XML file using the unique attachment_id received in the output. The attachment is saved in a zip format.

Input Parameters

Key (Body Parameter)

Value

transaction_id

Example: 1aa4a459-050b-4126-90f6-333bc507f30a

attachment_id

Example: 8971fea0-e4ac-4c54-9bc6-5b926dc9c2b

delete_after_fetch

Example: true

    In the Body Parameters::
  • transaction_id (required): Transaction id getting from “Conversion to elabel” api endpoint in elabel json output.
  • attachment_id (required): Attachment id getting from “Conversion to elabel” api endpoint in elabel json output.
  • delete_after_fetch (optional): True, if you want to download the attachment only once.

  1. API Quota Updation

    1. Download Files from IVANS mailbox

      For all the endpoints, the quota is increased by 1.

    2. Convert AL3 files to JSON/CSV

      These endpoints also count the number of policies in each file that is uploaded. For example: If you convert an AL3 file with 10 policies, 10 will be added to your previously used quota after you make the call.

      This calculation is done for all the endpoints, i.e Conversion & Policy Transaction Endpoints, Per-Policy Endpoints and DB Commission Endpoints.

    3. Convert CSV to ACORD AL3

      Here, we only add your quota for Create AL3 File Endpoint. This endpoint counts the number of Policies (Transactions) that are converted in a single AL3 file. The quota is updated only for a successful conversion. If there are errors in your file, quota is not updated.

      For example: If you convert a file with 10 policies (transactions), 10 will be added to your previously used quota after you convert the file to AL3.

    4. Convert Claims/ACORD XML to Elabels

      For Conversion to elabels Endpoint, the quota is increased by the number of attachments in a file + 1.

      For Pull Attachment Endpoint, the quota is updated by 1 for every call.


  2. To check your used limit go to Subscriptions