Home
APIs
Data & Extraction
Unstructured Text to Structured JSON Extractor API

Data & Extraction API

Unstructured Text to Structured JSON Extractor API

Structured data extraction API that converts unstructured emails, PDFs, and invoices into validated JSON objects.

POST https://rsflowhub.com/api/v1/ai/json-extractor

2 credits per call
X-API-Key header
JSON in, JSON out

Try it in the playground API reference

POST /api/v1/ai/json-extractor

{
    "text": "John is 30 years old and lives in New York. He is a software engineer.",
    "schema": {
        "name": "string",
        "age": "integer",
        "city": "string",
        "role": "string"
    },
    "custom_instructions": "Convert all keys to uppercase and output the city name in all-caps."
}

200 OK response.json

{
    "result": {
        "extracted_data": {
            "invoice_number": "INV-2041",
            "vendor": "Acme Supplies",
            "total": 1240.5,
            "currency": "USD",
            "due_date": "2026-11-02"
        },
        "schema_conforms": true
    }
}

Definition

What is the Unstructured Text to Structured JSON Extractor API?

Unstructured Text to Structured JSON Extractor API is a REST API on RSFlowHub for web, mobile and AI agent applications. Send a JSON request to POST /api/v1/ai/json-extractor with your API key; RSFlowHub runs it on a tuned AI model, falls back to a backup provider if needed, and returns a structured JSON result, usually within 1 to 3 seconds.

Category: Data & Extraction
Endpoint: POST /api/v1/ai/json-extractor
Authentication: X-API-Key header
Price: 2 credits per call
Rate limit: 10 to 120 requests / minute by plan
Typical response: 1 to 3 seconds
Format: JSON, UTF-8

Request parameters

Send these fields as a JSON body. An invalid or missing field returns a 422 error that names the field.

Field	Type	Required	Description
`text`	string	Required	The raw unstructured text containing data to be extracted (Max: 20,000 characters).
`schema`	object	Optional	Optional JSON object defining the key-value schema structure to guide the extraction.
`custom_instructions`	string	Optional	Optional text describing custom formatting, filtering, or sanitization rules (Max: 1,000 characters).
`allow_large_text`	boolean	Optional	Optional flag. Set to true to raise the maximum text size limit to 100,000 characters (charges 1 extra credit per 10k characters above 20k).

Code examples

Copy, replace rfh_your_api_key with your key and run. Prefer a client library? See the official SDKs.

request.sh

curl -X POST "https://rsflowhub.com/api/v1/ai/json-extractor" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: rfh_your_api_key" \
  -d '{"text":"John is 30 years old and lives in New York. He is a software engineer.","schema":{"name":"string","age":"integer","city":"string","role":"string"},"custom_instructions":"Convert all keys to uppercase and output the city name in all-caps."}'

client.php

<?php

$client = new \GuzzleHttp\Client();
$response = $client->post('https://rsflowhub.com/api/v1/ai/json-extractor', [
    'headers' => [
        'Content-Type' => 'application/json',
        'X-API-Key'    => 'rfh_your_api_key',
    ],
    'json' => array (
      'text' => 'John is 30 years old and lives in New York. He is a software engineer.',
      'schema' => 
      array (
        'name' => 'string',
        'age' => 'integer',
        'city' => 'string',
        'role' => 'string',
      ),
      'custom_instructions' => 'Convert all keys to uppercase and output the city name in all-caps.',
    ),
]);

echo $response->getBody();

client.js

const response = await fetch('https://rsflowhub.com/api/v1/ai/json-extractor', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-API-Key': 'rfh_your_api_key'
  },
  body: JSON.stringify({"text":"John is 30 years old and lives in New York. He is a software engineer.","schema":{"name":"string","age":"integer","city":"string","role":"string"},"custom_instructions":"Convert all keys to uppercase and output the city name in all-caps."})
});

const data = await response.json();
console.log(data);

main.py

import requests

url = "https://rsflowhub.com/api/v1/ai/json-extractor"
headers = {
    "Content-Type": "application/json",
    "X-API-Key": "rfh_your_api_key"
}
payload = {"text":"John is 30 years old and lives in New York. He is a software engineer.","schema":{"name":"string","age":"integer","city":"string","role":"string"},"custom_instructions":"Convert all keys to uppercase and output the city name in all-caps."}

response = requests.post(url, json=payload, headers=headers)
print(response.json())

Response

Every RSFlowHub endpoint uses the same envelope, so one parser handles all of them. Failed calls are not charged.

response.json

