YAPU SNAP — Gross Climate Risk API

YAPU SNAP is YAPU's standalone REST API for assessing physical climate risk at the borrower level. It accepts a geographic coordinate, a set of active economic sectors, and sector-specific sensitivity parameters, and returns structured climate risk scores — Exposure, Sensitivity, and a Global Net Risk — across five hazard types, per sector, in real time.

YAPU SNAP is purpose-built for financial institutions that need to embed standardized climate risk intelligence into loan origination or portfolio monitoring workflows without requiring the full YAPU platform.

:::tip Sandbox environment A sandbox environment is available for integration testing. Contact your YAPU implementation specialist for the sandbox API key — do not use production credentials for testing. :::

How it works

Your system sends a POST request containing:

Personal details — borrower identification (echoed back in the response)
Economic activities — which sectors to assess (Yes / No per activity type)
Exposure — the geographic coordinates of the loan location
Sensitivity — detailed parameters for each active sector (crop types, livestock species, construction materials, etc.)

The API performs a geospatial hazard lookup at the submitted coordinates and computes climate risk scores for each active sector. Sectors not included in loan_purposes as "Yes" are not scored.

[Your System]
  │  POST /api/v2/fge/single/execute  (Bearer token + full JSON payload)
  ▼
[API Gateway]
  │  Authenticates token · Validates payload
  ▼
[Climate Engine]
  │  Geospatial hazard lookup (5 hazards) · Resolves Exposure by coordinates
  │  Resolves Sensitivity per active sector + submitted parameters
  ▼
[Response Layer]
  │  Packages per-sector scores + global net risk · Echoes input fields
  ▼
[Your System]
  │  Receives structured JSON → display or downstream processing

Base URLs

Environment	Base URL
Sandbox	`https://yapu-development-su.herokuapp.com`
Production	Provided by your YAPU account manager at production sign-off

Authentication

All requests require a valid Bearer token in the Authorization header. Tokens are issued per institution and per environment — sandbox and production keys are not interchangeable.

Authorization: Bearer <your_api_key>
Content-Type: application/json

:::warning Keep your API key secure API keys carry full access privileges. Never hardcode a key in source code, commit it to version control, or expose it in client-side code. Keys are available from your YAPU administrator and can be rotated on request. :::

See Authentication & Security for the full security architecture.

Endpoint

`POST /api/v2/fge/single/execute`

Submits borrower details, active economic sectors, geographic coordinates, and sector sensitivity parameters. Returns per-sector Exposure and Sensitivity scores across five hazard types, plus a Global Net Risk score.

Request headers

Header	Required	Value
`Authorization`	Yes	`Bearer <api_key>`
`Content-Type`	Yes	`application/json`

Request body structure

The request body has four top-level sections:

Section	Required	Description
`personal_details`	Yes	Borrower identification fields — echoed back in the response
`economic_activities`	Yes	Defines which economic sectors to assess
`exposure`	Yes	Geographic coordinates of the loan or asset location
`sensitivity`	Yes	Sector-specific parameters used to calculate sensitivity scores

`personal_details`

Field	Type	Description
`name`	string	Borrower first name
`last_name`	string	Borrower last name
`client_id_number`	string	Borrower identifier in the client system
`gender`	string	Borrower gender (`"Male"` or `"Female"`)

`economic_activities.loan_purposes`

Defines which sectors are included in the climate risk assessment. Set each sector to "Yes" to include it, or omit / set to "No" to exclude it.

Field	Type	Values	Description
`agriculture`	string	`"Yes"` / `"No"`	Include crop-based agriculture in assessment
`livestock`	string	`"Yes"` / `"No"`	Include livestock/animal husbandry
`trade`	string	`"Yes"` / `"No"`	Include commercial trade activities
`services`	string	`"Yes"` / `"No"`	Include service-sector activities
`manufacturing`	string	`"Yes"` / `"No"`	Include manufacturing activities
`housing`	string	`"Yes"` / `"No"`	Include residential housing

`exposure`

Field	Type	Required	Description
`geolocation`	string	Yes	Geographic coordinates formatted as `"latitude,longitude"` in decimal degrees (WGS84). Latitude: `-90.0` to `90.0`. Longitude: `-180.0` to `180.0`.

`sensitivity`

The sensitivity section contains one subsection per sector. Only include subsections for sectors set to "Yes" in loan_purposes. Unused sectors are ignored.

sensitivity.agriculture — up to three crops:

Field	Description
`crop_1.name`, `crop_2.name`, `crop_3.name`	Crop species names. Must match values from the YAPU taxonomy list.

sensitivity.livestock — up to three livestock types:

Field	Description
`item_1.name`, `item_2.name`, `item_3.name`	Livestock species names. Must match values from the YAPU taxonomy list.

