Walnut Partner API – TypeScript SDK

TypeScript/JavaScript SDK for the Walnut Partner API. Use it to create referrals, manage customers, and integrate Walnut insurance products (card, digital protection, group tenant, home warranty, creditor, cobrand, headless) from your own backend or scripts.

Install

npm install @walnut-insurance/partner-api

Authentication

The Partner API uses API keys. Pass your key when creating the client. Do not commit API keys to source control; use environment variables or a secrets manager.

• Get your API key from Walnut.
• Use header x-api-key (the SDK sets this automatically from your config).

Quick start

import { WalnutPartnerApi } from '@walnut-insurance/partner-api';

const api = new WalnutPartnerApi({
  apiKey: process.env.WALNUT_API_KEY!,
  environment: 'production', // or 'staging' for test
});

// Create a customer
const { id } = await api.customers.create({
  firstName: 'Jane',
  lastName: 'Doe',
  email: '[email protected]',
});

// Create a home referral (returns checkout URL for the customer)
const ref = await api.referrals.createHomeReferral({
  email: '[email protected]',
  address: { streetNum: '123', streetName: 'Main St', city: 'Toronto', province: 'ON', postalCode: 'M5V 1A1' },
  owners: [{ firstName: 'Joe', lastName: 'Smith', currentAddress: { ... } }],
  coverageStart: '2025-03-01',
});
console.log(ref.checkoutUrl); // redirect user here

Environment / Base URL

Configure the environment to pick the base URL, or pass a custom baseUrl:

| Environment | Base URL | |---------------|-----------------------------------| | production | https://partner.api.gowalnut.com (default) | | staging | https://partner.api.gowalnut.xyz |

// Use staging (test) environment
const api = new WalnutPartnerApi({
  apiKey: process.env.WALNUT_API_KEY!,
  environment: 'staging',
});

// Production is the default; you can set it explicitly
const prodApi = new WalnutPartnerApi({
  apiKey: process.env.WALNUT_API_KEY!,
  environment: 'production',
});

// Or override with a custom base URL (e.g. for a proxy or local dev)
const customApi = new WalnutPartnerApi({
  apiKey: process.env.WALNUT_API_KEY!,
  baseUrl: 'https://partner.api.gowalnut.xyz',
});

Constants PRODUCTION_BASE_URL and STAGING_BASE_URL are exported if you need the URLs elsewhere.

API overview

| Area | Description | |------|-------------| | Customers | Create, get, update, delete customers; list memberships | | Card | Card insurance memberships and claims under a customer | | Digital | Digital protection memberships under a customer | | Group tenant | Quotes, users, coverages, certificates (e.g. income protection group) | | Referrals | Home, travel, tenant, group-tenant, bill payment protection, PNC referrals; get user coverage | | Cobrand / Headless | Proxy APIs for cobrand and headless integrations | | Creditor | Bill payment protection and other creditor endpoints (proxy) | | Home warranty | Create user, add/update coverage (proxy) |

Customers

await api.customers.create({ firstName, lastName, email, phone?, address?, ... });
await api.customers.get(customerId);
await api.customers.getMemberships(customerId);
await api.customers.update(customerId, { firstName, ... });
await api.customers.delete(customerId);

Card insurance (per customer)

const cardApi = api.card(customerId);
await cardApi.createMembership(body);
await cardApi.listMemberships();
await cardApi.getMembership(membershipId);
await cardApi.updateMembership(membershipId, body);
await cardApi.deleteMembership(membershipId);
await cardApi.createClaim(membershipId, body);
await cardApi.addClaimAttachment(membershipId, claimId, body);
await cardApi.getClaimAttachmentUrl(membershipId, claimId, attachmentId);

Digital protection (per customer)

const digitalApi = api.digital(customerId);
await digitalApi.createMembership(body);
await digitalApi.listMemberships();
await digitalApi.getMembership(membershipId);
await digitalApi.deleteMembership(membershipId);

Group tenant

await api.groupTenant.getQuote({ address: { ... } }); // or leadId + groupTenantLeadId
await api.groupTenant.createUser(body);
await api.groupTenant.getUser(userId);
await api.groupTenant.addCoverage(userId, body);
await api.groupTenant.updateUser(userId, body);
await api.groupTenant.deleteUser(userId);
await api.groupTenant.updatePolicyCoverage(userId, policyId, body);
await api.groupTenant.getPolicyCertificate(userId, policyId);
await api.groupTenant.deletePolicyCoverage(userId, policyId);
await api.groupTenant.getUserCertificate(userId);

Referrals

await api.referrals.createHomeReferral(body);
await api.referrals.createTravelReferral(body);
await api.referrals.createTenantReferral(body);
await api.referrals.createGroupTenantReferral(body);
await api.referrals.createBillPaymentProtectionReferral(body);
await api.referrals.createPncReferral(body);
await api.referrals.getPncReferral(id);
await api.referrals.getUserCoverage(userId);

Cobrand / Headless / Creditor / Home warranty

For proxy-style APIs you can use the typed helpers or a generic request:

await api.cobrand.createUser(body);
await api.cobrand.request('GET', '/some/path');

await api.headless.createUser(body);
await api.headless.request('POST', '/path', body);

await api.creditor.request('POST', '/bill-payment/...', body);

await api.homeWarranty.createUser(body);
await api.homeWarranty.addCoverage(userId, body);
await api.homeWarranty.updateCoverage(userId, policyId, body);
await api.homeWarranty.request('GET', '/path');

Error handling

Failed requests throw PartnerApiError with message, status, and optional body:

import { WalnutPartnerApi, PartnerApiError } from '@walnut-insurance/partner-api';

try {
  await api.customers.get(invalidId);
} catch (err) {
  if (err instanceof PartnerApiError) {
    console.error(err.status, err.body);
  }
  throw err;
}

Types

The package exports TypeScript types for requests and responses (e.g. CustomerBase, CreateReferralResponse, Address). Use them for type-safe payloads and responses.

License

MIT