Forge Json

Flatten JSON API Example

Walk through a realistic API response and see exactly how nested customer, billing, metadata, and item fields become flat JSON paths.

Paste your JSON → Get results instantly (no signup)

⚡ Instant resultsNo signupRuns in your browser
Try examples:

→ Flatten or nest keys in this JSON structure and flatten nested object.

{
"user": {
"name": "Alice",
"address": {
"city": "NYC",
"zip": "10001"
}
}
}
Output✓
1{
2  "user.name": "Alice",
3  "user.address.city": "NYC",
4  "user.address.zip": "10001"
5}

Love the result?

Use this exact pipeline in your app, backend, or LLM workflow.

No setup needed. Works with curl, Node, Python.

Uses example data. For edited input, copy from the playground.

Read integration guide

Works with:

  • REST API examples
  • Webhook sample payloads
  • API documentation snippets
  • QA and support tickets

Example: input → output

Flatten JSON API example

API examples are easier to understand when you can see both shapes: the nested response an endpoint returns, and the flat path map that makes each value visible. This page walks through a realistic nested API response and shows how customer, billing, metadata, and item fields become flat JSON keys.

It uses the same engine as the JSON flattener, but the content here is example-first for people searching for a concrete API payload.

Nested API response

Input:

{
  "data": {
    "id": "sub_1001",
    "customer": {
      "id": "cus_42",
      "email": "ada@example.com"
    },
    "billing": {
      "plan": "pro",
      "amount": 4900,
      "currency": "USD"
    }
  },
  "meta": {
    "request_id": "req_abc",
    "environment": "production"
  }
}

Flattened output:

{
  "data.id": "sub_1001",
  "data.customer.id": "cus_42",
  "data.customer.email": "ada@example.com",
  "data.billing.plan": "pro",
  "data.billing.amount": 4900,
  "data.billing.currency": "USD",
  "meta.request_id": "req_abc",
  "meta.environment": "production"
}

The flat version is useful when you need to paste a field list into documentation, compare two environments, or export a response sample to CSV.

Why API examples help

Generic flattening examples are often too small. Real API responses have wrappers like data, meta, attributes, edges, nodes, and included. Flattening an API example shows the exact path convention your team will use in docs, tests, and support tickets.

If your input is a webhook or vendor response, use Flatten API Response JSON. If your output is headed to a spreadsheet, use Flatten JSON for CSV.

Flatten API example for docs

Flat paths make API docs easier to scan:

  • data.customer.email - customer email used for notifications.
  • data.billing.amount - amount in minor currency units.
  • meta.request_id - trace identifier for support.

That format helps readers understand where values live without expanding a full nested document.

Common API example mistakes

  • Flattening the example and forgetting to keep the original nested response in docs.
  • Expanding arrays by index when the API returns variable-length line items.
  • Using a delimiter that conflicts with source keys.
  • Comparing flattened examples across environments without sorting or normalizing fields first.
  • Treating a flattened example as the request shape an API expects.

Frequently asked questions

What is a JSON API flattening example?+

It shows a nested API response beside the flat path-key output, so values such as data.customer.email become easy to inspect, export, or document.

Should API docs show flat or nested JSON?+

Show the original nested response as the canonical API shape. Use flat paths as a companion field list for readability.

Can I flatten webhook examples too?+

Yes. Webhook payloads are often deeply nested and benefit from a flat path map for debugging, testing, and documentation.

Related tools

Read more on the blog

Advanced usage (optional)

Flatten / Nest

v1.0.0
Structure
objectarrayreversible

Description

Flatten / Nest

Convert between nested and flat object structures. Flatten deep objects into single-level key-value pairs, or nest flat keys back into hierarchical objects. Supports multiple key formats: delimiter-separated, camelCase, snake_case, PascalCase, and kebab-case.

Modes

Flatten

Convert nested objects into flat keys. Each nested path becomes part of the key name.

{ "user": { "name": "Alice" } }  →  { "user.name": "Alice" }

Nest

Convert flat keys back into nested objects by splitting on the delimiter or case boundaries.

{ "user.name": "Alice" }  →  { "user": { "name": "Alice" } }

Key Formats

Delimiter (default)

Join/split key segments with a character (default: .).

  • Flatten: user + name → user.name
  • Nest: user.name → user / name

camelCase

Join/split on uppercase letter boundaries.

  • Flatten: user + address + city → userAddressCity
  • Nest: userAddressCity → user / address / city

snake_case

Join/split on underscores.

  • Flatten: user + address + city → user_address_city
  • Nest: user_address_city → user / address / city

PascalCase

Same as camelCase but with uppercase first letter.

  • Flatten: user + name → UserName

kebab-case

Join/split on hyphens.

  • Flatten: user + name → user-name

Configuration

FieldTypeDefaultDescription
Modeenumflattenflatten or nest
Key Formatenumdelimiterdelimiter, camelCase, snake_case, PascalCase, or kebab-case
Delimiterstring.Character(s) used to join/split key segments (only for delimiter format)
Max Depthnumber0Maximum nesting depth to flatten (0 = unlimited)
Target Pathspath-picker[]Scope operation to specific paths only (empty = apply everywhere)

Use Cases

API Integration

  • Flatten for forms: Convert nested API responses to flat form field names
  • Nest for APIs: Convert flat form data back to nested API request bodies
  • Format conversion: Transform between dot-notation and camelCase conventions

Database Operations

  • MongoDB flattening: Flatten nested documents for tabular export
  • SQL mapping: Convert hierarchical JSON to flat column names for SQL insertion
  • Schema migration: Convert between naming conventions (snake_case ↔ camelCase)

Configuration Management

  • Environment variables: Flatten config objects to dot-notation for .env files
  • Depth limiting: Flatten only the first level while preserving deep structures

Configuration

NameTypeDefaultDescription
Modeenumflattenflatten: convert nested objects to flat keys. nest: convert flat keys back to nested objects. flatten nest
Key Formatenumdelimiterdelimiter: use a character to join/split. Others: camelCase, snake_case, PascalCase, kebab-case. delimiter camelCase snake_case PascalCase kebab-case
Delimiterstring.Character(s) used to join/split key segments (default is dot)
Max Depthnumber0Maximum nesting depth to flatten (0 = unlimited)
Target Pathspath-picker[]Scope operation to specific paths only (empty = apply everywhere)

Examples

AI Prompt
Flatten or nest keys in this JSON structure and flatten nested object.
{
"user": {
"name": "Alice",
"address": {
"city": "NYC",
"zip": "10001"
}
}
}
Output✓
1{
2  "user.name": "Alice",
3  "user.address.city": "NYC",
4  "user.address.zip": "10001"
5}
Config
Mode
flatten
Delimiter
.
Max Depth
0
Target Paths
all

API Usage

POST /api/v1/utilities/structure.flatten-nest
Example:
curl -X POST https://your-domain.com/api/v1/utilities/structure.flatten-nest \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"inputs":{"primary":{"user":{"name":"Alice","address":{"city":"NYC","zip":"10001"}}}},"config":{"mode":"flatten","delimiter":".","maxDepth":0,"targetPaths":[]}}'
Response
1{
2  "user.name": "Alice",
3  "user.address.city": "NYC",
4  "user.address.zip": "10001"
5}