sensitivity.trade — up to three trade activities:

Field	Description
`activity_1.name`, `activity_2.name`, `activity_3.name`	Trade activity names. Must match values from the YAPU taxonomy list.

sensitivity.services — up to three service activities:

Field	Description
`service_1.name`, `service_2.name`, `service_3.name`	Service type names. Must match values from the YAPU taxonomy list.

sensitivity.manufacturing — up to three manufacturing activities:

Field	Description
`activity_1.name`, `activity_2.name`, `activity_3.name`	Manufacturing activity names. Must match values from the YAPU taxonomy list.

sensitivity.housing — physical construction parameters:

Field	Description
`construction_quality`	Overall construction quality (e.g., `"Formal"`, `"Informal"`)
`foundation_type`	Foundation type (e.g., `"Shallow"`, `"Deep"`)
`walls_type`	Wall structural type (e.g., `"Reinforced"`, `"Unreinforced"`)
`roof_type`	Roof structural type
`foundation_material`	Foundation material (e.g., `"Concrete"`, `"Wood"`)
`wall_material`	Wall material
`roof_material`	Roof material (e.g., `"Concrete tiles"`, `"Metal sheet"`)

:::note Taxonomy values All names and categorical values in the sensitivity section must exactly match entries in the YAPU taxonomy list, which is provided during onboarding. Values that do not match a valid entry return a 400 Bad Request. YAPU's onboarding team supports the mapping of your internal labels to taxonomy values. :::

Request example

POST /api/v2/fge/single/execute HTTP/1.1
Host: yapu-development-su.herokuapp.com
Authorization: Bearer <your_sandbox_api_key>
Content-Type: application/json

{
  "personal_details": {
    "name": "Maria",
    "last_name": "Lopez",
    "client_id_number": "12345678",
    "gender": "Female"
  },
  "economic_activities": {
    "loan_purposes": {
      "agriculture": "Yes",
      "livestock": "Yes",
      "trade": "Yes",
      "services": "Yes",
      "manufacturing": "Yes",
      "housing": "Yes"
    }
  },
  "exposure": {
    "geolocation": "-0.30890461568653893,-78.5483719923041"
  },
  "sensitivity": {
    "agriculture": {
      "crop_1": { "name": "Corn" },
      "crop_2": { "name": "Cucumber" },
      "crop_3": { "name": "Onions" }
    },
    "livestock": {
      "item_1": { "name": "Beef cattle" },
      "item_2": { "name": "Breeding pigs" },
      "item_3": { "name": "Dairy cattle" }
    },
    "trade": {
      "activity_1": { "name": "Bakery" },
      "activity_2": { "name": "Bookstores" },
      "activity_3": { "name": "Candy Sale" }
    },
    "services": {
      "service_1": { "name": "Construction" },
      "service_2": { "name": "Credits and finance" },
      "service_3": { "name": "Delivery Services" }
    },
    "manufacturing": {
      "activity_1": { "name": "Agricultural products" },
      "activity_2": { "name": "Agrochemical production" },
      "activity_3": { "name": "Alcohol production" }
    },
    "housing": {
      "construction_quality": "Formal",
      "foundation_type": "Shallow",
      "walls_type": "Reinforced",
      "roof_type": "Map",
      "foundation_material": "Wood",
      "wall_material": "Wood",
      "roof_material": "Concrete tiles"
    }
  }
}

Successful response

HTTP Status: 200 OK

The response echoes the full input payload and appends a yapu_result array containing:

A customer_exposure object with location-level hazard scores
One sensitivity object per active sector
A GlobalNetRisk aggregate score (0–1 scale)

