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 data

Use the public product catalog before selecting domain data. No API key is required.

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

The response lists current product IDs, descriptions, fields, bundles, and usage units.

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 "products=profile,tech" \
  --data-urlencode "include=country,site_category,primary_platform,tech"

The request selects only the profile and tech products, then narrows the response to the fields needed by the integration. Omit include to receive all fields in the selected products.

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,primary_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,primary_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=primary_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.