← Back

Integration Instruction for Purchase:
Marine Import Insurance — Basic cover / ICC C

All requests under this integration are sent to a specific endpoint, which is https://a4004.mngr.imas.octamile.com:62004. The protocol used to communicate with our All-In-One Insurance Mangement Solution is HTTP. All requests should use the HTTP POST method.

The rest of this page would demonstrate the purchase of 'Marine Import Insurance — Basic cover / ICC C', for an imaginary customer by the name Folake Arinze.

Sections

• Request 1: Get Premium to Charge The Consumer →

• Request 2: Register the Consumer →

• Request 3: Request an Insurance Policy →

• Request 4: Fetch Policy Request Approval Status →

Request 1: Get Premium to Charge The Consumer

The first step in selling insurance to a consumer, is knowing and charging the appropriate premium.

Do not ask our API for an insurance policy, unless you have already collected the appropriate premium from the consumer.

This section shows how to get the appropriate premium to charge the consumer for this product.

For specified cargo:

{ "userInfo": { "id" : "--PUT THE CUSTOMER ID WE ASSIGNED YOU HERE--", "athrzt" : { "id" : "--PUT YOUR AUTHORIZATION ID HERE--", "key": "--PUT YOUR AUTHORIZATION KEY HERE--" } }, "cmmnd": { "cmmnd": "dump ipck_mrnn-stnd-1111*PRMM", "seed" : { "cargoType" : "gnrl" , "originPort": "--PUT THE ORIGIN PORT'S COUNTRY OR REGION HERE--", "proformaInvoiceValue": "--PUT THE VALUES OF THE PROFORMA INVOICE HERE--", "DstntnCountry" : "--PUT THE DESTINATION COUNTRY HERE--", "insrncDrtn": "--PUT THE PREFERED COVER PERIOD HERE--" } } }

Customer ID This must have been given to you. If it has not, speak to our engineering team

Authorization This must have been given to you. If it has not, speak to our engineering team

Origin Port This is the origin port's country or region. If you would like to specify the country, specify the ISO Alpha-3 country code of the country, e.g. NGA for Nigeria, USA for United States, etc. If you would like to specify the region, possible values are:
ucnd — USA & Canada
csam — Central & South America
afrc — Africa
safr — South Africa
fest — Far East
erpp — Europe
iapn — India & Arabian Pennisula
anzl — Australia & New Zealand

Proforma Invoice Value (proformaInvoiceValue) This data should be the value of the proforma invoice. Specify NGN for the Nigerian Naira, GHS for the Ghanaian Cedi, USD for the United States Dollar, or GBP for the Great Britain Pound. Special characters not allowed

Cover Period — insrncDrtn See this product's profile for possible cover periods. Format: 7d for 7 days, 1m for 1 month, 1y for 1 year, etc

See examples below:

{ "userInfo": { "id" : "--PUT THE CUSTOMER ID WE ASSIGNED YOU HERE--", "athrzt" : { "id" : "--PUT YOUR AUTHORIZATION ID HERE--", "key": "--PUT YOUR AUTHORIZATION KEY HERE--" } }, "cmmnd": { "cmmnd": "dump ipck_mrnn-stnd-1111*PRMM", "seed" : { "cargoType" : "spcf", "cargoDscrptn": "--PUT THE CARGO'S DESCRIPTION HERE--", "proformaInvoiceValue": "--PUT THE VALUES OF THE PROFORMA INVOICE HERE--", "DstntnCountry" : "--PUT THE DESTINATION COUNTRY HERE--", "insrncDrtn": "--PUT THE PREFERED COVER PERIOD HERE--" } } }

For general cargo:

{ "userInfo": { "id" : "1234567890abcdef", "athrzt" : { "id" : "1234567890abcdef", "key": "^]L*ug^S-ZxQQU.}" } }, "cmmnd": { "cmmnd": "dump ipck_mrnn-stnd-1111*PRMM", "seed" : { "cargoType" : "gnrl", "originPort": "ucnd", "proformaInvoiceValue": "NGN 950000", "DstntnCountry" : "Nigeria" , "insrncDrtn": "1y" } } }

