FuzzyMatch

API basics (Pro+)

The REST API runs the same matching as the app, from your own code. It's included in the Pro and Business plans.

1. Create an API key

Sign in, open API keys in the app and click Create key. Copy the key when it's shown: for your security it's displayed only once. Send it with every request:

Authorization: Bearer fm_live_…

Keep keys on your server. Never put them in a web page or a mobile app.

2. Submit a match job

Send both lists as arrays of flat objects (column name to value), plus which columns to compare:

curl https://api.fuzzymatcher.com/api/v1/jobs \
  -H "Authorization: Bearer $FUZZYMATCH_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "name": "CRM vs billing",
    "source": [{"name": "Richard Garcia", "email": "richard.garcia@kestrelfreight.com"}],
    "target": [{"contact": "Rick Gacria", "email": "RICHARD.GARCIA@KESTRELFREIGHT.COM"}],
    "configuration": {"field_mapping": {"name": "contact", "email": "email"}, "min_threshold": 0.75}
  }'

The response is 202 Accepted with a job id. Matching runs in the background. The Idempotency-Key header makes retries safe: sending the same key again returns the first job instead of creating a second one.

3. Get the results

Poll the job until its status is completed, then fetch the matches:

curl https://api.fuzzymatcher.com/api/v1/jobs/$JOB_ID \
  -H "Authorization: Bearer $FUZZYMATCH_API_KEY"

curl https://api.fuzzymatcher.com/api/v1/jobs/$JOB_ID/results \
  -H "Authorization: Bearer $FUZZYMATCH_API_KEY"

Rather than polling, you can register a webhook for job.completed. Webhook requests are signed so you can check they came from FuzzyMatch.

Limits and errors

  • Each request counts toward your plan's daily API calls; see Plans & limits. Every response includes X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset.
  • Rows you submit count toward your monthly row allowance, the same as jobs in the app.
  • 402 means a plan limit would be exceeded, 429 means too many requests, and errors return JSON with a code and a message.

The API reference lists every endpoint and field, and links the OpenAPI spec for generating a client.