Onboarding your organization

From signup to a verified organization with recorded underwriting capacity.

Before you can sell cover, your organization must be created, KYB-verified (which includes your insurance regulator’s operating licence), and have underwriting capacity recorded by MicroCrop. This is a one-time setup.

1. Create the account

Self-service signup creates your organization and its first admin user, and returns login tokens and your API key:

curl -X POST https://app.microcrop.app/api/auth/register-organization \
  -H "Content-Type: application/json" \
  -d '{
    "organizationName": "Acme Insurance Ltd",
    "registrationNumber": "C.12345",
    "type": "INSURANCE_COMPANY",
    "countryCode": "KE",
    "county": "Nairobi",
    "firstName": "Asha",
    "lastName": "Otieno",
    "email": "[e-mail]",
    "password": "••••••••",
    "phone": "[phone]"
  }'

• type is one of COOPERATIVE, NGO, MFI, INSURANCE_COMPANY, GOVERNMENT, OTHER.
• countryCode is KE or GH (defaults to KE). It drives your market currency, the KYB document set and your regulator.
• password must be at least 8 characters with an uppercase letter, a digit and a special character.
• The new organization starts at kybStatus: NOT_STARTED and serviceTier: DETERMINATION.

{ "success": true, "data": {
  "organization": { "id": "…", "apiKey": "…", "kybStatus": "NOT_STARTED", "serviceTier": "DETERMINATION" },
  "user": { "…": "…" }, "accessToken": "…", "refreshToken": "…"
} }

Copy data.organization.apiKey now. GET /api/organizations/me strips it. If you lose it, mint a new one with POST /api/organizations/me/api-key/rotate. See Authentication.

2. Check what your market requires

curl https://app.microcrop.app/api/organizations/me/kyb -H "x-api-key: $KEY"

{ "success": true, "data": {
  "kybStatus": "NOT_STARTED",
  "onboardingStep": "KYB_VERIFICATION",
  "countryCode": "KE",
  "checklist": {
    "regulator": "IRA",
    "regulatorLicenseRequired": true,
    "regulatorLicenseDocType": "IRA_LICENSE",
    "livestockEnabled": true,
    "requiredDocuments": [
      { "documentType": "BUSINESS_REGISTRATION", "required": true, "satisfied": false },
      { "documentType": "TAX_CERTIFICATE",       "required": true, "satisfied": false },
      { "documentType": "IRA_LICENSE",           "required": true, "satisfied": false }
    ],
    "optionalDocuments": [ { "documentType": "PROOF_OF_ADDRESS", "…": "…" } ]
  },
  "verification": null
} }

checklist is the authority — read it rather than hard-coding a document set.

Market	Required documents	Regulator
Kenya (KE)	Business registration, KRA PIN tax certificate, IRA operating licence	IRA
Ghana (GH)	NIC operating licence, Certificate of Incorporation, Ghana TIN, director’s Ghana Card	NIC

3. Submit KYB documents

Multipart upload. The file field names map to document types:

Field	Document type
businessRegistrationCert	BUSINESS_REGISTRATION
taxPinCert	TAX_CERTIFICATE
iraLicenseCert	IRA_LICENSE
nicLicenseCert	NIC_LICENSE
certificateOfIncorporation	CERTIFICATE_OF_INCORPORATION
ghanaTin	GHANA_TIN
directorId	DIRECTOR_ID
proofOfAddress	PROOF_OF_ADDRESS
bankStatement	BANK_STATEMENT
otherDocument	OTHER

Send the licence number and expiry as ordinary form fields alongside the files:

curl -X POST https://app.microcrop.app/api/organizations/me/kyb \
  -H "x-api-key: $KEY" \
  -F "businessRegistrationCert=@business-reg.pdf" \
  -F "taxPinCert=@kra-pin.pdf" \
  -F "iraLicenseCert=@ira-licence.pdf" \
  -F "regulatorLicenseNumber=IRA/12/3456" \
  -F "licenseExpiresAt=2027-12-31"

licenseExpiresAt must be an ISO date in the future. Files must be PDF, JPEG or PNG and at most 10 MB each.

Requires ORG_ADMIN. Status moves to PENDING_REVIEW. Poll the same path with GET:

curl https://app.microcrop.app/api/organizations/me/kyb -H "x-api-key: $KEY"
# data.kybStatus: NOT_STARTED → PENDING_REVIEW → VERIFIED | REJECTED

A resubmission only needs the documents you are replacing — documents already on file count toward the required set.

Missing a required document returns 400 naming exactly which ones are missing. A verified organization whose regulator licence was never captured, or has lapsed, is still blocked from selling with 403 REGULATOR_LICENSE_REQUIRED / 403 REGULATOR_LICENSE_EXPIRED.

4. Have your underwriting capacity recorded

MicroCrop does not hold your capital. Before you can sell, a MicroCrop administrator records a solvency attestation: the maximum aggregate sum insured your off-platform capital stands behind, in one currency, for a bounded period, on named evidence.

There is no partner endpoint for this — send MicroCrop the treaty, trust statement, letter of credit, bank guarantee, proof of funds or regulator solvency return you want it recorded against, with the effective window and a signing officer. Until a live attestation exists, POST /api/policies/purchase is refused:

{ "success": false, "error": { "code": "INVALID_INPUT",
  "message": "This organization has no recorded solvency attestation. A platform administrator must record attested off-platform capacity before any cover can be sold. Contact MicroCrop to record or restate the attestation." } }

Over-capacity, expired, revoked, not-yet-effective and currency-mismatch each produce a distinct message naming the condition — see Requirements.

There is no POST /me/wallet/fund, POST /me/reserve/deposit or GET /me/reserve. Those endpoints were removed with the non-custodial model and now 404.

5. Confirm your service tier

curl https://app.microcrop.app/api/organizations/me -H "x-api-key: $KEY"
# → data.serviceTier: "DETERMINATION" | "DETERMINATION_AND_SETTLEMENT"
# → data.kybStatus, data.countryCode, data.isActive

New organizations start on DETERMINATION. Which tier you are on decides who settles the farmer, and it is stamped onto every policy at purchase — see Service tiers.

6. Configure webhooks (recommended)

curl -X PUT https://app.microcrop.app/api/organizations/me/webhook \
  -H "x-api-key: $KEY" -H "Content-Type: application/json" \
  -d '{ "url": "https://your-system.example.com/microcrop/webhooks" }'

See Webhooks.

You’re now ready to register farmers and sell policies — and, on Tier 1, to follow the Tier 1 integration guide.