{
    "success": true,
    "request_id": "req_3f9a2c7e-5b1d-4e8a-9c2f-7d6e1a0b4c8d",
    "data": {
        "result": {
            "extracted_data": {
                "invoice_number": "INV-2041",
                "vendor": "Acme Supplies",
                "total": 1240.5,
                "currency": "USD",
                "due_date": "2026-11-02"
            },
            "schema_conforms": true
        }
    },
    "meta": {
        "version": "v1",
        "timestamp": "2026-10-05T09:30:00Z"
    }
}

error.json

{
    "success": false,
    "request_id": "req_8c1d4e2a-7f3b-4a9c",
    "error": {
        "code": "VALIDATION_ERROR",
        "message": "The given data was invalid.",
        "details": {
            "text": [
                "This field is required."
            ]
        }
    },
    "meta": {
        "version": "v1",
        "timestamp": "2026-10-05T09:30:00Z"
    }
}

Envelope fields
Field	Type	Meaning
`success`	boolean	true when the call worked, false on any error.
`request_id`	string	Unique id for this call. Quote it when you contact support.
`data.result`	object	The result of this endpoint (see the example).
`error`	object	Only on failure: code, message and details per field.
`meta`	object	API version and server timestamp.

All error codes: Errors reference

Features

Custom JSON Schema Validation

Enforces strict data types (string, integer, boolean, array, nested object) matching your exact target schema.

PDF & Raw Document Parsing

Extracts structured records, line item tables, and metadata fields from raw document text dumps.

Custom Field Formatting Directives

Supports custom transformation instructions like date normalization, uppercase formatting, or phone cleaning.

Validated JSON Responses

Guarantees syntactically valid, parseable JSON output with zero markdown formatting wrappers.

Use cases

How teams use the Unstructured Text to Structured JSON Extractor API in production.

FinTech & Accounting

Automated Invoice & Receipt Parsing

Extract line items, tax numbers, vendor details, and totals from unstructured invoice emails into accounting software.

Input: Invoice #1042 from Acme Corp. Total due: $450.00 by 2026-09-01. Item: Web Hosting ($450).
Output: {"invoice_id": "1042", "vendor": "Acme Corp", "total": 450.00, "due_date": "2026-09-01"}

Turns invoice and receipt text into structured fields instead of manual data entry.

HRTech & Recruitment

Resume & Candidate Data Extraction

Parse candidate contact details, work experience, education, and skill sets from raw resume text dumps.

Input: John Doe, Senior Software Engineer with 8 years experience in PHP, Laravel, and MySQL. Graduated MIT 2018.
Output: {"name": "John Doe", "role": "Senior Software Engineer", "experience_years": 8, "skills": ["PHP", "Laravel", "MySQL"]}

Automates candidate profile creation in ATS databases.

Logistics & E-Commerce

E-Commerce Order Confirmation Parsing

Extract tracking numbers, carrier names, and shipping addresses from buyer confirmation emails.

Input: Your order #SHP-9921 has shipped via FedEx tracking #992817261 to 123 Main St, New York.
Output: {"order_id": "SHP-9921", "carrier": "FedEx", "tracking_number": "992817261"}

Powers automated shipment tracking dashboards.

Unstructured Text to Structured JSON Extractor API vs building it yourself

The same job done three ways.

Topic	RSFlowHub API	Raw LLM prompts	Rules / regex
Output	Validated JSON fields	Free text you have to parse	Fixed patterns only
Setup	One POST request, no prompts	Write and maintain prompts and parsing	Write and maintain rule lists
Provider outage	Automatic fallback to a backup model	You build retries and a second vendor	Not applicable
Pricing	2 credits per call, failed calls free	Per token, per vendor	Your own servers and upkeep
Understands context	Yes, AI model	Yes, AI model	No, keywords only

Frequently asked questions

How does the JSON Extractor API guarantee valid JSON output?

Our gateway enforces strict grammar constraint decoders, ensuring the output is always 100% syntactically valid JSON parseable by json_decode() or JSON.parse().

Can I provide custom JSON schema types?

Yes! You can define custom key-value data types in the "schema" object parameter to enforce exact output keys and data types.

What happens if a field is missing in the source text?

If a requested schema key is not present in the input text, the API returns null or an empty array for that specific key.

How fast is the JSON Extractor API?

JSON Extractor requests usually complete in 1 to 3 seconds, depending on input length and the AI model. Identical repeat requests are served from cache and return faster.

How many credits are deducted per request?

JSON Extractor API calls consume 2 base credits per request.

Start using the Unstructured Text to Structured JSON Extractor API

Free plan with 100 credits/month + 1,000 bonus credits when you sign in before 23 Nov. Test it in the playground first, no code needed.

Get a free API key Try it now