Motor certificates (DMVIC)

7 endpoints · base URL https://flexysure.intrepidprojects.co.ke/api/v1

Issue, fetch, check and cancel DMVIC motor insurance certificates. Issuance follows the paid-stage rule: a policy is certified once it is active (first instalment paid in full); on an instalment plan the cover period is split into stages and stage n is issued once instalment n is paid and stage n−1 exists. Every issue runs DMVIC's double-insurance check first. Responses keep Insurance Cloud's {success, message} shape; failures are problem documents that also carry success: false and message. In the demo every call goes to the bundled DMVIC simulator.

Method	Path	Summary	Scope
POST	/api/v1/dmvic	Issue certificates for a risk note	certificate
POST	/api/v1/dmvic/agent	Issue a certificate as an agent	certificate
POST	/api/v1/dmvic/get-certificate	Download a certificate	certificate
POST	/api/v1/dmvic/double-insurance	Check for double insurance	certificate
POST	/api/v1/dmvic/stock	Get certificate stock	certificate
POST	/api/v1/dmvic/cancel	Cancel a certificate Flexysure only	certificate
GET	/api/v1/certificates/{number}/verify	Verify a certificate Flexysure only	certificate

POST /api/v1/dmvic

Issue certificates for a risk note

Issues the next eligible certificate stage for each listed vehicle on the policy. start_date and expiring must fall inside the policy cover; the certificate period itself follows the paid stage. Repeating the call for an issued stage returns the existing certificate. email and phone are accepted for Insurance Cloud compatibility.

Scope: certificate
Authentication: Bearer token
Rate limit: 60 requests per minute per token (per-client override)
Idempotency: Required: send an Idempotency-Key; a retry with the same key replays the first response.

Headers

Header	Meaning
Authorization	Bearer <access_token> (scope `certificate`)
Idempotency-Key	Required. A unique value (a UUID) per write. Replays within 24 hours return the stored response with `Idempotent-Replayed: true`; the same key with a different body is rejected (`idempotency_key_reused`).

Body fields

Field	Type	Required	Description
risknote	string	Yes	Risk note number (policy number also accepted). Example: `RN/2026/000123`
email	string	No	Policyholder email.
phone	string	No	Policyholder phone.
vehicles	object[]	Yes	Vehicles on the risk note to certify.
vehicles[].registration	string	Yes	Example: `KDA 123A`
vehicles[].start_date	string	Yes	Example: `2026-10-14`
vehicles[].expiring	string	Yes	Example: `2027-10-13`

Example

Request cURL

curl -X POST 'https://flexysure.intrepidprojects.co.ke/api/v1/dmvic' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Accept: application/json' \
  -H 'Idempotency-Key: 6caa59f3-f385-484f-a8e2-5fe3ddfaa8fd' \
  -H 'Content-Type: application/json' \
  -d '{
    "risknote": "RN/2026/000123",
    "email": "wanjiru@example.test",
    "phone": "0712345678",
    "vehicles": [
        {
            "registration": "KDA 123A",
            "start_date": "2026-10-14",
            "expiring": "2027-10-13"
        }
    ]
}'

Request body (JSON)

Request body JSON

{
    "risknote": "RN/2026/000123",
    "email": "wanjiru@example.test",
    "phone": "0712345678",
    "vehicles": [
        {
            "registration": "KDA 123A",
            "start_date": "2026-10-14",
            "expiring": "2027-10-13"
        }
    ]
}

Response JSON

{
    "success": true,
    "message": "Certificate C12345678 issued.",
    "data": [
        {
            "certificate_number": "C12345678",
            "status": "issued",
            "class": "C",
            "cover_code": 100,
            "stage": 1,
            "stage_of": 1,
            "registration": "KDA 123A",
            "chassis": "NZE161-3012456",
            "policy_no": "POL/2026/000123",
            "risknote": "RN/2026/000123",
            "start_date": "2026-10-14",
            "expiring": "2027-10-13",
            "issued_at": "2026-10-14T10:17:00+03:00",
            "cancelled_at": null,
            "error_code": null,
            "error_text": null
        }
    ]
}

