UEI Lookup API

Q: What happens for an entity whose SAM registration has expired?

You still get a 200 response with registration.status ="E" and registration.active = false. The other fields populate normally. Expired registrations stay in the dataset.

Q: What happens for a UEI that's never been in SAM (e.g. a typo)?

404 with {"detail":"UEI XYZ not found in SAM registry"}.

Q: Does this endpoint return contract history?

No. Use /api/v1/companies/{uei} for entity + award profile in one call (Pro), /api/v1/contracts/search?uei=… for every FPDS prime contract transaction since Oct 2024 (Developer), or /api/v1/awards/search?uei=… for the SAM Award Notice slice (Developer).

Updated September 20, 2026

SAM.gov entity data, JSON, one HTTP call. Registration status, expiration, certifications, NAICS, CAGE codes.

A Unique Entity Identifier (UEI) is the 12-character string SAM.gov assigns to every entity that registers to do business with the US federal government. Resolving one against SAM.gov itself means either the website, whose public entity search does not return registration records without an account, or the official Entity Management API, which needs a registered key and allows 10 requests a day unless your account holds a role at a registered entity. This endpoint returns the same record flat, on a key that also searches the rest of the registry by name, NAICS, state, certification and registration status.

Who this page is for: developers integrating SAM lookup into a CRM, compliance tool, proposal pipeline, vendor-onboarding flow, or research dashboard. Anyone who needs to ask "is this UEI active and what's their expiration date" programmatically.

What this page is NOT: a marketing pitch. The endpoint is a thin, useful shape over public SAM data, refreshed regularly. If you need real-time SAM data, hit sam.gov directly. If you need OFAC sanctions, beneficial ownership, or international registries, this isn't that.

What one call returns

You pass a UEI. You get back two structured blocks. The registration block answers "is this entity active and when do they need to renew." The entity block answers "who is this firm, where, and what do they say they do."

Real response for XX2WFHJEFB45 (KAMPI Components Co Inc), trimmed to fit:

{
  "uei": "XX2WFHJEFB45",
  "registration": {
    "status": "A",
    "active": true,
    "registration_date": "2001-08-16",
    "activation_date": "2026-01-21",
    "expiration_date": "2027-01-19",
    "expiring_soon": false,
    "source_extract_date": "2026-04-05"
  },
  "entity": {
    "legal_business_name": "KAMPI COMPONENTS CO INC",
    "dba_name": null,
    "entity_structure_code": "2L",
    "entity_url": "www.kampi.com",
    "physical_address": {
      "street1": "...",
      "city": "FAIRLESS HILLS",
      "state": "PA",
      "zip": "19030",
      "country": "USA"
    },
    "primary_naics": "423990",
    "naics_codes": ["423990Y", "332710Y", "..."],
    "psc_codes": ["...", "..."],
    "business_types": ["2X", "XS"],
    "business_types_labels": ["For Profit Organization", "Subchapter S Corporation"],
    "cage_codes": ["7Z016"]
  }
}

Field-level explanations are below.

Use cases this enables

Concrete things people build on this endpoint.

Compliance check before a contract is signed.

Two questions: is the counterparty's SAM registration active right now, and are they on the federal exclusion list? This endpoint answers the first (registration.active + registration.expiration_date). Combine with /api/v1/exclusions/search?uei=… for the second. Two calls, full check.

CRM enrichment.

Your sales/BD system stores UEIs. On record open or daily sync, hit this endpoint to populate legal name, DBA, address, NAICS, certifications, and registration status. source_extract_date tells you when the data was last refreshed.

Renewal nag in your own UI.

If registration.expiring_soon is true, the entity's SAM registration expires within 60 days. Surface that in your dashboard or send the customer a renewal reminder. Polling once a day is sufficient.

Vendor-onboarding form auto-fill.

User pastes the UEI; you populate the rest of the form (legal name, address, NAICS) without making them type it. Reduces typo errors that downstream procurement systems reject.

Set-aside qualification preview.

Before scoping a small-business set-aside RFP, look up the candidate's business_types array. WOSB (8W), SDVOSB (QF), Self-Cert SDB (27), and others come back as raw codes plus decoded labels in business_types_labels. (See caveats for what's not in this field.)

UEI-to-CAGE bridge.

