API Documentation

Base URL

https://floodcert.org/api

API Version

v1

Format

JSON

Authentication

API Key Authentication

All API requests require authentication using your API key in the header:

HTTP Header

X-API-Key: your-api-key-here

Python Example

import requests

        api_key = "your-api-key-here"
        headers = {
            "X-API-Key": api_key,
            "Content-Type": "application/json"
        }

        response = requests.get("https://floodcert.org/api/lenders/", headers=headers)

Keep your API key secure

Never share your API key or commit it to version control. Use environment variables or secure configuration management.

GET /api/lenders/

Get Lenders

Retrieve a list of all registered lenders associated with your account.

Python

import requests

        url = "https://floodcert.org/api/lenders/"
        headers = {
            "X-API-Key": "your-api-key",
            "Content-Type": "application/json"
        }

        response = requests.get(url, headers=headers)
        lenders = response.json()

        # Example response handling
        if response.status_code == 200:
            for lender in lenders['lenders']:
                print(f"ID: {lender['id']}")
                print(f"Name: {lender['name']}")
                print(f"Servicer ID: {lender['servicer_id']}")

cURL

curl -X GET "https://floodcert.org/api/lenders/" \
        -H "X-API-Key: your-api-key" \
        -H "Content-Type: application/json"

Response

{
            "count": 2,
            "lenders": [
                {
                    "id": 1,
                    "name": "Example Bank",
                    "servicer_id": "EB123",
                    "email": "contact@examplebank.com",
                    "address": {
                        "line1": "123 Main St",
                        "city": "Anytown",
                        "state": "CA",
                        "zip": "12345"
                    }
                }
            ]
        }

POST /api/requests/create/

Create Certificate Request

Generate a new flood certification request for a property.

Request Parameters

Parameter	Type	Required	Description
address	string	Required	Property address for flood certification
loan_number	string	Required	Loan identifier number
lender_id	integer	Required	ID of the registered lender
borrower_name	string	Optional	Name of the borrower

Python

import requests

        url = "https://floodcert.org/api/requests/create/"
        headers = {
            "X-API-Key": "your-api-key",
            "Content-Type": "application/json"
        }

        data = {
            "address": "1708 Roydon Trail, Annapolis MD 21401",
            "loan_number": "44444555",
            "lender_id": 1,
            "borrower_name": "John Appleseed"
        }

        response = requests.post(url, json=data, headers=headers)

        if response.status_code == 201:
            request_id = response.json()['id']
            print(f"Certificate request created with ID: {request_id}")

cURL

curl -X POST "https://floodcert.org/api/requests/create/" \
        -H "X-API-Key: your-api-key" \
        -H "Content-Type: application/json" \
        -d '{
            "address": "1708 Roydon Trail, Annapolis MD 21401",
            "loan_number": "44444555",
            "lender_id": 1,
            "borrower_name": "John Appleseed"
        }'

Response

{
            "id": 12345,
            "user": "username",
            "lender": "Example Bank",
            "property_address": "1708 Roydon Trail, Annapolis MD 21401",
            "loan_number": "44444555",
            "status": "pending"
        }

GET /api/certificates/{request_id}/

Download Certificate

Download the generated flood certification PDF for a specific request.

Path Parameters

Parameter	Type	Description
request_id	integer	The ID of the certificate request

Python

import requests

        request_id = "12345"
        url = f"https://floodcert.org/api/certificates/{request_id}/"
        headers = {
            "X-API-Key": "your-api-key",
            "Accept": "application/pdf"
        }

        response = requests.get(url, headers=headers)

        if response.status_code == 200:
            with open(f"certificate_{request_id}.pdf", "wb") as f:
                f.write(response.content)
            print(f"Certificate downloaded successfully")

cURL

curl -X GET "https://floodcert.org/api/certificates/12345/" \
        -H "X-API-Key: your-api-key" \
        -H "Accept: application/pdf" \
        --output certificate.pdf

Credit Usage

Downloading a certificate will consume one credit from your balance for prepaid accounts.

GET /api/certificates/{request_id}/data/

Get Certificate Data

Retrieve detailed certificate data for a specific request in JSON format.

Path Parameters

Parameter	Type	Description
request_id	integer	The ID of the certificate request

Python

import requests
            
            request_id = "12345"
            url = f"https://floodcert.org/api/certificates/{request_id}/data/"
            headers = {
                "X-API-Key": "your-api-key",
                "Accept": "application/json"
            }
            
            response = requests.get(url, headers=headers)
            
            if response.status_code == 200:
                certificate_data = response.json()
                print(f"Certificate ID: {certificate_data['certificate_info']['certificate_id']}")
                print(f"Flood Zone: {certificate_data['certificate_info']['flood_zone']}")
                print(f"Property: {certificate_data['request_info']['property_address']}")

cURL

curl -X GET "https://floodcert.org/api/certificates/12345/data/" \
                -H "X-API-Key: your-api-key" \
                -H "Accept: application/json"

Response

{
                "request_info": {
                    "request_id": 12345,
                    "status": "completed",
                    "created_at": "2024-03-15T14:30:00Z",
                    "property_address": "123 Main St, Anytown, USA",
                    "loan_number": "LN12345",
                    "borrower_name": "John Doe"
                },
                "lender_info": {
                    "name": "Example Bank",
                    "servicer_id": "EB123",
                    "address": {
                        "line1": "456 Bank Ave",
                        "line2": "Suite 100",
                        "city": "Banktown",
                        "state": "CA",
                        "zip": "12345"
                    }
                },
                "certificate_info": {
                    "certificate_id": 67890,
                    "issued_at": "2024-03-15T14:35:00Z",
                    "flood_zone": "X",
                    "nfip_community_name": "Anytown",
                    "counties": "Example County",
                    "state": "CA",
                    "community_number": "123456",
                    "map_number": "06001C0123F",
                    "revision_date": "2024-01-01",
                    "is_flood_zone": false,
                    "is_not_flood_zone": true,
                    "flood_insurance_is_available": true,
                    "regular_program_is_available": true,
                    "emergency_program_of_nfip": false,
                    "federal_flood_insurance_not_available": false,
                    "coastal_barrier_area": false,
                    "cbra_opa_designation_date": null,
                    "commentary": ""
                }
            }