Responses

Status	Meaning
200	`{success: true, message, data: [certificate]}`
404	Unknown risk note
422	`certificate_not_issued` (policy not active, stage not paid, double insurance, DMVIC refusal; `data` holds the attempt) or `validation_failed` (vehicle not on the risk note, dates outside cover)

Errors are problem documents; the common codes (401, 403 insufficient_scope, 422, 429) apply to every endpoint.

POST /api/v1/dmvic/agent

Issue a certificate as an agent

Insurance Cloud's agent issuance: identifies the agent by X-Agent-Code and X-Agent-Key, checks the policy is theirs and issues the next eligible stage (CertificateStages). The headers are required here.

Scope: certificate
Authentication: Bearer token
Rate limit: 60 requests per minute per token (per-client override)
Idempotency: Required: send an Idempotency-Key; a retry with the same key replays the first response.
Agent headers: Accepts X-Agent-Code and X-Agent-Key: the call runs as that agent and sees only the agent's own records.

Headers

Header	Meaning
Authorization	Bearer <access_token> (scope `certificate`)
X-Agent-Code	Required. The agent's code (see GET /sales-people).
X-Agent-Key	Required. The agent's key.
Idempotency-Key	Required. A unique value (a UUID) per write. Replays within 24 hours return the stored response with `Idempotent-Replayed: true`; the same key with a different body is rejected (`idempotency_key_reused`).

Body fields

Field	Type	Required	Description
policy_id	string	Yes	Policy id, uuid, policy number or risk note number. Example: `5d0c8a1e-…`

Example

Request cURL

curl -X POST 'https://flexysure.intrepidprojects.co.ke/api/v1/dmvic/agent' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Accept: application/json' \
  -H 'Idempotency-Key: 9e47fec1-cb0c-4f34-a610-34311f2ed306' \
  -H 'X-Agent-Code: KK01' \
  -H "X-Agent-Key: $AGENT_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "policy_id": "5d0c8a1e-…"
}'

Request body (JSON)

Request body JSON

{
    "policy_id": "5d0c8a1e-…"
}

Response JSON

{
    "success": true,
    "message": "Certificate C12345678 issued.",
    "data": [
        {
            "certificate_number": "C12345678",
            "status": "issued",
            "class": "C",
            "cover_code": 100,
            "stage": 1,
            "stage_of": 1,
            "registration": "KDA 123A",
            "chassis": "NZE161-3012456",
            "policy_no": "POL/2026/000123",
            "risknote": "RN/2026/000123",
            "start_date": "2026-10-14",
            "expiring": "2027-10-13",
            "issued_at": "2026-10-14T10:17:00+03:00",
            "cancelled_at": null,
            "error_code": null,
            "error_text": null
        }
    ],
    "stage": 1,
    "of": 1
}

Responses

Status	Meaning
200	`{success: true, message, data: [certificate], stage, of}`
400	`agent_headers_required`
403	`agent_denied` (headers do not match) or `policy_not_agents` (the policy was written by someone else)
404	Unknown policy
422	`not_eligible` (not active, next instalment unpaid, every stage issued) or `certificate_not_issued`

Errors are problem documents; the common codes (401, 403 insufficient_scope, 422, 429) apply to every endpoint.

POST /api/v1/dmvic/get-certificate

Download a certificate

The certificate as a PDF file (application/pdf, attachment). Flexysure's rendering is marked SAMPLE; DMVIC's own PDF is the certificate of record. Only issued certificates download.

Scope: certificate
Authentication: Bearer token
Rate limit: 60 requests per minute per token (per-client override)
Idempotency: Not keyed. Check before retrying.

Headers

Header	Meaning
Authorization	Bearer <access_token> (scope `certificate`)

Body fields

Field	Type	Required	Description
CertificateNumber	string	Yes	DMVIC certificate number. Example: `C12345678`

Example

Request cURL

curl -X POST 'https://flexysure.intrepidprojects.co.ke/api/v1/dmvic/get-certificate' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
    "CertificateNumber": "C12345678"
}'

