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

# Search SAM.gov entity registrations

> Search registrations from the public SAM.gov extract. By default, results are active, unexpired registrations in the latest extract. Set includeHistorical to include the latest known version of expired or missing registrations. Each row has a unique combination of UEI and EFT indicator. Use the UEI to group alternate registrations for the same entity. Filters combine with AND. Lists match any listed value. Omit a filter to leave it unrestricted. Unknown fields, nulls, and invalid values return 400. Use query for ranked name and keyword search across legal names, DBA names, public former names, SAM business type labels, and keywords from linked public SBA profiles. Use websiteDomain for an exact domain match from either source. A certification match reports what SAM published for the registration on lastSeenInExtractOn. NAICS matching covers the codes listed on the registration. Small business eligibility under a NAICS code is a separate determination.



## OpenAPI

````yaml /openapi/tools-v1.yaml post /api/tools/v1/sam_registrations/search
openapi: 3.1.0
info:
  title: Govly Tools API
  version: 1.0.0-alpha
  description: >
    ALPHA / UNSTABLE: This API is still in active development. Endpoint
    behavior, request fields, response fields, error codes, and operation names
    may change before the Tools API is declared stable.

    REST-callable tool surface for agent and automation workflows. Agents are
    the primary consumer, but integrations can be built on this API. Responses
    are JSON for typed clients; MCP tools may render action results into
    text-oriented formats separately.

    Validating requests: validate against this schema in your client before
    sending. Most operations ignore unrecognized request fields, so a misspelled
    filter can return 200 with a broader result set than you intended.
    Operations that reject unknown fields document that behavior. Validate names
    and types in your client, including for schemas with `additionalProperties:
    false`.

    Rate limits: each resource (for example awards, opportunities, or
    workspaces) allows 70 requests per minute per user. Exceeding it returns 429
    with the standard error envelope, `code: rate_limited`, and a `Retry-After`
    header. Keys sent in the `X-API-KEY` header are also subject to the
    Enterprise API limit of 300 requests per minute per key; see the Rate Limits
    page.
servers:
  - url: https://app.govly.com
security:
  - bearerApiKey: []
  - headerApiKey: []
tags:
  - name: Workflows
    description: Workflow reference file management.
  - name: Opportunities
    description: Search, fetch, and inspect Govly opportunity records.
  - name: Awards
    description: Search and inspect awarded government contracts.
  - name: SAM Registrations
    description: Search entity registrations in the latest SAM.gov public extract.
  - name: Contacts
    description: Search and inspect government points of contact.
  - name: Signals
    description: Search clustered procurement and market intelligence signals.
  - name: Places
    description: Resolve place names to canonical Govly Place ids.
  - name: Product Catalogs
    description: List government contract price lists and search their line items.
  - name: Workspaces
    description: Create, update, and inspect opportunity workspaces.
  - name: Organization Users
    description: Discover the members of your organization and their account status.
  - name: Workspace Members
    description: Add users and teams to workspaces.
  - name: File Attachments
    description: >-
      Attach new or existing files through a signed Govly transfer or an
      authorized reference.
  - name: Workspace Attachments
    description: List and upload workspace attachments.
  - name: Workspace Comments
    description: Post comments to workspaces.
  - name: Organization Labels
    description: List, create, rename, recolor, and delete the organization's labels.
  - name: Record Labels
    description: >-
      Apply and remove the organization's labels on opportunities, awards,
      contacts, and workspaces.
  - name: Follows
    description: Follow opportunities and related workspace activity.
  - name: Shares
    description: Share opportunities, awards, and contacts with colleagues by email.
  - name: Saved Searches
    description: List saved opportunity searches and cached matches.
  - name: Documents
    description: >-
      Read document representations and request temporary original-file
      downloads.
  - name: Libraries
    description: Discover accessible Libraries and create additional Libraries.
  - name: Library Documents
    description: List and manage documents in a selected Library.
  - name: Quote Submissions
    description: >-
      Inspect quote submission requirements, submit quotes, and poll submission
      status.
  - name: Inbox
    description: Read and triage the authenticated user's matched inbox items.
