> ## Documentation Index
> Fetch the complete documentation index at: https://docs.datadingo.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Fuzzy company lookup by name

> Look up an Australian company by free-text name. Runs an exact / prefix / words-in-order / trigram match ladder over each company's searched names (display, legal, trading, trustee names and LinkedIn specialties), returning a best_match candidate (when one dominates) plus the other ranked candidates, every one as a short company card (`GET /v1/company?id=` for a full card). Every candidate says which name it matched on (`matched_on`).



## OpenAPI

````yaml /openapi.json get /v1/company/by-name
openapi: 3.1.0
info:
  title: DataDingo API
  description: Company enrichment API.
  version: 1.0.0
  termsOfService: https://datadingo.com/terms
servers:
  - url: https://api.datadingo.com
security:
  - bearerAuth: []
paths:
  /v1/company/by-name:
    get:
      tags:
        - Company
      summary: Fuzzy company lookup by name
      description: >-
        Look up an Australian company by free-text name. Runs an exact / prefix
        / words-in-order / trigram match ladder over each company's searched
        names (display, legal, trading, trustee names and LinkedIn specialties),
        returning a best_match candidate (when one dominates) plus the other
        ranked candidates, every one as a short company card (`GET
        /v1/company?id=` for a full card). Every candidate says which name it
        matched on (`matched_on`).
      parameters:
        - schema:
            minLength: 1
            maxLength: 1000
            type: string
          in: query
          name: name
          required: true
          description: >-
            Free-text company name. Case- and punctuation-insensitive; common
            suffixes like 'Pty Ltd', 'Limited', and 'The Trustee For' are
            stripped before matching.
        - schema:
            anyOf:
              - type: string
                enum:
                  - NSW
              - type: string
                enum:
                  - VIC
              - type: string
                enum:
                  - QLD
              - type: string
                enum:
                  - SA
              - type: string
                enum:
                  - WA
              - type: string
                enum:
                  - TAS
              - type: string
                enum:
                  - NT
              - type: string
                enum:
                  - ACT
          in: query
          name: state
          required: false
          description: >-
            Optional AU state/territory filter: keeps companies with ANY office
            in that state (the same rule as search's `state`), not only those
            headquartered there. Useful when several companies share a name
            across jurisdictions.
        - schema:
            minimum: 1
            maximum: 25
            default: 5
            type: integer
          in: query
          name: limit
          required: false
          description: Maximum number of candidates to return (default 5, max 25).
        - schema:
            maxLength: 64
            type: string
          in: query
          name: tz
          required: false
          description: >-
            IANA timezone (e.g. Australia/Sydney, the default) used to render
            `signals.news.last_published_at` as a calendar day and to interpret
            `news_published_after` as local midnight. Unknown zones are rejected
            with 400.
      responses:
        '200':
          description: >-
            Fuzzy-name lookup result. `best_match` is set when one candidate
            clearly dominates (top score ≥ 0.85 AND a margin to the runner-up: ≥
            0.15 on the exact/words_in_order/trigram rungs, ≥ 0.05 on the graded
            prefix rung — a word-boundary completion like 'aldi' → 'aldi stores'
            scores in [0.95, 0.99) and a mid-word one like 'aldi' → 'aldinga …'
            in [0.85, 0.89), so a boundary hit over a mid-word runner-up
            resolves and two same-class hits do not) OR when a unique exact
            match was found; otherwise null and the LLM should ask the user to
            disambiguate from `candidates`.
          content:
            application/json:
              schema:
                description: >-
                  Fuzzy-name lookup result. `best_match` is set when one
                  candidate clearly dominates (top score ≥ 0.85 AND a margin to
                  the runner-up: ≥ 0.15 on the exact/words_in_order/trigram
                  rungs, ≥ 0.05 on the graded prefix rung — a word-boundary
                  completion like 'aldi' → 'aldi stores' scores in [0.95, 0.99)
                  and a mid-word one like 'aldi' → 'aldinga …' in [0.85, 0.89),
                  so a boundary hit over a mid-word runner-up resolves and two
                  same-class hits do not) OR when a unique exact match was
                  found; otherwise null and the LLM should ask the user to
                  disambiguate from `candidates`.
                type: object
                required:
                  - best_match
                  - candidates
                properties:
                  best_match:
                    description: >-
                      The one candidate that clearly dominates (score,
                      match_kind, matched_on, and its short company card), or
                      null when the caller should ask the user to choose from
                      `candidates`.
                    anyOf:
                      - description: >-
                          The candidate that clearly dominates, with the
                          matching method, the name it matched on, the
                          confidence, and its short company card (id, name,
                          website, one-line summary, industry, hq_location,
                          states, employee_range); call `lookup_company` with
                          its `id` for the full card.
                        type: object
                        required:
                          - score
                          - match_kind
                          - matched_on
                          - company
                        properties:
                          score:
                            description: >-
                              Confidence in [0, 1]. 1.0 = exact normalised
                              match; words_in_order scores sit in [0.6, 0.8);
                              trigram scores reflect pg_trgm similarity.
                            type: number
                          match_kind:
                            description: >-
                              How the candidate was matched, strongest first.
                              `exact` = a normalised name equals the query.
                              `prefix` = a normalised name starts with the
                              query. `words_in_order` = every query word appears
                              in a name as a whole word, in order, with other
                              words between or around ("Summit Group" → "Summit
                              Homes Group"); never auto-resolved as best_match
                              on its own — confirm it. `trigram` = pg_trgm
                              similarity over the normalised name set.
                            anyOf:
                              - type: string
                                enum:
                                  - exact
                              - type: string
                                enum:
                                  - prefix
                              - type: string
                                enum:
                                  - words_in_order
                              - type: string
                                enum:
                                  - trigram
                          matched_on:
                            description: >-
                              Which name the candidate matched on — so a high
                              score on a name other than the display name can be
                              explained.
                            type: object
                            required:
                              - name
                              - kind
                            properties:
                              name:
                                description: >-
                                  The name that matched, as the record holds it
                                  (e.g. "Summit Homes Group").
                                type: string
                              kind:
                                description: >-
                                  Which of the record's names matched: `display`
                                  = the company's own (LinkedIn) name,
                                  `legal_name` = the ABR legal name
                                  (`legal_entity.legal_name`), `trading_name` =
                                  a registered trading or business name
                                  (`legal_entity.trading_names`, which shows at
                                  most 10 — the matched one may be past the
                                  cut), `trustee_name` = the trust's corporate
                                  trustee (`legal_entity.trustee`), `other_name`
                                  = another name the record is found by that the
                                  card does not show.
                                anyOf:
                                  - type: string
                                    enum:
                                      - display
                                  - type: string
                                    enum:
                                      - legal_name
                                  - type: string
                                    enum:
                                      - trading_name
                                  - type: string
                                    enum:
                                      - trustee_name
                                  - type: string
                                    enum:
                                      - other_name
                          company:
                            additionalProperties: false
                            type: object
                            required:
                              - id
                              - name
                              - website
                              - summary
                              - industry
                              - hq_location
                              - hq_state
                              - states
                              - employee_range
                              - matched_office
                            properties:
                              id:
                                description: >-
                                  DataDingo company ID — pass it to
                                  `lookup_company` for the full card.
                                type: string
                              name:
                                description: Display name, as on the full card.
                                type: string
                              website:
                                description: The company's website, as on the full card.
                                anyOf:
                                  - type: string
                                  - type: 'null'
                              summary:
                                description: >-
                                  The card's `description` on one line: cut at
                                  the last sentence end within 200 characters,
                                  or a hard cut ending in "…". Null when there
                                  is no description.
                                anyOf:
                                  - type: string
                                  - type: 'null'
                              industry:
                                description: >-
                                  The LinkedIn industry label
                                  (`industry.linkedin.label` on the full card).
                                anyOf:
                                  - type: string
                                  - type: 'null'
                              hq_location:
                                description: >-
                                  Head-office suburb or city, as on the full
                                  card.
                                anyOf:
                                  - type: string
                                  - type: 'null'
                              hq_state:
                                description: >-
                                  State or territory of the head office; null
                                  when the head office is outside Australia or
                                  its state is unknown. The state the `hq_state`
                                  filter matches.
                                anyOf:
                                  - anyOf:
                                      - type: string
                                        enum:
                                          - NSW
                                      - type: string
                                        enum:
                                          - VIC
                                      - type: string
                                        enum:
                                          - QLD
                                      - type: string
                                        enum:
                                          - SA
                                      - type: string
                                        enum:
                                          - WA
                                      - type: string
                                        enum:
                                          - TAS
                                      - type: string
                                        enum:
                                          - NT
                                      - type: string
                                        enum:
                                          - ACT
                                  - type: 'null'
                              states:
                                description: >-
                                  Every Australian state or territory the
                                  company has an office in, head office first —
                                  what the `state` filter matches (`states` on
                                  the full card). One entry for most companies;
                                  `[]` when none is known.
                                type: array
                                items:
                                  type: string
                              employee_range:
                                description: >-
                                  LinkedIn size band, as on the full card; null
                                  = not measured, not small.
                                anyOf:
                                  - type: string
                                  - type: 'null'
                              matched_office:
                                description: >-
                                  With a `locality` filter: the office that
                                  matched it when that is NOT the head office
                                  (any stored office, including ones the full
                                  card's `locations` does not list). Null when
                                  the head office matches (`hq_location` already
                                  names it), with no `locality` filter, and on
                                  `lookup_by_name`.
                                anyOf:
                                  - additionalProperties: false
                                    type: object
                                    required:
                                      - locality
                                      - state
                                      - postcode
                                    properties:
                                      locality:
                                        description: Suburb or town of the matched office.
                                        anyOf:
                                          - type: string
                                          - type: 'null'
                                      state:
                                        description: >-
                                          State or territory of the matched
                                          office.
                                        anyOf:
                                          - type: string
                                          - type: 'null'
                                      postcode:
                                        description: Postcode of the matched office.
                                        anyOf:
                                          - type: string
                                          - type: 'null'
                                  - type: 'null'
                      - type: 'null'
                  candidates:
                    description: >-
                      The other candidates, sorted best-first, each with a short
                      company card; never includes the best_match. best_match
                      plus candidates hold at most `limit` companies. Useful for
                      chat-window "or did you mean…" UX.
                    type: array
                    items:
                      description: >-
                        One candidate company for a name query, with the
                        matching method, the name it matched on and the
                        confidence surfaced so the LLM can hedge. `company` is
                        the short card (id, name, website, one-line summary,
                        industry, hq_location, states, employee_range); call
                        `lookup_company` with its `id` for the full card.
                      type: object
                      required:
                        - score
                        - match_kind
                        - matched_on
                        - company
                      properties:
                        score:
                          description: >-
                            Confidence in [0, 1]. 1.0 = exact normalised match;
                            words_in_order scores sit in [0.6, 0.8); trigram
                            scores reflect pg_trgm similarity.
                          type: number
                        match_kind:
                          description: >-
                            How the candidate was matched, strongest first.
                            `exact` = a normalised name equals the query.
                            `prefix` = a normalised name starts with the query.
                            `words_in_order` = every query word appears in a
                            name as a whole word, in order, with other words
                            between or around ("Summit Group" → "Summit Homes
                            Group"); never auto-resolved as best_match on its
                            own — confirm it. `trigram` = pg_trgm similarity
                            over the normalised name set.
                          anyOf:
                            - type: string
                              enum:
                                - exact
                            - type: string
                              enum:
                                - prefix
                            - type: string
                              enum:
                                - words_in_order
                            - type: string
                              enum:
                                - trigram
                        matched_on:
                          description: >-
                            Which name the candidate matched on — so a high
                            score on a name other than the display name can be
                            explained.
                          type: object
                          required:
                            - name
                            - kind
                          properties:
                            name:
                              description: >-
                                The name that matched, as the record holds it
                                (e.g. "Summit Homes Group").
                              type: string
                            kind:
                              description: >-
                                Which of the record's names matched: `display` =
                                the company's own (LinkedIn) name, `legal_name`
                                = the ABR legal name
                                (`legal_entity.legal_name`), `trading_name` = a
                                registered trading or business name
                                (`legal_entity.trading_names`, which shows at
                                most 10 — the matched one may be past the cut),
                                `trustee_name` = the trust's corporate trustee
                                (`legal_entity.trustee`), `other_name` = another
                                name the record is found by that the card does
                                not show.
                              anyOf:
                                - type: string
                                  enum:
                                    - display
                                - type: string
                                  enum:
                                    - legal_name
                                - type: string
                                  enum:
                                    - trading_name
                                - type: string
                                  enum:
                                    - trustee_name
                                - type: string
                                  enum:
                                    - other_name
                        company:
                          additionalProperties: false
                          type: object
                          required:
                            - id
                            - name
                            - website
                            - summary
                            - industry
                            - hq_location
                            - hq_state
                            - states
                            - employee_range
                            - matched_office
                          properties:
                            id:
                              description: >-
                                DataDingo company ID — pass it to
                                `lookup_company` for the full card.
                              type: string
                            name:
                              description: Display name, as on the full card.
                              type: string
                            website:
                              description: The company's website, as on the full card.
                              anyOf:
                                - type: string
                                - type: 'null'
                            summary:
                              description: >-
                                The card's `description` on one line: cut at the
                                last sentence end within 200 characters, or a
                                hard cut ending in "…". Null when there is no
                                description.
                              anyOf:
                                - type: string
                                - type: 'null'
                            industry:
                              description: >-
                                The LinkedIn industry label
                                (`industry.linkedin.label` on the full card).
                              anyOf:
                                - type: string
                                - type: 'null'
                            hq_location:
                              description: Head-office suburb or city, as on the full card.
                              anyOf:
                                - type: string
                                - type: 'null'
                            hq_state:
                              description: >-
                                State or territory of the head office; null when
                                the head office is outside Australia or its
                                state is unknown. The state the `hq_state`
                                filter matches.
                              anyOf:
                                - anyOf:
                                    - type: string
                                      enum:
                                        - NSW
                                    - type: string
                                      enum:
                                        - VIC
                                    - type: string
                                      enum:
                                        - QLD
                                    - type: string
                                      enum:
                                        - SA
                                    - type: string
                                      enum:
                                        - WA
                                    - type: string
                                      enum:
                                        - TAS
                                    - type: string
                                      enum:
                                        - NT
                                    - type: string
                                      enum:
                                        - ACT
                                - type: 'null'
                            states:
                              description: >-
                                Every Australian state or territory the company
                                has an office in, head office first — what the
                                `state` filter matches (`states` on the full
                                card). One entry for most companies; `[]` when
                                none is known.
                              type: array
                              items:
                                type: string
                            employee_range:
                              description: >-
                                LinkedIn size band, as on the full card; null =
                                not measured, not small.
                              anyOf:
                                - type: string
                                - type: 'null'
                            matched_office:
                              description: >-
                                With a `locality` filter: the office that
                                matched it when that is NOT the head office (any
                                stored office, including ones the full card's
                                `locations` does not list). Null when the head
                                office matches (`hq_location` already names it),
                                with no `locality` filter, and on
                                `lookup_by_name`.
                              anyOf:
                                - additionalProperties: false
                                  type: object
                                  required:
                                    - locality
                                    - state
                                    - postcode
                                  properties:
                                    locality:
                                      description: Suburb or town of the matched office.
                                      anyOf:
                                        - type: string
                                        - type: 'null'
                                    state:
                                      description: >-
                                        State or territory of the matched
                                        office.
                                      anyOf:
                                        - type: string
                                        - type: 'null'
                                    postcode:
                                      description: Postcode of the matched office.
                                      anyOf:
                                        - type: string
                                        - type: 'null'
                                - type: 'null'
        '400':
          description: Standard error response
          content:
            application/json:
              schema:
                description: Standard error response
                type: object
                required:
                  - error
                  - message
                properties:
                  error:
                    description: HTTP status code
                    type: integer
                  message:
                    description: Human-readable error message
                    type: string
        '401':
          description: Standard error response
          content:
            application/json:
              schema:
                description: Standard error response
                type: object
                required:
                  - error
                  - message
                properties:
                  error:
                    description: HTTP status code
                    type: integer
                  message:
                    description: Human-readable error message
                    type: string
        '403':
          description: 'The user''s plan has ended: subscribe to keep using DataDingo'
          content:
            application/json:
              schema:
                description: 'The user''s plan has ended: subscribe to keep using DataDingo'
                type: object
                required:
                  - error
                  - code
                  - message
                  - subscribe_url
                properties:
                  error:
                    description: HTTP status code (403)
                    type: integer
                  code:
                    type: string
                    enum:
                      - plan_required
                  message:
                    description: Human-readable error message, with the subscribe link
                    type: string
                  subscribe_url:
                    description: Where to subscribe to get access back
                    type: string
        '429':
          description: Rate limit exceeded, or today's free search results used up
          content:
            application/json:
              schema:
                description: Rate limit exceeded, or today's free search results used up
                type: object
                required:
                  - error
                  - message
                  - limit
                  - remaining
                  - resets_at
                properties:
                  error:
                    description: HTTP status code (429)
                    type: integer
                  message:
                    description: Human-readable error message
                    type: string
                  limit:
                    description: >-
                      The limit that was hit: requests allowed per minute, or
                      (on `POST /v1/company/search`) search results one user may
                      receive per UTC day
                    type: integer
                  remaining:
                    description: What is left of that limit (0)
                    type: integer
                  resets_at:
                    format: date-time
                    description: >-
                      ISO 8601 instant the limit resets (the next minute, or the
                      next UTC midnight for search results)
                    type: string
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.