{
  "personal_details": {
    "name": "Maria",
    "last_name": "Lopez",
    "client_id_number": "12345678",
    "gender": "Female"
  },
  "economic_activities": {
    "loan_purposes": {
      "agriculture": "Yes",
      "livestock": "Yes",
      "trade": "Yes",
      "services": "Yes",
      "manufacturing": "Yes",
      "housing": "Yes"
    }
  },
  "exposure": {
    "geolocation": "-0.30890461568653893,-78.5483719923041"
  },
  "sensitivity": { "...": "input echoed back" },
  "yapu_result": [
    {
      "customer_exposure": {
        "rowsTitles": ["Exposure"],
        "columnTitles": ["Drought", "Frost", "Heat", "Flood", "Storm"],
        "value": [[3, 1, 3.92, 2.83, 2.08]]
      }
    },
    {
      "agriculture": {
        "rowsTitles": ["Sensitivity"],
        "columnTitles": ["Drought", "Frost", "Extreme Heat", "Flood", "Storm"],
        "value": [[2.82, 2.76, 2.68, 2.44, 2.06]]
      }
    },
    {
      "livestock": {
        "rowsTitles": ["Sensitivity"],
        "columnTitles": ["Drought", "Frost", "Extreme Heat", "Flood", "Storm"],
        "value": [[2.78, 2.28, 2, 3.05, 2.9]]
      }
    },
    {
      "trade": {
        "rowsTitles": ["Sensitivity"],
        "columnTitles": ["Drought", "Frost", "Extreme Heat", "Flood", "Storm"],
        "value": [[2, 2, 2, 4.33, 3.33]]
      }
    },
    {
      "services": {
        "rowsTitles": ["Sensitivity"],
        "columnTitles": ["Drought", "Frost", "Extreme Heat", "Flood", "Storm"],
        "value": [[2, 2.33, 2.67, 3.67, 3]]
      }
    },
    {
      "manufacturing": {
        "rowsTitles": ["Sensitivity"],
        "columnTitles": ["Drought", "Frost", "Extreme Heat", "Flood", "Storm"],
        "value": [[4.27, 2.8, 3.6, 4.87, 3.37]]
      }
    },
    {
      "housing": {
        "rowsTitles": ["Sensitivity"],
        "columnTitles": ["Drought", "Frost", "Extreme Heat", "Flood", "Storm"],
        "value": [[1.05, 1.65, 1.2, 2.7, 2.4]]
      }
    },
    {
      "GlobalNetRisk": 0.26
    }
  ]
}

Response fields

Echoed input fields

The response body repeats personal_details, economic_activities, exposure, and sensitivity exactly as submitted. Use these to validate request/response alignment in your system.

`yapu_result` array

yapu_result is an ordered array. The first element is always customer_exposure. The following elements are one object per active sector (in submission order). The final element is always GlobalNetRisk.

customer_exposure object:

Field	Type	Description
`rowsTitles`	string[]	Always `["Exposure"]`
`columnTitles`	string[]	Hazard types: `Drought`, `Frost`, `Heat`, `Flood`, `Storm`
`value`	number[][]	Single row of five exposure scores, one per hazard. Scores reflect the physical hazard intensity at the submitted geolocation.

Per-sector sensitivity objects (agriculture, livestock, trade, services, manufacturing, housing):

Field	Type	Description
`rowsTitles`	string[]	Always `["Sensitivity"]`
`columnTitles`	string[]	Hazard types: `Drought`, `Frost`, `Extreme Heat`, `Flood`, `Storm`
`value`	number[][]	Single row of five sensitivity scores, averaged across the submitted items for that sector.

GlobalNetRisk object:

Field	Type	Description
`GlobalNetRisk`	number	Aggregate net climate risk score across all active sectors and hazards. Range: `0.0` (no risk) to `1.0` (maximum risk).

Reading the response

Exposure scores

The customer_exposure values represent the physical hazard intensity at the submitted location, on a scale of 1–5:

Score range	Interpretation
1.0 – 2.0	Low exposure
2.1 – 3.0	Moderate exposure
3.1 – 4.0	High exposure
4.1 – 5.0	Very high exposure

Example from sample response — at coordinates -0.309, -78.548 (Ecuador):

Hazard	Exposure score	Interpretation
Drought	3.0	High
Frost	1.0	Low
Heat	3.92	High
Flood	2.83	Moderate
Storm	2.08	Moderate

Sector sensitivity scores

Each active sector returns a sensitivity score per hazard on a 1–5 scale. Higher scores indicate greater vulnerability of that activity type to the hazard.

Example — manufacturing sensitivity:

Hazard	Score	Interpretation
Drought	4.27	Very high sensitivity
Frost	2.80	Moderate
Extreme Heat	3.60	High
Flood	4.87	Very high sensitivity
Storm	3.37	High

Global Net Risk

GlobalNetRisk is a single composite score that combines Exposure and Sensitivity across all active sectors and hazards:

Score range	Interpretation
0.00 – 0.25	Low overall climate risk
0.26 – 0.50	Moderate
0.51 – 0.75	High
0.76 – 1.00	Very high

In the sample response, GlobalNetRisk: 0.26 places this borrower at the lower boundary of moderate risk.

Gross climate risk: conceptual definition

Exposure measures how physically affected a geographic location is by each climate hazard, based on historical frequency, intensity, and spatial distribution at the submitted coordinates. The same coordinates produce the same exposure scores regardless of sector.

Sensitivity measures how vulnerable a specific economic activity is to each hazard, given the parameters submitted (crop types, livestock species, construction materials, etc.). Two borrowers at the same location but with different activities will have different sensitivity profiles.