paths:
  /api/tools/v1/sam_registrations/search:
    post:
      tags:
        - SAM Registrations
      summary: Search SAM.gov entity registrations
      description: >-
        Search registrations from the public SAM.gov extract. By default,
        results are active, unexpired registrations in the latest extract. Set
        includeHistorical to include the latest known version of expired or
        missing registrations. Each row has a unique combination of UEI and EFT
        indicator. Use the UEI to group alternate registrations for the same
        entity. Filters combine with AND. Lists match any listed value. Omit a
        filter to leave it unrestricted. Unknown fields, nulls, and invalid
        values return 400. Use query for ranked name and keyword search across
        legal names, DBA names, public former names, SAM business type labels,
        and keywords from linked public SBA profiles. Use websiteDomain for an
        exact domain match from either source. A certification match reports
        what SAM published for the registration on lastSeenInExtractOn. NAICS
        matching covers the codes listed on the registration. Small business
        eligibility under a NAICS code is a separate determination.
      operationId: search_sam_registrations
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              additionalProperties: false
              properties:
                query:
                  type: string
                  minLength: 1
                  maxLength: 200
                  description: >-
                    A company name or keyword phrase. Supports spelling
                    variations and known public aliases.
                uei:
                  type: string
                  pattern: ^[A-Z0-9]{12}$
                  description: Match an exact SAM Unique Entity Identifier.
                cageCodes:
                  type: array
                  minItems: 1
                  maxItems: 100
                  items:
                    type: string
                    pattern: ^[A-Z0-9]{5}$
                  description: Match the CAGE code on the registration.
                states:
                  type: array
                  minItems: 1
                  maxItems: 100
                  items:
                    type: string
                    pattern: ^[A-Z]{2}$
                  description: >-
                    Two-letter U.S. state codes for the physical address, such
                    as CA for California.
                naics:
                  type: array
                  minItems: 1
                  maxItems: 100
                  items:
                    type: string
                    pattern: ^[0-9]{6}$
                  description: >-
                    Match codes anywhere on the registration, including its
                    primary NAICS.
                psc:
                  type: array
                  minItems: 1
                  maxItems: 100
                  items:
                    type: string
                    pattern: ^[A-Z0-9]{4}$
                  description: Match listed Product Service Codes.
                websiteDomain:
                  type: string
                  description: >-
                    Match an exact website host from SAM or SBA, such as
                    example.com. Case, a leading www. and a trailing dot are
                    ignored.
                includeHistorical:
                  type: boolean
                  default: false
                  description: >-
                    Include expired registrations and registrations missing from
                    the latest extract. Current matches are favored.
                sbaCertification:
                  type: string
                  enum:
                    - any
                    - A0
                    - A4
                    - A6
                    - A9
                    - JT
                    - XX
                  description: >-
                    Use any for at least one reported SBA certification. For a
                    specific program, use A0 for EDWOSB, A4 for SBA-certified
                    Small Disadvantaged Business, A6 for 8(a), A9 for WOSB, JT
                    for an 8(a) joint venture, or XX for HUBZone. Certifications
                    with a known past expiration are excluded. Only entries with
                    a valid expiry or an omitted expiry qualify.
                perPage:
                  type: integer
                  minimum: 1
                  maximum: 100
                  default: 25
                cursor:
                  type: string
                  minLength: 1
                  description: >-
                    Copy meta.nextCursor with the same filters to fetch the next
                    page. Restart without a cursor when the API returns a cursor
                    error.
            example:
              states:
                - CA
              naics:
                - '541330'
              sbaCertification: any
      responses:
        '200':
          description: >-
            Matching SAM registrations ordered by relevance with query,
            registration ID with websiteDomain alone, or otherwise by UEI and
            EFT indicator. Historical searches favor current matches.
          content:
            application/json:
              schema:
                type: object
                required:
                  - data
                  - meta
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/SamRegistrationSearchResult'
                  meta:
                    type: object
                    required:
                      - count
                      - nextCursor
                      - sourceExtractOn
                    properties:
                      count:
                        type: integer
                        description: Number of registrations on this page.
                      nextCursor:
                        type:
                          - string
                          - 'null'
                      sourceExtractOn:
                        type:
                          - string
                          - 'null'
                        format: date
                        description: >-
                          Date of the latest imported SAM extract, or null
                          before the first import.
        '400':
          $ref: '#/components/responses/Error'
          description: >-
            Invalid search input or cursor. The source pointer identifies the
            applicable field.
        '401':
          $ref: '#/components/responses/Error'
        '403':
          $ref: '#/components/responses/Error'
        '429':
          $ref: '#/components/responses/RateLimited'
        '503':
          $ref: '#/components/responses/Error'
          description: The SAM registration search backend is temporarily unavailable.
