Matches

Match endpoints need an API key. They also need an active subscription that is in its free trial or has a payment method on file (402 / 403 otherwise). For the full behaviour, see Matching.

The match object

{
  "id": "9f1c2d4e-6b7a-4c3d-8e9f-0a1b2c3d4e5f",
  "tenantId": "3a7e1c90-5d2b-4f8e-a1c3-7b9d0e2f4a6c",
  "pickup": { "lat": 40.713, "lng": -74.0055 },
  "vehicleType": "sedan",
  "radiusMeters": 10000,
  "status": "searching",
  "currentCandidateAgentId": "agt_1001",
  "matchedAgentId": null,
  "triedAgentIds": ["agt_1001"],
  "createdAt": "2026-09-23T08:15:02.114Z",
  "updatedAt": "2026-09-23T08:15:02.131Z"
}

Prop

Type

Create a match

POST /matches

Starts looking for an agent. The first offer goes out before this call returns.

Body

Prop

Type

Example

curl -X POST "$RWC_API_URL/matches" \
  -H "Authorization: Bearer $RWC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "pickup": { "lat": 40.713, "lng": -74.0055 },
    "vehicleType": "sedan",
    "radiusMeters": 5000
  }'

Responses

Status	When
`202 Accepted`	Match created. Body is the match object, either `searching` with an offer out, or already `unmatched` if no eligible agent exists
`400`	Invalid body
`401` / `402` / `403`	See errors

Get a match

GET /matches/{matchId}

Returns the current state of a match.

curl "$RWC_API_URL/matches/9f1c2d4e-6b7a-4c3d-8e9f-0a1b2c3d4e5f" \
  -H "Authorization: Bearer $RWC_API_KEY"

Status	When
`200 OK`	The match object
`400`	`matchId` isn't a UUID
`404`	No such match for your tenant

Cancel a match

POST /matches/{matchId}/cancel

Cancels a match that is still searching. Any outstanding offer is withdrawn and the agent's reservation is released. No body is needed.

curl -X POST "$RWC_API_URL/matches/9f1c2d4e-6b7a-4c3d-8e9f-0a1b2c3d4e5f/cancel" \
  -H "Authorization: Bearer $RWC_API_KEY"

Status	When
`200 OK`	Cancelled. Body is the match with `status: "cancelled"`. A `match:update` is also emitted
`404`	No such match for your tenant
`409`	`Match is already matched / unmatched / cancelled and can no longer be cancelled`
`409`	`Match is changing state right now; retry shortly`: an agent answer or timeout is being processed. Retry after a moment