How to type third-party API responses in TypeScript (without lying to your compiler)

You add TypeScript to a project, turn on strict, fix every red squiggle, and feel safe. Then a third-party API quietly changes a field from a number to a string, your app explodes in production, and TypeScript never said a word.

That gap surprises people, so it's worth saying plainly: TypeScript checks your code, not the data your code receives at runtime. The moment a value crosses the network boundary, your types are a promise nobody is enforcing. This article walks through how to type API responses honestly — from the quick approaches that only look safe, to the ones that actually hold up when the data misbehaves.

The starting point: fetch gives you nothing

Here's the shape of the problem. The built-in fetch returns a response whose .json() resolves to any:

const response = await fetch("https://api.example.com/users/1");
const user = await response.json(); // user: any
console.log(user.naem.toUpperCase()); // typo, no error, crashes at runtime

any switches type checking off. Every property access is allowed, including the typo. So the first instinct is usually to reach for a type assertion.

The trap: as assertions

This compiles, and it's tempting:

interface User {
  id: number;
  name: string;
  email: string;
}

const user = (await response.json()) as User;
console.log(user.name.toUpperCase());

Now your editor autocompletes user.name and the typo is caught. It feels solved. It isn't.

as is you telling the compiler "trust me, this is a User." The compiler stops arguing and assumes you're right. But nothing checks the actual JSON. If the API returns { "id": "1", "name": null }, TypeScript still believes name is a string, and user.name.toUpperCase() throws Cannot read properties of null in production — exactly the failure types were supposed to prevent.

A type assertion doesn't verify anything. It silences the one part of your stack that was being honest about not knowing.

Step one: generics for a reusable typed wrapper

Before we fix the runtime problem, let's at least stop repeating ourselves. A small generic wrapper lets each call site say what it expects:

async function getJson<T>(url: string): Promise<T> {
  const response = await fetch(url);
  if (!response.ok) {
    throw new Error(`Request failed: ${response.status}`);
  }
  return response.json() as Promise<T>;
}

interface User {
  id: number;
  name: string;
  email: string;
}

const user = await getJson<User>("https://api.example.com/users/1");
console.log(user.name.toUpperCase()); // user is typed as User

This is genuinely useful: the <T> flows through, so every caller gets a typed result without scattering assertions everywhere. The error handling lives in one place.

But be honest about what it does and doesn't do. That as Promise<T> inside the wrapper is the same assertion as before, just hidden one level down. The ergonomics improved; the runtime safety did not. The data is still unverified.

Step two: validate at the boundary with a schema

The real fix is to check the data once, at the edge where it enters your app, and only hand the rest of your code values that have actually been verified. A schema validation library like Zod makes this the path of least resistance.

The key idea: you write the schema as the single source of truth, and derive the TypeScript type from it — instead of writing an interface and a separate validator that drift apart over time.

import { z } from "zod";

const UserSchema = z.object({
  id: z.number(),
  name: z.string(),
  email: z.string().email(),
});

// Derive the type from the schema — one source of truth.
type User = z.infer<typeof UserSchema>;

async function getUser(url: string): Promise<User> {
  const response = await fetch(url);
  const json: unknown = await response.json(); // start from unknown, not any
  return UserSchema.parse(json); // throws if the payload doesn't match
}

Two things changed that matter:

1. json starts as unknown, not any. unknown forces you to prove what the value is before you can use it — the compiler won't let you skip the check.
2. UserSchema.parse(json) actually inspects the data at runtime. If the API returns { "id": "1", ... } with a stringy id, it throws a ZodError immediately, at the boundary, with a clear message — instead of three components deep when you try to do math on it.

If you'd rather handle bad data as a value than a thrown exception, use safeParse:

const result = UserSchema.safeParse(json);
if (!result.success) {
  // result.error.issues is an array of every problem found
  console.error(result.error.issues);
  return;
}
// result.data is fully typed AND verified here
console.log(result.data.name.toUpperCase());

I tested both paths against a deliberately malformed payload (id as a string, invalid email): parse throws a ZodError, and safeParse returns success: false with two issues — one per bad field. That's the difference between "TypeScript thinks this is fine" and "this data is provably correct."

Step three: codegen, when the API already has a schema

Hand-writing schemas is the right call for APIs you don't control or that have no machine-readable contract. But if the API publishes one, generate your types from it instead of transcribing them by hand:

• REST with an OpenAPI/Swagger spec → openapi-typescript turns the spec into types.
• GraphQL → GraphQL Code Generator produces types from your schema and even your individual queries.

Codegen's advantage is that the types are mechanically tied to the contract: when the API's spec changes and you regenerate, the new or removed fields show up as type errors across your codebase, pointing you straight at what broke. The tradeoff is that most codegen describes the shape at build time; it doesn't, by itself, validate the actual response at runtime. For untrusted or flaky sources, people often pair generated types with a runtime check at the boundary.

Which approach should you reach for?

There's no single winner — it depends on how much you trust the source and what the API gives you:

• Internal API you control, low risk, want speed: a generic getJson<T> wrapper with hand-written interfaces is fine. Just know the runtime is unchecked.
• Third-party or user-facing data, correctness matters: validate at the boundary with a schema (Zod or similar) and derive your types from it. This is the default I'd recommend for anything important.
• API ships an OpenAPI or GraphQL schema: generate types from the contract, and add a runtime check at the edge if the data is untrusted.

Notice the through-line: the safest options all push verification to the boundary and keep a single source of truth for the type. Everything inside your app then works with data that's already been proven to match its type — which is the actual promise TypeScript was supposed to give you.

Takeaway

TypeScript types describe what your data should be. They don't make it so. For data you generate inside your own code, that's enough. For data arriving over the network, you need something that checks reality:

• Reach for generics to stop repeating type assertions, but don't mistake nicer ergonomics for safety.
• Avoid as on API responses — it silences the compiler instead of verifying the data.
• Validate at the boundary with a schema and infer your types from it, so the type and the check can never drift apart.
• Generate types from an OpenAPI or GraphQL contract when one exists, and validate at runtime when the source is untrusted.

Do that, and the next time an API quietly changes a field, you find out at the boundary with a clear error — not from a user, in production, three layers deep.