Customer ID This must have been given to you. If it has not, speak to our engineering team

Authorization This must have been given to you. If it has not, speak to our engineering team

Cover Period — insrncDrtn See this product's profile for possible cover periods. Format: 7d for 7 days, 1m for 1 month, 1y for 1 year, etc

See examples below:

{ "userInfo": { "id" : "1234567890abcdef", "athrzt" : { "id" : "1234567890abcdef", "key": "^]L*ug^S-ZxQQU.}" } }, "cmmnd": { "cmmnd": "dump ipck_mrnn-stnd-1111*PRMM", "seed" : { "cargoType" : "spcf", "cargoDscrptn": "bmhr", "proformaInvoiceValue": "GHS 950000", "DstntnCountry" : "Nigeria" , "insrncDrtn": "1y" } } }

Response 1

Our HTTP response code is always 200 (OK).

In addition to the 200 HTTP code, we also return a JSON data. The JSON data elaborates the outcome of the request.

{ "exctnFdbck": { "id": "75" }, "prmm": "5000" }

Request Outcome — exctnFdbck.id Possible values:
35 — I (the API) am already operating at full capacity. Please try again at a later time
55 — I (the API) could not process your request. An error occured on Octamile's end
75 — I (the API) was able to process your request
These possible values and their respective meanings are identical for all responses across our API

Premium Value — prmm This is the amount to charge the consumer, in Naira

Request 2: Register the Consumer

For every consumer you need to purchase an insurance cover for, you need to create a profile for them. This section shows how to achieve that.

For an individual:

{ "userInfo": { "id" : "--PUT THE CUSTOMER ID WE ASSIGNED YOU HERE--", "athrzt" : { "id" : "--PUT YOUR AUTHORIZATION ID HERE--", "key": "--PUT YOUR AUTHORIZATION KEY HERE--" } }, "cmmnd": { "cmmnd": "prfl entity", "seed" : { "type" : "s", "class" : "h", "name" : { "first" : "--PUT THE CONSUMER'S FIRST NAME HERE--", "last" : "--PUT THE CONSUMER'S LAST NAME HERE--" }, "socialId" : { "type" : "--PUT THE TYPE OF ID HERE--", "id" : "--PUT THE ID NO HERE--", "image" : "--PUT THE BASE 64 ENCODING OF A SCANNED COPY OF THE ID HERE--" }, "taxId" : "--PUT THE CONSUMER'S TAX ID HERE--", "addrss" : { "addrss": "--PUT THE CONSUMER'S CONTACT ADDRESS HERE--", }, "phoneNo": "--PUT THE CONSUMER'S PHONE NO HERE--", "eMail" : "--PUT THE CONSUMER'S EMAIL ADDRESS HERE--" } } }

Means of ID Types / Social ID Types (socialId.type) Possible values:
nidd — NIMC National ID
dlcn — Driver's License
vcrd — Voter's ID
epss — ECOWAS Passport
ipss — International Passport

Means of ID No (socialId.id) Uppercase letters and special characters are not allowed

Phone no The phone no provided should take the international format. It must begin with the '+' sign

See examples below:

{ "userInfo": { "id" : "1234567890abcdef", "athrzt" : { "id" : "1234567890abcdef", "key": "1234567890abcdef" } }, "cmmnd": { "cmmnd": "prfl entity", "seed" : { "type" : "s", "class" : "h", "name" : { "first" : "Folake", "last" : "Arinza" }, "socialId": { "type" : "vcrd", "id" : "1234567890abcd", "image" : "/9j/4AABAAD/w=" } "taxId" : "1234567890abcd", "addrss" : { "addrss": "26B, DELE ADEDEJI ST, LEKKI PHASE 1, LAGOS", }, "phoneNo": "+2348001110000", "eMail" : "fola@gmail.com" } } }

For an organization:

