Skip to content

Getting Started with API Integration

This guide will walk you through the essential steps to integrate with Riskwolf's API for parametric insurance solutions. Whether you're building crop insurance, travel insurance, or other weather-based coverage products, this guide provides a clear path to get started.

Prerequisites

Before you begin, ensure you have:

  • API Credentials: Contact your Riskwolf representative to obtain:
    • Client App ID
    • Client Secret
    • Server App ID
    • Tenant ID
    • Environment URL
  • Development Environment: Set up your preferred development environment
  • Basic Understanding: Familiarity with REST APIs and JSON

Step 1: Authentication Setup

Riskwolf uses OAuth2 authentication with Microsoft Authentication Library (MSAL).

Quick Test Authentication

For testing purposes, you can obtain a token using curl:

#!/bin/bash
CLIENT_APP_ID='your-client-id'
CLIENT_SECRET='your-secret' # pragma: allowlist secret
SERVER_APP_ID='your-server-app-id'
TENANT_ID='your-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'

Production Authentication

For production applications, implement proper OAuth2 flow using MSAL libraries for your programming language. See the Microsoft documentation for detailed implementation guides.

Step 2: Configure Base URL and Headers

Set up your API client with the correct base URL and headers:

Base URL: https://{environment}.riskwolf.com/external
Headers:
  - Authorization: Bearer {your-access-token}
  - x-tenant-id: {your-tenant-id}
  - Content-Type: application/json

Step 3: Your First API Call

Let's start with a simple test to verify your setup by listing available index definitions:

curl -X GET "https://your-environment.riskwolf.com/external/index-definitions" \
  -H "Authorization: Bearer your-access-token" \
  -H "x-tenant-id: your-tenant-id"

If successful, you'll receive a JSON response with available weather indices.

Next Steps

Now that you have the basics working, explore these areas:

Learn More About API Operations

Explore Use Case Examples

Error Handling

Common Integration Patterns

Pattern 1: Simple Quote-to-Policy Flow

  1. Create quote → 2. Review pricing → 3. Convert to policy → 4. Activate policy

Pattern 2: Bulk Operations

  1. Upload multiple coverages → 2. Create program → 3. Generate multiple quotes → 4. Batch policy creation

Pattern 3: Monitoring and Claims

  1. Active policy monitoring → 2. Trigger detection → 3. Claim processing → 4. Payout calculation

Getting Help

Troubleshooting

Common Issues

Authentication Errors (401)

  • Verify your credentials are correct
  • Check that your token hasn't expired
  • Ensure you're using the correct tenant ID

Not Found Errors (404)

  • Verify the base URL is correct for your environment
  • Check that the endpoint path is accurate
  • Ensure the resource ID exists

Bad Request Errors (400)

  • Validate your JSON payload structure
  • Check required parameters are included
  • Verify data types match the API specification

For detailed error handling, see the Error Handling Guide.