# Match API

Supports exact, fuzzy, and AI-assisted matching with grouped boolean logic.

## Overview
The Match API provides sophisticated matching capabilities for Account, Contact, and Lead objects. It supports multiple matching modes including simple field matching, grouped boolean logic, and AI-assisted matching with natural language explanations.

## Request Body
- object: Object type to match (account, contact, lead)
- candidates: List of candidates to match against Salesforce records
- rules: Matching rules configuration
- context: Optional context information (Salesforce instance, org ID, etc.)
- max_credits: Maximum credits to spend on this request

## Matching Modes

### Simple Mode
Basic field-by-field matching with exact and fuzzy rules.

### Grouped Mode
Advanced boolean logic with grouped rules:
- groups: List of rule groups
- all: Rules within a group that must all match
- any: Whether any group needs to be true
- threshold: Overall confidence cutoff

### AI Mode
AI-assisted matching using LLM scoring:
- Natural language explanations
- Context-aware matching
- Use when structured rules fail

## Field Rules
- field:exact: Exact string match
- field:fuzzy0.x: Fuzzy match with 0.x threshold
- field:eq: Equality match
- field:contains: Contains match

## Response Fields
- success: Boolean indicating request success
- results: List of candidate results with matches
- credits_consumed: Number of credits used
- credits_remaining: Credits remaining in account
- processing_time_ms: Processing time in milliseconds
- cached: Whether result was from cache

## Credit Usage
Match API consumes credits based on complexity:
- Simple Mode: 1 credit per candidate
- Grouped Mode: 2 credits per candidate
- AI Mode: 5 credits per candidate

Endpoint: POST /v1/match
Version: 1.4.1
Security: BearerAuth

## Request fields (application/json):

  - `object` (string, required)
    Object type to match
    Enum: "account", "contact", "lead"

  - `candidates` (array, required)
    List of candidates to match

  - `candidates.company_name` (any)
    Company name

  - `candidates.domain` (any)
    Company domain

  - `candidates.billing_street` (any)
    Billing street address

  - `candidates.phone` (any)
    Phone number

  - `candidates.email` (any)
    Email address

  - `candidates.first_name` (any)
    First name (for contacts/leads)

  - `candidates.last_name` (any)
    Last name (for contacts/leads)

  - `candidates.title` (any)
    Job title (for contacts/leads)

  - `rules` (object, required)
    Matching rules configuration

  - `rules.mode` (string, required)
    Matching mode
    Enum: "simple", "grouped", "ai"

  - `rules.groups` (any)
    Match groups (for grouped mode)

  - `rules.any` (boolean)
    Match if any group is true

  - `rules.threshold` (number, required)
    Overall confidence cutoff

  - `rules.effort` (any)
    Enrichment effort level (for AI mode)

  - `context` (any)
    Context information

  - `max_credits` (integer)
    Maximum credits to spend

## Response 200 fields (application/json):

  - `success` (boolean, required)
    Boolean indicating request success

  - `results` (array, required)
    List of candidate results

  - `results.input_index` (integer, required)
    Index of the input candidate

  - `results.matches` (array, required)
    List of matches found

  - `results.matches.sf_id` (string, required)
    Salesforce ID of the matched record

  - `results.matches.object` (string, required)
    Object type of the matched record (e.g., 'Account', 'Contact', 'Lead')

  - `results.matches.confidence` (number, required)
    Overall confidence score

  - `results.matches.explanations` (array, required)
    List of match explanations (e.g., ['domain eq', 'name fuzzy 0.86'])

  - `results.matches.fields` (object, required)
    Matched record fields (e.g., {'Name': 'Company Name', 'Website': 'example.com'})

  - `results.best_match` (boolean, required)
    Whether this is the best match

  - `results.status` (string, required)
    Match status
    Enum: "matched", "no_match", "ambiguous"

  - `confidence` (any)
    Confidence score (0.0-1.0) or null if disabled/not found

  - `credits_consumed` (integer, required)
    Number of credits used for this request

  - `credits_remaining` (integer, required)
    Credits remaining in your account after this request

  - `processing_time_ms` (integer, required)
    Time taken to process the request in milliseconds

  - `cached` (boolean, required)
    Boolean indicating if this result was returned from cache

## Response 400 fields (application/json):

  - `success` (boolean)
    Always false for error responses

  - `error` (string, required)
    Error message

  - `details` (any)
    Additional error details

  - `request_id` (any)
    Request ID for tracking

  - `credits_required` (any)
    Credits required for insufficient credit errors

  - `credits_remaining` (any)
    Credits remaining for insufficient credit errors

  - `retry_after` (any)
    Seconds to wait before retrying for rate limit errors

## Response 401 fields (application/json):

  - `success` (boolean)
    Always false for error responses

  - `error` (string, required)
    Error message

  - `details` (any)
    Additional error details

  - `request_id` (any)
    Request ID for tracking

  - `credits_required` (any)
    Credits required for insufficient credit errors

  - `credits_remaining` (any)
    Credits remaining for insufficient credit errors

  - `retry_after` (any)
    Seconds to wait before retrying for rate limit errors

## Response 402 fields (application/json):

  - `success` (boolean)
    Always false for error responses

  - `error` (string, required)
    Error message

  - `details` (any)
    Additional error details

  - `request_id` (any)
    Request ID for tracking

  - `credits_required` (any)
    Credits required for insufficient credit errors

  - `credits_remaining` (any)
    Credits remaining for insufficient credit errors

  - `retry_after` (any)
    Seconds to wait before retrying for rate limit errors

## Response 422 fields (application/json):

  - `detail` (array)

  - `detail.loc` (array, required)

  - `detail.msg` (string, required)

  - `detail.type` (string, required)

## Response 429 fields (application/json):

  - `success` (boolean)
    Always false for error responses

  - `error` (string, required)
    Error message

  - `details` (any)
    Additional error details

  - `request_id` (any)
    Request ID for tracking

  - `credits_required` (any)
    Credits required for insufficient credit errors

  - `credits_remaining` (any)
    Credits remaining for insufficient credit errors

  - `retry_after` (any)
    Seconds to wait before retrying for rate limit errors

## Response 500 fields (application/json):

  - `success` (boolean)
    Always false for error responses

  - `error` (string, required)
    Error message

  - `details` (any)
    Additional error details

  - `request_id` (any)
    Request ID for tracking

  - `credits_required` (any)
    Credits required for insufficient credit errors

  - `credits_remaining` (any)
    Credits remaining for insufficient credit errors

  - `retry_after` (any)
    Seconds to wait before retrying for rate limit errors