UEI Lookup API: SAM.gov Entity Data in One HTTP Call

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. Looking one up on sam.gov requires a logged-in session and returns HTML; the official entity-management API requires an API-key application process and returns XML wrapped in pagination. This endpoint takes the same UEI, returns flat JSON, and works on the first call.

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. The shape is stable; new fields may be added but existing fields are not renamed or removed.

Use cases this enables

Concrete things people build on this endpoint, drawn from actual customer requests.

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. Auth via Authorization: Bearer <api_key>. The API key comes from your dashboard after signup.

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.
`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 Bundle): 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 (Developer for q; Pro for 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 Bundle): 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 Bundle): 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 ~880K-entity dataset. SBA's certified-program data lives in DSBS (Dynamic Small Business Search), a separate system you'd need to integrate alongside this one. Plan accordingly if your use case depends on confirming SBA certification rather than self-attestation.

~243K of 873K 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.

POC phone and email are not in this response. The public SAM data carries POC names and addresses but not phone numbers or email addresses for entity points of contact.

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

This endpoint is on the Developer tier:

Free: 100 requests / day to public SEO endpoints. Not this one.
Developer ($19/mo): 1,000 requests/hour across the whole API surface. Includes /api/v1/entities/{uei}, /api/v1/entities/by-cage/{cage}, /api/v1/entities/search?q=… (name search), /api/v1/exclusions/search, /api/v1/awards/search, opportunities endpoints.
Pro Bundle ($39/mo): everything Developer has, plus /api/v1/companies/{uei} (entity + award merge), /api/v1/entities/search with NAICS/state/cert filters, /api/v1/entities/expiring (renewal radar), /api/v1/vendor-risk/* (seven-signal screening).

No annual contracts, no setup fees, monthly billing via Stripe. Cancel anytime.

FAQ

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

sam.gov requires a logged-in account, returns HTML pages designed for humans, and has documented usage limits that get enforced unpredictably. This API returns machine-readable JSON, no login, with a published rate limit you can plan against. Same source data.

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

You can; we use it ourselves for some workflows. SAM's API requires an API-key application that takes 1-2 weeks to approve, returns XML, paginates aggressively, and has nominal hourly caps (10/day per the registration form, anecdotally higher in practice). For most JSON-first integrations, our endpoint is faster to integrate against; for very high volume or near-real-time use cases, going to source is 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 award history?

No. Use /api/v1/companies/{uei} for entity + awards in one call (Pro Bundle), or /api/v1/awards/search?uei=… for awards alone (Developer).

UEI Lookup API