Documentation

Connect

The connector is served three ways from the same handlers, with the same sign-in.

• MCP, over streamable HTTP: /api/mcp
• REST, one route per tool: /api/tools
• An OpenAPI document describing those routes: /openapi.json

All three are HTTPS only. Location and the person’s details are tool inputs or come from our own sign-in; nothing is assumed from the assistant.

Sign-in

Sign-in is OAuth with PKCE. The person signs in with a one-time code, so there is no password to set. In demo mode, emailed codes are off and the reviewer account signs in with a password. An unauthenticated request to /api/mcp returns 401 with OAuth resource metadata, which is how an assistant discovers where to send the person.

The two-step book

book shares nothing and calls nobody without a preview first.

1. Call book without a confirmationToken. The result is needs_confirmation: it names the business, lists exactly what will be shared, and carries a single-use token that lasts 30 minutes. No booking exists yet.
2. Show the person that preview. When they agree, call book again with the same inputs and the token. Only this call creates a booking.

Repeating a call with a token that was already used returns the same booking and does not place a second call, so a retry is safe. A second attempt at the same business happens only when the person asks again, with a fresh preview and token. To book the runner-up after the first business did not come through, call book with the same pickId and useRunnerUp set to true.

Errors

Every result a person can cause, or needs to hear about, is a status in the tool’s result, not an error. Inputs that do not match the tables above are rejected before the tool runs, with a message naming the field.

A fault on our side returns one fixed message, with isError set over MCP and 500 over REST: “Something went wrong on our side. Please try again.” It carries no stack trace, vendor name or internal id.

Limits

When no AI call is placed

AI calls are placed only between 9am and 6pm in the business’s local time, only to landline and internet phone numbers unless the business has given verified consent, and not to businesses in Indiana, Louisiana, Minnesota, Montana and Nebraska. In every other case book returns call_yourself with one of these reasons.

no_phone

The business has no usable phone number.

mobile_number

The number is a mobile number. Without the business's verified consent, only landline and internet phone numbers are called.

line_type_unknown

The kind of line could not be determined, so the number is treated as one we may not call.

excluded_state

The business is in a state where no AI booking call is placed: Indiana, Louisiana, Minnesota, Montana and Nebraska.

outside_hours

It is outside 9am to 6pm in the business's local time. retryAfter says when a call becomes possible.

calls_stopped

The business asked us to stop AI calls to this number. That request is permanent.

call_limit

The business has had its limit of calls: 2 attempts for one request, or 3 calls in any 30 days.

Example prompts

These work:

• I need a haircut near 07030 on Friday after 5pm. Pick a barber and book it.
• My AC stopped cooling. Find an HVAC company in Hoboken, NJ and book the earliest visit this week.
• Find a house cleaner near Austin, TX 78704 and book a first clean for Saturday morning.
• Book a plumber for a leaking kitchen tap in Tampa, FL, any weekday between 9 and noon.
• Did my lawn care booking go through? If not, try the next business.

These are declined:

Book me a dentist appointment for a cleaning next week.

Health and dental bookings are out of scope. find_pick returns nothing_found with the reason unsupported_service.

Get me a table for four at an Italian place tonight.

Restaurant bookings are out of scope. find_pick returns nothing_found with the reason unsupported_service.

Find a plumber near Toronto, ON.

Only US locations are served. find_pick returns nothing_found with the reason unknown_location.

Data sources and notices

onepick's directory of businesses is built from open data. This file carries the notices those licences ask for.

No Google Places or Yelp content is used.

Business listings: Overture Maps Foundation, places theme

Business names, addresses, phone numbers, websites and locations come from the Overture Maps Foundation places theme, https://overturemaps.org. Each stored business records which upstream datasets it came from (dataSources, for example overture-places:meta).

