canonical: https://jentic.com/apis/ipums.org/ipums # IPUMS API IPUMS provides programmatic access to the world's largest collection of harmonized census and survey microdata, covering U.S. and international censuses, the American Community Survey, the Current Population Survey, and global health and time-use studies. This API exposes a token-based authentication endpoint and resource listing operations that index the available IPUMS data products and let developers retrieve metadata about each resource by ID. Authentication uses an X-API-Key header, with bearer access tokens issued from `/auth/token` for downstream calls. ## For AI agents Discover and retrieve metadata about IPUMS census and survey data resources for research workflows. Authenticate with an API key, list available resources, and fetch details about a specific resource by ID. ## Scope Does not handle live data extracts, statistical analysis, or visualization - use for IPUMS resource discovery and metadata retrieval only. ## Capabilities - Authenticate with an IPUMS account and obtain a bearer access token - List available IPUMS data resources for a researcher's account - Retrieve metadata for a specific IPUMS resource by its identifier - Programmatically index harmonized census and survey microdata products - Drive automated data-extraction pipelines from a research notebook or agent ## Use cases ### Programmatic IPUMS Data Discovery Researchers building reproducible pipelines can query the IPUMS API to enumerate the harmonized census, ACS, CPS, and international survey resources their account has access to, instead of copying sample names from the web extract builder. The /resources endpoint returns the index, and `/resources/{id}` returns metadata for any specific dataset. Example prompt: Call GET /resources with a valid X-API-Key and write the returned resource list to a manifest file used by the extract pipeline. ### Authenticated Token Bootstrap Long-running services that consume IPUMS data exchange an X-API-Key for a short-lived bearer token via POST `/auth/token`, reducing exposure of the underlying key during downstream extract or harmonization calls. The token can then be passed to subsequent operations without re-sending the key on every request. Example prompt: POST `/auth/token` with the X-API-Key header set and store the returned access_token for use in subsequent /resources calls within its expiry. ### Resource Metadata Retrieval for Codebooks Documentation pipelines and codebook generators can fetch metadata for a specific IPUMS resource by ID via GET `/resources/{id}` to render variable lists, sample coverage, and descriptions in a research handbook or dashboard, avoiding manual transcription from the IPUMS website. Example prompt: Call GET `/resources/{id}` for each resource ID in the project manifest and write the returned metadata to a structured codebook file. ### Agent IPUMS Lookup via Jentic An AI research assistant can answer questions about which IPUMS samples or surveys are available without scraping the IPUMS website by calling these three endpoints through Jentic. Jentic resolves the agent's intent to /resources or `/resources/{id}`, injects the API key from the vault, and returns parsed JSON ready for summarization. Example prompt: Use Jentic to search for 'list IPUMS data resources', load the GET /resources operation, and execute it to retrieve the catalogue for the researcher. ## Key endpoints | Method | Path | Description | | --- | --- | --- | | POST | `/auth/token` | Exchange an API key for a bearer access token | | GET | `/resources` | List available IPUMS data resources | | GET | `/resources/{id}` | Retrieve metadata for a specific resource | ## Key resources - **Auth Token** — Exchange an API key for a bearer access token used on subsequent requests - **Resources** — List and retrieve metadata for IPUMS data resources accessible to the caller ## Why Jentic - **Setup:** Wiring IPUMS by hand means registering for a key, sending it in the X-API-Key header to api.ipums.org, and running the `/auth/token` exchange before you can list or read resources. Through Jentic you install once, import IPUMS from the API Directory, store the key once, and your agent calls it. - **Permission scoping:** IPUMS puts the resource id in the URL path (`/resources/{id}`), so a rule can pin your agent to one resource: it can list and read that metadata and nothing else. You choose the operations it may call, so it is limited to discovery and retrieval unless you add more. - **Credential handling:** Your IPUMS X-API-Key is stored once, encrypted, by your own Jentic One instance and injected into the request header at execution time. It never enters the agent's prompt, logs, or context, nor does the token returned by `/auth/token.` - **Discovery method:** Agents search Jentic by intent such as 'list available IPUMS surveys', and Jentic returns the matching /resources operation with its input schema, so the agent calls the right endpoint without reading the IPUMS developer site. ## Related APIs - **U.S. Census Bureau API** — Direct U.S. Census Bureau API for ACS, decennial, and economic survey data. - **Abstract Geolocation API** — Geocode addresses and IPs to enrich survey records with spatial context. - **Google API** — Sheets, Drive, and Cloud Storage endpoints for staging IPUMS extracts. ## FAQ ### What authentication does the IPUMS API use? IPUMS uses an X-API-Key header for direct authentication and additionally exposes a POST `/auth/token` endpoint that exchanges the API key for a short-lived bearer access token. Through Jentic, the API key is stored in the encrypted vault and injected at execution time. ### Can I list available IPUMS data resources programmatically? Yes. The GET /resources endpoint returns the resources accessible to the caller, and GET `/resources/{id}` returns metadata for a specific resource by its identifier. ### How do I get an access token for the IPUMS API? POST to `/auth/token` with the X-API-Key header set. The response contains an access token to attach to subsequent requests. ### What are the rate limits for the IPUMS API? IPUMS does not publish per-minute rate limits in the spec; throughput is governed by your IPUMS account and the size of the data extracts you request. Heavy automated usage should respect the IPUMS terms of use. ### How do I fetch resource metadata through Jentic? Search Jentic for 'get IPUMS resource metadata', load the GET `/resources/{id}` operation, and execute it with the resource ID. Jentic injects the X-API-Key and returns the parsed metadata. ### Is the IPUMS API free? IPUMS data is free for academic and non-commercial research use, subject to registration and acceptance of the IPUMS terms. Some commercial uses require a separate agreement with IPUMS. ### Can I limit what my agent is allowed to do with the IPUMS API? Yes. Because you run Jentic One yourself, your own rules decide which IPUMS operations and credentials the agent may use, so you can allow only GET /resources and GET `/resources/{id}` and keep it to discovery and metadata retrieval. Since IPUMS puts the resource identifier in the URL path (`/resources/{id}`), a rule can even pin the agent to a single resource, letting it list and read that metadata and nothing else. Your X-API-Key stays with your instance and is added to the request at execution time, so the agent never gets to widen its own access.