Request body (JSON)

Request body JSON

{
    "CertificateNumber": "C12345678"
}

Response PDF

%PDF-1.4 … (binary)

Responses

Status	Meaning
200	PDF file
404	Unknown certificate
422	`certificate_not_active` (cancelled, failed or still requested)

Errors are problem documents; the common codes (401, 403 insufficient_scope, 422, 429) apply to every endpoint.

POST /api/v1/dmvic/double-insurance

Check for double insurance

Asks DMVIC whether the vehicle already has cover overlapping the period. clear: true means none; otherwise data lists the overlapping certificates. Read-only.

Scope: certificate
Authentication: Bearer token
Rate limit: 60 requests per minute per token (per-client override)
Idempotency: Not keyed. Check before retrying.

Headers

Header	Meaning
Authorization	Bearer <access_token> (scope `certificate`)

Body fields

Field	Type	Required	Description
registration	string	Yes	Example: `KDA 123A`
chassis	string	No	Example: `NZE161-3012456`
start_date	string	Yes	Example: `2026-10-14`
expiring	string	Yes	Example: `2027-10-13`

Example

Request cURL

curl -X POST 'https://flexysure.intrepidprojects.co.ke/api/v1/dmvic/double-insurance' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
    "registration": "KDA 123A",
    "start_date": "2026-10-14",
    "expiring": "2027-10-13"
}'

Request body (JSON)

Request body JSON

{
    "registration": "KDA 123A",
    "start_date": "2026-10-14",
    "expiring": "2027-10-13"
}

Response JSON

{
    "success": true,
    "message": "No overlapping cover on DMVIC for this period.",
    "clear": true,
    "data": []
}

Responses

Status	Meaning
200	Result
502	`dmvic_unavailable`

Errors are problem documents; the common codes (401, 403 insufficient_scope, 422, 429) apply to every endpoint.

POST /api/v1/dmvic/stock

Get certificate stock

Blank certificate stock DMVIC holds for an underwriter, by certificate class. insurer is the DMVIC member company id (dmvic_member_id from GET /insurers).

Scope: certificate
Authentication: Bearer token
Rate limit: 60 requests per minute per token (per-client override)
Idempotency: Not keyed. Check before retrying.

Headers

Header	Meaning
Authorization	Bearer <access_token> (scope `certificate`)

Body fields

Field	Type	Required	Description
insurer	integer	Yes	DMVIC member company id. Example: `901`

Example

Request cURL

curl -X POST 'https://flexysure.intrepidprojects.co.ke/api/v1/dmvic/stock' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
    "insurer": 901
}'

Request body (JSON)

Request body JSON

{
    "insurer": 901
}

Response JSON

{
    "success": true,
    "message": "Stock for Savanna General.",
    "insurer": {
        "id": 1,
        "name": "Savanna General",
        "member_company_id": 901
    },
    "data": [
        {
            "classification_id": 3,
            "title": "Type C - Private",
            "stock": 480
        }
    ]
}

Responses

Status	Meaning
200	`{success: true, data: [...]}`
404	No insurer with that member id in your organisation
422	`dmvic_rejected`

Errors are problem documents; the common codes (401, 403 insufficient_scope, 422, 429) apply to every endpoint.

POST /api/v1/dmvic/cancel Flexysure only

Cancel a certificate

Cancels the certificate with DMVIC. DMVIC only allows this within its cancellation window (24 hours after issue); after that the certificate stays issued and the reason comes back as dmvic_rejected. Cancelling an already cancelled certificate succeeds.

Scope: certificate
Authentication: Bearer token
Rate limit: 60 requests per minute per token (per-client override)
Idempotency: Required: send an Idempotency-Key; a retry with the same key replays the first response.

Headers

Header	Meaning
Authorization	Bearer <access_token> (scope `certificate`)
Idempotency-Key	Required. A unique value (a UUID) per write. Replays within 24 hours return the stored response with `Idempotent-Replayed: true`; the same key with a different body is rejected (`idempotency_key_reused`).

