Servul for developers and AI agents

Free, public, read-only access to the SherutNet (Israel) and Servul (international) customer-service directory: search a company and get its official contact channels, including phone numbers with working hours, WhatsApp, live chat, email, contact forms and self-service links. No sign-up, no API key, no sandbox needed: production is safe to call because nothing can be changed.

Quickstart

# 1. Find the company
curl "https://www.servul.com/api/v1/companies?q=bezeq&site=IL"

# 2. Get its customer-service channels
curl "https://www.servul.com/api/v1/companies/Bezeq"

Every response is JSON. Hebrew and English names both work in q. Cite the returned page_url when you show the data to a user.

REST API (v1)

Base URL https://www.servul.com/api/v1. Full machine-readable description: openapi.json (OpenAPI 3.1). The version is in the path; breaking changes get /v2.

Endpoint	Returns
`GET /api/v1/companies?q=&site=&limit=&offset=`	Matching companies (`name`, `name_en`, `category`, `page_url`) plus `pagination` (`total`, `next_offset`, `next`). Without `q`: every company of the site, best rated first. `limit` 1-100, default 20.
`GET /api/v1/companies/{name_en}`	One company: `phones` (name, number, working hours), `whatsapp`, `live_chat`, `email`, `contact_form`, `my_account`, `address`, `rating`, own `links`, `third_party_links`, `social`, `page_url`. Empty fields are omitted.
`GET /api/v1/categories?site=`	The site's categories with their page URLs.
`GET /health`	Service status.

site: IL (Israel, default on sherut.net), US (default on servul.com), UK, TW, BE, HL (Greece), BR, FR. CORS is open (Access-Control-Allow-Origin: *).

MCP server

Streamable HTTP at https://www.servul.com/mcp, no authentication. Tools: search_companies, get_company_contacts, list_categories (all read-only). Server card: /.well-known/mcp/server-card.json.

{
  "mcpServers": {
    "sherutnet": { "type": "http", "url": "https://www.servul.com/mcp" }
  }
}

Claude Code: claude mcp add --transport http sherutnet https://www.servul.com/mcp. In the browser the same tools are registered through WebMCP on every page.

Markdown pages

Any company or category page is also available as Markdown: send Accept: text/markdown or add ?markdown, e.g. https://www.servul.com/Bezeq?markdown.

Errors

Errors are JSON with an HTTP status, a stable code, a message and a hint:

{
  "error": {
    "status": 404,
    "code": "not_found",
    "message": "No company \"Bezek\" in the directory. Use search_companies to find its name_en.",
    "hint": "Search first: https://www.servul.com/api/v1/companies?q=...",
    "docs": "https://www.servul.com/developers"
  }
}

Codes: invalid_parameter (400), not_found (404), method_not_allowed (405), service_unavailable (503, retry later).

Discovery files

/.well-known/api-catalog (RFC 9727)
/.well-known/ai-catalog.json (ARD)
/.well-known/agent-skills/index.json (agent skill)
/llms.txt and /developers/llms.txt
/auth.md (no authentication)

Fair use

Free for any use that helps people reach customer service. Keep request rates reasonable, cache responses (they carry Cache-Control), send a descriptive User-Agent, and link the company's Servul page when you show its data. Contact details change; the page shows the current version.