Agents

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

Free-plan users must include a link to ParseAPI on their website, app, or project documentation. A footer, about page, credits page, or another reasonable location is fine. Paid plans do not require ParseAPI attribution. Example HTML: Data provided by <a href="https://parseapi.com">ParseAPI</a>. Details: https://parseapi.com/legal/attribution#crediting-parseapi.

Pin application lookups with an exact X-API-Version request header, such as 2.1.0. Legacy Parse-Version pins are also accepted; both headers must match if sent together. With neither header, 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 X-API-Version response header for the exact version that answered. 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 routine lookups and eligible plan detail. Metered endpoints, including POST /email/verify, return 403 for App keys. 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.

API 2.1 returns the complete ordinary answer on Free and automatically includes existing profile detail on paid plans. Available fields appear at their natural homes beside the routine answer, including each collection item. There is no response deep object. Inaccessible optional fields are absent; returned unknown values are null. Test the field you need. Carrier and HLR return their complete selected result without a deep switch.

Email mailbox verification is explicit POST /email/verify with JSON {"email":"address@example.com"}; it uses your account's verification allowance or enabled on-demand billing. Use GET /email/{email} for ordinary validation; deep=true is rejected on that route in 2.1. /carrier/{number} (carrier + line type), /caller/{number} (caller ID, NANP), /hlr/{number} (live phone status, worldwide) are separate metered lookups. Check https://parseapi.com/docs/usage and https://parseapi.com/plans for 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.