Skip to content

Goods-in-Transit Insurance Integration Guide

Product code: gtrn-stnd-1111

Single-transit cover for goods or parcels moving within Nigeria. Coverage is active from departure until arrival.

What Is and Is Not Covered

Covered goods: Domestic appliances, general merchandise, clothing, textiles, tools, furniture, building materials (excluding tiles/ceramics), packaged foods, electronics.

Not covered: Gas cylinders, chemicals, ceramic tiles, financial instruments, glassware, explosives, jewellery, artwork, perishable items.

Covered perils: Vehicle accident, collision, overturning, fire, explosion, burglary, theft, windstorm, flood.

Not covered: War, riot, strike, civil unrest, pilferage, driver misconduct, shortages, payment cards, ID cards, government seizure.

Prerequisites

Before you can issue a GIT policy you must have a consumer_id — a UUID returned by the prfl entity (consumer registration) call. If you put any other identifier in the entt_ command the request will be rejected with a 55 error.

If you have not integrated consumer registration yet, start with the Consumer Management Guide before continuing here.

Integration Flow

Standard 4-step flow. Premium is based on the declared value of the goods.

Step 1 — Get Premium Quote

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_gtrn-stnd-1111*PRMM",
      "seed": {
        "goodsValue": 250000
      }
    }
  }'

goodsValue is the declared value of the goods in Naira. The premium is calculated as a percentage of this value.

Type note: goodsValue must be a number, not a string — send 250000, not "250000". This applies in the Step 1 quote seed and in Step 3 addtnlFact.

Response: 

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

Step 2 — Register Consumer

Returning customer? If this customer has purchased insurance through your platform before, you already have their consumer_id — skip this step and use it directly in Step 3. See the Consumer Management Guide.

{
  "cmmnd": {
    "cmmnd": "prfl entity",
    "seed": {
      "class": "individual",
      "name": { "first": "Tunde", "last": "Adeyemi" },
      "phoneNo": "+2348023456789",
      "eMail": "tunde.adeyemi@logistics.com"
    }
  }
}

Response:

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

The id value in this response is your consumer_id. Store it in your database and use it in Step 3 — this is the only value that is valid in the entt_ command. Do not use your own internal user ID, session ID, shipment ID, or any other identifier in its place.

Step 3 — Request Policy

Replace {CONSUMER_ID} in the command with the id returned in Step 2.

{CONSUMER_ID} vs seed.id — these are different fields.

entt_{CONSUMER_ID}: insure — the consumer UUID from your Step 2 prfl entity response. This identifies who is being insured. Using any other identifier here (an internal user ID, shipment ID, or UUID you generated yourself) will cause a 55 error.

seed.id — your own internal transaction reference (alphanumeric, up to 32 chars). This is for your own deduplication. It is not a consumer identifier and has no effect on who the policy is issued to.

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_a1b2c3d4e5f67890abcdef1234567890: insure",
      "seed": {
        "ctgry": "gtrn",
        "type": "stnd",
        "pckg": "1111",
        "id": "your-internal-tx-ref-001",
        "addtnlFact": {
          "goodsType": "gnrl",
          "goodsDscrptn": "Electronics - 5 laptops, 10 phones",
          "goodsValue": 250000,
          "voyage": [
            { "origin": "Lagos" },
            { "destination": "Abuja" }
          ],
          "dprtrDateTime": "2024-03-21 08:00:00",
          "estmtdArrvlDateTime": "2024-03-21 18:00:00",
          "proformaInvoice": "INV-2024-0042",
          "proformaDate": "2024-03-20"
        }
      }
    }
  }'

Required Fields

Field Type Description
ctgry string "gtrn"
type string "stnd"
pckg string "1111"
id string Your own internal transaction reference — alphanumeric, up to 32 chars. Not the consumer ID.
addtnlFact.goodsType string Goods category code (see below)
addtnlFact.goodsDscrptn string Plain-language description of the goods
addtnlFact.goodsValue number (float) Declared value in Naira — e.g., 250000. Must be a number, not a string.
addtnlFact.voyage array Leg objects with origin and destination keys — [{"origin": "Lagos"}, {"destination": "Abuja"}]. Origin and destination must be different cities.
addtnlFact.dprtrDateTime string Departure datetime: YYYY-MM-DD HH:MM:SS
addtnlFact.estmtdArrvlDateTime string Estimated arrival datetime: YYYY-MM-DD HH:MM:SS
addtnlFact.proformaInvoice string Invoice reference number — e.g. "INV-2024-0042". Printed on the certificate. Not a URL — use the invoice number, not a link to the invoice PDF.
addtnlFact.proformaDate string Invoice date: YYYY-MM-DD

Goods Type Codes

Code Category
"gnrl" General merchandise
"elct" Electronics
"frd" Furniture
"txtl" Clothing and textiles
"appl" Domestic appliances
"fod" Packaged foods
"bldg" Building materials
"tool" Tools

Response:

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

A 200 response means the request was accepted — not that the policy is already approved. Proceed to Step 4 to retrieve the status and certificate.

Test mode vs live mode

Your account starts in test mode. The behaviour differs:

Test mode Live mode
Policy approval Instant — auto-approved on issuance Processed by the insurer — may take seconds to minutes
Certificate Demo certificate (watermarked) Real certificate, issued by the insurer
Status on first poll "a" (approved) immediately "p" (pending) until the insurer responds
How to check your mode Look for the TEST or LIVE badge in your dashboard Same
How to switch { "cmmnd": { "cmmnd": "set env_live" } } { "cmmnd": { "cmmnd": "set env_test" } }

Recommendation: Complete your full integration and verify the 4-step flow in test mode before switching to live.

Step 4 — Check Policy Status

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 entt_{CONSUMER_ID}|insr_gtrn-stnd-1111-{TX_ID}*STATUS"
    }
  }'

Approved response: 

{
  "exctnFdbck": { "id": 75, "id_v4": 200 },
  "status": "a",
  "crtfct": "<base64-encoded-certificate>",
  "crtfctType": "pdf",
  "tmstmp": "2024-03-21 07:45:00"
}

Cover Period

This policy is valid from dprtrDateTime until estmtdArrvlDateTime. There is no fixed monthly or annual term — the cover lasts exactly as long as the transit.

Purchase the policy as close to departure time as practical. Policies submitted significantly before the transit window may not be active at the time of departure.

Common Mistakes

Issue Cause Fix
55 error on every request entt_ command contains your own internal ID instead of the consumer_id from prfl entity Call prfl entity first, store the returned id, use that UUID in the command
55 error despite correct consumer ID Consumer was registered under different API credentials Consumer records are scoped to the partner account — register and issue with the same credentials
Policy stuck on "p" in test mode Account is set to live mode Check the TEST/LIVE badge in your dashboard and toggle to TEST mode
Policy stuck on "p" in live mode Normal — insurer processing in progress Poll every 5–10 seconds; live issuance can take up to 60 seconds
proformaInvoice rejected A URL was sent instead of an invoice number Send the invoice reference number (e.g. "INV-2024-0042"), not a link to the PDF
goodsValue validation error Value sent as a string ("250000") instead of a number Send as a JSON number: 250000
Decline on goods type Goods fall under excluded categories Review the covered/excluded list above before submitting
Transit not covered Departure or arrival datetime already passed Submit within a reasonable window before departure
Premium lower than expected goodsValue underestimated Use the full declared value to avoid underinsurance

See also