Developers • v1 Reference

LienDeadline API Documentation

API reference for deadline workflows and state-guide data across all 50 states and DC. Public supplier date calculations cover reviewed Florida and Kansas scenarios; other jurisdictions and unsupported conditions require qualified review.

View Quickstart Open API Playground Open Swagger Explorer Get API Access

Base URL

https://secure-api-v1.liendeadline.com/api/v1

Target SLA

99.9% uptime for Automation plan

State guide data

All 50 states + DC

Overview

Use the API to calculate and monitor upcoming preliminary notice and lien filing deadlines from invoice data. Customer calculation and supported-state routes require a dedicated API key. The server examples, strict validation, credential errors and limits below describe that customer API contract.

Requests to /api/v1/calculate-deadline and /api/v1/supported-states, and to the legacy API-host aliases /api/v1/calculate, /api/calculate, /v1/calculate and /v1/states, return 401 with detail.code=invalid_credentials and a WWW-Authenticate: Bearer header when they carry no valid customer key. Use the explicit demo routes, /api/v1/demo/calculate-deadline and /api/v1/demo/supported-states, for evaluation without a key. Contact API support to provision a customer key.

Use Cases

Bulk invoice deadline calculations
Automated reminders into Slack/Email/Sales workflows
In-app validation before invoice closeout

Response Contract

JSON bodies with UTC timestamps
State-specific deadline logic applied server side
Customer credential errors use detail.code; rate errors include Retry-After

Customer quickstart

Send this request from your server with the customer API key that API support provisions for your account.

POST /api quickstart

curl -X POST "https://secure-api-v1.liendeadline.com/api/v1/calculate-deadline" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "invoice_date": "2025-01-15",
    "state": "CA",
    "role": "supplier",
    "project_type": "commercial"
}'

The response is a stateless, non-billable invoice-date projection. Repeated calls create no project or charge. Confirm the applicable statutory event dates; Kansas invoice-only requests return review_required and require the reviewed supplier-events-v1 contract.

API playground

Use the interactive playground to send test requests, validate payloads, and inspect responses before integrating.

The browser playground uses /api/v1/demo/calculate-deadline and /api/v1/demo/supported-states. These public demonstrations save no projects, send no email and grant no customer account access. Use synthetic inputs. Keep issued customer keys in your server-side secret manager.

Start testing Open Swagger endpoint tester

Swagger explorer for technical buyers

If your team evaluates API providers through integration feasibility, use the explorer to validate all supported calls before procurement.

What you get

Clear endpoint docs and schemas
Sample payloads with real response shapes
Live try-it execution from browser

What it proves

Public demonstration of payload and response formats
State-specific logic from one contract
Clear onboarding story for internal teams

Decision support

Public demos stay separate from the customer contract
Safe for prospect walkthroughs
Consistent language your support team can quote

Open technical explorer now

Customer authentication

Customer calculation and supported-state routes accept only a dedicated API key in the Authorization Bearer header. Browser sessions and provider tokens do not grant customer API access.

Authorization: Bearer YOUR_API_KEY

Authorization best practices

Store keys in secret management services only
Keys are shown once at issuance; replacement immediately revokes the old key
Do not pass credentials in query strings, browser storage, logs or provider payloads

Common headers

Content-Type: application/json
Accept: application/json

Endpoints

The Zapier integration uses separate OAuth 2.0 endpoints under /api/zapier instead of customer API keys.

Zapier integration API reference

POST

/api/v1/calculate-deadline

This route requires a customer key with deadline:calculate scope. It returns an invoice-date projection from public rules without saving customer projects or billing usage. Use only commercial or residential project_type and real YYYY-MM-DD calendar dates; unsupported roles and state codes fail validation.

Field	Type	Required	Description
invoice_date	string	Yes	Date in YYYY-MM-DD format
state	string	Yes	US state code (2 letters)
role	string	No	supplier (default), contractor, or subcontractor

{
  "preliminary_notice": {
    "required": true,
    "deadline": "2025-02-04",
    "days_from_now": 20
  },
  "lien_filing": {
    "deadline": "2025-04-15",
    "days_from_now": 90
  },
  "warnings": [
    "If Notice of Completion is filed, deadline can shorten to 30 days"
  ]
}

GET

/api/v1/supported-states

This route requires a customer key with states:read scope. It returns current rule availability; inclusion does not verify that an invoice date is the correct statutory event.

{
  "states": ["AL", "AK", "AZ", "AR", "...", "WY", "DC"],
  "count": 51
}

GET

/api/v1/state-guides/{state}

Pull state-specific guidance and rules when you need context for internal auditability.

{
  "state": "CA",
  "state_name": "California",
  "notice_window_days": 90,
  "filing_deadline_rule": "30-day rule when notice of completion is filed",
  "references": ["Cal. Civ. Code §8200-8444"]
}

GET

/api/v1/state-guides/index

Lightweight list endpoint used for dropdowns and UI controls before opening full guides.

{
  "states": [
    { "state_code": "CA", "title": "California Mechanics Lien" },
    { "state_code": "TX", "title": "Texas Preliminary Notice" }
  ]
}

GET

/api/v1/state-guides/{state}/calculator-payload

Fetches normalized rule payload exactly as used by the calculator for downstream integrations.

{
  "state_code": "CA",
  "state_name": "California",
  "rule_payload": {
    "preliminary_notice": {
      "required": true,
      "days": 20,
      "when": "Notice of completion may shorten timing"
    },
    "lien_filing": {
      "required": true,
      "days": 90
    }
  }
}

Code examples

Server examples for the customer API contract. Each request needs a customer API key provisioned by API support.

Example

curl

Raw HTTP call you can run in terminal or scripts.

Language

Server examples for the customer API contract. Each request needs a customer API key provisioned by API support; the public playground remains available for evaluation without a key.

curl -X POST "https://secure-api-v1.liendeadline.com/api/v1/calculate-deadline" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "invoice_date": "2025-01-15",
    "state": "CA",
    "role": "supplier",
    "project_type": "commercial"
}'

Open integration guide

Customer errors & limits

These credential errors and shared limits apply to the customer calculation and supported-state routes.

HTTP status	Meaning	Action
200	Success	Use response payload as delivered
400	Invalid request data	Check required fields and type formats
422	Invalid input or event review required	Correct validation errors; Kansas invoice-only inputs require verified supplier event facts
401	Authorization failure	Check the Bearer key; missing, unknown, expired or revoked keys return invalid_credentials
403	Scope or account access denied	Contact the API administrator to verify ownership, scope and enabled account access
503	Customer credential store or rules unavailable	Retry later; customer access fails closed
429	Rate limit reached	Honor Retry-After seconds before retrying

Rate policy

Customer calculation and state routes share 60 requests per key per fixed UTC minute. A defensive source limit allows 300 attempts per minute, including failed credentials. All aliases share persisted limits across servers; 429 returns detail.code=rate_limited and Retry-After seconds.

Support & next steps

For technical access requests, plan-specific feature questions, and integration troubleshooting, use our support channels.

Email support Help articles Contact sales

Need a custom SLA? Enterprise customers can request a dedicated integration playbook and SLA addendum.