# CrustAPI

> People Refresh, public LinkedIn data, Google Maps and Search through one API account.

Keep an existing people database current using LinkedIn profile URLs. CrustAPI also returns public person and company profiles, posts, jobs, people search and Google results. LinkedIn collection uses public, logged-out sources. Field availability varies by record.

## References

- [API documentation](https://crustapi.com/docs): requests, response fields, billing and integrations.
- [中文文档](https://crustapi.com/zh-cn/docs): Chinese API documentation.
- [OpenAPI specification](https://crustapi.com/v1/openapi.json): request parameters and response schemas.
- [Dashboard](https://crustapi.com/app): API keys, requests and billing.
- [People Refresh](https://crustapi.com/): refresh use cases and evaluation.
- [Datasets](https://crustapi.com/datasets): available datasets.

## Authentication

Base URL: `https://crustapi.com`. Pass your key in the `x-api-key` header. Keep keys in a secret or credential store.

```sh
curl "https://crustapi.com/v1/linkedin?type=refresh&url=https://www.linkedin.com/in/dharmesh" \
  -H "x-api-key: key_live_xxxx"
```

## People Refresh

`GET /v1/linkedin?type=refresh&url=<LinkedIn-profile-URL>`

Refresh returns a flat response. Compare it with your stored record to identify changes; it does not maintain your database or generate change reports automatically.

Returned fields, where available:

- `url`, `publicIdentifier`, optional `resolvedUrl`: requested identity and confirmed current destination.
- `firstName`, `lastName`: published name.
- `headline`, `headlineSource`, `currentTitle`, `titleSource`: headline, supported current role and provenance. `titleSource: "headline"` means derived from headline wording; `"linkedin"` means an explicit role title. A headline is not necessarily a title.
- `currentCompany`, `currentSchool`: objects containing `name`, `slug`, `linkedInUrl` and `linkedInId`. Numeric IDs are strings. Unknown IDs can be null.
- `accessible`, `profileState`, `companyState`: public readability and employer availability.
- `photo`, `photoState`: public photo and availability.
- `memorialized`, `memorializedSource`: true only when public memorialization is established; otherwise null. Null says nothing about whether a person is alive or an account is active.
- `memberIdentifier`: optional numeric member ID string with `member=true`. This option can increase response time.
- `tookMs`, `creditsRemaining`, and wallet `billing` where applicable. Compatibility credit counts are not dollar amounts.

`profileState` values:

- `accessible`: public data returned.
- `exists_not_public`: the profile is recognized but public data is unavailable; exact account settings are unknown.
- `not_resolvable`: the URL did not resolve to a profile. It does not prove permanent deletion.
- `unknown`: insufficient information to establish the state. Keep existing data and retry later.

`companyState` can be `public`, `restricted`, `not_published`, `unknown`, or null when unavailable. A missing employer does not prove a job change. Preserve existing values when new information is missing or uncertain. Automatic discovery of renamed profile URLs is not included. Inaccessible Refresh results are not charged.

## Other LinkedIn operations

Use `GET /v1/linkedin` with `type` and the appropriate URL, keywords or filters.

- `person` (alias `profile`): a person by URL, returned under `profile`. Available fields include identity, headline/current title, About text, location and flat city/state/country fields; employer name, IDs, domain, industry, size and headquarters; employment and education; skills, languages, certifications, courses, volunteering, organizations, publications, projects, honors and recommendations; follower/connection counts; websites, photo/background images and public account markers. Complete employment history is not guaranteed.
- `company`: a company or showcase page by URL, returned under `company`. Identity, industry, size band, employee count, headquarters, website, founding year, specialties, addresses, locations, similar/affiliated pages, employee sample, featured products, published contacts and images when available. An affiliate is not necessarily a subsidiary; samples are not a complete workforce or product catalog. Published contacts are not verified primary contacts.
- `people` (alias `search`): people matching names, professions or supported filters, returned in `people`. Filters include location, title/profession, company, school, industry, company size, past company, follower/connection/experience counts and exclusions. `enrich=true` returns available full profiles and bills per full profile returned.
- `posts`: public posts from a person or company URL, returned in `posts`. Available text, date, URL, author, images, reactions and comment counts. `comments=true` adds available comments.
- `job` / `jobs`: a job URL returns one record under `jobs`; keywords or filters return a `jobs` array. Available title, company, location, description, seniority, employment type, functions, industries, salary, poster and status. Optional fields include `datePosted`, `validThrough`, `educationRequirements`, `experienceRequirements`, `jobLocation`, `sourceJobIdentifier` and `jobMetadataSource`. Search and detail fields can differ. `validThrough` is a published validity date, not confirmed closure.

Person `currentCompany` is a name string. Refresh `currentCompany` is an object. Do not use the same field mapping for both.

Employment rows can include role title, employer name/URL/ID, location, description, dates, logo and provenance. `experienceAvailability` counts returned rows: `returnedPositions`, `positionsWithTitle`, `positionsWithDerivedTitle`, `positionsWithStartDate`, `positionsWithEndDate`, `positionsWithDescription`. Source and derived titles are counted separately. These counts and `experienceState` do not establish complete work history. Missing end dates do not prove a current role.

Education rows can include school name/URL/ID, degree, field of study, dates, description and logo. `websites` contains `{url, label}` links; `website` is the single-link field. `recommendations` may be a subset of `recommendersCount`.

Company `employeeCount` differs from the `companySize` band. `locations` can include `addressLines`, `directionsUrl` and `isPrimary`. `employeeSearchCompanyIds` is not a replacement for the company’s own ID. `jobSearchUrl` is not a vacancy count. `employees=true` adds a separate people sample.

Person/profile options include `email=true` for `workEmail`, `emailStatus`, `emailConfidence` and `companyDomain`; `domain` supplies a known employer domain. `pattern-likely` is unverified. A successful profile remains billable if no email is found. `companyId=true` and `schoolId=true` request numeric IDs for the first returned company or school. Other rows can include IDs when available.


People/Jobs `count=true` gives a free count preview without rows. Check `totalCapped` when returned; `totalAvailable` can be null when unavailable. Search results can include `source`, `returned`, `totalAvailable` and `totalCapped`. Search data can be periodically updated; returned fields do not guarantee that a person has updated their profile.

## Bulk requests and webhooks

`POST /v1/linkedin/batch` accepts `refresh`, `person`/`profile`, `company` or `posts`.

```json
{
  "type": "refresh",
  "urls": ["https://www.linkedin.com/in/dharmesh"]
}
```

Send `x-api-key` and `Content-Type: application/json`. Up to 100 URLs return synchronously in a `results` array in input order. Rows contain `url`, `ok`, and `data` or `error`. `data` is the operation payload without the single-request timing/billing envelope. Inaccessible results are uncharged; inspect `data.accessible` or `notAccessible` where present. One failed row does not fail other rows.

For up to 10,000 URLs, add `webhook` with a public HTTPS URL. HTTP 202 returns `jobId`, `status` and `count`. The webhook receives completed results with the `X-Crustapi-Job` header. Large results may arrive as a temporary `resultsUrl`, with `resultsBytes` and `resultsExpireAt`. Download before expiry; the temporary file is then deleted. Save inline results in your own system.

`GET /v1/linkedin/batch?id=<jobId>` with the same account’s key returns status, counts and delivery information, not result rows. Webhook URLs cannot contain embedded credentials. Redirects are not followed; failed delivery is retried once.

Options: `member: true` for Refresh, `comments: true` for posts. Batch does not support `employees=true`. Successful rows use their endpoint’s rate. Unavailable results and malformed URLs are uncharged.

## Google Maps and Search

`GET /v1/search?type=<surface>&q=<query>`

Types: `maps`, `web`, `places`, `news`, `shopping`, `images`, `videos`, `reviews`, `scholar`, `patents`, `autocomplete`, `webpage`, `lens`.

```sh
curl "https://crustapi.com/v1/search?type=maps&q=coffee%20shops%20in%20Denver%20CO&limit=1" \
  -H "x-api-key: key_live_xxxx"
```

Maps returns businesses in `places`. Available fields:

- `position`, `title`, `placeId`, `fid`, `cid`, `url`.
- `address`, `street`, `city`, `state`, `postalCode`, `countryCode`, `location: {lat, lng}`.
- `phone`, `phoneUnformatted`, `website`.
- `categoryName`, `categories`, `description`.
- `totalScore`, `reviewsCount`, `reviewsDistribution`.
- `openingHours`, `priceLevel`, `permanentlyClosed`.
- `mainImage`, `thumbnailUrl`, `bookingLinks`, `attributes`, `scrapedAt`.

Maps field availability varies by business, category and country. `stars=true` (alias `details=true`) requests available `reviewsDistribution` counts: `oneStar`, `twoStar`, `threeStar`, `fourStar`, `fiveStar`. This option can increase response time. Use `type=reviews` for individual review text. The lean `places` response uses different names, including `rating`, `ratingCount` and `phoneNumber`; do not substitute these for Maps names.

Common parameters: `gl` country, `hl` language, `location` for Maps/Places, `limit` for Maps (default 20, max 100), `page` where supported. Reviews uses `num` (default 20, max 50), a listing identifier and optional sort/page token. Webpage and Lens take `url`; Lens takes an image URL and does not use country/language filters. See OpenAPI for operation-specific parameters.

Identical Google searches may reuse a result for up to 60 seconds, marked `cached: true` and `cacheAgeSeconds`. Use `fresh=1` to request a fresh result. Respect HTTP 429 and `Retry-After`; failed and rate-limited calls are uncharged.

## Pricing and accounting

- Eligible accounts get $6 free usage monthly. Paid funds never expire. Deposits start at $10.
- Each deposit qualifies separately and retains its rates until spent. Free funds are spent first, then the cheapest applicable paid funds, oldest first for ties.
- Starting prices per 1,000 units: Refresh, People, Jobs and Maps $1.96; Google Search $1.00; person profiles $4.00; companies $3.00; posts $6.00. Larger deposits lower rates; use the current pricing page for the complete table.
- Maps bills per business, Refresh per accessible profile and enriched People per full profile. Other operations bill per successful request. Work email is included. Empty and failed results are free.
- Wallet `billing.chargedUsd` and `billing.remainingUsd` are decimal strings. `GET /v1/balance` returns `wallet.availableUsd`, available funds and saved prices.
- Numeric `credits`, `charged` and `creditsRemaining` compatibility fields are not dollars. Accounts still using legacy credits and the separate x402 agent path retain their applicable terms.

## Connect with HTTP requests

Use any tool that supports HTTP requests and custom headers. Add a GET request with the endpoint and query parameters below, and pass your API key in the `x-api-key` header. Store the key in your tool’s credential settings.

- People Refresh: `/v1/linkedin`, query `type=refresh` and `url` mapped to a LinkedIn profile URL. Map `currentCompany.name`, `currentCompany.linkedInId`, `currentTitle`, `titleSource` and `profileState` from the response root. Preserve saved values when new information is unavailable.
- Local businesses: `/v1/search`, query `type=maps`, `q` mapped to a business name and location, and `limit=1`. Map the first result’s `website`, `phone`, `address`, `totalScore` and `reviewsCount` fields under `places[0]`. Verify the name, address and website before accepting a match. The first result is not a guaranteed company-domain match.

Map the returned JSON fields into your workflow or spreadsheet. Full examples: https://crustapi.com/docs#integrations.

## MCP and CLI

The published `crustapi-mcp` package supplies `search`, `scrape_webpage`, `get_reviews` and `linkedin`. Its LinkedIn tool currently supports profile, company, posts, jobs and people search. For Refresh and additional endpoint options, use an HTTP tool with the OpenAPI specification.

```json
{
  "mcpServers": {
    "crustapi": {
      "command": "npx",
      "args": ["-y", "crustapi-mcp"],
      "env": {"CRUSTAPI_API_KEY": "key_live_xxxx"}
    }
  }
}
```

CLI examples:

```sh
npm install -g crustapi-cli
export CRUSTAPI_API_KEY=key_live_xxxx
crust linkedin https://www.linkedin.com/in/dharmesh
crust search coffee --type maps --location "Austin, TX" --limit 20
crust search plumbers --type maps --csv > leads.csv
```

CLI output goes to stdout; status messages go to stderr. `--csv` returns CSV.

## Agent payments (x402)

The separate x402 path uses USDC on Base. `POST /v1/x402/topup?pack=agent` returns HTTP 402 payment requirements. A compatible wallet signs and retries; successful settlement returns an API key and credits. The agent pack is $5 for 2,500 credits. It is separate from dashboard wallet deposits. See https://crustapi.com/docs#x402 for the flow.

## Support

support@crustapi.com · https://crustapi.com/terms · https://crustapi.com/privacy

## Google response field references

The endpoint selector at https://crustapi.com/docs#quickstart includes an expandable Response fields reference for every Google operation. Fields are listed individually with types and availability notes; nested objects expand into child fields. The canonical OpenAPI reference at https://crustapi.com/v1/openapi.json provides a separate Google response schema for each operation.