API v1 · Read-Only + Webhooks

URTI Platform API

Connect your AI to URTI's certification platform. Query real-time NFCC data, verify supply chains, and receive push notifications when new certifications are issued or deals are created.

Base URL https://urti-forestry.polsia.app/api/v1

Authentication

All API v1 endpoints require an API key. Pass it via the X-Api-Key request header (preferred) or as an api_key query parameter.

Your API key for the JT Foxx AI integration has been pre-generated. Contact the URTI team to retrieve it, or log into the admin panel.

Header (recommended)

X-Api-Key: urti_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Query parameter (for testing)

https://urti-forestry.polsia.app/api/v1/stats?api_key=urti_live_xxxx...

Example request

curl https://urti-forestry.polsia.app/api/v1/stats \
  -H "X-Api-Key: urti_live_xxxx..."

Errors

The API uses standard HTTP status codes. All error responses include a JSON body:

{
  "success": false,
  "error": "Human-readable error message"
}

Status	Meaning
200	Success
400	Bad request — invalid parameters
401	Unauthorized — missing or invalid API key
404	Resource not found
409	Conflict — resource already exists
500	Server error — retry with backoff

Read-Only Endpoints

GET /api/v1/stats Real-time platform statistics

Returns real-time counts of NFCCs issued, active certifications, and client totals. No parameters required.

Example Response

{
  "success": true,
  "stats": {
    "total_nfccs_issued":    1847203,
    "active_nfccs":          1832110,
    "revoked_nfccs":         15093,
    "nfccs_today":           12500,
    "nfccs_this_month":      248000,
    "total_active_clients":  47
  },
  "recent_certifications": [ /* last 5 certs */ ],
  "generated_at": "2026-03-27T13:00:00Z"
}

GET /api/v1/certificates Query NFCC certification data

Query all NFCC certificates with optional filters. Returns paginated results (max 200 per page).

Query Parameters

Parameter	Type	Description
company_idoptional	string	Filter by company ID
product_typeoptional	string	Filter by type: `tree`, `pallet`, `timber`, `finished`
statusoptional	string	Filter by status: `active`, `revoked`, `expired`
pageoptional	integer	Page number (default: 1)
limitoptional	integer	Results per page (default: 50, max: 200)

Example

curl "https://urti-forestry.polsia.app/api/v1/certificates?company_id=acme-corp&status=active&limit=10" \
  -H "X-Api-Key: urti_live_xxxx..."

Example Response

{
  "success": true,
  "certificates": [
    {
      "certificate_number": "NFCC-A3F7-B2E9-C8D1",
      "product_type":       "timber",
      "status":             "active",
      "issued_at":          "2026-03-15T10:30:00Z",
      "asset_description":  "Timber unit certified under TLTS Protocol...",
      "company_id":         "acme-corp",
      "company_name":       "ACME Forestry Corp"
    }
  ],
  "pagination": {
    "total": 1420,
    "page": 1,
    "limit": 10,
    "pages": 142
  }
}

GET /api/v1/certificates/:certNumber Look up a specific certification

Retrieve full details for a single NFCC certificate by its certificate number. Format must match NFCC-XXXX-XXXX-XXXX.

Example

curl https://urti-forestry.polsia.app/api/v1/certificates/NFCC-A3F7-B2E9-C8D1 \
  -H "X-Api-Key: urti_live_xxxx..."

Example Response

{
  "success": true,
  "certificate": {
    "certificate_number": "NFCC-A3F7-B2E9-C8D1",
    "status":             "active",
    "product_type":       "timber",
    "asset_description":  "Timber unit certified under TLTS Protocol for ACME Forestry Corp",
    "issued_at":          "2026-03-15T10:30:00Z",
    "company_id":         "acme-corp",
    "company_name":       "ACME Forestry Corp",
    "verification_url":   "https://urtiforestry.com/verify/NFCC-A3F7-B2E9-C8D1"
  }
}

GET /api/v1/companies List all certified clients

Returns all companies that have approved NFCC certification orders, sorted by total certifications issued.

Parameter	Type	Description
statusoptional	string	Account status: `active` (default), `suspended`
pageoptional	integer	Page number (default: 1)
limitoptional	integer	Results per page (default: 50, max: 200)

Example Response

{
  "success": true,
  "companies": [
    {
      "company_id":      "acme-corp",
      "company_name":    "ACME Forestry Corp",
      "contact_email":   "ceo@acme.com",
      "total_orders":    3,
      "total_certs":     500000,
      "onboarded_at":    "2026-01-10T09:00:00Z",
      "account_status":  "active"
    }
  ],
  "pagination": { "total": 47, "page": 1, "limit": 50 }
}

