Skip to content

Sample API Calls for Parametric Crop Insurance

In the "Parametric Crop Insurance" scenario, an agricultural insurance provider integrates with Riskwolf's APIs to offer comprehensive parametric crop insurance in India. This insurance plan aims to protect farmers from financial losses resulting from adverse weather conditions, focusing on specific 6-digit PIN codes representing distinct agricultural regions. As an example, envision a farmer in a particular PIN code seeking coverage against insufficient rainfall during the critical crop-growing period. The insurance provider seamlessly integrates with Riskwolf's APIs to assess available coverages, each associated with different risk rates, generate customized quotes based on the specified PIN code, confirm policies for enrolled farmers, and subsequently evaluate and process claims triggered by unfavorable weather conditions.

Code lists and enums:

Authentication

Get access token from OAuth2 endpoint:


**cURL Request:**

```bash
CLIENT_APP_ID='<app_id>'
CLIENT_SECRET='<app_secret>'
SERVER_APP_ID='<server_app_id>'
TENANT_ID='<tenant_id>'

curl -sS -d "client_id=${CLIENT_APP_ID}&scope=api%3A%2F%2F${SERVER_APP_ID}%2F.default&client_secret=${CLIENT_SECRET}&grant_type=client_credentials" \
  -XPOST \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  "https://login.microsoftonline.com/${TENANT_ID}/oauth2/v2.0/token" | jq -r '.access_token'

General information about the auth integration can be found in the Microsoft Authentication Library (MSAL) overview.

More information about API to API authentication with examples for specific languages can be found in the Microsoft Entra ID service-to-service documentation.

Coverages

Get all coverages

curl --location 'https://dev.riskwolf.com/internal/coverages' \
--header 'x-tenant-id: <tenant_id>' \
--header 'Authorization: Bearer <access_token>'

Get coverages for a pin code

curl --location 'https://dev.riskwolf.com/internal/coverages?targetName=<pincode>' \
--header 'x-tenant-id: <tenant_id>' \
--header 'Authorization: Bearer <access_token>'

Response:

{
    "content": [
        {
            "id": "052d0dff-c446-4f45-8483-92efd415c3c1",
            "label": null,
            "riskCarrier": "Riskwolf",
            "currency": "USD",
            "simulations": 10000,
            "limit": {
                "amount": 100.00,
                "currency": "USD"
            },
            "expectedLossRatio": 0.65,
            "factSheetReportFileId": "b892ea83-fb96-4095-b731-acf017a985de",
            "technicalPricingReportFileId": "11fd891c-45c1-4d19-9aaa-41b5c291c1af",
            "status": "ACTIVE",
            "uiState": "active",
            "start": "2023-10-01T00:00:00.000+00:00",
            "end": "2024-09-30T00:00:00.000+00:00",
            "createdBy": "sahil.singhal@riskwolf.com",
            "createdAt": "2023-09-17T20:30:34.703+00:00",
            "updatedAt": "2023-11-24T09:36:57.513+00:00",
            "riskType": "Natural > Meteorological > Temperature",
            "riskTypeId": "TEMPERATURE",
            "indexDefinition": "Cumulative daily upward deviation from 40 degrees over the period > Trigger",
            "indexDefinitionId": "00000000-0000-0000-0000-000000000056",
            "triggerUnit": "°C",
            "triggerLabel": "Daily temperature",
            "dataSourceId": "imd",
            "dataSourceDescription": "IMD (India Meteorological Department)",
            "dataSet": "Daily Maximum Temp. (1.0x1.0)",
            "dataSetId": "imd__1deg__tmax",
            "monitoringTarget": "414003 Maharashtra (Cell No. 566)",
            "monitoringTargetId": "ind__566",
            "trigger": 50.0,
            "exit": null,
            "minPayout": {
                "amount": 2.00,
                "currency": "USD"
            },
            "payoutPerUnit": {
                "amount": 2.00,
                "currency": "USD"
            },
            "riskPremium": {
                "amount": 0.00,
                "currency": "USD"
            },
            "riskPremiumPct": 0,
            "grossPremiumIndicationPct": 0.01
        }
    ],
    "pageable": {
        "sort": {
            "unsorted": false,
            "sorted": true,
            "empty": false
        },
        "pageNumber": 0,
        "pageSize": 15,
        "offset": 0,
        "paged": true,
        "unpaged": false
    },
    "totalPages": 1,
    "totalElements": 1,
    "last": false,
    "numberOfElements": 1,
    "first": true,
    "size": 15,
    "number": 0,
    "sort": {
        "unsorted": false,
        "sorted": true,
        "empty": false
    },
    "empty": false
}

Quotes

Create Business Partner

Allowed roles:

  • INTERMEDIARY
  • POLICY_HOLDER
  • RISK_CARRIER
curl --location 'https://demo.riskwolf.com/internal/business-partners' \
--header 'Content-Type: application/json' \
--header 'x-tenant-id: <tenant_id>' \
--header 'Authorization: Bearer <access_token>' \
--data-raw '{
    "@type": "NewBusinessPartner",
    "name": "Apple & Co.",
    "role": "POLICY_HOLDER",
    "contactName": "John Foo",
    "contactEmailAddress": "John.Foo@email.com",
    "contactPhoneNumber": "12345+6789",
    "address": {
        "@type": "NewAddress",
        "countryCode": "au",
        "houseNumber": "586",
        "street": "Little Bourke Street",
        "country": "Australia",
        "county": "Melbourne",
        "postcode": "3000",
        "state": "Victoria",
        "district": "Melbourne",
        "city": "Melbourne",
        "stateCode": "VIC"
    },
    "taxStatus": "NA"
}'

Create quote

curl --location 'https://demo.riskwolf.com/internal/fast-quotes' \
-XPOST \
--header 'Content-Type: application/json' \
--header 'x-tenant-id: <tenant_id>' \
--header 'Authorization: Bearer <access_token>' \
--data-raw '{
    "@type": "NewFastQuote",
    "name": "Test XYZ",
    "customerId": "4939b0b1-5ecf-47b1-b732-44dfdfdc7cab",
    "coverageIds": ["<coverage_id>"],
    "sumInsured": {
        "amount": 10000.0,
        "currency": "USD"
    }
}'

Check quote status

Once the quote is created it will trigger async job to calculate aggregated pricing report and quote document. The status of the job can be checked by calling the following endpoint:

curl --location 'https://demo.riskwolf.com/internal/quotes/<quote_id>' \
--header 'x-tenant-id: <tenant_id>' \
--header 'Authorization: Bearer <access_token>'

And then checking the state field.

Possible values:

  • created: quote has been created, documentation is not yet generated
  • queued: doc generation job is queued
  • running: doc generation job is running
  • completed: job has finished and results can be pulled from the quote. The quote is ready to be converted to a policy draft.
  • accepted: quote has been converted to a policy draft
  • error: there was an error during the async job execution

Policies

Convert quote to policy draft

curl --location 'https://demo.riskwolf.com/internal/policies' \
-XPOST \
--header 'Content-Type: application/json' \
--header 'x-tenant-id: <tenant_id>' \
--header 'Authorization: Bearer <access_token>' \
--data-raw '{
    "@type": "NewPolicyFromQuote",
    "quoteId": "<quote_id>"
}'

Expected response

{
    "@type": "Policy",
    "id": "711e608d-a1c8-4c82-97de-68bbad331fa4",
    "name": "Apples AppleINSURE 413501 undefined",
    "issuer": "Riskwolf AG",
    "customer": "Aon plc",
    "inceptionDate": "2024-03-01T00:00:00.000+00:00",
    "expiryDate": "2024-06-30T00:00:00.000+00:00",
    "status": "CREATED",
    "totalSumInsured": {
        "amount": 800000.00,
        "currency": "INR"
    },
    "riskPremium": {
        "amount": 61600.00,
        "currency": "INR"
    },
    "grossPremium": {
        "amount": 0.00,
        "currency": "INR"
    },
    "grossPremiumRatePct": 0,
    "commission": null,
    "policyItems": [
        {
            "@type": "PolicyItem",
            "id": "c24dd94f-8d69-434d-9df2-c02a2030595c",
            "name": " Rainfall Stress Cover",
            "description": null,
            "quantity": 100,
            "sumInsured": {
                "amount": 8000.00,
                "currency": "INR"
            },
            "totalSumInsured": {
                "amount": 800000.00,
                "currency": "INR"
            },
            "totalMinPayout": {
                "amount": 200000.00,
                "currency": "INR"
            },
            "coverage": {
                "@type": "Coverage",
                "id": "97d150df-7783-4566-9a7e-57438995c081",
                "label": null,
                "riskCarrier": "Riskwolf AG",
                "currency": "USD",
                "simulations": 10000,
                "limit": {
                    "amount": 100.00,
                    "currency": "USD"
                },
                "expectedLossRatio": 0.65,
                "factSheetReportFileId": "12fb07ad-63a1-4f94-904e-739fc62f1d12",
                "technicalPricingReportFileId": "41ed4912-a26e-423a-8752-4c2aa5434ee3",
                "status": "ACTIVE",
                "uiState": "active",
                "start": "2024-03-01T00:00:00.000+00:00",
                "end": "2024-06-30T00:00:00.000+00:00",
                "createdBy": "thomas@riskwolf.com",
                "createdAt": "2023-09-23T03:39:14.703+00:00",
                "updatedAt": "2023-11-15T10:42:54.005+00:00",
                "riskType": "Natural > Meteorological > Rainfall",
                "riskTypeId": "RAINFALL",
                "indexDefinition": "Total rainfall over the period  < Trigger",
                "indexDefinitionId": "00000000-0000-0000-0000-000000000010",
                "triggerUnit": "mm",
                "triggerLabel": "Cumulative rainfall",
                "dataSourceId": "imd",
                "dataSourceDescription": "IMD (India Meteorological Department)",
                "dataSet": "Daily Rainfall (0.25x0.25)",
                "dataSetId": "imd__0.25deg__precip",
                "monitoringTarget": "413501 Maharashtra (Cell No. 10975)",
                "monitoringTargetId": "ind__10975",
                "trigger": 125.0,
                "exit": null,
                "minPayout": {
                    "amount": 25.00,
                    "currency": "USD"
                },
                "payoutPerUnit": {
                    "amount": 2.00,
                    "currency": "USD"
                },
                "riskPremium": {
                    "amount": 7.70,
                    "currency": "USD"
                },
                "riskPremiumPct": 0.077,
                "grossPremiumIndicationPct": 0.1185
            }
        }
    ],
    "sumInsuredBasis": "Revenue loss",
    "exclusions": null,
    "state": "CREATED"
}

Accept policy

curl --location 'https://demo.riskwolf.com/internal/policies/<policy_id>/accept' \
-XPOST \
--header 'Content-Type: application/json' \
--header 'x-tenant-id: <tenant_id>' \
--header 'Authorization: Bearer <access_token>'

Expected response

{
    "@type": "Policy",
    "id": "5438e85c-8ba1-4e0d-a700-4a39af6a234f",
    "name": "Test XYZ",
    "issuer": "Riskwolf AG",
    "customer": "RedBull AG",
    "inceptionDate": "2024-03-01T00:00:00.000+00:00",
    "expiryDate": "2024-06-30T00:00:00.000+00:00",
    "status": "ACCEPTED",
    "totalSumInsured": {
        "amount": 10000.00,
        "currency": "USD"
    },
    "riskPremium": {
        "amount": 770.00,
        "currency": "USD"
    },
    "grossPremium": {
        "amount": 1185.00,
        "currency": "USD"
    },
    "grossPremiumRatePct": null,
    "commission": null,
    "policyItems": [
        {
            "@type": "PolicyItem",
            "id": "b75078b1-8918-4f76-a811-5e2806ada269",
            "name": null,
            "description": null,
            "quantity": 1,
            "sumInsured": {
                "amount": 10000.00,
                "currency": "USD"
            },
            "totalSumInsured": {
                "amount": 10000.00,
                "currency": "USD"
            },
            "totalMinPayout": {
                "amount": 2500.00,
                "currency": "USD"
            },
            "coverage": {
                "@type": "Coverage",
                "id": "97d150df-7783-4566-9a7e-57438995c081",
                "label": null,
                "riskCarrier": "Riskwolf AG",
                "currency": "USD",
                "simulations": 10000,
                "limit": {
                    "amount": 100.00,
                    "currency": "USD"
                },
                "expectedLossRatio": 0.65,
                "factSheetReportFileId": "12fb07ad-63a1-4f94-904e-739fc62f1d12",
                "technicalPricingReportFileId": "41ed4912-a26e-423a-8752-4c2aa5434ee3",
                "status": "ACTIVE",
                "uiState": "active",
                "start": "2024-03-01T00:00:00.000+00:00",
                "end": "2024-06-30T00:00:00.000+00:00",
                "createdBy": "thomas@riskwolf.com",
                "createdAt": "2023-09-23T03:39:14.703+00:00",
                "updatedAt": "2023-11-15T10:42:54.005+00:00",
                "riskType": "Natural > Meteorological > Rainfall",
                "riskTypeId": "RAINFALL",
                "indexDefinition": "Total rainfall over the period  < Trigger",
                "indexDefinitionId": "00000000-0000-0000-0000-000000000010",
                "triggerUnit": "mm",
                "triggerLabel": "Cumulative rainfall",
                "dataSourceId": "imd",
                "dataSourceDescription": "IMD (India Meteorological Department)",
                "dataSet": "Daily Rainfall (0.25x0.25)",
                "dataSetId": "imd__0.25deg__precip",
                "monitoringTarget": "413501 Maharashtra (Cell No. 10975)",
                "monitoringTargetId": "ind__10975",
                "trigger": 125.0,
                "exit": null,
                "minPayout": {
                    "amount": 25.00,
                    "currency": "USD"
                },
                "payoutPerUnit": {
                    "amount": 2.00,
                    "currency": "USD"
                },
                "riskPremium": {
                    "amount": 7.70,
                    "currency": "USD"
                },
                "riskPremiumPct": 0.077,
                "grossPremiumIndicationPct": 0.1185
            }
        }
    ],
    "policyScheduleDocumentId": null,
    "activatedAt": "2023-11-29T15:38:30.118520366Z",
    "signatureConfirmed": true,
    "sumInsuredBasis": null,
    "exclusions": null,
    "state": "ACCEPTED"
}