Skip to content

Marine Insurance Integration Guide

Covers Marine Export (mexx-stnd-1111), Marine Import Basic ICC C (mrnn-stnd-1111), and Marine Import Comprehensive ICC A (mrnn-cmpr-1111).

Product Overview

Marine Export Marine Import Basic (ICC C) Marine Import Comprehensive (ICC A)
Product code mexx-stnd-1111 mrnn-stnd-1111 mrnn-cmpr-1111
Direction Export from Nigeria Import into Nigeria Import into Nigeria
Coverage level Standard Basic perils only Full coverage
Consumer type Individual or organisation Individual or organisation Individual or organisation

Important: Organisation vs Individual Consumer

Marine insurance supports both individual and organisational policyholders. The consumer registration step (Step 2) differs significantly between the two. Determine the consumer type before proceeding.

Step 1 — Get Premium Quote

Marine Export:

curl -X POST https://octamile-api.azurewebsites.net \
  -H "Content-Type: application/json" \
  -d '{
    "userInfo": {
      "id": "YOUR_PARTNER_ID",
      "athrzt": { "id": "YOUR_AUTH_ID", "key": "YOUR_AUTH_KEY" }
    },
    "cmmnd": {
      "cmmnd": "dump ipck_mexx-stnd-1111*PRMM",
      "seed": {
        "goodsValue": 5000000,
        "insrncDrtn": "1m"
      }
    }
  }'

Use mrnn-stnd-1111 or mrnn-cmpr-1111 for import products.

Seed field Type Description
goodsValue number Proforma invoice value of the goods in Naira — e.g. 5000000. Must be a number, not a string.
insrncDrtn string Duration: "1m", "3m", "6m", "1y"

Response: 

{
  "exctnFdbck": { "id": 75, "id_v4": 200 },
  "prmm": 25000
}

Step 2 — Register Consumer

Individual Consumer

{
  "cmmnd": {
    "cmmnd": "prfl entity",
    "seed": {
      "type": "s",
      "class": "h",
      "name": { "first": "Babajide", "last": "Fashola" },
      "socialID": {
        "type": "nidd",
        "id": "98765432101",
        "image": "BASE64_ENCODED_ID_SCAN"
      },
      "taxId": "1234567890",
      "addrss": { "addrss": "15 Apapa Port Road, Lagos" },
      "phoneNo": "+2348061234567",
      "eMail": "babajide.fashola@tradecompany.com"
    }
  }
}

Organisation Consumer

{
  "cmmnd": {
    "cmmnd": "prfl entity",
    "seed": {
      "type": "s",
      "class": "o",
      "name": { "brand": "Apex Trade Nigeria Ltd" },
      "rc": "RC123456",
      "cac02": "BASE64_ENCODED_CAC02_DOC",
      "cac07": "BASE64_ENCODED_CAC07_DOC",
      "taxId": "0123456789",
      "addrss": { "addrss": "Plot 5, Apapa Industrial Estate, Lagos" },
      "phoneNo": "+2341234567890",
      "eMail": "info@apextrade.com"
    }
  }
}

Individual vs Organisation Fields

Field Individual Organisation Notes
class "h" "o" Required
name.first + name.last Required — For individuals
name.brand — Required Company name
socialID.type Required — "nidd" (NIN), "dlcn" (driver's licence), "ipss" (passport), "vcrd" (voter's card), "bvnn" (BVN)
socialID.id Required — ID number
socialID.image Required — Base64 scan
rc — Required CAC registration number
cac02 — Required CAC Form 02 — Base64 scan
cac07 — Required CAC Form 07 — Base64 scan
taxId Required Required Tax Identification Number
addrss.addrss Required Required Full address
phoneNo Required Required International format
eMail Required Required —

Response: Returns id — store as consumer_id.

Step 3 — Request Policy

Prerequisite: The {CONSUMER_ID} in the command string must be the id returned by prfl entity (SR05) using the same API credentials you are using here. Passing a self-generated or copied UUID that was not returned by SR05 will result in a 409 Consumer not found error.

Marine Export:

