# Company qualification: API Bridge function `qualify`

Base URL `https://tools.epsimo.org`; auth with the `x-token` header; credits, rate limits and errors for every function: https://tools.epsimo.org/llms-full.txt

## Purpose

Industry, target audience, market and a value proposition from any company website.

## When to use

- You need the industry, target audience, market (B2B/B2C) and a one-sentence value proposition of a company from its website.

## Do not use when

- You also need the registry record or the email domain: call `enrich` once instead of several functions.
- You need raw page text (use `scrape`) or a free-form answer (use `question`).

## Endpoint

- Method and URL: `POST https://tools.epsimo.org/qualify`
- Auth: `x-token: $API_KEY` header (API key from https://tools.epsimo.org/#signup)
- Cost: 4 credits, 1 credit when served from the 7-day cache

## Request fields

| Name | Type | Required | Default | Constraints | Description |
| --- | --- | --- | --- | --- | --- |
| `url` | string | yes | - | - | The company website URL to scrape and qualify. |
| `refresh` | boolean | no | `false` | - | Bypass the 7-day result cache and recompute (full cost). |

## Example request

```bash
curl -X POST https://tools.epsimo.org/qualify \
  -H "x-token: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://acme.fr"}'
```

Request body:

```json
{
  "url": "https://acme.fr"
}
```

## Example response

```json
{
  "value_proposition": "ACME builds cloud invoicing software for small businesses.",
  "industry": "Software",
  "target_audience": "business owners",
  "market": "B2B",
  "status": 200,
  "error_message": null
}
```

Trimmed: some fields are omitted; "..." marks omitted fields.

## Response notes

- Results are cached 7 days per normalised URL; a cache hit has `cached: true` and costs the cached price. `refresh: true` recomputes at full cost.
- HTTP 200 with a body `status` other than 200 (for example 422 when the site could not be read, 400 for an invalid URL) is a failure and is not billed.
- The classification is generated by a language model from the site text: treat it as an estimate.

## Errors

- 402: Insufficient credits
- 403: Invalid or missing token, forbidden key, or terms not accepted
- 422: Request validation failed (a field is missing, mistyped or out of range)
- 429: Rate limit exceeded or monthly quota reached (`Retry-After` seconds; 60 for the rate limit)

Error body: `{"status": <int>, "error_message": "<text>"}`.

## MCP tool

Tool `qualify_company` on `https://tools.epsimo.org/mcp`.
Arguments: `url` (required), `refresh`.