components:
  schemas:
    SamRegistrationSearchResult:
      type: object
      required:
        - uei
        - eftIndicator
        - cageCode
        - legalBusinessName
        - dbaName
        - websiteUrl
        - samWebsiteDomain
        - sbaWebsiteDomain
        - registrationExpiresOn
        - registrationPurpose
        - businessTypes
        - city
        - state
        - countryCode
        - primaryNAICS
        - matchedNAICS
        - sbaCertifications
        - sbaProfileState
        - sbaProfileObservedAt
        - sbaProfileCheckedAt
        - registrationStatus
        - lastSeenInExtractOn
        - presentInLatestExtract
      properties:
        uei:
          type: string
        eftIndicator:
          type: string
          description: >-
            Four-character EFT indicator, or an empty string for the main
            registration.
        cageCode:
          type:
            - string
            - 'null'
        legalBusinessName:
          type:
            - string
            - 'null'
        dbaName:
          type:
            - string
            - 'null'
        websiteUrl:
          type:
            - string
            - 'null'
          description: Website text supplied by the registrant.
        samWebsiteDomain:
          type:
            - string
            - 'null'
          description: Normalized website domain from the SAM registration.
        sbaWebsiteDomain:
          type:
            - string
            - 'null'
          description: >-
            Normalized website domain from the public SBA profile for the same
            UEI and CAGE code.
        sbaProfileState:
          type: string
          enum:
            - not_checked
            - missing
            - public
            - restricted
            - unknown
          description: >-
            Availability of the linked SBA profile at the last recorded
            observation or miss.
        sbaProfileObservedAt:
          type:
            - string
            - 'null'
          format: date-time
          description: Time of the last successful SBA profile observation.
        sbaProfileCheckedAt:
          type:
            - string
            - 'null'
          format: date-time
          description: >-
            Time of the last successful SBA profile observation or confirmed
            miss.
        registrationExpiresOn:
          type:
            - string
            - 'null'
          format: date
          description: Expiration date of the SAM registration.
        registrationStatus:
          type: string
          enum:
            - active
            - expired
          description: The last registration status reported by SAM.
        lastSeenInExtractOn:
          type: string
          format: date
          description: >-
            Date of the latest extract containing a valid row for this
            registration.
        presentInLatestExtract:
          type: boolean
          description: >-
            Whether the latest imported extract contains a valid row for this
            registration.
        registrationPurpose:
          oneOf:
            - $ref: '#/components/schemas/SamRegistrationCodeLabel'
            - type: 'null'
        businessTypes:
          type: array
          description: Business classifications reported by SAM.
          items:
            $ref: '#/components/schemas/SamRegistrationCodeLabel'
        city:
          type:
            - string
            - 'null'
        state:
          type:
            - string
            - 'null'
        countryCode:
          type:
            - string
            - 'null'
        primaryNAICS:
          type:
            - string
            - 'null'
        matchedNAICS:
          type: array
          description: >-
            Requested NAICS codes listed on this registration. Empty when the
            request omits the NAICS filter.
          items:
            type: string
        sbaCertifications:
          type: array
          description: >-
            Reported certifications matching the request, including
            certifications with an unknown expiration.
          items:
            type: object
            required:
              - code
              - label
              - expiresOn
            properties:
              code:
                type: string
              label:
                type:
                  - string
                  - 'null'
              expiresOn:
                type:
                  - string
                  - 'null'
                format: date
    SamRegistrationCodeLabel:
      type: object
      required:
        - code
        - label
      properties:
        code:
          type: string
        label:
          type:
            - string
            - 'null'
          description: A readable label when the SAM code is recognized.
    ErrorEnvelope:
      type: object
      required:
        - errors
      properties:
        errors:
          type: array
          items:
            type: object
            required:
              - status
              - code
              - title
              - detail
            properties:
              status:
                type: string
              code:
                type: string
              title:
                type: string
              detail:
                type: string
              source:
                type: object
                properties:
                  pointer:
                    type: string
    RateLimitError:
      type: object
      required:
        - error
      properties:
        error:
          type: string
  responses:
    Error:
      description: Error response
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorEnvelope'
    RateLimited:
      description: >
        Too many requests. Two limiters can produce this status and they use
        different bodies. The per-user limit of 70 requests per minute for each
        resource returns the standard error envelope with `code: rate_limited`
        and a `Retry-After` header. Keys sent in the `X-API-KEY` header are also
        subject to the Enterprise API limit of 300 requests per minute per key,
        which returns the plain `error` form with `Retry-After` and the
        `X-RateLimit-*` headers. Clients should accept either body.
      headers:
        Retry-After:
          description: Seconds to wait before retrying.
          schema:
            type: string
      content:
        application/json:
          schema:
            oneOf:
              - $ref: '#/components/schemas/ErrorEnvelope'
              - $ref: '#/components/schemas/RateLimitError'
  securitySchemes:
    bearerApiKey:
      type: http
      scheme: bearer
      bearerFormat: API key
    headerApiKey:
      type: apiKey
      in: header
      name: X-API-KEY

````

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