Global Net Risk is YAPU's composite indicator that synthesizes Exposure and Sensitivity across all active sectors and hazard types into a single 0–1 score, enabling straightforward portfolio-level comparison and reporting.

:::note Gross vs. comprehensive assessment YAPU SNAP provides a gross (rapid) assessment. For a comprehensive climate risk analysis that includes adaptive capacity modelling and full questionnaire-based data collection, refer to the YAPU standard platform and API bundles. :::

Error responses

HTTP Status	Condition	Recommended action
`400 Bad Request`	Missing required field, malformed payload, invalid geolocation format, or taxonomy value not recognized	Check field names and types. Verify all `sensitivity` values match the YAPU taxonomy list exactly.
`401 Unauthorized`	Bearer token missing, invalid, or expired	Confirm `Authorization: Bearer <key>` header is present. Confirm correct key for the target environment.
`402 Payment Required`	Subscription or quota limit reached	Contact your YAPU account manager.
`403 Forbidden`	Token valid but lacks permission for this operation	Contact your YAPU administrator to review access permissions.
`404 Not Found`	Endpoint path incorrect	Verify the endpoint path exactly: `POST /api/v2/fge/single/execute`.
`429 Too Many Requests`	Per-key rate limit exceeded	Read the `Retry-After` header and wait the specified duration.
`500 / 502 / 503 / 504`	Server-side error	Retry with exponential backoff (max 3 attempts). Contact YAPU support if persistent.

Common failure scenarios

Symptom	Likely cause	Resolution
`401` on every request	Missing `Bearer` prefix, wrong API key, or wrong environment key	Confirm header format: `Bearer <key>` (space after `Bearer`). Confirm sandbox vs. production key.
`400` on sensitivity field	Taxonomy value does not match exactly	Verify against taxonomy list provided during onboarding. Values are case-sensitive.
`400` on geolocation	Coordinates out of valid range or wrong format	Confirm format: `"latitude,longitude"`. Latitude `-90.0` to `90.0`, longitude `-180.0` to `180.0`.
No sectors scored	All `loan_purposes` set to `"No"` or omitted	Set at least one sector to `"Yes"` in `loan_purposes`.
`500` persisting	YAPU infrastructure issue	Contact YAPU support.

Retry logic

Status	Behavior
`429`	Read `Retry-After` header. Wait exactly that many seconds before retrying.
`500 / 502 / 503 / 504`	Exponential backoff: 1s → 2s → 4s. Maximum 3 retries before escalating to YAPU support.
`400` / `401`	Deterministic — fix the root cause before retrying. The same request will return the same error.

Integration patterns

Pattern	Description	Best for
A — Inline Assessment (Recommended)	API called synchronously during loan application. Scores displayed to loan officer before credit decision.	Modern, digital-first LOS platforms.
B — Batch Assessment	API called in bulk for existing portfolio records, sequentially or in parallel.	Legacy environments where real-time calls are not feasible.
C — Periodic Refresh	Climate risk re-assessed for active loans on a defined schedule (e.g., quarterly).	Ongoing portfolio-level monitoring.

Performance targets

Metric	Target
API response latency (P95)	≤ 800 ms per request
System throughput	500 concurrent requests without degradation
Monthly uptime SLA	≥ 99.5%
System error rate (5xx)	≤ 0.1% of requests

Limitations and considerations

Dynamic IP — YAPU does not support static IP addresses. Do not configure client-side IP allowlists to fixed YAPU IPs. Contact YAPU during onboarding if your IT security policy requires outbound allowlisting.
HTTPS required — all requests must use HTTPS. Plain HTTP requests are not processed.
Taxonomy values — all sensitivity field values must exactly match the YAPU taxonomy list provided during onboarding. YAPU's onboarding team supports the mapping of your internal labels.
Single questionnaire per integration — applicable when combining SNAP with standard API bundles.
Sandbox credentials — sandbox API keys are provided by YAPU and must not be used in production environments.

Getting Started — how to begin the integration process
API Concepts — REST, JSON, HTTPS, and YAPU data conventions
Authentication & Security — full security architecture
Integration Process — delivery phases, timelines, and responsibilities
Support & Contact — reach your YAPU representative

How it works​

Base URLs​

Authentication​

Endpoint​

POST /api/v2/fge/single/execute​

Request headers​

Request body structure​

personal_details​

economic_activities.loan_purposes​

exposure​

sensitivity​

Request example​

Successful response​

Response fields​

Echoed input fields​

yapu_result array​

Reading the response​

Exposure scores​

Sector sensitivity scores​

Global Net Risk​

Gross climate risk: conceptual definition​

Error responses​

Common failure scenarios​

Retry logic​

Integration patterns​

Performance targets​

Limitations and considerations​

Related resources​