{ "userInfo": { "id" : "--PUT THE CUSTOMER ID WE ASSIGNED YOU HERE--", "athrzt" : { "id" : "--PUT YOUR AUTHORIZATION ID HERE--", "key": "--PUT YOUR AUTHORIZATION KEY HERE--" } }, "cmmnd": { "cmmnd": "prfl entity", "seed" : { "type" : "s", "class" : "o", "name" : { "first" : "--PUT THE CONSUMER'S NAME HERE--", }, "cac02" : "--PUT THE BASE 64 ENCODING OF A SCANNED COPY OF THE CONSUMER'S CAC 02 DOCUMENT HERE--", "cac07" : "--PUT THE BASE 64 ENCODING OF A SCANNED COPY OF THE CONSUMER'S CAC 07 DOCUMENT HERE--", "taxId" : "--PUT THE CONSUMER'S TAX ID HERE--", "addrss" : { "addrss": "--PUT THE CONSUMER'S CONTACT ADDRESS HERE--", }, "phoneNo": "--PUT THE CONSUMER'S PHONE NO HERE--", "eMail" : "--PUT THE CONSUMER'S EMAIL ADDRESS HERE--" } } }

Phone no The phone no provided should take the international format. It must begin with the '+' sign

See examples below:

{ "userInfo": { "id" : "1234567890abcdef", "athrzt" : { "id" : "1234567890abcdef", "key": "1234567890abcdef" } }, "cmmnd": { "cmmnd": "prfl entity", "seed" : { "type" : "s", "class" : "o", "name" : { "first" : "Company XY Ltd" }, "cac02" : "/9j/4AABAAD/w=", "cac07" : "/9j/4AABAAD/w=", "taxId" : "1234567890abcd", "addrss" : { "addrss": "26B, DELE ADEDEJI ST, LEKKI PHASE 1, LAGOS", }, "phoneNo": "+2348001110000", "eMail" : "xy01@gmail.com" } } }

Response 2

{ "exctnFdbck": { "id": "75" }, "id": "61681828132984833037cli3gmpucmdl" }

Consumer ID — id This is a unique ID for identifying the consumer. Anytime you need to insure or make a claim for the consumer, provide it. Thus, it should be stored on your end

Request 3: Request an Insurance Policy

At this point, you must have charged the consumer. If you have not, do not make this request.

This request shows how to request an insurance policy from our API.

{ "userInfo": { "id" : "--PUT THE CUSTOMER ID WE ASSIGNED YOU HERE--", "athrzt" : { "id" : "--PUT YOUR AUTHORIZATION ID HERE--", "key": "--PUT YOUR AUTHORIZATION KEY HERE--" } }, "cmmnd": { "cmmnd": "entt_--PUT THE CONSUMER'S ID HERE--: insure", "seed" : { "ctgry": "mrnn", "type" : "stnd", "pckg" : "1111", "id" : "--PUT A GENERATED TRANSACTION REF HERE--", "addtnlFact": { "Conveyance": "--PUT THE MODE OF SHIPMENT HERE--", "Cargo" : { "Type" : "--PUT THE TYPE OF THE GOODS HERE--", "Dscrptn": "--PUT THE DESCRIPTION OF THE GOODS HERE--" }, "Packaging" : "--PUT THE PACKAGING INFO OF THE GOODS HERE--", "OriginPort": "--PUT THE ORIGIN PORT OF THE GOODS HERE--", "RiskLocation" : "--PUT THE CURRENT LOCATION OF THE GOODS HERE--", "ProformaInvoice": { "Id" : "--PUT THE PROFORMA INVOICE ID/NO HERE--", "Value" : "--PUT THE PROFORMA INVOICE VALUE HERE--", "Document" : "--PUT THE BASE 64 ENCODING OF A SCANNED COPY OF THE PROFORMA INVOICE HERE--" , "Date" : "--PUT THE PROFORMA INVOICE DATE HERE--" }, "Lien": { "Existence" : true, "ThirdParty": "--PUT THE NAME OF THE LIEN HERE--" }, "DstntnCountry" : "--PUT THE DESTINATION COUNTRY HERE--", "CoverStartDate" : "--PUT THE DESIRED COVER START DATE HERE--" } } } }