Some legacy DoD systems still key on CAGE. entity.cage_codes returns every CAGE registered to that UEI. Most entities have one; some (USPS, big banks) have up to 80.

How to call the API

Single GET, documented at the entity-by-UEI endpoint. Auth via Authorization: Bearer <api_key>. Your key arrives by email when you sign up.

curl -H "Authorization: Bearer $API_KEY" \
     https://govconapi.com/api/v1/entities/XX2WFHJEFB45

The UEI in the path is normalized: lowercase, mixed case, and surrounding whitespace are all accepted and converted to canonical uppercase.

You can also look up by CAGE code if that's what your legacy system stores:

curl -H "Authorization: Bearer $API_KEY" \
     https://govconapi.com/api/v1/entities/by-cage/1A2B3

Same response shape, plus a queried_cage field echoing the input.

Error shapes:

401: missing or invalid Authorization header
404: UEI/CAGE not found in current SAM snapshot
429: rate limit (60/min per IP burst, 1000/hr per API key)

Field reference

Every field in the response, what it carries, and where it comes from.

`registration` block

Field	Source	Notes
`status`	SAM	`"A"` Active, `"E"` Expired
`active`	derived	Boolean shortcut for `status =="A"`
`registration_date`	SAM	When the entity first registered. ISO 8601.
`activation_date`	SAM	When the most recent activation took effect.
`expiration_date`	SAM	When the current registration expires. SAM requires annual renewal.
`expiring_soon`	derived	True if `active` AND `expiration_date` ≤ today + 60 days. Flag for renewal-radar UI.
`source_extract_date`	SAM	The snapshot date for the underlying record. Tells you the data's freshness.

`entity` block

Field	Source	Notes
`legal_business_name`	SAM	Required. The canonical legal name.
`dba_name`	SAM	Doing-business-as, often null.
`entity_structure_code`	SAM	2J=Sole Prop, 2K=Partnership, 2L=Corp, 8H=Tax-Exempt Corp, 2A=US Gov, X6=International Org, ZZ=Other.
`entity_url`	SAM	Self-reported website. Often missing or stale.
`physical_address`	SAM	Object: `street1`, `street2`, `city`, `state` (US), `zip`, `country` (3-char). For non-US entities, `state` is null.
`primary_naics`	SAM	The primary NAICS code with no Y/N suffix.
`naics_codes[]`	SAM	Array of NAICS codes the entity claims competence in. Each suffixed Y/N/E by SAM (small-business eligibility flag per-NAICS). Average 4.8 codes per entity when populated. Every `naics` parameter accepts a code with or without the suffix, so a value from this array can be passed on as is.
`psc_codes[]`	SAM	Federal Product Service Codes the entity supplies. Free-text; not validated.
`business_types[]`	SAM	Raw 2-3 char socio-economic + structure codes (e.g. `8W`=WOSB, `QF`=SDVOSB, `27`=Self-Cert SDB). 76 valid codes; full list documented in our OpenAPI spec.
`business_types_labels[]`	derived	Same length and order as `business_types`, with each code replaced by its human-readable label.
`cage_codes[]`	SAM	5-char CAGE codes assigned by DoD/DLA. One per registration, sorted. Most entities have exactly one.

Combining with other endpoints

This endpoint stays focused on entity data. For workflows that need more, our other endpoints chain off the same UEI:

/api/v1/entities/by-cage/{cage} (Developer): same lookup keyed by 5-character CAGE code instead of UEI. For DoD-flavored data and legacy systems.
/api/v1/companies/{uei} (Pro): same registration + entity blocks, plus award-history aggregations (total awards, total $, top NAICS, top agencies, recent activity windows). Use this when you need both compliance signal and contract history in one call.
/api/v1/entities/search (every plan, all filters): find entities by name, or by NAICS / state / certification / active-status combinations when you don't have a UEI yet.
/api/v1/entities/expiring (Pro): list active registrations expiring within N days, sorted by urgency. The renewal-radar use case.
/api/v1/exclusions/search?uei={uei} (Developer): debarment / suspension check.
/api/v1/vendor-risk/{uei} (Pro): seven-signal risk screening including address-cluster and name-variant matches.

What this doesn't do (data caveats)

Honest list of what's not in the response, so you don't build assumptions on data we don't carry.

