AI agents.

Most lookup requests use GET at https://api.parseapi.com. Bank prefers POST /bank with Content-Type: application/json: send the original IBAN and optional country/deep in the JSON body, or the documented US ACH routing/account body. Keep account input out of URLs, logs and analytics. Send X-API-Key, or Authorization: Bearer. Bare /ip and /useragent self-lookups also work without a key.

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).

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.

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.

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.

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.

Deep is per endpoint. Request it with ?deep=true for GET or deep: true in the Bank IBAN JSON body; US ACH has no Deep option. On successful responses, when not requested, 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.

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.

Errors contain code, message, docs, and request_id. A failed DNS lookup returns HTTP 503 with code dns_resolution_failed. Handle the code, not message text; this is not an invalid-mailbox verdict. Honor Retry-After on DNS failures, use at most two retries with jitter, and keep a total deadline. 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.

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.

Use POST /preflight with operation counts to estimate permissions, advisory capacity and additional charges. Its budget_usd is advisory. For an authorized task with an enforced additional-charge limit, POST /task with operations and budget_usd, then POST /task/{id}/lookup with operation, value, optional country and optional deep. Send a unique Idempotency-Key for creation and each intended lookup, and reuse it with identical inputs on retries. Tasks allow up to 1000 lookups, expire after 24 hours, and retain accessible results for 48 hours from creation. Inspect status_code and result in each saved execution. task_in_progress and task_outcome_unknown retain the reservation; never use a new ID to repeat uncertain work. GET /task/{id} reports budget and progress. POST /task/{id}/cancel prevents new work while started lookups can finish. A new request still needs room for its conservative maximum charge, even when included quota appears available. These task limits apply only through the task endpoint. Existing account limits still apply.