API examples

These examples use the production API. Start in the Playground if you want to build and inspect the same requests in your browser.

Set your key once before running an authenticated example:

export SEMANTIL_API_KEY="your_api_key"

Inspect available fields and billing

Use the public field catalog before requesting domain data. It includes the two billing units and requires no API key.

curl "https://semantil.com/api/fields"

The response describes available fields, filters and the company-record and paid lead units with their current credit costs.

Enrich a company you already know

Use domain enrichment when you have a company website and need structured facts about that specific business.

curl --get "https://semantil.com/api/domains/notino.pl" \
  -H "Authorization: Bearer $SEMANTIL_API_KEY" \
  --data-urlencode "include=domain,company_name,country,ecommerce_platform,tech,payment_providers" \
  --data-urlencode "max_credits=1"

The request returns selected fields from the same complete first-party record. Omit include to receive every approved record field. Selecting fewer fields reduces the payload, not the one-credit record price.

Paid accounts can request quality-gated registry and business-contact evidence with enrich=true. The lead add-on costs four additional credits only when evidence is found:

curl --get "https://semantil.com/api/domains/notino.pl" \
  -H "Authorization: Bearer $SEMANTIL_API_KEY" \
  --data-urlencode "enrich=true" \
  --data-urlencode "include=domain,company_name,vat_number,contact_email" \
  --data-urlencode "max_credits=5"

Search for companies in a target market

Use search when you can describe the companies you want but do not yet know their domains.

curl --get "https://semantil.com/api/search" \
  -H "Authorization: Bearer $SEMANTIL_API_KEY" \
  --data-urlencode "query=online fashion store" \
  --data-urlencode "query_operator=and" \
  --data-urlencode 'filters={"country":["Germany"]}' \
  --data-urlencode "include=domain,company_name,country,ecommerce_platform" \
  --data-urlencode "limit=10"

The text query defines the business intent. filters narrows it with exact catalog values. Use the public GET /api/fields catalog to discover filter names and their published value sources instead of guessing the contract.

Find companies similar to a good example

Use lookalike when you already know a representative customer, prospect, or competitor and want more companies with a similar profile.

curl --get "https://semantil.com/api/lookalike/notino.pl" \
  -H "Authorization: Bearer $SEMANTIL_API_KEY" \
  --data-urlencode "k=10" \
  --data-urlencode 'filters={"country":["Poland"]}' \
  --data-urlencode "include=domain,company_name,country,ecommerce_platform" \
  --data-urlencode "include_evidence=true"

The seed domain provides the similarity signal. Filters constrain the candidate market, while include_evidence=true explains why candidates matched when evidence is available.

Exclude companies already in your CRM

Use POST /api/search when a search must omit a list of known customers or accounts. Send domains in the JSON body so they never appear in the URL.

curl "https://semantil.com/api/search" \
  -X POST \
  -H "Authorization: Bearer $SEMANTIL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "cosmetics manufacturer",
    "query_operator": "and",
    "filters": {"country": ["Poland"]},
    "exclude_domains": ["existing-customer.pl", "current-account.com"],
    "include": "domain,company_name,country,site_category",
    "limit": 10
  }'

Send the complete current exclusion list with each request. Semantil normalizes domains before applying the exclusions.

Measure a market instead of returning companies

Use a breakdown when you need a categorical distribution for a segment rather than individual company rows.

curl --get "https://semantil.com/api/search" \
  -H "Authorization: Bearer $SEMANTIL_API_KEY" \
  --data-urlencode "query=online store" \
  --data-urlencode "query_operator=and" \
  --data-urlencode 'filters={"country":["Germany"]}' \
  --data-urlencode "breakdown=ecommerce_platform" \
  --data-urlencode "population=ecommerce" \
  --data-urlencode "breakdown_limit=10"

Only fields published as breakdown facets by GET /api/fields are accepted. The response describes the segment, field coverage, missing values, and the returned buckets.

Inspect usage after a request

Authenticated responses expose the charged amount and remaining balance in response headers. Add -i to any example to inspect them:

curl -i -H "Authorization: Bearer $SEMANTIL_API_KEY" \
  "https://semantil.com/api/me"

Use the usage guide for request caps and charging behavior, and the API reference for the complete contract.