Skip to main content
Use the Matching API to refresh your organization’s Price Radar from a scheduled scraper, matching pipeline, or partner integration. It accepts the same raw and already-matched competitor exports as Update on the Competitor matching page, with the same validation, coverage controls, and publication behavior. Both upload and progress requests use your Public API bearer key. A signed-in browser session is not required.

​
Choose the right upload

The Matching endpoint accepts one UTF-8 CSV. The header decides how it is processed:
  • item_id is present: the file is treated as already matched and published against your catalog.
  • item_id is absent: Price Radar matches the raw competitor export to your catalog before publication.
  • A raw file must also omit the link columns external_match_id, match_relation, match_method, and match_confidence. A file containing any of those columns without item_id is refused.
The matched-snapshots name covers both file kinds; there is no separate raw-upload endpoint or upload-type parameter. Use the same export format you would upload on the Competitor matching page. The CSV header must fit within 64 KiB.

​
Upload a file

The entire multipart request must be at most 25 MiB (26,214,400 bytes), including form fields and multipart overhead. Keep the file below that total. Let curl set the multipart Content-Type and boundary. For partial coverage, prices belonging to competitors outside covered_competitors remain in place. A partial delivery with no covered competitors adds what it carries and retires nothing. For full coverage, the file declares the whole set and may retire matches it omits; covered_competitors does not narrow that declaration.
Choose full only when the file is a complete delivery. Check the export before setting allow_large_removal=true; this confirmation lets an unusually large removal proceed.
A successful upload returns 202 Accepted and a job handle:
This means the publish was queued. Validation, matching for raw files, and publication continue in the background. Keep the job ID and follow it to a terminal status.

​
Follow publication

Poll the dedicated Matching progress endpoint with the same API key:
This endpoint includes progress, counts, and row refusals. Use it for these jobs rather than the generic /v1/jobs/{job_id} endpoint.
status is queued, running, cancelling, completed, failed, or cancelled. The last three are terminal. Poll every 5–10 seconds while running and every 30–60 seconds while queued; polling draws on the organization’s shared usage budget. Within result_summary, accepted is the accepted row count, rejected is the total refused row count, and sent is the total processed row count. Inspect these counts even when status is completed: a published file can contain refused rows. row_errors contains a sample of at most 200 refusals, each with line, code, message, and item_id. The item ID can be empty, for example when a raw row has no catalog match. This is not a full reject report. The sample can be shorter than rejected, or empty if refusal details could not be retrieved; use rejected for the total.

​
Handle conflicts and failures

CSV validation and upstream publication failures can happen after 202; they appear as a terminal failed job. Check error_message and available row refusals, correct the input or wait for a temporary service problem to clear, then submit a new upload. Publication and progress are shared by the organization. Another API-key caller in the same organization can follow the job; a caller in another organization cannot. Only one matching delivery runs at a time across API and in-app uploads.