Agent integration guide.

Build one working lookup

Inspect the project's language, runtime, and existing patterns. Prefer an official SDK when available: Node, Python, Go, Ruby, PHP, Rust, Swift, and Kotlin. Read its installation and usage instructions before writing code. Do not guess package names or methods.

For a server integration, load the secret key from an environment variable. This core IP request uses PARSE_API_KEY from the terminal environment.

curl --max-time 15 --fail-with-body \
  "https://api.parseapi.com/ip/8.8.8.8" \
  -H "X-API-Key: ${PARSE_API_KEY}"

Inspect the HTTP status and returned JSON before connecting fields to the application. Verify a valid input, an invalid input, an unknown result, and an error. Follow the selected endpoint's behavior rather than assuming every failed validation uses the same status.

Follow the integration contract

1. Lookup requests use GET at https://api.parseapi.com. Send X-API-Key, or Authorization: Bearer. Bare /ip and /useragent self-lookups also work without a key.
2. Pin application lookups with an exact Parse-Version request header, such as 2.0.0. Without it, keyed requests use the saved team default and keyless self-lookups use 1.0.0. Keep the pin with the code through staging, deployment and rollback. Version-pinned SDKs send their supported contract automatically. Earlier published packages keep their original behavior. Check the Parse-Version response header. Invalid or unsupported headers return invalid_request (400), and retired selections return api_version_retired (410).
3. Keep secret keys on the server and out of source control, logs, URLs, browser bundles, and mobile apps. Use a parse_public_ key for browsers and list the allowed domains, including localhost for local development. Use a parse_app_ key with the Swift or Kotlin SDK for native apps. List the exact bundle ID or package name and send X-App-Id.
4. App keys support core lookups and plan deep. Metered endpoints return 403. Email and VAT deep return core plus deep: {} without a verification charge. Run metered checks from a server with a secret key.
5. Read the selected endpoint's parameters and coverage before coding. Country is optional for State and Postal. Add a country code, such as ?country=US, when the input needs disambiguation. Encode values and query parameters instead of concatenating raw user input.
6. Check HTTP status and response fields. false is a negative answer. null means no answer is available. An omitted field is absent from this response. Do not turn unknown values into false or reject a valid response because a new field appears.
7. Deep is per endpoint. On successful responses, without ?deep=true, deep is omitted. When requested but unavailable for the endpoint, plan, or key type, deep is {}. When included, deep contains fields that may individually be null. Test the field you need, not the truthiness of an empty object. Phone already returns its full parsing result. ?deep=true only adds deep: {}. Exhausted metered allowances can return quota_exceeded instead of a lookup result.
8. Plan deep is included on eligible paid plans. Email and VAT deep use metered allowances, including limited checks on Free. /carrier/{number} (carrier + line type), /caller/{number} (caller ID, NANP), /hlr/{number} (live phone status, worldwide) are separate metered lookups with included monthly units. Check https://parseapi.com/docs#usage and the selected endpoint for what counts as a unit. Use https://parseapi.com/plans for current allowances and rates.
9. Errors contain code, message, docs, and request_id. Set a timeout. Honor Retry-After for rate_limited, and use bounded backoff for temporary connection failures, server_error, or service_unavailable. quota_exceeded needs allowance or billing action, not a retry loop. A timeout may follow a processed request. Repeating a metered check can consume another unit. Official SDKs default to no automatic retries for metered checks.
10. Before running live metered checks or starting paid Bulk processing, explain the intended checks and usage, and get the user's approval unless that scope is already authorized. Do not enable paid checks, on-demand usage, or automatic metered retries as an incidental part of setup.

Response fieldsError codesUsageCurrent plans

Use the tools already connected

If ParseAPI is available through MCP, inspect the available tool definitions and call the tool that matches the requested lookup. Use its result as evidence. Do not present an answer as a verified lookup without a successful call.

The hosted MCP server is https://mcp.parseapi.com. If a connection is needed, direct the user to MCP setup. Tool calls use the same plan allowances and metered usage as the API.

For a spreadsheet task, use Bulk. Review the free sample, selected columns, quote, and current pricing and refund terms before approving paid processing.