API Import: REST API to Import Documents Only (V1.1)

Documentation related to importing transactions into the InsCipher portal (Updated on 12/7/2022)

Table Of Contents

  1. Introduction
  2. Authentication
  3. Document Import Request Endpoint
  4. JSON Request Sample
  5. Field Descriptions and Requirements
  6. Change History

 

Introduction

InsCipher has an API Endpoint available for your agency to programmatically import documents/forms that are affiliated with surplus lines tax policy transactions. This API solution is if you do not already import documents with your transactional detail using this method.

Most of our clients that have set this up, import batches daily into InsCipher. All batches imported, will be logged and tracked in InsCipher with a batch import ID number. This number also gets associated with individual transactions. InsCipher does have the ability to make certain documents required or optional, depending on your workflow and the state requirements. In addition, you can import ad-hoc documents or supporting documents, should you choose to do so. If you have questions about this process or want to get set up, please contact support@inscipher.com.

TIP: There are different methods or approaches to importing transactions using this REST API. If you need a quick solution to test out an import and do not currently have one, consider utilizing Postman. 

 

Authentication

A user is authenticated using a unique and encrypted API key and an "ID" number. 

API Key = XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX

Note: Your API Key can be reset at any time by the primary Filing Agency Admin logging into the InsCipher Connect portal. After logging in, go to "My Profile" by first clicking the arrow next to the user name in the top right corner. Afterward, click the button to “GET NEW API KEY”.

HTTP Method

POST     

Document Import Request Endpoint

There are two approaches to importing documents via API. You can either use an internal "invoice number" or use an InsCipher-generated transaction ID number.

IMPORTANT: It is important that you include the {id} and the API Key in the URL in order for the import to work correctly.

METHOD 1: Import by your internal "Invoice Number"

ENDPOINT:

https://surpluslines.inscipher.com/api/v4/transaction/{invoiceNumber}/document.json?useInvoiceNumber=1&apikey=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

  • Where the {invoiceNumber} =  the "invoice_number" in transaction.json or transaction details tracking tab.

METHOD 2: Import by InsCipher's assigned "Transaction ID" number

ENDPOINT: 
https://surpluslines.inscipher.com/api/v4/transaction/{id}/document.json?apikey=xxxxxxxxxxxxxxxxxxxx

  • Where {id} = InsCipher's generated Transaction ID number. If you aren't sure where to get this number, refer to the API import guide. There is a GET request for transaction status that will return this ID for you. Here is an example of this GET Request and the data you will get back.

Get Import results (HTTP method: GET)

https://surpluslines.inscipher.com/api/v4/transaction-import-results.json?apikey=xxxxx&batch_id=yyyyyy

Success Response

 {
"batch_id": "912a654e961bb083981145c344ca40c6",
"status": "processed",
"transactions": [
{
"id": "201909240000000001",
"policy_number": "CA20170228-05",
"transaction_id": 34859,
"status": 0,
"status_message": "Success"
}]
}

Note: If you choose this method, you will need to perform a status GET request for import results defined below. Sometimes it may take 20-30 minutes to retrieve the ID depending on the size of the batch you are trying to initially import.

Field Descriptions and Requirements

Field Title

Description

Field type

Optional

Required

code

This is an InsCipher-specific document import code that corresponds to a specific document folder in InsCipher. Document requirements can vary based on user type.

  • For InsCipher Connect software users, click here to view all document import codes and requirements.
  • For InsCipher Filing Services clients, click here to view all document import codes and requirements.

Note: if you want to upload ad-hoc documents, you would need to create your own custom code that doesn't already exist in InsCipher.

varchar (50)

 

name

A valid uploading file name with an extension

Example: "policy_85F-56565.pdf"

varchar (255)

 

file

The location of the file (how to retrieve it).

File content encoded to base 64 string. 

string

 


Change History

DATE DESCRIPTION OF CHANGE
12/7/2022 Added detail about importing either through invoice ID or by transaction ID
6/8/2022 New API - Added article