Body fields

Field	Type	Required	Description
certificate_number	string	Yes	Example: `C12345678`
reason	string	Yes	DMVIC cancellation reason. One of: `INSURED_REQUESTED`, `AMEND_PASSENGER_COUNT`, `CHANGE_SCOPE_OF_COVER`, `POLICY_NOT_TAKEN_UP`, `VEHICLE_SOLD`, `AMEND_INSURED_DETAILS`, `AMEND_VEHICLE_DETAILS`, `SUSPECTED_FRAUD`, `NON_PAYMENT`, `MISSING_KYC`, `GOVERNMENT_REQUEST`, `SUBJECT_MATTER_CEASED`, `CHANGE_PERIOD_OF_INSURANCE`, `INSURER_DECLINED_COVER`, `WRITTEN_OFF`, `STOLEN` Example: `INSURED_REQUESTED`

Example

Request cURL

curl -X POST 'https://flexysure.intrepidprojects.co.ke/api/v1/dmvic/cancel' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Accept: application/json' \
  -H 'Idempotency-Key: f114fa67-e595-4e49-a43c-49adb62c81e5' \
  -H 'Content-Type: application/json' \
  -d '{
    "certificate_number": "C12345678",
    "reason": "INSURED_REQUESTED"
}'

Request body (JSON)

Request body JSON

{
    "certificate_number": "C12345678",
    "reason": "INSURED_REQUESTED"
}

Response JSON

{
    "success": true,
    "message": "Certificate C12345678 cancelled: Insured requested.",
    "data": {
        "certificate_number": "C12345678",
        "status": "cancelled",
        "class": "C",
        "cover_code": 100,
        "stage": 1,
        "stage_of": 1,
        "registration": "KDA 123A",
        "chassis": "NZE161-3012456",
        "policy_no": "POL/2026/000123",
        "risknote": "RN/2026/000123",
        "start_date": "2026-10-14",
        "expiring": "2027-10-13",
        "issued_at": "2026-10-14T10:17:00+03:00",
        "cancelled_at": "2026-10-14T11:00:00+03:00",
        "error_code": null,
        "error_text": null
    }
}

Responses

Status	Meaning
200	`{success: true, message, data: certificate}`
404	Unknown certificate
422	`dmvic_rejected` or `validation_failed`

Errors are problem documents; the common codes (401, 403 insufficient_scope, 422, 429) apply to every endpoint.

GET /api/v1/certificates/{number}/verify Flexysure only

Verify a certificate

state is valid, expired, future (cover not started), cancelled, not_issued or mismatch (the registration you passed is not the certified vehicle).

Scope: certificate
Authentication: Bearer token
Rate limit: 60 requests per minute per token (per-client override)
Idempotency: Safe to repeat (read only).

Headers

Header	Meaning
Authorization	Bearer <access_token> (scope `certificate`)

Parameters

Name	In	Type	Required	Description
number	path	string	Yes	Example: `C12345678`
registration	query	string	No	Check the certificate belongs to this vehicle. Example: `KDA123A`

Example

Request cURL

curl -X GET 'https://flexysure.intrepidprojects.co.ke/api/v1/certificates/C12345678/verify' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Accept: application/json'

Response JSON

{
    "data": {
        "state": "valid",
        "valid": true,
        "insurer": "Savanna General",
        "certificate_number": "C12345678",
        "status": "issued",
        "class": "C",
        "cover_code": 100,
        "stage": 1,
        "stage_of": 1,
        "registration": "KDA 123A",
        "chassis": "NZE161-3012456",
        "policy_no": "POL/2026/000123",
        "risknote": "RN/2026/000123",
        "start_date": "2026-10-14",
        "expiring": "2027-10-13",
        "issued_at": "2026-10-14T10:17:00+03:00",
        "cancelled_at": null,
        "error_code": null,
        "error_text": null
    }
}

Responses

Status	Meaning
200	Verification
404	Unknown certificate

Errors are problem documents; the common codes (401, 403 insufficient_scope, 422, 429) apply to every endpoint.