Welcome Test User US01
Sign out →
← Back

Integration Instruction for Purchase:
Device Warranty — Comprehensive cover

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 'Device Warranty — Comprehensive cover', 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: Activate Policy →

• Request 5: Fetch the Policy Final Activation Status & Certificate →

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.

{ "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_phnn-flx2-1111*PRMM", "seed" : { "insrncDrtn": "--PUT THE 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
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_phnn-flx2-1111*PRMM", "seed" : { "insrncDrtn": "6m" } } }

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.

{ "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--" }, "phoneNo": "--PUT THE CONSUMER'S PHONE NO HERE--", "eMail" : "--PUT THE CONSUMER'S EMAIL 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" : "h", "name" : { "first": "Folake", "last" : "Arinze" }, "phoneNo": "+2347010001234", "eMail" : "folake.arinze.dummy@gmail.com" } } }

Response 2

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

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
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": "phnn", "type" : "flx2", "pckg" : "1111", "id" : "--PUT A GENERATED TRANSACTION REF HERE--", "addtnlFact": { "brand": "--PUT THE DEVICE BRAND HERE--", "model": "--PUT THE DEVICE MODEL HERE--", "uIdnt": "--PUT THE DEVICE IMEI 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
dontSendActivationCode When a cover purchase request has been pushed, there is a last step required.
This last step is a video verification step. It involves the end-user sending us a video that shows the device is in good working condition. You do not have do anything as regards this, this step would be handled behind the scene, between us and the end-user.
Typically, we send the end-user an email that contains, their policy number, their policy activation code, and a link to a webpage where they can upload their verification video. That is what that last step basically is.
However, there are partners who do not like Octamile communicating directly to their end-users, these partners would rather handle the video verification aspect by themselves.
If you are one of such partners, you can leverage this field, to prevent us from sending your end-users their activation code.
Just set the value of this field to 'true'. When this field is set to 'true', we would return the activation code to use, in the response of this request. You can then send this activation code to your customer by yourself, and of course provide a webpage where they can upload their verification video, you would then forward us these details later via this API

See examples below:

{ "userInfo": { "id" : "1234567890abcdef", "athrzt" : { "id" : "1234567890abcdef", "key": "1234567890abcdef" } }, "cmmnd": { "cmmnd": "entt_601234567890abcdefghij1234567890: insure", "seed" : { "ctgry": "phnn", "type" : "flx2", "pckg" : "1111", "id" : "1234567890abcdefghij1234567890ab", "addtnlFact": { "brand": "Nokia", "model": "G20Xi", "uIdnt": "1234567890ABCDEFGHIJKLMNOPQ" } } } }

Response 3

{ "exctnFdbck": { "id": "75" }, "activationCode": "CDEF3489" }

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

Request 4: Activate Policy

This request is only required when you prefer to handle the video verification (policy activation) by yourself. If you do not understand what we mean here, refer to the description under request 3.

This request is made when the consumer (end-user) must have submitted their verification video to you.

{ "userInfo" : {"id": "indv"}, "cmmnd": { "cmmnd": "entt_1234567890abcdefghij1234567890ab|insr_dvcc-stnd-1111-1234567890abcdefghij1234567890ab*VVNN: updt", "seed" : { "name" : [ "--PUT THE CUSTOMER's FIRST NAME HERE--", "--PUT THE CUSTOMER's LAST NAME HERE--" ], "phoneNo" : "--PUT THE CUSTOMER's PHONE NO HERE--", "eMail" : "--PUT THE CUSTOMER's E-MAIL HERE--", "phoneBrand": "--PUT THE PHONE BRAND HERE--", "phoneModel": "--PUT THE PHONE MODEL HERE--", "imei" : "--PUT THE PHONE IMEI HERE--", "policyID": "--PUT THE POLICY NO HERE HERE--", "verificationVideo" : "--PUT THE PHONE VERIFICATION VIDEO HERE--", "policyActivationCode": "--PUT THE POLICY ACTIVATION CODE HERE--" } } }

Policy ID This should be the transaction ref/insurance ID of the user's policy
Verification Video The value of this should be the base 64 encoding of the video

See examples below:

{ "userInfo" : {"id": "indv"}, "cmmnd": { "cmmnd": "entt_1234567890abcdefghij1234567890ab|insr_dvcc-stnd-1111-1234567890abcdefghij1234567890ab*VVNN: updt", "seed" : { "name" : ["JOHN" , "ASHA"], "phoneNo" : "+2348145798559" , "eMail" : "john@gmail.com" , "phoneBrand": "Tecno", "phoneModel": "Camon 20 Pro" , "imei" : "12345678ABCD00" , "policyID": "12345678-90ABCDEF-GHIJ1234-567890BG", "verificationVideo" : "9/4gfhjg4/Dwd4/hLk5hgg==", "policyActivationCode": "CDEF3489" } } }

Response 4

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

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

Request 5: Fetch the Policy Final Activation Status & Certificate

After the the verification video has been submitted, there is a final review done on our end.

A final review is usually done to ensure the consumer is not purchasing a duplicate policy, etc. In other words, Octamile hardly ever declines the activation of a policy. If the final policy activation fails, we would also notify you via mail.

This request shows how to check the final activation status of the policy.

{ "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 entt_--PUT THE CONSUMER'S ID HERE--|insr_phnn-flx2-1111---PUT THE COVER ID HERE--*STATUS" } }

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_phnn-flx2-1111-1234567890abcdefghij1234567890ab*STATUS" } }

Response 5

If a cover was 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 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
Final Activation Status — status Possible values:
p — Final activation status is pending
d — Final activation status was declined
a — Final activation 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