Extract
Custom
Pass your own JSON Schema and get back data conformant to it.
POST /v1/extract/custom accepts a JSON Schema and a document. The response strictly conforms to the schema or returns extract_failed (422).
Request
curl https://api.untangledapi.com/v1/extract/custom \
-H "x-api-key: $UNTANGLED_KEY" \
-H "content-type: application/json" \
-d '{
"document": {
"text": "Patient: J. Smith, DOB 1982-03-14, BP 120/80, HR 64, allergies: penicillin"
},
"schema": {
"type": "object",
"properties": {
"patient_name": { "type": "string" },
"date_of_birth": { "type": "string", "format": "date" },
"vitals": {
"type": "object",
"properties": {
"blood_pressure": { "type": "string" },
"heart_rate": { "type": "integer" }
}
},
"allergies": { "type": "array", "items": { "type": "string" } }
},
"required": ["patient_name", "date_of_birth"]
}
}'Response
{
"data": {
"patient_name": "J. Smith",
"date_of_birth": "1982-03-14",
"vitals": { "blood_pressure": "120/80", "heart_rate": 64 },
"allergies": ["penicillin"]
},
"model": "claude-haiku-4-5",
"usage": {
"inputTokens": 390,
"outputTokens": 95
}
}Schema rules
- Top-level must be
type: "object". - All standard JSON Schema keywords are supported (
type,properties,required,enum,format,items,oneOf,anyOf,allOf). - Nested objects and arrays are supported up to 8 levels deep.
- Use
format: "date"/"date-time"/"email"/"uri"to constrain string shapes — Untangled validates server-side. - A field marked
requiredthat the document doesn't carry returns422 extract_failedrather than null. If the value is genuinely optional, omit it fromrequired.
When to use a prebuilt schema instead
If the document fits one of the prebuilt shapes (invoice, receipt, contract, job posting, meeting notes), use that endpoint directly — the prebuilt schemas are tuned for higher accuracy and a stable response shape across document variants. Custom is for shapes the prebuilts don't cover.