Batch Processing

GET /api/v1/batch/

List Batch Jobs

Retrieve a paginated list of your batch upload jobs. Optionally filter by status.

Query Parameters

Parameter	Type	Required	Description
status	string	Optional	Filter by status: `pending`, `processing`, `completed`, `failed`
page	integer	Optional	Page number for pagination

Python

import requests

url = "https://floodcert.org/api/v1/batch/"
headers = {
    "X-API-Key": "your-api-key",
    "Accept": "application/json"
}
params = {"status": "completed"}

response = requests.get(url, headers=headers, params=params)

if response.status_code == 200:
    data = response.json()
    for batch in data["results"]:
        print(f"Batch {batch['id']}: {batch['status']}")

cURL

curl -X GET "https://floodcert.org/api/v1/batch/?status=completed" \
    -H "X-API-Key: your-api-key" \
    -H "Accept: application/json"

Response

{
    "count": 3,
    "next": null,
    "previous": null,
    "results": [
        {
            "id": 1,
            "name": "March 2025 Batch",
            "status": "completed",
            "total_items": 50,
            "completed_items": 50,
            "failed_items": 0,
            "created_at": "2025-03-01T10:00:00Z"
        }
    ]
}

GET /api/v1/batch/{batch_id}/

Get Batch Detail

Retrieve details of a specific batch job, including its individual items and their statuses.

Path Parameters

Parameter	Type	Description
batch_id	integer	The ID of the batch job

Python

import requests

batch_id = 1
url = f"https://floodcert.org/api/v1/batch/{batch_id}/"
headers = {
    "X-API-Key": "your-api-key",
    "Accept": "application/json"
}

response = requests.get(url, headers=headers)

if response.status_code == 200:
    batch = response.json()
    print(f"Batch: {batch['name']}")
    print(f"Status: {batch['status']}")
    for item in batch["items"]:
        print(f"  {item['address']}: {item['status']}")

cURL

curl -X GET "https://floodcert.org/api/v1/batch/1/" \
    -H "X-API-Key: your-api-key" \
    -H "Accept: application/json"

GET /api/v1/batch/{batch_id}/download/

Download Batch Results

Download the ZIP file containing all generated certificates for a completed batch job.

Path Parameters

Parameter	Type	Description
batch_id	integer	The ID of the batch job

Python

import requests

batch_id = 1
url = f"https://floodcert.org/api/v1/batch/{batch_id}/download/"
headers = {"X-API-Key": "your-api-key"}

response = requests.get(url, headers=headers)

if response.status_code == 200:
    download_url = response.json()["download_url"]
    print(f"Download your results: {download_url}")

cURL

curl -X GET "https://floodcert.org/api/v1/batch/1/download/" \
    -H "X-API-Key: your-api-key"

Invoices

GET /api/invoices/

List Invoices

Retrieve a paginated list of all invoices for your account, ordered by most recent first.

Query Parameters

Parameter	Type	Required	Description
page	integer	Optional	Page number for pagination

Python

import requests

url = "https://floodcert.org/api/invoices/"
headers = {
    "X-API-Key": "your-api-key",
    "Accept": "application/json"
}

response = requests.get(url, headers=headers)

if response.status_code == 200:
    data = response.json()
    for invoice in data["results"]:
        print(f"Invoice #{invoice['id']}: ${invoice['total_amount']}")

cURL

curl -X GET "https://floodcert.org/api/invoices/" \
    -H "X-API-Key: your-api-key" \
    -H "Accept: application/json"

GET /api/invoices/{invoice_id}/

Get Invoice Detail

Retrieve detailed information for a specific invoice, including line items.

Path Parameters

Parameter	Type	Description
invoice_id	integer	The ID of the invoice

Python

import requests

invoice_id = 42
url = f"https://floodcert.org/api/invoices/{invoice_id}/"
headers = {
    "X-API-Key": "your-api-key",
    "Accept": "application/json"
}

response = requests.get(url, headers=headers)

if response.status_code == 200:
    invoice = response.json()
    print(f"Invoice #{invoice['id']}")
    print(f"Period: {invoice['billing_period_start']} - {invoice['billing_period_end']}")
    print(f"Total: ${invoice['total_amount']}")

cURL

curl -X GET "https://floodcert.org/api/invoices/42/" \
    -H "X-API-Key: your-api-key" \
    -H "Accept: application/json"

GET /api/invoices/{request_id}/

Download Invoice PDF

Download the invoice PDF for a specific certificate request.

Path Parameters

Parameter	Type	Description
request_id	integer	The ID of the certificate request

Python

import requests

request_id = "12345"
url = f"https://floodcert.org/api/invoices/{request_id}/"
headers = {
    "X-API-Key": "your-api-key",
    "Accept": "application/pdf"
}

response = requests.get(url, headers=headers)

if response.status_code == 200:
    with open(f"invoice_{request_id}.pdf", "wb") as f:
        f.write(response.content)
    print(f"Invoice downloaded successfully")

cURL

curl -X GET "https://floodcert.org/api/invoices/12345/" \
    -H "X-API-Key: your-api-key" \
    -H "Accept: application/pdf" \
    --output invoice.pdf