{"openapi":"3.0.0","paths":{"/documents/types":{"get":{"description":"Returns all document types you can process, with their endpoints and status.","operationId":"listDocumentTypes","parameters":[],"responses":{"200":{"description":"Available document types","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DocumentTypesResponseDto"}}}},"401":{"description":"Invalid or missing API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UnauthorizedErrorDto"},"examples":{"invalidKey":{"summary":"A key that is unknown, revoked or expired","value":{"error":"Unauthorized","message":"Invalid or expired API key","timestamp":"2026-10-02T12:00:00.000Z"}},"missingKey":{"summary":"No key","value":{"error":"Unauthorized","message":"API key is required. Provide Authorization: Bearer <your-api-key>","timestamp":"2026-10-02T12:00:00.000Z"}}}}}}},"security":[{"api-key":[]}],"summary":"List available document types","tags":["documents"],"x-codeSamples":[{"lang":"Shell","label":"cURL","source":"#!/usr/bin/env bash\n# The document types the API reads, and the endpoint of each.\n# Needs DOCSOCR_API_KEY in the environment; create a key in the panel.\nset -euo pipefail\n\ncurl -sS --max-time 30 https://api.docsocr.com/api/v1/documents/types \\\n  -H \"Authorization: Bearer $DOCSOCR_API_KEY\"\n"},{"lang":"Python","label":"Python","source":"\"\"\"The document types the API reads, and the endpoint of each.\n\nNeeds the requests package and DOCSOCR_API_KEY in the environment.\n\"\"\"\nimport os\n\nimport requests\n\nresponse = requests.get(\n    \"https://api.docsocr.com/api/v1/documents/types\",\n    headers={\"Authorization\": f\"Bearer {os.environ['DOCSOCR_API_KEY']}\"},\n    timeout=30,\n)\nresponse.raise_for_status()\nfor document_type in response.json()[\"types\"]:\n    print(f\"{document_type['id']}: POST {document_type['endpoint']}\")\n"},{"lang":"JavaScript","label":"Node.js","source":"// The document types the API reads, and the endpoint of each.\n// Needs Node.js 18+ and DOCSOCR_API_KEY in the environment.\nconst response = await fetch('https://api.docsocr.com/api/v1/documents/types', {\n  headers: { Authorization: `Bearer ${process.env.DOCSOCR_API_KEY}` },\n  signal: AbortSignal.timeout(30_000),\n})\nif (!response.ok) {\n  console.error(response.status, await response.text())\n  process.exit(1)\n}\nfor (const type of (await response.json()).types) {\n  console.log(`${type.id}: POST ${type.endpoint}`)\n}\n"},{"lang":"PHP","label":"PHP","source":"<?php\n// The document types the API reads, and the endpoint of each.\n// Needs the curl extension and DOCSOCR_API_KEY in the environment.\n\n$request = curl_init('https://api.docsocr.com/api/v1/documents/types');\ncurl_setopt_array($request, [\n    CURLOPT_RETURNTRANSFER => true,\n    CURLOPT_TIMEOUT => 30,\n    CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . getenv('DOCSOCR_API_KEY')],\n]);\n$body = curl_exec($request);\n$status = curl_getinfo($request, CURLINFO_RESPONSE_CODE);\nif ($body === false || $status !== 200) {\n    fwrite(STDERR, \"$status \" . ($body === false ? curl_error($request) : $body) . PHP_EOL);\n    exit(1);\n}\nforeach (json_decode($body, true)['types'] as $type) {\n    echo \"{$type['id']}: POST {$type['endpoint']}\", PHP_EOL;\n}\n"},{"lang":"Java","label":"Java","source":"// The document types the API reads, and the endpoint of each.\n// Needs Java 17+ and DOCSOCR_API_KEY in the environment. Run: java DocumentTypes.java\nimport java.net.URI;\nimport java.net.http.HttpClient;\nimport java.net.http.HttpRequest;\nimport java.net.http.HttpResponse;\nimport java.time.Duration;\n\npublic class DocumentTypes {\n    public static void main(String[] args) throws Exception {\n        HttpRequest request = HttpRequest.newBuilder(URI.create(\"https://api.docsocr.com/api/v1/documents/types\"))\n            .timeout(Duration.ofSeconds(30))\n            .header(\"Authorization\", \"Bearer \" + System.getenv(\"DOCSOCR_API_KEY\"))\n            .GET()\n            .build();\n        HttpResponse<String> response = HttpClient.newHttpClient().send(request, HttpResponse.BodyHandlers.ofString());\n\n        // The answer is JSON, e.g. {\"types\": [{\"id\": \"birth-certificate\", ...}]}; read it with your JSON library\n        System.out.println(response.body());\n        if (response.statusCode() != 200) {\n            System.exit(1);\n        }\n    }\n}\n"},{"lang":"C#","label":"C#","source":"// The document types the API reads, and the endpoint of each.\n// Needs .NET 8+ and DOCSOCR_API_KEY in the environment. Run: dotnet run DocumentTypes.cs (.NET 10)\nusing System.Net.Http.Headers;\nusing System.Text.Json;\n\nusing var http = new HttpClient { Timeout = TimeSpan.FromSeconds(30) };\nhttp.DefaultRequestHeaders.Authorization =\n    new AuthenticationHeaderValue(\"Bearer\", Environment.GetEnvironmentVariable(\"DOCSOCR_API_KEY\"));\n\nusing var response = await http.GetAsync(\"https://api.docsocr.com/api/v1/documents/types\");\nvar body = await response.Content.ReadAsStringAsync();\nif (!response.IsSuccessStatusCode)\n{\n    Console.Error.WriteLine($\"{(int)response.StatusCode} {body}\");\n    return 1;\n}\n\nusing var answer = JsonDocument.Parse(body);\nforeach (var type in answer.RootElement.GetProperty(\"types\").EnumerateArray())\n{\n    Console.WriteLine($\"{type.GetProperty(\"id\").GetString()}: POST {type.GetProperty(\"endpoint\").GetString()}\");\n}\nreturn 0;\n"}]}},"/documents/prices":{"get":{"description":"What an extraction costs now: on the standard engines, on the fast engine when the request asks for it, and the extra for `resizeImage`. No API key needed. fast's price may change: read it here.","operationId":"getExtractionPrices","parameters":[],"responses":{"200":{"description":"The prices in force","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExtractionPricesDto"}}}}},"security":[],"summary":"Prices of an extraction, in credits","tags":["documents"],"x-codeSamples":[{"lang":"Shell","label":"cURL","source":"#!/usr/bin/env bash\n# The price of an extraction, in credits, per engine and for resizeImage.\n# A public endpoint: no key needed.\nset -euo pipefail\n\ncurl -sS --max-time 30 https://api.docsocr.com/api/v1/documents/prices\n"},{"lang":"Python","label":"Python","source":"\"\"\"The price of an extraction, in credits, per engine and for resizeImage.\n\nA public endpoint: no key needed. Needs the requests package.\n\"\"\"\nimport requests\n\nresponse = requests.get(\"https://api.docsocr.com/api/v1/documents/prices\", timeout=30)\nresponse.raise_for_status()\nfor name, credits in response.json().items():\n    print(f\"{name}: {credits} credit(s)\")\n"},{"lang":"JavaScript","label":"Node.js","source":"// The price of an extraction, in credits, per engine and for resizeImage.\n// A public endpoint: no key needed. Needs Node.js 18+.\nconst response = await fetch('https://api.docsocr.com/api/v1/documents/prices', {\n  signal: AbortSignal.timeout(30_000),\n})\nif (!response.ok) {\n  console.error(response.status)\n  process.exit(1)\n}\nfor (const [name, credits] of Object.entries(await response.json())) {\n  console.log(`${name}: ${credits} credit(s)`)\n}\n"},{"lang":"PHP","label":"PHP","source":"<?php\n// The price of an extraction, in credits, per engine and for resizeImage.\n// A public endpoint: no key needed. Needs the curl extension.\n\n$request = curl_init('https://api.docsocr.com/api/v1/documents/prices');\ncurl_setopt_array($request, [CURLOPT_RETURNTRANSFER => true, CURLOPT_TIMEOUT => 30]);\n$body = curl_exec($request);\nif ($body === false || curl_getinfo($request, CURLINFO_RESPONSE_CODE) !== 200) {\n    fwrite(STDERR, 'The price list did not answer' . PHP_EOL);\n    exit(1);\n}\nforeach (json_decode($body, true) as $name => $credits) {\n    echo \"$name: $credits credit(s)\", PHP_EOL;\n}\n"},{"lang":"Java","label":"Java","source":"// The price of an extraction, in credits, per engine and for resizeImage.\n// A public endpoint: no key needed. Needs Java 17+. Run: java Prices.java\nimport java.net.URI;\nimport java.net.http.HttpClient;\nimport java.net.http.HttpRequest;\nimport java.net.http.HttpResponse;\nimport java.time.Duration;\n\npublic class Prices {\n    public static void main(String[] args) throws Exception {\n        HttpRequest request = HttpRequest.newBuilder(URI.create(\"https://api.docsocr.com/api/v1/documents/prices\"))\n            .timeout(Duration.ofSeconds(30))\n            .GET()\n            .build();\n        HttpResponse<String> response = HttpClient.newHttpClient().send(request, HttpResponse.BodyHandlers.ofString());\n\n        // The answer is JSON, e.g. {\"standard\": 1, ...}; read it with your JSON library\n        System.out.println(response.body());\n        if (response.statusCode() != 200) {\n            System.exit(1);\n        }\n    }\n}\n"},{"lang":"C#","label":"C#","source":"// The price of an extraction, in credits, per engine and for resizeImage.\n// A public endpoint: no key needed. Needs .NET 8+. Run: dotnet run Prices.cs (.NET 10)\nusing System.Text.Json;\n\nusing var http = new HttpClient { Timeout = TimeSpan.FromSeconds(30) };\nusing var prices = JsonDocument.Parse(await http.GetStringAsync(\"https://api.docsocr.com/api/v1/documents/prices\"));\n\nforeach (var price in prices.RootElement.EnumerateObject())\n{\n    Console.WriteLine($\"{price.Name}: {price.Value} credit(s)\");\n}\n"}]}},"/documents/birth-certificate":{"post":{"description":"\n**What it does:** extracts every field of a Brazilian birth certificate from a photo, a scan or a PDF.\n\n**Send the image** at a public URL (`imageType: \"url\"` with `imageUrl`) or in the body (`imageType: \"base64\"` with `imageBase64`). Try it with the hosted sample, https://docsocr.com/samples/certidao-nascimento-exemplo.jpg (fictitious data).\n\n**Our image standard:** 1344 to 2048 px on the long side, where every engine reads best. An image outside it is refused with 422 at no charge, unless `resizeImage: true` asks us to resize it, for 1 extra credit; that adds time to the answer.\n\n**The fast engine:** `\"engine\": \"fast\"` asks for it. It is tried first, and the standard engines follow if it cannot answer.\n\n**The answer:** the certificate's fields in `data`, the engine that answered (`engine`) and what the request cost (`creditsCharged`). When no engine can answer, the status is still 201, with `success: false`, an `errorCode` and nothing charged: `EXTRACTION_BUSY`, `EXTRACTION_TIMEOUT` and `EXTRACTION_UNAVAILABLE` may pass when you send the same request again later; `DOCUMENT_NOT_RECOGNIZED` and `IMAGE_NOT_PROCESSABLE` need another image.\n\n**Repeating a request:** the same `requestId`, file and options within 15 minutes of the answer get the same answer at no charge, without running the engines, with the header `Idempotent-Replayed: true`. While the first request still runs, a repeat gets 409 `REQUEST_IN_PROGRESS` with `Retry-After`.\n\n**Price:** 1 credit per answer with data, on the standard engines; with `\"engine\": \"fast\"`, fast's price when fast answers (`GET /documents/prices`). **[Check balance](https://app.docsocr.com/admin/billing/credits)**\n    ","operationId":"extractBirthCertificate","parameters":[{"name":"accept-language","required":false,"in":"header","description":"The language of the messages in refusals and errors: `pt-BR` for Portuguese, English otherwise.","schema":{"type":"string","enum":["en","pt-BR"],"default":"en"}}],"requestBody":{"required":true,"description":"The certificate image, at a public URL or in base64: `imageType` says which.","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/BirthCertificateOcrRequestWithUrl"},{"$ref":"#/components/schemas/BirthCertificateOcrRequestWithBase64"}],"discriminator":{"propertyName":"imageType","mapping":{"url":"#/components/schemas/BirthCertificateOcrRequestWithUrl","base64":"#/components/schemas/BirthCertificateOcrRequestWithBase64"}}},"examples":{"sample":{"summary":"The hosted sample certificate (fictitious data)","value":{"imageType":"url","imageUrl":"https://docsocr.com/samples/certidao-nascimento-exemplo.jpg","requestId":"6f1c2a9e-3b7d-4e5f-9a8b-1c2d3e4f5a6b"}},"base64":{"summary":"A file in base64 (cut short here)","value":{"imageType":"base64","imageBase64":"data:image/jpeg;base64,/9j/4AAQSkZJRgABAQAAAQABAAD/2wBDAAgGBgcG...","requestId":"0b9d4c7e-58a1-4f2b-8c3d-6e7f8a9b0c1d"}},"resize":{"summary":"An image below our standard, resized for 1 extra credit","value":{"imageType":"url","imageUrl":"https://docsocr.com/samples/certidao-nascimento-exemplo-800x640.jpg","requestId":"9a8b7c6d-5e4f-4a3b-9c2d-1e0f9a8b7c6d","resizeImage":true}},"fast":{"summary":"Asking for the fast engine","value":{"imageType":"url","imageUrl":"https://docsocr.com/samples/certidao-nascimento-exemplo.jpg","requestId":"3c4d5e6f-7a8b-4c9d-8e0f-1a2b3c4d5e6f","engine":"fast"}}}}}},"responses":{"201":{"description":"The certificate's data. With `success: false`, no engine could answer: `errorCode` says why, and nothing was charged.","headers":{"Idempotent-Replayed":{"description":"`true` when the answer is the one kept for a repeat: the same answer as the first time, at no charge, without the engines. Absent otherwise.","schema":{"type":"string","enum":["true"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BirthCertificateOcrResponseDto"},"examples":{"data":{"summary":"The sample certificate, answered by a standard engine","value":{"success":true,"processingTimeMs":6120,"data":{"documento":{"tipo":"Certidão de Nascimento","órgão_emissor":"CARTÓRIO DO 1º OFÍCIO DE REGISTRO CIVIL DE RECIFE - PE"},"dados_pessoais":{"nome_completo":"ANA BEATRIZ DOS SANTOS TESTE","cpf":"123.456.789-09","matrícula":"123456 01 55 2020 1 00012 123 0001234 56","data_nascimento":{"texto_completo":"","dia":"15","mês":"03","ano":"2020"},"hora_nascimento":"08:45","naturalidade":"RECIFE - PE","sexo":"FEMININO"},"local_nascimento":{"estabelecimento":"HOSPITAL EXEMPLO","município":"RECIFE","uf":"PE"},"registro":{"município":"RECIFE","uf":"PE","cartório":"CARTÓRIO DO 1º OFÍCIO DE REGISTRO CIVIL DE RECIFE - PE","data_registro":"20/03/2020","número_dnv":"","livro":"A-123","folha":"045","termo":"00012"},"filiação":{"genitor_1":{"nome_completo":"CARLA DOS SANTOS TESTE","naturalidade":""},"genitor_2":{"nome_completo":"JOÃO PEREIRA TESTE","naturalidade":""}},"avós":{"paternos":{"avô":"ANTÔNIO PEREIRA","avó":"LÚCIA PEREIRA"},"maternos":{"avô":"JOSÉ DOS SANTOS","avó":"MARIA DOS SANTOS"}},"gêmeos":{"status":"Não","informações_adicionais":""},"observações":{"averbações":"","anotações":""},"autenticação":{"selo_digital":"","oficial_registro":"PEDRO EXEMPLO","data_emissão":"20/03/2020"}},"engine":"mini","creditsCharged":1}},"resized":{"summary":"The 800×640 sample with resizeImage: true","value":{"success":true,"processingTimeMs":6120,"data":{"documento":{"tipo":"Certidão de Nascimento","órgão_emissor":"CARTÓRIO DO 1º OFÍCIO DE REGISTRO CIVIL DE RECIFE - PE"},"dados_pessoais":{"nome_completo":"ANA BEATRIZ DOS SANTOS TESTE","cpf":"123.456.789-09","matrícula":"123456 01 55 2020 1 00012 123 0001234 56","data_nascimento":{"texto_completo":"","dia":"15","mês":"03","ano":"2020"},"hora_nascimento":"08:45","naturalidade":"RECIFE - PE","sexo":"FEMININO"},"local_nascimento":{"estabelecimento":"HOSPITAL EXEMPLO","município":"RECIFE","uf":"PE"},"registro":{"município":"RECIFE","uf":"PE","cartório":"CARTÓRIO DO 1º OFÍCIO DE REGISTRO CIVIL DE RECIFE - PE","data_registro":"20/03/2020","número_dnv":"","livro":"A-123","folha":"045","termo":"00012"},"filiação":{"genitor_1":{"nome_completo":"CARLA DOS SANTOS TESTE","naturalidade":""},"genitor_2":{"nome_completo":"JOÃO PEREIRA TESTE","naturalidade":""}},"avós":{"paternos":{"avô":"ANTÔNIO PEREIRA","avó":"LÚCIA PEREIRA"},"maternos":{"avô":"JOSÉ DOS SANTOS","avó":"MARIA DOS SANTOS"}},"gêmeos":{"status":"Não","informações_adicionais":""},"observações":{"averbações":"","anotações":""},"autenticação":{"selo_digital":"","oficial_registro":"PEDRO EXEMPLO","data_emissão":"20/03/2020"}},"imageResized":true,"originalImageSize":{"width":800,"height":640},"finalImageSize":{"width":1344,"height":1075},"engine":"mini","creditsCharged":2}},"busy":{"summary":"No engine could answer: nothing charged, send it again later","value":{"success":false,"processingTimeMs":1203,"error":"The extraction service is busy. Please retry in a few moments. No credit was charged.","errorCode":"EXTRACTION_BUSY","data":{"documento":{"tipo":"","órgão_emissor":""},"dados_pessoais":{"nome_completo":"","cpf":"","matrícula":"","data_nascimento":{"texto_completo":"","dia":"","mês":"","ano":""},"hora_nascimento":"","naturalidade":"","sexo":""},"local_nascimento":{"estabelecimento":"","município":"","uf":""},"registro":{"município":"","uf":"","cartório":"","data_registro":"","número_dnv":""},"filiação":{"genitor_1":{"nome_completo":"","naturalidade":""},"genitor_2":{"nome_completo":"","naturalidade":""}},"avós":{"paternos":{"avô":"","avó":""},"maternos":{"avô":"","avó":""}},"gêmeos":{"status":"Não","informações_adicionais":""},"observações":{"averbações":"","anotações":""},"autenticação":{"selo_digital":"","oficial_registro":"","data_emissão":""}},"creditsCharged":0}},"notRecognized":{"summary":"Not a birth certificate: nothing charged, do not retry","value":{"success":false,"processingTimeMs":2410,"error":"The document could not be processed. Check that the image shows a birth certificate. No credit was charged.","errorCode":"DOCUMENT_NOT_RECOGNIZED","data":{"documento":{"tipo":"","órgão_emissor":""},"dados_pessoais":{"nome_completo":"","cpf":"","matrícula":"","data_nascimento":{"texto_completo":"","dia":"","mês":"","ano":""},"hora_nascimento":"","naturalidade":"","sexo":""},"local_nascimento":{"estabelecimento":"","município":"","uf":""},"registro":{"município":"","uf":"","cartório":"","data_registro":"","número_dnv":""},"filiação":{"genitor_1":{"nome_completo":"","naturalidade":""},"genitor_2":{"nome_completo":"","naturalidade":""}},"avós":{"paternos":{"avô":"","avó":""},"maternos":{"avô":"","avó":""}},"gêmeos":{"status":"Não","informações_adicionais":""},"observações":{"averbações":"","anotações":""},"autenticação":{"selo_digital":"","oficial_registro":"","data_emissão":""}},"creditsCharged":0}}}}}},"400":{"description":"The body is not valid: `message` lists what to fix. Nothing was charged.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorDto"},"examples":{"validation":{"summary":"A field is missing or wrong","value":{"message":["imageUrl is required when imageType is \"url\"","requestId may only contain letters, digits, _, -, . and : (up to 128 characters)"],"error":"Bad Request","statusCode":400}}}}}},"401":{"description":"The API key is missing, malformed, unknown, revoked or expired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UnauthorizedErrorDto"},"examples":{"invalidKey":{"summary":"A key that is unknown, revoked or expired","value":{"error":"Unauthorized","message":"Invalid or expired API key","timestamp":"2026-10-02T12:00:00.000Z"}},"missingKey":{"summary":"No key","value":{"error":"Unauthorized","message":"API key is required. Provide Authorization: Bearer <your-api-key>","timestamp":"2026-10-02T12:00:00.000Z"}}}}}},"402":{"description":"Not enough credits for this request (`errorCode` `NOT_ENOUGH_CREDITS`). A request holds its price while it runs: its engine's price (see `GET /documents/prices`), plus 1 extra credit with `resizeImage: true`. `message` gives the price and the balance; send `Accept-Language: pt-BR` for it in Portuguese. A repeat of a request answered in the last 15 minutes needs no credits.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentRequiredErrorDto"},"examples":{"notEnoughCredits":{"summary":"The balance cannot pay the request","value":{"statusCode":402,"message":"This request costs 1 credit, and the available balance is 0 credits. Buy credits or upgrade your plan to continue.","error":"Payment Required","errorCode":"NOT_ENOUGH_CREDITS","action":"purchase_credits","creditsAvailable":0,"creditsRequired":1,"planCreditsRemaining":0,"purchasedCreditsRemaining":0}}}}}},"409":{"description":"A request with the same `requestId`, file and options is still running (`errorCode` `REQUEST_IN_PROGRESS`). Nothing ran and nothing was charged. Wait the `Retry-After` seconds and send it again: you get its answer at no charge.","headers":{"Retry-After":{"description":"Seconds to wait before sending it again, as `retryAfter`","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RequestInProgressErrorDto"},"examples":{"inProgress":{"summary":"The same request is still running","value":{"statusCode":409,"message":"A request with this requestId and the same content is still being processed. Try again in a few seconds to get its answer, at no charge.","error":"Conflict","errorCode":"REQUEST_IN_PROGRESS","retryAfter":5}}}}}},"413":{"description":"The request body is over 15 MB: `errorCode` `IMAGE_TOO_LARGE`. Nothing was charged.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PayloadTooLargeErrorDto"},"examples":{"tooLarge":{"summary":"The body is over the limit","value":{"success":false,"errorCode":"IMAGE_TOO_LARGE","error":"The image is larger than 10 MB. Send a smaller image, for example a JPG with lower resolution or quality.","processingTimeMs":0}}}}}},"422":{"description":"The image cannot be used, or `imageUrl` could not be downloaded. `success` is false, `errorCode` names the problem (for example `IMAGE_TOO_LARGE`, `IMAGE_FORMAT_UNSUPPORTED`, `IMAGE_RESOLUTION_TOO_LOW`, `IMAGE_DOWNLOAD_FAILED`) and `error` explains it in plain words, with what to fix. Send PDF*, JPG, PNG, WebP or GIF, up to 10 MB, inside our standard of 1344 to 2048 px on the long side. *Only the first page of a PDF is read. A refused request costs nothing. Send `Accept-Language: pt-BR` for the message in Portuguese.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BirthCertificateOcrResponseDto"},"examples":{"resolutionTooLow":{"summary":"IMAGE_RESOLUTION_TOO_LOW: the 800×640 sample without resizeImage","value":{"success":false,"processingTimeMs":35,"error":"The image has 800 px on its long side; our standard is 1,344 to 2,048 px. Send a photo with more resolution, or set resizeImage: true to have it enlarged (1 extra credit).","errorCode":"IMAGE_RESOLUTION_TOO_LOW","data":{"documento":{"tipo":"","órgão_emissor":""},"dados_pessoais":{"nome_completo":"","cpf":"","matrícula":"","data_nascimento":{"texto_completo":"","dia":"","mês":"","ano":""},"hora_nascimento":"","naturalidade":"","sexo":""},"local_nascimento":{"estabelecimento":"","município":"","uf":""},"registro":{"município":"","uf":"","cartório":"","data_registro":"","número_dnv":""},"filiação":{"genitor_1":{"nome_completo":"","naturalidade":""},"genitor_2":{"nome_completo":"","naturalidade":""}},"avós":{"paternos":{"avô":"","avó":""},"maternos":{"avô":"","avó":""}},"gêmeos":{"status":"Não","informações_adicionais":""},"observações":{"averbações":"","anotações":""},"autenticação":{"selo_digital":"","oficial_registro":"","data_emissão":""}},"creditsCharged":0}},"downloadFailed":{"summary":"IMAGE_DOWNLOAD_FAILED: the link answered 404","value":{"success":false,"processingTimeMs":410,"error":"We could not download the image from imageUrl: the link answered HTTP 404 (file not found). Use a public, direct link to a PDF, JPG, PNG, WebP or GIF file that opens without a login, or send the image as imageBase64.","errorCode":"IMAGE_DOWNLOAD_FAILED","data":{"documento":{"tipo":"","órgão_emissor":""},"dados_pessoais":{"nome_completo":"","cpf":"","matrícula":"","data_nascimento":{"texto_completo":"","dia":"","mês":"","ano":""},"hora_nascimento":"","naturalidade":"","sexo":""},"local_nascimento":{"estabelecimento":"","município":"","uf":""},"registro":{"município":"","uf":"","cartório":"","data_registro":"","número_dnv":""},"filiação":{"genitor_1":{"nome_completo":"","naturalidade":""},"genitor_2":{"nome_completo":"","naturalidade":""}},"avós":{"paternos":{"avô":"","avó":""},"maternos":{"avô":"","avó":""}},"gêmeos":{"status":"Não","informações_adicionais":""},"observações":{"averbações":"","anotações":""},"autenticação":{"selo_digital":"","oficial_registro":"","data_emissão":""}},"creditsCharged":0}},"formatUnsupported":{"summary":"IMAGE_FORMAT_UNSUPPORTED: not an image we read","value":{"success":false,"processingTimeMs":35,"error":"The file is not in one of these formats: PDF, JPG, PNG, WebP or GIF. Convert it to one of them and send it again.","errorCode":"IMAGE_FORMAT_UNSUPPORTED","data":{"documento":{"tipo":"","órgão_emissor":""},"dados_pessoais":{"nome_completo":"","cpf":"","matrícula":"","data_nascimento":{"texto_completo":"","dia":"","mês":"","ano":""},"hora_nascimento":"","naturalidade":"","sexo":""},"local_nascimento":{"estabelecimento":"","município":"","uf":""},"registro":{"município":"","uf":"","cartório":"","data_registro":"","número_dnv":""},"filiação":{"genitor_1":{"nome_completo":"","naturalidade":""},"genitor_2":{"nome_completo":"","naturalidade":""}},"avós":{"paternos":{"avô":"","avó":""},"maternos":{"avô":"","avó":""}},"gêmeos":{"status":"Não","informações_adicionais":""},"observações":{"averbações":"","anotações":""},"autenticação":{"selo_digital":"","oficial_registro":"","data_emissão":""}},"creditsCharged":0}}}}}},"429":{"description":"Over one of your plan's limits. `retryAfter` says how many seconds to wait; there is no Retry-After header. A limit per day resets at midnight UTC.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitErrorDto"},"examples":{"perMinute":{"summary":"Too many requests this minute","value":{"statusCode":429,"message":"Organization rate limit exceeded (10 requests per minute). Retry after 6 seconds.","error":"Too Many Requests","retryAfter":6}},"perDay":{"summary":"The day's limit is reached: it resets at midnight UTC","value":{"statusCode":429,"message":"Daily quota exceeded (1000 requests per day). Current usage: 1000","error":"Too Many Requests","retryAfter":43200}}}}}},"503":{"description":"The service is restarting: the proxy answers with an HTML page, and may answer 502 or 504 the same way. Send the same request again after a few seconds, with the same `requestId`, so it is never charged twice.","content":{"text/html":{"schema":{"type":"string"},"example":"<html>\r\n<head><title>503 Service Temporarily Unavailable</title></head>\r\n<body>\r\n<center><h1>503 Service Temporarily Unavailable</h1></center>\r\n<hr><center>nginx</center>\r\n</body>\r\n</html>\r\n"}}}},"security":[{"api-key":[]}],"summary":"Extract data from a birth certificate","tags":["documents"],"x-codeSamples":[{"lang":"Shell","label":"cURL","source":"#!/usr/bin/env bash\n# Your first call: extract the hosted sample certificate (fictitious data).\n# Needs DOCSOCR_API_KEY in the environment; create a key in the panel.\nset -euo pipefail\n\nREQUEST_ID=\"first-call-$(date +%s)-$RANDOM\" # one id per document\n\n# The API answers within 90 s\ncurl -sS --max-time 120 https://api.docsocr.com/api/v1/documents/birth-certificate \\\n  -H \"Authorization: Bearer $DOCSOCR_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  --data-binary @- <<EOF\n{\n  \"imageType\": \"url\",\n  \"imageUrl\": \"https://docsocr.com/samples/certidao-nascimento-exemplo.jpg\",\n  \"requestId\": \"$REQUEST_ID\"\n}\nEOF\n"},{"lang":"Python","label":"Python","source":"\"\"\"Your first call: extract the hosted sample certificate (fictitious data).\n\nNeeds the requests package and DOCSOCR_API_KEY in the environment.\n\"\"\"\nimport os\nimport uuid\n\nimport requests\n\nresponse = requests.post(\n    \"https://api.docsocr.com/api/v1/documents/birth-certificate\",\n    headers={\"Authorization\": f\"Bearer {os.environ['DOCSOCR_API_KEY']}\"},\n    json={\n        \"imageType\": \"url\",\n        \"imageUrl\": \"https://docsocr.com/samples/certidao-nascimento-exemplo.jpg\",\n        \"requestId\": str(uuid.uuid4()),  # one id per document\n    },\n    timeout=120,  # above the API's 90 s extraction budget\n)\nanswer = response.json()\nif response.status_code != 201 or not answer[\"success\"]:\n    raise SystemExit(f\"{response.status_code} {answer.get('errorCode', '')} {answer.get('message') or answer.get('error')}\")\nprint(answer[\"data\"][\"dados_pessoais\"][\"nome_completo\"])\n"},{"lang":"JavaScript","label":"Node.js","source":"// Your first call: extract the hosted sample certificate (fictitious data).\n// Needs Node.js 18+ and DOCSOCR_API_KEY in the environment.\nimport { randomUUID } from 'node:crypto'\n\nconst response = await fetch('https://api.docsocr.com/api/v1/documents/birth-certificate', {\n  method: 'POST',\n  headers: {\n    Authorization: `Bearer ${process.env.DOCSOCR_API_KEY}`,\n    'Content-Type': 'application/json',\n  },\n  body: JSON.stringify({\n    imageType: 'url',\n    imageUrl: 'https://docsocr.com/samples/certidao-nascimento-exemplo.jpg',\n    requestId: randomUUID(), // one id per document\n  }),\n  signal: AbortSignal.timeout(120_000), // above the API's 90 s extraction budget\n})\nconst answer = await response.json()\nif (response.status !== 201 || !answer.success) {\n  console.error(response.status, answer.errorCode ?? '', answer.message ?? answer.error)\n  process.exit(1)\n}\nconsole.log(answer.data.dados_pessoais.nome_completo)\n"},{"lang":"PHP","label":"PHP","source":"<?php\n// Your first call: extract the hosted sample certificate (fictitious data).\n// Needs the curl extension and DOCSOCR_API_KEY in the environment.\n\n$request = curl_init('https://api.docsocr.com/api/v1/documents/birth-certificate');\ncurl_setopt_array($request, [\n    CURLOPT_POST => true,\n    CURLOPT_RETURNTRANSFER => true,\n    CURLOPT_TIMEOUT => 120, // above the API's 90 s extraction budget\n    CURLOPT_HTTPHEADER => [\n        'Authorization: Bearer ' . getenv('DOCSOCR_API_KEY'),\n        'Content-Type: application/json',\n    ],\n    CURLOPT_POSTFIELDS => json_encode([\n        'imageType' => 'url',\n        'imageUrl' => 'https://docsocr.com/samples/certidao-nascimento-exemplo.jpg',\n        'requestId' => bin2hex(random_bytes(16)), // one id per document\n    ]),\n]);\n$body = curl_exec($request);\nif ($body === false) {\n    fwrite(STDERR, curl_error($request) . PHP_EOL);\n    exit(1);\n}\n$status = curl_getinfo($request, CURLINFO_RESPONSE_CODE);\n$answer = json_decode($body, true);\nif ($status !== 201 || empty($answer['success'])) {\n    fwrite(STDERR, \"$status \" . ($answer['errorCode'] ?? '') . ' ' . implode('; ', (array) ($answer['message'] ?? $answer['error'] ?? '')) . PHP_EOL);\n    exit(1);\n}\necho $answer['data']['dados_pessoais']['nome_completo'], PHP_EOL;\n"},{"lang":"Java","label":"Java","source":"// Your first call: extract the hosted sample certificate (fictitious data).\n// Needs Java 17+ and DOCSOCR_API_KEY in the environment. Run: java FirstCall.java\nimport java.net.URI;\nimport java.net.http.HttpClient;\nimport java.net.http.HttpRequest;\nimport java.net.http.HttpResponse;\nimport java.time.Duration;\nimport java.util.UUID;\n\npublic class FirstCall {\n    public static void main(String[] args) throws Exception {\n        String body = \"\"\"\n            {\n              \"imageType\": \"url\",\n              \"imageUrl\": \"https://docsocr.com/samples/certidao-nascimento-exemplo.jpg\",\n              \"requestId\": \"%s\"\n            }\"\"\".formatted(UUID.randomUUID()); // one id per document\n\n        HttpRequest request = HttpRequest.newBuilder(URI.create(\"https://api.docsocr.com/api/v1/documents/birth-certificate\"))\n            .timeout(Duration.ofSeconds(120)) // above the API's 90 s extraction budget\n            .header(\"Authorization\", \"Bearer \" + System.getenv(\"DOCSOCR_API_KEY\"))\n            .header(\"Content-Type\", \"application/json\")\n            .POST(HttpRequest.BodyPublishers.ofString(body))\n            .build();\n        HttpResponse<String> response = HttpClient.newHttpClient().send(request, HttpResponse.BodyHandlers.ofString());\n\n        // The answer is JSON: read data.dados_pessoais.nome_completo with your JSON library\n        System.out.println(response.body());\n        if (response.statusCode() != 201 || !response.body().contains(\"\\\"success\\\":true\")) {\n            System.exit(1);\n        }\n    }\n}\n"},{"lang":"C#","label":"C#","source":"// Your first call: extract the hosted sample certificate (fictitious data).\n// Needs .NET 8+ and DOCSOCR_API_KEY in the environment. Run: dotnet run FirstCall.cs (.NET 10)\nusing System.Net.Http.Headers;\nusing System.Text;\nusing System.Text.Json;\nusing System.Text.Json.Nodes;\n\nusing var http = new HttpClient { Timeout = TimeSpan.FromSeconds(120) }; // above the API's 90 s extraction budget\nhttp.DefaultRequestHeaders.Authorization =\n    new AuthenticationHeaderValue(\"Bearer\", Environment.GetEnvironmentVariable(\"DOCSOCR_API_KEY\"));\n\nvar body = new JsonObject\n{\n    [\"imageType\"] = \"url\",\n    [\"imageUrl\"] = \"https://docsocr.com/samples/certidao-nascimento-exemplo.jpg\",\n    [\"requestId\"] = Guid.NewGuid().ToString(), // one id per document\n};\nusing var content = new StringContent(body.ToJsonString(), Encoding.UTF8, \"application/json\");\nusing var response = await http.PostAsync(\"https://api.docsocr.com/api/v1/documents/birth-certificate\", content);\nusing var answer = JsonDocument.Parse(await response.Content.ReadAsStringAsync());\nvar root = answer.RootElement;\n\nif ((int)response.StatusCode != 201 || !root.GetProperty(\"success\").GetBoolean())\n{\n    Console.Error.WriteLine($\"{(int)response.StatusCode} {root}\");\n    return 1;\n}\nConsole.WriteLine(root.GetProperty(\"data\").GetProperty(\"dados_pessoais\").GetProperty(\"nome_completo\").GetString());\nreturn 0;\n"}]}},"/health":{"get":{"description":"Whether the API is up. No API key needed.","operationId":"getHealth","parameters":[],"responses":{"200":{"description":"API is healthy","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","example":"ok"},"timestamp":{"type":"string","format":"date-time"},"uptime":{"type":"number","example":123.4},"environment":{"type":"string","example":"production"},"loadTestMode":{"type":"boolean","example":false}}}}}},"503":{"description":"API is unhealthy"}},"security":[],"summary":"Basic health check","tags":["health"],"x-codeSamples":[{"lang":"Shell","label":"cURL","source":"#!/usr/bin/env bash\n# Whether the API is up: \"status\": \"ok\" when it is.\n# A public endpoint: no key needed.\nset -euo pipefail\n\ncurl -sS --max-time 30 https://api.docsocr.com/api/v1/health\n"},{"lang":"Python","label":"Python","source":"\"\"\"Whether the API is up: \"status\": \"ok\" when it is.\n\nA public endpoint: no key needed. Needs the requests package.\n\"\"\"\nimport requests\n\nresponse = requests.get(\"https://api.docsocr.com/api/v1/health\", timeout=30)\nresponse.raise_for_status()\nprint(response.json()[\"status\"])\n"},{"lang":"JavaScript","label":"Node.js","source":"// Whether the API is up: \"status\": \"ok\" when it is.\n// A public endpoint: no key needed. Needs Node.js 18+.\nconst response = await fetch('https://api.docsocr.com/api/v1/health', {\n  signal: AbortSignal.timeout(30_000),\n})\nif (!response.ok) {\n  console.error(response.status)\n  process.exit(1)\n}\nconsole.log((await response.json()).status)\n"},{"lang":"PHP","label":"PHP","source":"<?php\n// Whether the API is up: \"status\": \"ok\" when it is.\n// A public endpoint: no key needed. Needs the curl extension.\n\n$request = curl_init('https://api.docsocr.com/api/v1/health');\ncurl_setopt_array($request, [CURLOPT_RETURNTRANSFER => true, CURLOPT_TIMEOUT => 30]);\n$body = curl_exec($request);\nif ($body === false || curl_getinfo($request, CURLINFO_RESPONSE_CODE) !== 200) {\n    fwrite(STDERR, 'The API is not up' . PHP_EOL);\n    exit(1);\n}\necho json_decode($body, true)['status'], PHP_EOL;\n"},{"lang":"Java","label":"Java","source":"// Whether the API is up: \"status\": \"ok\" when it is.\n// A public endpoint: no key needed. Needs Java 17+. Run: java Health.java\nimport java.net.URI;\nimport java.net.http.HttpClient;\nimport java.net.http.HttpRequest;\nimport java.net.http.HttpResponse;\nimport java.time.Duration;\n\npublic class Health {\n    public static void main(String[] args) throws Exception {\n        HttpRequest request = HttpRequest.newBuilder(URI.create(\"https://api.docsocr.com/api/v1/health\"))\n            .timeout(Duration.ofSeconds(30))\n            .GET()\n            .build();\n        HttpResponse<String> response = HttpClient.newHttpClient().send(request, HttpResponse.BodyHandlers.ofString());\n\n        // The answer is JSON, e.g. {\"status\": \"ok\", ...}; read it with your JSON library\n        System.out.println(response.body());\n        if (response.statusCode() != 200) {\n            System.exit(1);\n        }\n    }\n}\n"},{"lang":"C#","label":"C#","source":"// Whether the API is up: \"status\": \"ok\" when it is.\n// A public endpoint: no key needed. Needs .NET 8+. Run: dotnet run Health.cs (.NET 10)\nusing System.Text.Json;\n\nusing var http = new HttpClient { Timeout = TimeSpan.FromSeconds(30) };\nusing var response = await http.GetAsync(\"https://api.docsocr.com/api/v1/health\");\nif (!response.IsSuccessStatusCode)\n{\n    Console.Error.WriteLine((int)response.StatusCode);\n    return 1;\n}\n\nusing var health = JsonDocument.Parse(await response.Content.ReadAsStringAsync());\nConsole.WriteLine(health.RootElement.GetProperty(\"status\").GetString());\nreturn 0;\n"}]}}},"info":{"title":"DocsOCR API","description":"\nExtract the data of a Brazilian birth certificate from a photo, a scan or a PDF, with one request.\n\n- **Your first call:** send the hosted sample certificate, https://docsocr.com/samples/certidao-nascimento-exemplo.jpg (fictitious data), to **POST /documents/birth-certificate**. Its code samples run as they are, in six languages.\n- **Authentication:** `Authorization: Bearer <your API key>`. **[Create a key](https://app.docsocr.com/admin/api-keys)**. Keys start with `dso_live_v1_` or `dso_test_v1_`; both call the engines and use credits.\n- **Prices:** **GET /documents/prices**, without a key. Credits are charged only when the answer carries the certificate's data.\n- **Repeats:** the same `requestId`, file and options within 15 minutes get the same answer at no charge.\n- **Errors:** every refusal says why in `errorCode` and how to fix it in its message. Send `Accept-Language: pt-BR` for Portuguese.\n\nGuides: **[docs.docsocr.com](https://docs.docsocr.com)**.\n","version":"2.2.1","contact":{"name":"DocsOCR support","url":"https://docsocr.com","email":"support@docsocr.com"}},"tags":[{"name":"documents","description":"Extract structured data from document images"},{"name":"health","description":"Check API availability and status"}],"servers":[{"url":"https://api.docsocr.com/api/v1","description":"Production"}],"components":{"securitySchemes":{"api-key":{"type":"http","scheme":"bearer","description":"Your DocsOCR API key, sent as `Authorization: Bearer <key>`. Keys start with `dso_live_v1_` or `dso_test_v1_`; both call the engines and use credits. **[Manage keys](https://app.docsocr.com/admin/api-keys)**"}},"schemas":{"DocumentTypeDto":{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier for the document type","example":"birth-certificate"},"name":{"type":"string","description":"Human-readable name of the document type","example":"Certidão de Nascimento"},"description":{"type":"string","description":"Brief description of the document type","example":"Brazilian birth certificate OCR extraction"},"icon":{"type":"string","description":"Icon emoji for the document type","example":"📜"},"enabled":{"type":"boolean","description":"Whether this document type is currently enabled for processing","example":true},"endpoint":{"type":"string","description":"API endpoint for processing this document type","example":"/documents/birth-certificate"}},"required":["id","name","description","icon","enabled","endpoint"]},"DocumentTypesResponseDto":{"type":"object","properties":{"types":{"description":"List of available document types","type":"array","items":{"$ref":"#/components/schemas/DocumentTypeDto"}}},"required":["types"]},"UnauthorizedErrorDto":{"type":"object","properties":{"error":{"type":"string","description":"Error category (always `Unauthorized`)","example":"Unauthorized"},"message":{"type":"string","description":"What went wrong with the key. **[Manage API keys](https://app.docsocr.com/admin/api-keys)**","example":"Invalid or expired API key"},"timestamp":{"type":"string","description":"When the request was refused, in UTC","example":"2026-10-02T12:00:00.000Z"}},"required":["error","message","timestamp"]},"ExtractionPricesDto":{"type":"object","properties":{"standard":{"type":"number","description":"Credits for an extraction answered by the standard engines: a request without `engine`.","example":1},"fast":{"type":"number","description":"Credits for an extraction answered by the fast engine, when the request asks for it with `engine: \"fast\"`. When fast cannot answer and a standard engine does, the extraction costs `standard`. This price may change: read it here."},"resizeImage":{"type":"number","description":"Extra credits when the server resizes the image into our standard, as `resizeImage: true` asks.","example":1}},"required":["standard","fast","resizeImage"]},"BirthCertificateOcrRequestWithUrl":{"type":"object","properties":{"requestId":{"type":"string","description":"**Required.** Your ID for this request, up to 128 characters: letters, digits, `_`, `-`, `.` and `:`. Put no personal data in it. The same `requestId` with the same file and options within 15 minutes of the answer returns the same answer at no charge, without running the engines; with another file or other options, it is a new request. The answer does not repeat it.","example":"6f1c2a9e-3b7d-4e5f-9a8b-1c2d3e4f5a6b","maxLength":128,"pattern":"^[\\w.:-]+$"},"resizeImage":{"type":"boolean","description":"Resize an image outside our standard (1344 to 2048 px on the long side) to fit it, instead of refusing it: the extraction then costs 1 extra credit, and the answer says `imageResized: true`. The request needs its price plus the resize available while it runs (2 credits on the standard engines). Without it, such an image is refused with 422 and costs nothing. An image inside the standard is never resized and costs the extraction's price either way.","default":false,"example":false},"engine":{"type":"string","description":"Ask for the fast engine: it is tried first, and when it cannot answer, the standard engines follow. Leave it out to use the standard engines. Only `\"fast\"` is accepted; any other value is refused with 400 and costs nothing.","enum":["fast"],"example":"fast"},"imageType":{"type":"string","description":"**Required.** `\"url\"`: the image is at `imageUrl`.","enum":["url"],"example":"url"},"imageUrl":{"type":"string","description":"**Required.** Public URL of the certificate image: a direct link that opens without a login.","example":"https://docsocr.com/samples/certidao-nascimento-exemplo.jpg"}},"required":["requestId","imageType","imageUrl"],"additionalProperties":false},"BirthCertificateOcrRequestWithBase64":{"type":"object","properties":{"requestId":{"type":"string","description":"**Required.** Your ID for this request, up to 128 characters: letters, digits, `_`, `-`, `.` and `:`. Put no personal data in it. The same `requestId` with the same file and options within 15 minutes of the answer returns the same answer at no charge, without running the engines; with another file or other options, it is a new request. The answer does not repeat it.","example":"6f1c2a9e-3b7d-4e5f-9a8b-1c2d3e4f5a6b","maxLength":128,"pattern":"^[\\w.:-]+$"},"resizeImage":{"type":"boolean","description":"Resize an image outside our standard (1344 to 2048 px on the long side) to fit it, instead of refusing it: the extraction then costs 1 extra credit, and the answer says `imageResized: true`. The request needs its price plus the resize available while it runs (2 credits on the standard engines). Without it, such an image is refused with 422 and costs nothing. An image inside the standard is never resized and costs the extraction's price either way.","default":false,"example":false},"engine":{"type":"string","description":"Ask for the fast engine: it is tried first, and when it cannot answer, the standard engines follow. Leave it out to use the standard engines. Only `\"fast\"` is accepted; any other value is refused with 400 and costs nothing.","enum":["fast"],"example":"fast"},"imageType":{"type":"string","description":"**Required.** `\"base64\"`: the image is in `imageBase64`.","enum":["base64"],"example":"base64"},"imageBase64":{"type":"string","description":"**Required.** The certificate file in base64, with or without the data URI prefix, e.g. `data:image/jpeg;base64,/9j/4AAQ...`. PDF*, JPG, PNG, WebP or GIF, up to 10 MB; the type is read from the file itself. *Only the first page of a PDF is read.","example":"data:image/jpeg;base64,/9j/4AAQSkZJRgABAQAAAQABAAD/2wBDAAgGBgcG..."}},"required":["requestId","imageType","imageBase64"],"additionalProperties":false},"DocumentoDto":{"type":"object","properties":{"tipo":{"type":"string","description":"Document type","example":"Certidão de Nascimento"},"órgão_emissor":{"type":"string","description":"Issuing authority","example":"Cartório Civil"}},"required":["tipo","órgão_emissor"]},"DataNascimentoDto":{"type":"object","properties":{"texto_completo":{"type":"string","description":"Complete birth date text","example":"Primeiro de Janeiro de Dois Mil"},"dia":{"type":"string","description":"Day of birth","example":"01"},"mês":{"type":"string","description":"Month of birth","example":"01"},"ano":{"type":"string","description":"Year of birth","example":"2000"}},"required":["texto_completo","dia","mês","ano"]},"DadosPessoaisDto":{"type":"object","properties":{"nome_completo":{"type":"string","description":"**Full name** as written on the certificate.","example":"João Pedro da Silva Santos"},"cpf":{"type":"string","description":"**CPF number** (Brazilian tax ID). Format: `XXX.XXX.XXX-XX`","example":"123.456.789-00"},"matrícula":{"type":"string","description":"**Registration number** (*matrícula*) — the unique certificate identifier.","example":"123456 01 55 2000 1 00012 034 0001234-56"},"data_nascimento":{"description":"Birth date details (day, month, year, full text).","allOf":[{"$ref":"#/components/schemas/DataNascimentoDto"}]},"hora_nascimento":{"type":"string","description":"Time of birth in 24-hour format.","example":"13:45"},"naturalidade":{"type":"string","description":"Place of birth — city name.","example":"São Paulo"},"sexo":{"type":"string","description":"Gender as written on the certificate.","example":"Masculino"}},"required":["nome_completo","cpf","matrícula","data_nascimento","hora_nascimento","naturalidade","sexo"]},"LocalNascimentoDto":{"type":"object","properties":{"estabelecimento":{"type":"string","description":"Birth establishment","example":"Hospital São Luiz"},"município":{"type":"string","description":"Municipality of birth","example":"São Paulo"},"uf":{"type":"string","description":"State/province of birth","example":"SP"}},"required":["estabelecimento","município","uf"]},"RegistroDto":{"type":"object","properties":{"município":{"type":"string","description":"Municipality of registration","example":"São Paulo"},"uf":{"type":"string","description":"State/province of registration","example":"SP"},"cartório":{"type":"string","description":"Registry office","example":"Cartório do 1º Ofício"},"data_registro":{"type":"string","description":"Registration date","example":"15/01/2000"},"número_dnv":{"type":"string","description":"Live birth declaration number","example":"12345678"},"livro":{"type":"string","description":"Book (livro) of the registration: as printed on older certificates, else taken from the 32-digit matrícula","example":"345"},"folha":{"type":"string","description":"Page (folha) of the registration: as printed on older certificates, else taken from the 32-digit matrícula","example":"210"},"termo":{"type":"string","description":"Entry (termo) of the registration: as printed on older certificates, else taken from the 32-digit matrícula","example":"4567"}},"required":["município","uf","cartório","data_registro","número_dnv"]},"GenitorDto":{"type":"object","properties":{"nome_completo":{"type":"string","description":"Full name","example":"José da Silva"},"naturalidade":{"type":"string","description":"Place of birth","example":"Rio de Janeiro"}},"required":["nome_completo","naturalidade"]},"FiliacaoDto":{"type":"object","properties":{"genitor_1":{"description":"The parent printed first on the certificate (the order as printed; no gender implied)","allOf":[{"$ref":"#/components/schemas/GenitorDto"}]},"genitor_2":{"description":"The parent printed second on the certificate (the order as printed; no gender implied)","allOf":[{"$ref":"#/components/schemas/GenitorDto"}]}},"required":["genitor_1","genitor_2"]},"AvosParentescoDto":{"type":"object","properties":{"avô":{"type":"string","description":"Grandfather's name","example":"José da Silva"},"avó":{"type":"string","description":"Grandmother's name","example":"Ana da Silva"}},"required":["avô","avó"]},"AvosDto":{"type":"object","properties":{"paternos":{"description":"Paternal grandparents","allOf":[{"$ref":"#/components/schemas/AvosParentescoDto"}]},"maternos":{"description":"Maternal grandparents","allOf":[{"$ref":"#/components/schemas/AvosParentescoDto"}]}},"required":["paternos","maternos"]},"GemeosDto":{"type":"object","properties":{"status":{"type":"string","description":"Twin status","example":"Não"},"informações_adicionais":{"type":"string","description":"Additional twin information","example":""}},"required":["status","informações_adicionais"]},"ObservacoesDto":{"type":"object","properties":{"averbações":{"type":"string","description":"Amendments to the registration","example":""},"anotações":{"type":"string","description":"Additional notes","example":""}},"required":["averbações","anotações"]},"AutenticacaoDto":{"type":"object","properties":{"selo_digital":{"type":"string","description":"Digital seal","example":"ABC123XYZ"},"oficial_registro":{"type":"string","description":"Registry official","example":"Maria Oliveira"},"data_emissão":{"type":"string","description":"Issue date","example":"20/01/2000"}},"required":["selo_digital","oficial_registro","data_emissão"]},"DocumentoEstruturaDto":{"type":"object","properties":{"documento":{"description":"Document information","allOf":[{"$ref":"#/components/schemas/DocumentoDto"}]},"dados_pessoais":{"description":"Personal data","allOf":[{"$ref":"#/components/schemas/DadosPessoaisDto"}]},"local_nascimento":{"description":"Birth location","allOf":[{"$ref":"#/components/schemas/LocalNascimentoDto"}]},"registro":{"description":"Registration information","allOf":[{"$ref":"#/components/schemas/RegistroDto"}]},"filiação":{"description":"Filiation information","allOf":[{"$ref":"#/components/schemas/FiliacaoDto"}]},"avós":{"description":"Grandparents information","allOf":[{"$ref":"#/components/schemas/AvosDto"}]},"gêmeos":{"description":"Twin information","allOf":[{"$ref":"#/components/schemas/GemeosDto"}]},"observações":{"description":"Observations and notes","allOf":[{"$ref":"#/components/schemas/ObservacoesDto"}]},"autenticação":{"description":"Authentication information","allOf":[{"$ref":"#/components/schemas/AutenticacaoDto"}]}},"required":["documento","dados_pessoais","local_nascimento","registro","filiação","avós","gêmeos","observações","autenticação"]},"ImageSizeDto":{"type":"object","properties":{"width":{"type":"number","description":"Width, in pixels.","example":4000},"height":{"type":"number","description":"Height, in pixels.","example":3000}},"required":["width","height"]},"BirthCertificateOcrResponseDto":{"type":"object","properties":{"success":{"type":"boolean","description":"`true` if extraction succeeded. Check `error` field if `false`.","example":true},"error":{"type":"string","description":"What went wrong. *Only present when success is false.*","example":"The extraction service is busy. Please retry in a few moments. No credit was charged."},"errorCode":{"type":"string","description":"Why the extraction failed, as a code you can handle in your code. `error` explains it in plain words. *Only present when success is false.*","enum":["IMAGE_MISSING","IMAGE_BASE64_INVALID","IMAGE_TOO_LARGE","IMAGE_TOO_MANY_PIXELS","IMAGE_FORMAT_UNSUPPORTED","IMAGE_UNREADABLE","IMAGE_URL_NOT_ALLOWED","IMAGE_RESOLUTION_TOO_LOW","IMAGE_RESOLUTION_TOO_HIGH","IMAGE_INVALID","PDF_PASSWORD_PROTECTED","PDF_UNREADABLE","PDF_TOO_MANY_PAGES","IMAGE_DOWNLOAD_FAILED","IMAGE_NOT_PROCESSABLE","DOCUMENT_NOT_RECOGNIZED","EXTRACTION_TIMEOUT","EXTRACTION_BUSY","EXTRACTION_UNAVAILABLE"],"example":"EXTRACTION_BUSY"},"processingTimeMs":{"type":"number","description":"How long the extraction took, in milliseconds.","example":1847},"data":{"description":"**Extracted certificate data.** Contains all fields found in the document — name, birth date, parents, registration info, and more. When `success` is false, every field is empty.","allOf":[{"$ref":"#/components/schemas/DocumentoEstruturaDto"}]},"imageResized":{"type":"boolean","description":"`true` when the image was outside our standard (1344 to 2048 px on the long side) and was resized to fit it, as `resizeImage` asked: the extraction cost 1 extra credit. *Only present when it happened.*","example":true},"originalImageSize":{"description":"Size of the image as you sent it, upright. *Only present when imageResized is true.*","allOf":[{"$ref":"#/components/schemas/ImageSizeDto"}]},"finalImageSize":{"description":"Size of the image once resized to our standard. *Only present when imageResized is true.*","allOf":[{"$ref":"#/components/schemas/ImageSizeDto"}]},"engine":{"type":"string","description":"The engine that answered with data: `fast` when the request asked for it and fast answered, or `mini` or `large` for the standard engines. *Only present when an engine answered.*","enum":["mini","large","fast"],"example":"fast"},"creditsCharged":{"type":"number","description":"Credits this request cost, to the hundredth: the price of the engine that answered (never more than the engine you asked for), plus the resize. 0 when nothing was charged: a refused image, no engine could answer, or a repeat answered from its kept answer (`Idempotent-Replayed: true`).","example":1}},"required":["success","processingTimeMs","creditsCharged"]},"ValidationErrorDto":{"type":"object","properties":{"statusCode":{"type":"number","description":"HTTP status code (always 400)","example":400},"message":{"description":"**What to fix**, one line per problem","example":["imageUrl is required when imageType is \"url\""],"type":"array","items":{"type":"string"}},"error":{"type":"string","description":"Error category","example":"Bad Request"}},"required":["statusCode","message","error"]},"PaymentRequiredErrorDto":{"type":"object","properties":{"statusCode":{"type":"number","description":"HTTP status code (always 402)","example":402},"message":{"type":"string","description":"The request's price and the balance, with what to do. Send `Accept-Language: pt-BR` for it in Portuguese.","example":"This request costs 1 credit, and the available balance is 0 credits. Buy credits or upgrade your plan to continue."},"error":{"type":"string","description":"Error category","example":"Payment Required"},"errorCode":{"type":"string","description":"Always `NOT_ENOUGH_CREDITS`","example":"NOT_ENOUGH_CREDITS"},"action":{"type":"string","description":"What to do: buy credits or change the plan","example":"purchase_credits"},"creditsAvailable":{"type":"number","description":"Credits the organization can use now, to the hundredth","example":0},"creditsRequired":{"type":"number","description":"The request's price, which it holds while it runs","example":1},"planCreditsRemaining":{"type":"number","description":"Credits left in the plan's monthly allowance","example":0},"purchasedCreditsRemaining":{"type":"number","description":"Credits left from purchases","example":0}},"required":["statusCode","message","error","errorCode","action","creditsAvailable","creditsRequired","planCreditsRemaining","purchasedCreditsRemaining"]},"RequestInProgressErrorDto":{"type":"object","properties":{"statusCode":{"type":"number","description":"HTTP status code (always 409)","example":409},"message":{"type":"string","description":"What to do — *human-readable*","example":"A request with this requestId and the same content is still being processed. Try again in a few seconds to get its answer, at no charge."},"error":{"type":"string","description":"Error category","example":"Conflict"},"errorCode":{"type":"string","description":"Always `REQUEST_IN_PROGRESS`","example":"REQUEST_IN_PROGRESS"},"retryAfter":{"type":"number","description":"Seconds to wait before sending the request again","example":5}},"required":["statusCode","message","error","errorCode","retryAfter"]},"PayloadTooLargeErrorDto":{"type":"object","properties":{"success":{"type":"boolean","description":"Always `false`","example":false},"errorCode":{"type":"string","description":"Always `IMAGE_TOO_LARGE`","example":"IMAGE_TOO_LARGE"},"error":{"type":"string","description":"What to send instead. `Accept-Language: pt-BR` gets it in Portuguese.","example":"The image is larger than 10 MB. Send a smaller image, for example a JPG with lower resolution or quality."},"processingTimeMs":{"type":"number","description":"Always 0: no work was done","example":0}},"required":["success","errorCode","error","processingTimeMs"]},"RateLimitErrorDto":{"type":"object","properties":{"statusCode":{"type":"number","description":"HTTP status code (always 429)","example":429},"message":{"type":"string","description":"Which limit you hit, and its size. **[View usage](https://app.docsocr.com/admin/analytics)**","example":"Organization rate limit exceeded (10 requests per minute). Retry after 6 seconds."},"error":{"type":"string","description":"Error category","example":"Too Many Requests"},"retryAfter":{"type":"number","description":"**Seconds to wait** before sending the request again. A limit per day lasts until midnight UTC, so its wait can be hours.","example":6}},"required":["statusCode","message","error","retryAfter"]}}},"security":[{"api-key":[]}]}