Skip to content

Match API

Request

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 (approximate balance; use GET /v1/credits/remaining for precise value)
  • 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
Security
BearerAuth
Bodyapplication/jsonrequired
objectstring(Object)required

Object type to match

Enum:"account""contact""lead"
candidatesArray of objects(Candidates)required

List of candidates to match

rulesobject(MatchRules)required

Matching rules configuration

contextobject or null(Context)
Any of:

Context information

max_creditsinteger, [ 1 .. 100 ](Max Credits)

Maximum credits to spend

Default:1
curl -i -X POST \
  https://api-gateway.agenthq.withlantern.com/v1/match \
  -H 'Authorization: Bearer <YOUR_ApiToken_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "object": "account",
    "candidates": [
      {
        "company_name": "string",
        "domain": "string",
        "billing_street": "string",
        "phone": "string",
        "email": "string",
        "first_name": "string",
        "last_name": "string",
        "title": "string"
      }
    ],
    "rules": {
      "mode": "simple",
      "groups": [
        {
          "all": [
            "string"
          ]
        }
      ],
      "any": true,
      "threshold": 1,
      "effort": "low"
    },
    "context": {},
    "max_credits": 1
  }'

Responses

Success Response

Bodyapplication/json
successboolean(Success)required

Boolean indicating request success

resultsArray of objects(Results)required

List of candidate results

confidencenumber or null(Confidence)
Any of:

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

[ 0 .. 1 ]
number
credits_consumedinteger(Credits Consumed)required

Number of credits used for this request

credits_remaininginteger or null(Credits Remaining)
Any of:

Approximate remaining credit balance. Use GET /v1/credits/remaining for precise balance.

integer
processing_time_msinteger(Processing Time Ms)required

Time taken to process the request in milliseconds

cachedboolean(Cached)required

Boolean indicating if this result was returned from cache

Response
{
  "success": true,
  "results": [
    { … }
  ],
  "confidence": 0.9,
  "credits_consumed": 1,
  "credits_remaining": 950,
  "processing_time_ms": 1200,
  "cached": true
}