# Find Company By Phone

`lawmatics_find-company-by-phone` · Lawmatics MCP tool · Lookups

Fuzzy-find a single company in Lawmatics by phone number. Searches the company's own phone, then falls back to associated contacts. Returns company details, postal addresses, and a `relationships` envelope of {id,type} pointers to related records (primary contact, associated contacts and matters, tags, emails, phone numbers, addresses, notes, and the creating user). Returns `{ match: <entity> }` on a hit and `{ match: null }` when no record matches. `match: null` is a normal empty result, not an error — do not retry.

## Input

- **phoneNumber** `string` (required, min length: 1) — Phone number to search for. Lawmatics strips non-digits and tries with and without a leading 1 for US numbers, then falls back to searching associated contacts.

## Output

- **match** `object | null` (required) — The single best matching company, or null if nothing matched. Returns `{ match: <entity> }` on a hit and `{ match: null }` when no record matches. `match: null` is a normal empty result, not an error — do not retry.
  - **id** `string` (required) — Lawmatics company ID
  - **name** `string` (required) — Company name
  - **email** `string | null` (required) — Company email address; null if unset
  - **address** `string | null` (required) — Full formatted address as a single line; null if unset
  - **city** `string | null` (required) — City; null if unset
  - **state** `string | null` (required) — State or province; null if unset
  - **postalCode** `string | null` (required) — Postal/ZIP code; null if unset
  - **country** `string | null` (required) — Country; null if unset
  - **phoneNumber** `string | null` (required) — Company phone number, as stored; null if unset
  - **createdAt** `string` (required) — When the company was created, as an ISO 8601 timestamp
  - **updatedAt** `string` (required) — When the company was last updated, as an ISO 8601 timestamp
  - **addresses** `array` (required) — Structured postal addresses on the company; may be empty
    - **[]** `object`
      - **id** `number` (required) — Address record ID
      - **street** `string` (required) — Street address line 1
      - **street2** `string | null` (required) — Street address line 2 (suite, unit); null if unset
      - **city** `string` (required) — City
      - **state** `string` (required) — State or province
      - **postalCode** `string` (required) — Postal/ZIP code
      - **country** `string` (required) — Country
      - **label** `string` (required) — Address label (e.g. Primary, Billing)
      - **addressableType** `string` (required) — Type of record this address belongs to (e.g. Company)
      - **addressableId** `number` (required) — ID of the record this address belongs to
      - **firmId** `number` (required) — ID of the Lawmatics firm that owns this address
      - **deletedAt** `string | null` (required) — Soft-deletion timestamp as ISO 8601; null if not deleted
      - **createdAt** `string` (required) — When the address was created, as an ISO 8601 timestamp
      - **updatedAt** `string` (required) — When the address was last updated, as an ISO 8601 timestamp
  - **relationships** `object` (required) — JSON:API relationship pointers to related records as {id,type} stubs. Not materialized — follow a pointer by calling that resource's own get/find tool (e.g. type 'contact' -> get-contact, type 'user' -> get-user). Distinct from the `addresses` attribute array above, which carries the nested address objects directly.
    - **primaryContact** `object | null` (required) — Primary contact pointer; null when unset
      - **id** `string` (required) — ID of the referenced Lawmatics record
      - **type** `string` (required) — JSON:API record class of the reference (e.g. "user", "contact", "prospect", "firm"); resolve it by calling that resource's own get/find tool — this pointer is not materialized
    - **createdBy** `object | null` (required) — Creating user pointer; null when unset
      - **id** `string` (required) — ID of the referenced Lawmatics record
      - **type** `string` (required) — JSON:API record class of the reference (e.g. "user", "contact", "prospect", "firm"); resolve it by calling that resource's own get/find tool — this pointer is not materialized
    - **contacts** `array` (required) — Associated contact pointers; empty if none
      - **[]** `object`
        - **id** `string` (required) — ID of the referenced Lawmatics record
        - **type** `string` (required) — JSON:API record class of the reference; resolve it by calling that resource's own tool
    - **prospects** `array` (required) — Associated matter (prospect) pointers; empty if none
      - **[]** `object`
        - **id** `string` (required) — ID of the referenced Lawmatics record
        - **type** `string` (required) — JSON:API record class of the reference; resolve it by calling that resource's own tool
    - **tags** `array` (required) — Tag pointers; empty if none
      - **[]** `object`
        - **id** `string` (required) — ID of the referenced Lawmatics record
        - **type** `string` (required) — JSON:API record class of the reference; resolve it by calling that resource's own tool
    - **emails** `array` (required) — Email-address pointers; empty if none
      - **[]** `object`
        - **id** `string` (required) — ID of the referenced Lawmatics record
        - **type** `string` (required) — JSON:API record class of the reference; resolve it by calling that resource's own tool
    - **phoneNumbers** `array` (required) — Phone-number pointers; empty if none
      - **[]** `object`
        - **id** `string` (required) — ID of the referenced Lawmatics record
        - **type** `string` (required) — JSON:API record class of the reference; resolve it by calling that resource's own tool
    - **addresses** `array` (required) — Address pointers; empty if none
      - **[]** `object`
        - **id** `string` (required) — ID of the referenced Lawmatics record
        - **type** `string` (required) — JSON:API record class of the reference; resolve it by calling that resource's own tool
    - **notes** `array` (required) — Note pointers; empty if none
      - **[]** `object`
        - **id** `string` (required) — ID of the referenced Lawmatics record
        - **type** `string` (required) — JSON:API record class of the reference; resolve it by calling that resource's own tool