Matches API¶

The Matches API provides AI-powered company-grant matching with a hybrid scoring algorithm. It supports both real-time match calculation and persisted match management with user interaction tracking.

All match endpoints require authentication and are scoped to the current user's tenant.

Scoring Algorithm¶

Matches are scored using a weighted hybrid algorithm:

Disqualifying rules:

• Country mismatch returns a score of 0
• Company size mismatch (when grant explicitly restricts sizes) returns a score of 0
• Carbon-focused grants receive a 1.2x bonus (capped at 1.0)

Endpoints¶

GET /matches¶

List persisted matches with optional filtering. This is the primary frontend-aligned endpoint for match listing.

Authentication: Required

{
  "items": [
    {
      "id": "d4e5f6a7-b8c9-0123-def0-456789012345",
      "company_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "grant_id": "b1c2d3e4-f5a6-7890-bcde-f12345678901",
      "score": 0.87,
      "rule_score": 0.92,
      "semantic_score": 0.81,
      "recency_score": 0.95,
      "collaborative_score": 0.65,
      "carbon_score": 0.88,
      "match_reasons": [
        "Country match: DE",
        "NACE code overlap: M71",
        "Carbon category match: renewable_energy",
        "ISO_14001 certification recognized"
      ],
      "is_viewed": true,
      "is_saved": false,
      "is_dismissed": false,
      "created_at": "2025-01-15T10:30:00Z",
      "grant": {
        "id": "b1c2d3e4-f5a6-7890-bcde-f12345678901",
        "title": "Green Innovation Fund",
        "deadline": "2025-06-30T23:59:59Z",
        "is_carbon_focused": true
      }
    }
  ],
  "total": 42,
  "page": 1,
  "page_size": 20
}

curl -X GET "https://api.carbonconnect.io/api/v1/matches?company_id=a1b2c3d4-e5f6-7890-abcd-ef1234567890&min_score=0.5&status=saved&page=1" \
  -H "Authorization: Bearer <token>"

Query Parameters:

POST /matches/calculate¶

Trigger match calculation for a company. Calculates matches and persists them to the database.

Authentication: Required

{
  "company_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
}

{
  "task_id": "e5f6a7b8-c9d0-1234-ef01-567890123456"
}

curl -X POST https://api.carbonconnect.io/api/v1/matches/calculate \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"company_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"}'

Request Body:

Status Codes:

GET /matches/stats¶

Get match statistics for a company or entire tenant.

Authentication: Required

{
  "total": 42,
  "by_eligibility": {
    "saved": 8,
    "dismissed": 3,
    "active": 31
  },
  "score_distribution": {
    "min": 0.23,
    "max": 0.95,
    "avg": 0.67
  }
}

curl -X GET "https://api.carbonconnect.io/api/v1/matches/stats?company_id=a1b2c3d4-e5f6-7890-abcd-ef1234567890" \
  -H "Authorization: Bearer <token>"

Query Parameters:

GET /matches/match/{match_id}¶

Get a single match by its ID with full details including the associated grant.

Authentication: Required

curl -X GET https://api.carbonconnect.io/api/v1/matches/match/d4e5f6a7-b8c9-0123-def0-456789012345 \
  -H "Authorization: Bearer <token>"

Path Parameters:

Status Codes:

PATCH /matches/match/{match_id}/action¶

Update the status of a match (save, dismiss, or restore).

Authentication: Required

{
  "action": "save"
}

{
  "id": "d4e5f6a7-b8c9-0123-def0-456789012345",
  "is_saved": true,
  "is_dismissed": false,
  "score": 0.87
}

curl -X PATCH https://api.carbonconnect.io/api/v1/matches/match/d4e5f6a7-b8c9-0123-def0-456789012345/action \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"action": "save"}'

Request Body:

Action Behavior:

Status Codes:

GET /matches/{company_id}¶

Calculate and return real-time matches for a company using the hybrid matching algorithm. Results are not persisted by default.

Authentication: Required

{
  "items": [
    {
      "grant": {
        "id": "b1c2d3e4-f5a6-7890-bcde-f12345678901",
        "title": "Green Innovation Fund",
        "is_carbon_focused": true
      },
      "score": 0.87,
      "rule_score": 0.92,
      "semantic_score": 0.81,
      "recency_score": 0.95,
      "collaborative_score": 0.65,
      "carbon_score": 0.88,
      "match_reasons": [
        "Country match: DE",
        "NACE code overlap: M71"
      ]
    }
  ],
  "total": 15,
  "company_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
}

curl -X GET "https://api.carbonconnect.io/api/v1/matches/a1b2c3d4-e5f6-7890-abcd-ef1234567890?min_score=0.3&page=1&page_size=10" \
  -H "Authorization: Bearer <token>"

Path Parameters:

Query Parameters:

GET /matches/{company_id}/saved¶

Get persisted matches for a company, including user interaction state.

Authentication: Required

curl -X GET "https://api.carbonconnect.io/api/v1/matches/a1b2c3d4-e5f6-7890-abcd-ef1234567890/saved?page=1" \
  -H "Authorization: Bearer <token>"

Path Parameters:

Query Parameters:

POST /matches/{company_id}/refresh¶

Recalculate matches for a company and optionally persist the results.

Authentication: Required

{
  "items": [...],
  "total": 20,
  "company_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
}

curl -X POST "https://api.carbonconnect.io/api/v1/matches/a1b2c3d4-e5f6-7890-abcd-ef1234567890/refresh?save_results=true&limit=30" \
  -H "Authorization: Bearer <token>"

Path Parameters:

Query Parameters:

PATCH /matches/{company_id}/{grant_id}/view¶

Mark a match as viewed.

Authentication: Required

curl -X PATCH https://api.carbonconnect.io/api/v1/matches/a1b2c3d4-e5f6-7890-abcd-ef1234567890/b1c2d3e4-f5a6-7890-bcde-f12345678901/view \
  -H "Authorization: Bearer <token>"

Status Codes:

PATCH /matches/{company_id}/{grant_id}/save¶

Toggle a match's saved state.

Authentication: Required

curl -X PATCH "https://api.carbonconnect.io/api/v1/matches/a1b2c3d4-e5f6-7890-abcd-ef1234567890/b1c2d3e4-f5a6-7890-bcde-f12345678901/save?saved=true" \
  -H "Authorization: Bearer <token>"

Query Parameters:

PATCH /matches/{company_id}/{grant_id}/dismiss¶

Toggle a match's dismissed state.

Authentication: Required

curl -X PATCH "https://api.carbonconnect.io/api/v1/matches/a1b2c3d4-e5f6-7890-abcd-ef1234567890/b1c2d3e4-f5a6-7890-bcde-f12345678901/dismiss?dismissed=true" \
  -H "Authorization: Bearer <token>"

Query Parameters:

Match Response Schema¶

MatchResponse (persisted)¶

MatchResultResponse (real-time)¶