The places theme combines several sources, each under its own licence (https://docs.overturemaps.org/attribution/):

The places theme contains no OpenStreetMap data.

Changes made by onepick

The data is changed before it is stored or shown: only places in the United States in six service categories are kept; places marked permanently closed are dropped; phone numbers are rewritten in E.164 form; duplicate listings of one business are merged; a timezone is derived from each location.

CDLA-Permissive-2.0

Section 2.1 of the agreement: "A Data Recipient may share Data, with or without modifications, so long as the Data Recipient makes available the text of this agreement with the shared Data."

The text of the agreement: https://cdla.dev/permissive-2-0/

Foursquare OS Places

Overture's note on these rows: Foursquare data was transformed to the Overture schema.

The Apache License, Version 2.0: http://www.apache.org/licenses/LICENSE-2.0

The full content of Foursquare's NOTICE.txt, as published at https://opensource.foursquare.com/places-notice-txt/ and read on 2026-09-21, unmodified:

© 2026 Foursquare Labs, Inc. All rights reserved.

The Foursquare OS Places dataset (the “Data”) is licensed under the Apache License, Version 2.0 (the “License”). You may not use, modify, or distribute the Data except in compliance with the License.

As set forth more fully in the License, if you use, modify, or distribute the Data, you must:
– provide recipients with a copy of the License.
– if applicable, include prominent notices to the extent you’ve changed the Data.
– preserve attribution to Foursquare, including preserving the full content of this NOTICE.txt file.

To ensure appropriate attribution to Foursquare, we recommend the following:
– if using/distributing the Data in flat file form as-is or after making changes/modifications: include this NOTICE.txt file, which may be modified to include an additional notice of your changes/modifications, if any.
– if using/distributing the Data in API form as-is or after making changes/modifications: include a copy of the content from this NOTICE.txt file prominently in your developer documentation for such API, which may be modified to include an additional notice of your changes/modifications, if any.

You may obtain a copy of the License at: http://www.apache.org/licenses/LICENSE-2.0. Unless required by applicable law or agreed to in writing, the Data distributed under the License is distributed on an “AS IS” BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.

See the License for the specific language governing permissions and limitations under the License.

We also encourage you to join our Placemaker community where you can contribute and provide suggestions to improve the accuracy of the Data for future releases for yourself and others.

Notice of changes, as that file invites: onepick's changes to the data are listed under "Changes made by onepick" above.

CC0 1.0 Universal

AllThePlaces rows are dedicated to the public domain: https://creativecommons.org/publicdomain/zero/1.0/

Zip codes and city names: United States Census Bureau

Zip code centroids, city names and their states come from the Census Bureau's 2025 gazetteer files and the 2020 ZCTA-to-county relationship file. Works of the United States government are in the public domain; no licence applies. This product uses Census Bureau data but is not endorsed or certified by the Census Bureau.

• https://www.census.gov/geographies/reference-files/time-series/geo/gazetteer-files.html
• https://www.census.gov/geographies/reference-files/time-series/geo/relationship-files.html

Timezones

Each business's and each location's timezone name (for example America/New_York) is worked out from its coordinates, offline, with the tz-lookup package. The package is published under CC0 1.0. Its boundary data comes from the timezone-boundary-builder project (https://github.com/evansiroky/timezone-boundary-builder), whose output is licensed under the Open Data Commons Open Database License (ODbL), https://opendatacommons.org/licenses/odbl/, and is derived from OpenStreetMap.

Timezone boundaries © OpenStreetMap contributors, https://www.openstreetmap.org/copyright.

onepick stores only the resulting timezone name beside each record; it does not store or redistribute the boundary data.

State license data

Whether a trade business holds a state license is checked against public license files published by three state agencies. Each stored license records the file it came from and the day that file was copied (source_file, source_date).

Changes made by onepick

Only heating and air conditioning, plumbing and electrical business licenses are kept. Names are normalized for matching, phone numbers are rewritten in E.164 form, and each agency's own status codes are reduced to "active" or "inactive". A license's current standing can change at any time: the agency's own lookup is the authority.

Texas Department of Licensing and Regulation (TDLR)

Source: Texas Department of Licensing and Regulation, https://www.tdlr.texas.gov, license data files at https://www.tdlr.texas.gov/LicenseSearch/licfile.asp. The date each record was copied is stored with it; the files are re-copied on every import.

This information is copied from the TDLR website. Neither onepick nor the way this information is presented is endorsed by the State of Texas or by TDLR. No TDLR logo is used.

Current status of any Texas license: https://www.tdlr.texas.gov/LicenseSearch/

California Contractors State License Board (CSLB)

Source: CSLB License Master file, https://www.cslb.ca.gov/onlineservices/dataportal/ContractorList. Information on State of California websites is, unless otherwise indicated, in the public domain (https://www.ca.gov/use/); no credit is required. The State of California makes no guarantee of its accuracy and does not endorse onepick.

Current status of any California license: https://www.cslb.ca.gov/OnlineServices/CheckLicenseII/CheckLicense.aspx

Florida Department of Business and Professional Regulation (DBPR)

Source: DBPR construction and electrical licensee files, https://www2.myfloridalicense.com/construction-industry/public-records/ and https://www2.myfloridalicense.com/electrical-contractors/public-records/, provided as public records under Chapter 119, Florida Statutes; no credit is required. DBPR does not endorse onepick.

Current status of any Florida license: https://www.myfloridalicense.com/wl11.asp