CanIBuildHere API
Integrate project-aware planning and property screening into an agreed internal, CRM or property-listing workflow.
API Pricing & Credits
CanIBuildHere APIs use prepaid team credits. Creating a new check or refreshing source data deducts credits; read-only access and configured placement updates do not normally deduct a report credit.
Portal names and listing URLs in the examples below are illustrative payloads, not a statement that a live commercial integration or native badge entitlement exists with that platform.
Credit Consumption Rules
Public Trade Pricing
API sandbox credentials are provided automatically. Live authentication requires an active organization with paid credits or a paid monthly plan. See the Pricing Page for details, or contact us to discuss high-volume integration mapping.
Authentication
All requests must include your API key as a bearer token in the HTTP authorization header. Retrieve keys from your dashboard settings.
API Reference
Use these endpoints to orchestrate private pre-listing screens, trigger updates, sync badge placements, and configure custom context.
/api/site-checksCreate a new site check by coordinates. Initializes a private pre-listing screen by default. Reusing an existing fresh check consumes 0 credits.
{
"latitude": 53.225054,
"longitude": -8.841205,
"project_type": "I want to build a one-off house",
"product_type": "private_screen",
"source": "agent_crm",
"external_listing_ref": "SITE-123",
"site_name": "Cois Na Habhainn, Galway"
}{
"success": true,
"reused_existing": false,
"recommended_action": "use_new_report",
"site_check_id": "CIBH-12345",
"report_version": 1,
"risk_level": "medium",
"cibh_risk_score": "medium",
"badge_label": "Checks recommended",
"headline": "Flood risk and zoning indicators found",
"summary": "This site is zoned residential but has moderate flood risk indicators.",
"checked_at": "2026-06-18T00:00:00Z",
"valid_until": "2026-09-18T00:00:00Z",
"freshness_status": "fresh",
"workflow_stage": "private_screen",
"visibility_status": "private_internal",
"agent_decision": "keep_private",
"listing_readiness": "needs_planner_review",
"seller_questions": [
"Has a site flood assessment been conducted?",
"Is there local planning history on this parcel?"
],
"suggested_next_action": "Consult local planning guidelines regarding zone A/B flood limits.",
"public_badge_report_eligibility": false,
"report_url": "https://www.canibuildhere.ie/reports/CIBH-12345"
}/api/site-checks/{site_check_id}/badgeRetrieve the current badge display status, risk levels, and any placement entitlement configured for an agreed partner integration.
URL Path Parameters:
- site_check_id (string): The public ID of the site check.
Query Parameters:
- platform (string, optional): Filter by platform to retrieve matching entitlement.
{
"site_check_id": "CIBH-12345",
"current_report_version": 1,
"risk_level": "medium",
"badge_label": "Checks recommended",
"badge_mode": "checks_recommended",
"headline": "Flood risk and zoning indicators found",
"summary": "Moderate indicators present.",
"workflow_stage": "public_listing_pack",
"visibility_status": "public_full",
"agent_decision": "publish_with_badge",
"agent_context_visibility": "public",
"agent_context_note": "Zoning verified. Buyer should verify planning caveats.",
"platform": "daft",
"entitlement_status": "active",
"can_show_native_badge": true,
"action_label": "View Report",
"checked_at": "2026-06-18T00:00:00Z",
"refreshed_at": "2026-06-18T00:00:00Z",
"valid_until": "2026-09-18T00:00:00Z",
"freshness_status": "fresh",
"report_url": "https://www.canibuildhere.ie/reports/CIBH-12345"
}/api/site-checks/{site_check_id}/refreshDeduct 1 credit to trigger a planning data update. This creates a new report version under the same canonical site_check_id and updates it globally.
{
"platform": "daft",
"reason": "age",
"requested_by": "Sherry Fitz Operations"
}{
"success": true,
"site_check_id": "CIBH-12345",
"previous_report_version": 1,
"new_report_version": 2,
"checked_at": "2026-06-18T01:30:00Z",
"refreshed_at": "2026-06-18T01:30:00Z",
"freshness_status": "fresh",
"platform": "daft",
"entitlement_status": "active",
"can_show_native_badge": true,
"badge_label": "Checks recommended",
"report_url": "https://www.canibuildhere.ie/reports/CIBH-12345"
}/api/site-checks/{site_check_id}/placementsRegister an agreed publication placement. Native badge display is available only where the relevant platform integration and entitlement have been enabled.
{
"platform": "daft",
"listing_url": "https://www.daft.ie/for-sale/site-cois-na-habhainn...",
"external_listing_id": "daft-987654",
"placement_type": "native_badge",
"entitlement_status": "active"
}{
"success": true,
"placement_id": "place_777",
"site_check_id": "CIBH-12345",
"platform": "daft",
"placement_type": "native_badge",
"listing_url": "https://www.daft.ie/for-sale/site-cois-na-habhainn...",
"external_listing_id": "daft-987654",
"active": true,
"entitlement_status": "active",
"can_show_native_badge": true,
"badge_url": "https://www.canibuildhere.ie/api/site-checks/CIBH-12345/badge",
"report_url": "https://www.canibuildhere.ie/reports/CIBH-12345"
}/api/site-checks/{site_check_id}/agent-contextAdd contextual notes, update listing readiness status, and customize the badge display style. This context does not modify the fixed CIBH safety score.
{
"agent_decision": "publish_with_badge",
"agent_context_note": "Local needs zoning applies. Buyers should consult with agent.",
"agent_context_visibility": "public",
"published_badge_mode": "checks_recommended",
"listing_readiness_status": "ready_to_publish"
}{
"success": true,
"site_check_id": "CIBH-12345",
"cibh_risk_score": "medium",
"agent_decision": "publish_with_badge",
"agent_context_visibility": "public",
"agent_context_note": "Local needs zoning applies. Buyers should consult with agent.",
"published_badge_mode": "checks_recommended",
"note": "Agent context is stored separately and does not override the CIBH calculated risk score."
}