GET /api/v1/supply-chain/:companyId Verify supply chain records

Returns a complete supply chain verification summary for a company: total certifications, product types, active vs revoked counts, and order history.

Example

curl https://urti-forestry.polsia.app/api/v1/supply-chain/acme-corp \
  -H "X-Api-Key: urti_live_xxxx..."

Example Response

{
  "success": true,
  "company_id":    "acme-corp",
  "company_name":  "ACME Forestry Corp",
  "account_status": "active",
  "supply_chain": {
    "total_certifications":  500000,
    "active_certifications": 498500,
    "revoked_certifications": 1500,
    "product_types_certified": ["timber", "pallet"],
    "first_certification_at": "2026-01-11T08:00:00Z",
    "latest_certification_at": "2026-03-20T14:00:00Z"
  },
  "recent_orders": [ /* last 10 orders */ ],
  "verified_at": "2026-03-27T13:00:00Z"
}

GET /api/v1/keys/me Get API key details

Returns information about the currently authenticated API key: name, permissions, and last usage timestamp.

Webhooks

Register a URL and URTI will push real-time events to your AI whenever certifications are issued or deals are created. Your AI receives the payload within seconds of the event occurring.

Webhook delivery is attempted once with a 10-second timeout. Failed deliveries increment the failure counter — use GET /api/v1/webhooks/:id/deliveries to debug.

Available Events

cert.issued

Fired when an order is approved and NFCC certificates are generated. Includes order ID, company details, product type, and count.

deal.created

Fired when a new prospect deal is added to the partner pipeline. Includes contact info, company, deal size, and source.

order.approved

Synonym for cert.issued — included for future differentiation between large background jobs and small synchronous jobs.

Webhook Payload Structure

All webhook payloads share the same envelope:

{
  "event":     "cert.issued",           // Event type
  "timestamp": "2026-03-27T13:00:00Z",  // ISO 8601 UTC
  "data": {
    // Event-specific fields (see below)
  }
}

cert.issued payload

{
  "event": "cert.issued",
  "timestamp": "2026-03-27T13:00:00Z",
  "data": {
    "order_id":            142,
    "company_id":          "acme-corp",
    "company_name":        "ACME Forestry Corp",
    "product_type":        "timber",
    "certificates_issued": 500000,
    "approved_at":         "2026-03-27T13:00:00Z"
  }
}

deal.created payload

{
  "event": "deal.created",
  "timestamp": "2026-03-27T13:05:00Z",
  "data": {
    "deal_id":           88,
    "name":             "Pacific Lumber Co",
    "company":          "Pacific Lumber Co",
    "contact_name":     "Jane Smith",
    "contact_email":    "jane@pacific.com",
    "deal_size_estimate": 2500000,
    "status":           "contacted",
    "source":           "JT Foxx referral",
    "created_at":       "2026-03-27T13:05:00Z"
  }
}

Signature Verification (optional)

If you set a secret when registering your webhook, URTI will send an X-URTI-Signature header with an HMAC-SHA256 signature of the request body.

// Node.js verification example
const signature = 'sha256=' + crypto
  .createHmac('sha256', YOUR_WEBHOOK_SECRET)
  .update(rawBody)
  .digest('hex');

const isValid = signature === req.headers['x-urti-signature'];

POST /api/v1/webhooks Register a new webhook

Request Body

Field	Type	Description
urlrequired	string	HTTPS URL to receive webhook POSTs
eventsoptional	string[]	Events to subscribe to (default: all events)
secretoptional	string	Secret for HMAC signature verification

Example

curl -X POST https://urti-forestry.polsia.app/api/v1/webhooks \
  -H "X-Api-Key: urti_live_xxxx..." \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your-ai.example.com/webhooks/urti",
    "events": ["cert.issued", "deal.created"],
    "secret": "your-optional-secret"
  }'

Response

{
  "success": true,
  "webhook": {
    "id":         1,
    "url":        "https://your-ai.example.com/webhooks/urti",
    "events":     ["cert.issued", "deal.created"],
    "status":     "active",
    "created_at": "2026-03-27T13:00:00Z"
  },
  "message": "Webhook registered for events: cert.issued, deal.created"
}

GET /api/v1/webhooks List registered webhooks

Returns all webhooks registered to the current API key, including delivery stats.

PATCH /api/v1/webhooks/:id Update a webhook

Update the URL, events list, or status (active / paused) of an existing webhook.

Setting status to active after paused resets the failure counter.

DELETE /api/v1/webhooks/:id Delete a webhook

Permanently removes a webhook registration and all delivery logs.

GET /api/v1/webhooks/:id/deliveries View delivery log

Returns the last 50 delivery attempts for a webhook, including HTTP status codes and error messages for debugging.