Near-real-time, not real-time.

We track SAM and refresh as upstream data publishes. In rare cases there can be up to ~30 days of latency between an entity updating their record on sam.gov and the change appearing here. The source_extract_date field tells you the freshness of any given record. For time-sensitive compliance decisions, verify directly with sam.gov as the system of record.

SBA-certified codes (A6, XX, JT, A4) are essentially absent from this dataset.

What's available are the self-certified socio-economic flags (27=Self-Cert SDB, 8W=Self-Cert WOSB, QF=SDVOSB), not SBA's own certified-program flags (A6=8(a), XX=HUBZone, JT=8(a) JV, A4=SBA-Certified SDB). Verified across our full ~887K-entity dataset. SBA's certified-program data lives in DSBS (Dynamic Small Business Search). On Pro we serve it inline as the sba_profile enrichment block on entity and company lookups, carrying verified SBA-registered certifications with their entry/exit dates, so you can confirm current SBA certification without integrating a second source.

~245K of 887K registered entities have no NAICS data at all.

SAM doesn't require it. primary_naics may be null and naics_codes[] may be empty. Don't write code that assumes either is always populated.

Entity points of contact are not in this response.

The public SAM entity extract carries POC names and addresses, and no phone numbers or email addresses at all. This response returns none of those fields. Named federal contracting officers are a separate dataset, with their own Contracting Officer Contacts endpoint; those are the government side of a contract, not the vendor's own registered contacts.

Foreign entities have `state` = null.

Non-US addresses don't fit the US state field. Read physical_address.country (3-char ISO code) when state is null. Example: a Kuwaiti firm returns {"city": "KUWAIT CITY", "state": null, "country": "KWT" }.

Pricing

The UEI lookup is on every plan, the free trial included, and so are the CAGE lookup, name search, exclusions search and the subaward endpoints. What a paid plan buys is throughput, 1,000 requests an hour, and what Pro adds is the computed layer: the entity and award merge, the renewal radar and vendor risk screening. Plan by plan, row by row, is the comparison table on Pricing.

FAQ

How is this different from sam.gov's own search?

Two differences: what it takes to get in, and what comes back. sam.gov's public entity search does not return registration records to a visitor without an account, and the official Entity Management API on api.sam.gov needs a registered key, capped at 10 requests every 24 hours unless your account holds a role at a registered entity. What it returns is one deeply nested record at a time, keyed by UEI, so you cannot ask it for every active WOSB in Ohio. This API returns a flat record, filtered search across 887,000 entities, and one key that also covers opportunities, contracts, subawards and exclusions, with a published rate limit. Same source data.

Why not just use SAM's official Entity Management API?

You can, and we use it ourselves for some workflows. The difference is the ceiling and the shape. A personal SAM.gov API key is capped at 10 requests every 24 hours unless your account holds a role at a registered entity, which raises it to 1,000 a day; 10,000 a day is a federal system account, which GSA approves case by case. Responses are deeply nested and paged in small batches, so assembling one firm's record takes several calls. Our endpoint returns that record flat, and the same key searches the whole registry by filter. For very high volume or near-real-time work, going to source is still a reasonable choice.

How fresh is the data?

We refresh as upstream data publishes. In rare cases there can be up to ~30 days of latency between an entity updating their record on sam.gov and the change appearing here. Each response carries source_extract_date so you know how recent the underlying snapshot is.

Can I batch-look-up many UEIs at once?

Currently single-UEI per request. We have a bulk pattern in /api/v1/vendor-risk/bulk (POST up to 100 UEIs) and could mirror it for entities if there's customer demand. Reach out if your daily volume needs it.

What happens for an entity whose SAM registration has expired?

You still get a 200 response with registration.status ="E" and registration.active = false. The other fields populate normally. Expired registrations stay in the dataset.

What happens for a UEI that's never been in SAM (e.g. a typo)?

404 with {"detail": "UEI XYZ not found in SAM registry"}.

Does this endpoint return contract history?

No. Use /api/v1/companies/{uei} for entity + award profile in one call (Pro), /api/v1/contracts/search?uei=… for every FPDS prime contract transaction since Oct 2024 (Developer), or /api/v1/awards/search?uei=… for the SAM Award Notice slice (Developer).