> ## Documentation Index > Fetch the complete documentation index at: https://docs.inboxfound.com/llms.txt > Use this file to discover all available pages before exploring further. # Find a person's email address > Give a full name and the domain the company receives mail at. We try the likely address formats for that name, ask the mail host about each, and return the one that qualifies. Charged only when exactly one candidate qualifies (`status: "found"`). Ambiguous, not-found and every failure mode are released. ## OpenAPI ````yaml /api-reference/openapi.yaml post /api/v1/find openapi: 3.1.0 info: title: InboxFound API version: '1' description: > Find a person's work email from a name and a company domain, or verify an address you already have. Every submission is asynchronous: you receive a job at once and poll it until `execution_state` is terminal. Base URL: `https://inboxfound.com` (preview: `https://emailfinder-web-preview.zhy27027.workers.dev`). contact: email: hello@inboxfound.com servers: - url: https://inboxfound.com description: Production - url: https://emailfinder-web-preview.zhy27027.workers.dev description: Preview security: - apiKey: [] tags: - name: Lookups description: Submit work and read results. - name: Account description: Read your wallet. paths: /api/v1/find: post: tags: - Lookups summary: Find a person's email address description: | Give a full name and the domain the company receives mail at. We try the likely address formats for that name, ask the mail host about each, and return the one that qualifies. Charged only when exactly one candidate qualifies (`status: "found"`). Ambiguous, not-found and every failure mode are released. operationId: find parameters: - $ref: '#/components/parameters/IdempotencyKey' requestBody: required: true content: application/json: schema: type: object required: - name - domain additionalProperties: false properties: name: type: string minLength: 2 maxLength: 160 description: Full name as the company would write it. example: Rachel Okafor domain: type: string maxLength: 254 description: Bare domain, no scheme or path. example: example.com responses: '202': description: Job accepted. Poll `GET /api/v1/jobs/{id}`. content: application/json: schema: $ref: '#/components/schemas/Job' example: id: b7d2e9a4-1c3f-4e8a-a5b6-2d9f0c1e7a34 operation: find execution_state: queued billing: reserved charged_micros: 0 rate_micros: 8000 result: null '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '402': $ref: '#/components/responses/InsufficientFunds' '403': $ref: '#/components/responses/Forbidden' '409': $ref: '#/components/responses/Conflict' '429': $ref: '#/components/responses/RateLimited' '503': $ref: '#/components/responses/Unavailable' components: parameters: IdempotencyKey: name: Idempotency-Key in: header required: true description: | 16 to 100 characters, letters, digits, underscore and hyphen only. A UUID fits. Anything outside that returns `400` `idempotency_key_required_16_to_100_characters`. Retrying with the same key and the same input returns the original job instead of starting or charging a second one. The same key with a different input returns `409`. schema: type: string minLength: 16 maxLength: 100 pattern: ^[a-zA-Z0-9_-]{16,100}$ example: 4f1d9c2a-7b30-4a11-9f5e-2c8d6a0b3e77 schemas: Job: type: object required: - id - operation - execution_state - billing - charged_micros - rate_micros - result properties: id: type: string format: uuid operation: type: string enum: - find - verify execution_state: type: string enum: - queued - running - complete - incomplete - review description: > Whether the work finished. `complete` and `incomplete` are terminal. `incomplete` means a stage did not finish and the result may be missing or partial; it is never presented as a confident negative. `review` means the job is parked for an operator; do not resubmit it. billing: type: string enum: - reserved - charged - released description: What happened to the reservation. Independent of `execution_state`. charged_micros: type: integer description: Micro-dollars captured. Zero until `billing` is `charged`. rate_micros: type: integer description: The rate reserved for this job, fixed at submission. result: oneOf: - $ref: '#/components/schemas/VerifyResult' - $ref: '#/components/schemas/FindResult' - type: 'null' description: Null until the engine has answered. VerifyResult: type: object required: - operation - email - status - reason - provider - domain - catch_all - role - free - disposable - retryable - checked_at properties: operation: type: string enum: - verify email: type: - string - 'null' status: type: string enum: - valid - invalid - catch_all - unknown description: | `valid` and `invalid` are definite answers and are charged. `catch_all` means the domain accepts every address and we found no profile tying this one to a real account. `unknown` covers everything else, including a host that refuses checks. See `reason` for which. reason: type: string enum: - recipient_accepted - profile_linked - recipient_rejected - domain_cannot_receive - catch_all_domain - policy_block - temporary_failure - insufficient_evidence description: | Why the status landed where it did. `profile_linked` is the interesting one: an accept-all domain where our identity lane tied this exact address to a real account profile and a control address to none. That is a `valid`, and it is charged. provider: type: - string - 'null' description: >- Mail provider inferred from MX, e.g. `google`, `microsoft`, `proofpoint`. Null when unknown or self-hosted. domain: type: - string - 'null' catch_all: type: - boolean - 'null' description: >- True when the domain accepts every address. Can be true on a `valid` result when identity evidence settled the mailbox anyway. role: type: boolean description: Shared mailbox such as info@ or sales@. free: type: boolean description: Consumer mailbox provider such as gmail.com. disposable: type: boolean description: Throwaway mailbox provider. retryable: type: boolean description: The host asked us to try again later. checked_at: type: - string - 'null' format: date-time FindResult: type: object required: - operation - email - status - reason - confidence - mailbox - provider - domain - role - free - disposable properties: operation: type: string enum: - find email: type: - string - 'null' description: The address when exactly one qualified. Null otherwise.: null status: type: string enum: - found - not_found - unknown description: | `found` means exactly one candidate qualified; it is the only charged outcome. `not_found` means every candidate was rejected by the host. `unknown` means we could not tell — several qualified, or the domain accepts everything, or the search could not run. **`unknown` is never evidence that the person has no address.** reason: type: string enum: - qualified - all_rejected - ambiguous - unconfirmed - unavailable description: Which flavour of the status above. confidence: type: - string - 'null' enum: - high - medium - low - null description: | `high` means the identity lane tied the address to a real account profile. `medium` means the host accepted it after a complete search. `low` means the search did not finish. Null when no address was emitted. mailbox: type: string enum: - valid - invalid - catch_all - unknown - unverified description: >- Mailbox validity of the emitted address. `unverified` means no probe ran. provider: type: - string - 'null' domain: type: - string - 'null' role: type: boolean free: type: boolean disposable: type: boolean Error: type: object required: - error - requestId properties: error: type: string description: Stable machine-readable code. See Errors. requestId: type: string description: >- Quote this in a support message. It identifies the request without exposing your input. responses: BadRequest: description: The body could not be used. Nothing was reserved. content: application/json: schema: $ref: '#/components/schemas/Error' example: error: invalid_email requestId: 6c1e0b2a-4d3f-4a7e-9b8c-1f2e3d4c5b6a Unauthorized: description: Missing, revoked or unknown key. content: application/json: schema: $ref: '#/components/schemas/Error' example: error: valid_api_key_required requestId: 6c1e0b2a-4d3f-4a7e-9b8c-1f2e3d4c5b6a InsufficientFunds: description: Not enough available credit to reserve the job. Nothing was reserved. content: application/json: schema: $ref: '#/components/schemas/Error' example: error: insufficient_funds requestId: 6c1e0b2a-4d3f-4a7e-9b8c-1f2e3d4c5b6a Forbidden: description: The key or account cannot do this right now. content: application/json: schema: $ref: '#/components/schemas/Error' example: error: key_scope_denied requestId: 6c1e0b2a-4d3f-4a7e-9b8c-1f2e3d4c5b6a Conflict: description: The same idempotency key was reused with a different input. content: application/json: schema: $ref: '#/components/schemas/Error' example: error: idempotency_conflict requestId: 6c1e0b2a-4d3f-4a7e-9b8c-1f2e3d4c5b6a RateLimited: description: >- Too many submissions or jobs in flight. Retry after `Retry-After` seconds. headers: Retry-After: schema: type: integer content: application/json: schema: $ref: '#/components/schemas/Error' example: error: rate_limit_exceeded requestId: 6c1e0b2a-4d3f-4a7e-9b8c-1f2e3d4c5b6a Unavailable: description: Execution is paused or unreachable. No funds are reserved. content: application/json: schema: $ref: '#/components/schemas/Error' example: error: engine_temporarily_unavailable requestId: 6c1e0b2a-4d3f-4a7e-9b8c-1f2e3d4c5b6a securitySchemes: apiKey: type: http scheme: bearer description: >- Server-side API key created in the dashboard. Send as `Authorization: Bearer ak_…`. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.