Service Request API

How it works

1. 1. You POST a request with the person's need, timing, location and their consent to share it with one business.
2. 2. A Bloombilt operator qualifies it and picks one eligible merchant. Nothing is broadcast.
3. 3. That merchant accepts or declines from their phone. Their contact details are released only on acceptance.
4. 4. You poll the status endpoint. If the merchant declined, we try one other — you are never told who passed.

Authentication

Bearer API key, issued per distribution channel.

Authorization: Bearer <your-api-key>

The key that creates a request is the only key that can read its status. There is no endpoint that lists requests, and no way to reach another channel's.

Access requirements

• Account: an API key from Bloombilt. Email support@bloombilt.com.
• Region: the Twin Cities metro (Minneapolis–St. Paul, Minnesota, USA) only. Requests outside our merchants' postcodes are rejected with outside_service_area.
• Multiple merchants: this one integration represents many independent local businesses. Bloombilt is the operator of record; each merchant contracts with us, not with the calling platform.
• Categories: non-regulated local services only. Call GET /capabilities for the live list.
• Not supported: emergencies (police, fire, medical, utility), medical, legal, financial, childcare and other regulated professional advice, restaurant ordering, retail inventory, delivery, lodging and ticketing.
• Rate: no published limit during the pilot. We will agree one in writing with you before it matters, rather than discover it in production.
• Money: no consumer ever pays Bloombilt. The merchant owes us a disclosed fee when they accept a qualified request. We do not process, hold or route customer payments.

Submit a request

POST /requests

{
  "need": "Leaking water heater in the basement, needs looking at this week",
  "capability_id": "plumbing",
  "fulfillment": {
    "mode": "onsite",
    "address": "123 Main St, Minneapolis MN",
    "postal_code": "55418"
  },
  "needed_by": "2026-09-27T17:00:00Z",
  "customer": {
    "name": "Dana Reed",
    "phone": "+16125550100",
    "email": "dana@example.com"
  },
  "consent": {
    "purpose_text": "Share this request and my contact details with one matching Twin Cities business.",
    "granted_at": "2026-09-20T14:02:11Z"
  },
  "source_ref": "your-conversation-id"
}

Consent is not a boolean. Send the exact sentence the person was shown. If you cannot produce one, you have not collected consent and we cannot route the request.

Returns 201 with an opaque request_id. A 422 carries a machine-readable error — branch on that, never on the message.

Read the status

GET /requests/{id}

{
  "request_id": "0f6e...",
  "status": "accepted",
  "accepted_by": {
    "merchant_name": "Northside Plumbing",
    "next_step": "They have your contact details and will reach out directly."
  },
  "rejection_reason": null,
  "explanation": "Northside Plumbing accepted your request and will contact you directly."
}

There is deliberately no state for "a merchant declined". Which business passed is not information we will give out, in either direction.

Testing

Send "test": true. The request flows through the entire pipeline — qualification, offer, acceptance — and is structurally incapable of producing a charge. The database refuses a billing entry against a test request; it is not a flag someone remembers to check.