Consumer's ID Recall that after registering the consumer, a 32-character string was returned. That string is the consumer ID

Generated Transaction Refernce/Insurance ID/Cover ID Generate a transaction reference on your end. This should be a unique 32-character alphanumeric string. Only lowercase letters allowed. This should be saved on your end. It would be needed down the line

Director Info This is only required when the consumer is an organization

Webhook This data is optional. If you want to be notified when the status of the request changes from processing to approved OR from processing to declined, provide a URL we should call

See examples below:

{ "userInfo": { "id" : "1234567890abcdef", "athrzt" : { "id" : "1234567890abcdef", "key": "1234567890abcdef" } }, "cmmnd": { "cmmnd": "entt_601234567890abcdefghij1234567890: insure", "seed" : { "ctgry": "mrnn", "type" : "stnd", "pckg" : "1111", "id" : "1234567890abcdefghij1234567890ab", "addtnlFact": { "Conveyance": "seax", "Cargo" : { "Type" : "gnrl", "Dscrptn": "bmhr" }, "Packaging" : "cnty", "OriginPort": "fest", "RiskLocationAddress": "26b, dele adedeji street, lekki phase 1, lagos", "ProformaInvoice": { "Id" : "EHGT4535LP", "Value" : "NGN 500500", "Document": "9/4fjdgfhjg4/fdd45/Kddsgg==", "Date" : "2022-05-31" }, "Lien": { "Existence" : true , "ThirdParty": "Peaked Hotels Limited" }, "DstntnCountry" : "Nigeria" , "CoverStartDate": "2022-08-30" } } } }

Webhook sample data:

{ "product": "gtrn-stnd-1111", "consumerId": "cn1234567890abcdefghij1234567890", "trnsctnId" : "tr1234567890abcdefghij1234567890", "status" : "p", "statusNote": "...", "crtfct" : "...", "crtfctType": "jpg" }

Status Possible values:
p — processing
d — declined
a — approved

Status Note This data is provided when the status is declined. This would be a description of the reason why the transaction was declined

Certificate This data is provided when the status is approved and the product comes with a certificate. This would be a base64 encoding of the PDF, PNG, or JPG

Response 3

{ "exctnFdbck": { "id": "75" } }

Request 4: Fetch Policy Request Approval Status

This request is used to check the approval status of a policy request.

If a cover is approved and it comes with a certificate, the certificate is included in the response. This data would come as a base 64 encoded string.

Consumer's ID Recall that after registering the consumer, a 32-character string was returned. That string is the consumer ID

Cover ID Recall that you generated a transaction reference in the previous request. That is the cover ID

See examples below:

{ "userInfo": { "id" : "1234567890abcdef", "athrzt" : { "id" : "1234567890abcdef", "key": "1234567890abcdef" } }, "cmmnd": { "cmmnd": "dump entt_601234567890abcdefghij1234567890|insr_mrnn-stnd-1111-1234567890abcdefghij1234567890ab*STATUS" } }

Response 4

If the policy request has been approved and it comes with a certificate, the certificate is included in this response, in the base 64 format.

{ "exctnFdbck": { "id": "75" }, "status": "a", "crtfct": "/9Aad4r4/454f/3Gi==", "tmstmp": "2023-04-07 05:55:09" }

Request Approval Status — status Possible values:
p — Request approval status is pending
d — Request approval status was declined
a — Request approval status was approved

Certificate — crtfct This field is added in the response only when the cover has been approved and the cover comes with a certificate. It comes as a base 64 of a PNG, JPG, or PDF

Status Timestamp — tmstmp The time the transaction was declined or approved

Integration Instruction for Purchase:Marine Import Insurance — Basic cover / ICC C

Sections

Integration Instruction for Purchase:
Marine Import Insurance — Basic cover / ICC C