Public API documentation

Use the Levida API with authenticated account access.

This page is public so visitors can evaluate the workflow, but every useful API endpoint requires authentication. Examples below use placeholders only.

Overview

Base URL: https://levida.ai

Authentication: bearer token returned by the login endpoint.

Usage: send Authorization: Bearer YOUR_TOKEN on authenticated requests.

Authentication required

The account endpoint, lead-generation endpoints, import endpoints, and job polling require a valid API token tied to an account. Public docs do not imply public API access.

Login

curl -X POST https://levida.ai/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email":"YOUR_EMAIL","password":"YOUR_PASSWORD"}'

Poll job status

curl https://levida.ai/api/v1/lead-generation/jobs/JOB_ID \
  -H "Authorization: Bearer YOUR_TOKEN"

Generate leads

All lead-generation examples below require a valid bearer token.

Postal-code example

curl -X POST https://levida.ai/api/v1/lead-generation/jobs \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "search_method": "postal_code",
    "country": "Spain",
    "postal_code": "15005",
    "keyword": "fisioterapeuta"
  }'

Region and city example

curl -X POST https://levida.ai/api/v1/lead-generation/jobs \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "search_method": "region_city",
    "region": "A Coruña",
    "cities": ["A Coruña"],
    "keyword": "psicologos"
  }'

US ZIP example

curl -X POST https://levida.ai/api/v1/lead-generation/jobs \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "search_method": "us_zip",
    "zip_code": "90210",
    "keyword": "dentist"
  }'

Bulk example

curl -X POST https://levida.ai/api/v1/lead-generation/bulk \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "requests": [
      {
        "search_method": "postal_code",
        "country": "Spain",
        "postal_code": "15005",
        "keyword": "fisioterapeuta"
      },
      {
        "search_method": "region_city",
        "region": "A Coruña",
        "cities": ["A Coruña"],
        "keyword": "psicologos"
      }
    ]
  }'

Import existing leads

generate-leads creates new searches and queues new lead-generation jobs. import-leads uploads an existing CSV or JSON file of already collected leads into the authenticated account.

curl -X POST https://levida.ai/api/v1/leads/import \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"leads":[{"customer":"Example Business","city":"Madrid"}]}'

CLI quickstart

python3 scripts/levida_cli.py login --base-url https://levida.ai
python3 scripts/levida_cli.py generate-leads
python3 scripts/levida_cli.py generate-leads examples/generate_leads_postal_code.json --wait
python3 scripts/levida_cli.py import-leads leads.csv

Security

Keep API tokens private and rotate exposed tokens.
Use HTTPS for live traffic.
Do not commit tokens into scripts or example files.
Use placeholders like YOUR_TOKEN, YOUR_EMAIL, and YOUR_PASSWORD in shared documentation.

Error codes

400: validation or malformed request payload.
401: missing, invalid, or revoked authentication token.
413: payload too large.
429: request or queue limit reached.
500: server-side failure.