curl -X POST https://octamile-api.azurewebsites.net \
  -H "Content-Type: application/json" \
  -d '{
    "userInfo": {
      "id": "YOUR_PARTNER_ID",
      "athrzt": { "id": "YOUR_AUTH_ID", "key": "YOUR_AUTH_KEY" }
    },
    "cmmnd": {
      "cmmnd": "entt_{CONSUMER_ID}: insure",
      "seed": {
        "ctgry": "mexx",
        "type": "stnd",
        "pckg": "1111",
        "id": "YOUR_UUID_V4_TX_REF",
        "insrncDrtn": "1m",
        "addtnlFact": {
          "items": [
            { "description": "Industrial generators", "quantity": 5, "value": 2000000 },
            { "description": "Electrical cables (rolls)", "quantity": 20, "value": 3000000 }
          ],
          "goodsValue": 5000000,
          "goodsDscrptn": "Industrial generators and electrical cables",
          "voyage": [
            { "origin": "Apapa Port, Lagos, Nigeria" },
            { "destination": "Tema Port, Accra, Ghana" }
          ],
          "proformaInvoice": "INV-2024-0042",
          "proformaDate": "2024-03-20",
          "coverStartDate": "2024-03-22"
        }
      }
    }
  }'

For import products, use ctgry: "mrnn" and type: "stnd" (basic) or type: "cmpr" (comprehensive). All other fields are the same.

Required Fields

Field Type Description
ctgry string "mexx" (export) or "mrnn" (import)
type string "stnd" (basic) or "cmpr" (comprehensive)
pckg string "1111"
id string Your 32-char transaction ref
insrncDrtn string Duration: "1m", "3m", "6m", "1y"
addtnlFact.items array List of goods being shipped (at least 1 item)
addtnlFact.items[].description string Description of each item
addtnlFact.items[].quantity number (integer) Quantity
addtnlFact.items[].value number (float) Value in Naira — e.g. 2000000
addtnlFact.goodsValue number (float) Proforma invoice value of the goods in Naira — e.g. 5000000. Printed on the certificate.
addtnlFact.goodsDscrptn string Brief description of the goods — e.g. "Industrial generators and cables". Printed on the certificate.
addtnlFact.voyage array Voyage route. At least 2 entries. Each entry is an object with exactly one key: either "origin" or "destination". Example: [{"origin": "Apapa Port, Lagos, NG"}, {"destination": "Tema Port, Accra, GH"}]
addtnlFact.proformaInvoice string Proforma invoice reference number — e.g. "INV-2024-0042". Printed on the certificate.
addtnlFact.proformaDate string Date on the proforma invoice: YYYY-MM-DD

Optional Fields

Field Type Description
addtnlFact.coverStartDate string Policy start date: YYYY-MM-DD (defaults to today)

For Organisation Consumers (Additional)

Field Type Description
addtnlFact.DrctrName string Director's full name
addtnlFact.DrctrDob string Director's date of birth: YYYY-MM-DD

Response: 

{
  "exctnFdbck": { "id": 75, "id_v4": 200 }
}

Step 4 — Check Policy Status

Marine Export: 

dump entt_{CONSUMER_ID}|insr_mexx-stnd-1111-{TX_ID}*STATUS

Marine Import Basic: 

dump entt_{CONSUMER_ID}|insr_mrnn-stnd-1111-{TX_ID}*STATUS

Marine Import Comprehensive: 

dump entt_{CONSUMER_ID}|insr_mrnn-cmpr-1111-{TX_ID}*STATUS

Status values

status Meaning Next step
"p" Pending — policy is under review Continue polling (Import only)
"a" Approved — base64 certificate in response Done
"d" Declined — see statusNote for the reason Do not retry; contact Octamile

Marine Export auto-approves. In live mode, status is "a" on the first check — no polling required. Marine Import requires manual review; poll every 5–10 seconds, typically approved within 60 seconds in live mode.

Approved response — Marine Export (live mode): 

{
  "exctnFdbck": { "id": 75, "id_v4": 200 },
  "status": "a",
  "crtfct": "<base64-encoded-docx>",
  "crtfctType": "docx"
}

Marine Export returns a cargo certificate as a DOCX file. Decode the Base64 crtfct and save it with a .docx extension.

Approved response — Marine Import: 

{
  "exctnFdbck": { "id": 75, "id_v4": 200 },
  "status": "a",
  "crtfct": "<base64-encoded-certificate>",
  "crtfctType": "pdf"
}

Common Decline Reasons

Issue Likely cause Fix
Organisation declined CAC documents unreadable Re-scan at higher resolution, ensure all text is legible
Value mismatch goodsValue doesn't match sum of items Ensure goodsValue equals the total of all item values in addtnlFact.items
Missing director details Organisation consumer without director info Add DrctrName and DrctrDob to addtnlFact

See also