Extract data from a birth certificate

POST /documents/birth-certificate

What it does: extracts every field of a Brazilian birth certificate from a photo, a scan or a PDF.

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).

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.

The fast engine: "engine": "fast" asks for it. It is tried first, and the standard engines follow if it cannot answer.

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.

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.

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

Authentication

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

Parameters

accept-language header "en" or "pt-BR", default "en" Optional
The language of the messages in refusals and errors: pt-BR for Portuguese, English otherwise.

Request body

The certificate image, at a public URL or in base64: imageType says which.

Content-Type: application/json

imageType "url" or "base64" Required
"url": the image is at imageUrl. "base64": the image is in imageBase64.
requestId string 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.
imageUrl string With imageType: "url"
Public URL of the certificate image: a direct link that opens without a login.
imageBase64 string With imageType: "base64"
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.
resizeImage boolean, default false Optional
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.
engine "fast" Optional
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.

Examples

The hosted sample certificate (fictitious data)A file in base64 (cut short here)An image below our standard, resized for 1 extra creditAsking for the fast engine

json

{
  "imageType": "url",
  "imageUrl": "https://docsocr.com/samples/certidao-nascimento-exemplo.jpg",
  "requestId": "6f1c2a9e-3b7d-4e5f-9a8b-1c2d3e4f5a6b"
}

json

{
  "imageType": "base64",
  "imageBase64": "data:image/jpeg;base64,/9j/4AAQSkZJRgABAQAAAQABAAD/2wBDAAgGBgcG...",
  "requestId": "0b9d4c7e-58a1-4f2b-8c3d-6e7f8a9b0c1d"
}

json

{
  "imageType": "url",
  "imageUrl": "https://docsocr.com/samples/certidao-nascimento-exemplo-800x640.jpg",
  "requestId": "9a8b7c6d-5e4f-4a3b-9c2d-1e0f9a8b7c6d",
  "resizeImage": true
}

json

{
  "imageType": "url",
  "imageUrl": "https://docsocr.com/samples/certidao-nascimento-exemplo.jpg",
  "requestId": "3c4d5e6f-7a8b-4c9d-8e0f-1a2b3c4d5e6f",
  "engine": "fast"
}

Responses

201 Created

The certificate's data. With success: false, no engine could answer: errorCode says why, and nothing was charged.

Idempotent-Replayed header
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.

Response fields

success boolean
true if extraction succeeded. Check error field if false.
error string
What went wrong. Only present when success is false.
errorCode "IMAGE_MISSING" or "IMAGE_BASE64_INVALID" or "IMAGE_TOO_LARGE" or "IMAGE_TOO_MANY_PIXELS" or "IMAGE_FORMAT_UNSUPPORTED" or "IMAGE_UNREADABLE" or "IMAGE_URL_NOT_ALLOWED" or "IMAGE_RESOLUTION_TOO_LOW" or "IMAGE_RESOLUTION_TOO_HIGH" or "IMAGE_INVALID" or "PDF_PASSWORD_PROTECTED" or "PDF_UNREADABLE" or "PDF_TOO_MANY_PAGES" or "IMAGE_DOWNLOAD_FAILED" or "IMAGE_NOT_PROCESSABLE" or "DOCUMENT_NOT_RECOGNIZED" or "EXTRACTION_TIMEOUT" or "EXTRACTION_BUSY" or "EXTRACTION_UNAVAILABLE"
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.
processingTimeMs number
How long the extraction took, in milliseconds.
data object
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.
imageResized boolean
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.
originalImageSize object
Size of the image as you sent it, upright. Only present when imageResized is true.
originalImageSize.width number
Width, in pixels.
originalImageSize.height number
Height, in pixels.
finalImageSize object
Size of the image once resized to our standard. Only present when imageResized is true.
finalImageSize.width number
Width, in pixels.
finalImageSize.height number
Height, in pixels.
engine "mini" or "large" or "fast"
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.
creditsCharged number
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).

The sample certificate, answered by a standard engineThe 800×640 sample with resizeImage: trueNo engine could answer: nothing charged, send it again laterNot a birth certificate: nothing charged, do not retry

json

{
  "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
}

json

{
  "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
}

json

{
  "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
}

json

{
  "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 Bad Request

The body is not valid: message lists what to fix. Nothing was charged.

Response fields

statusCode number
HTTP status code (always 400)
message string[]
What to fix, one line per problem
error string
Error category

A field is missing or wrong

json

{
  "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 Unauthorized

The API key is missing, malformed, unknown, revoked or expired.

Response fields

error string
Error category (always Unauthorized)
message string
What went wrong with the key. Manage API keys
timestamp string
When the request was refused, in UTC

A key that is unknown, revoked or expiredNo key

json

{
  "error": "Unauthorized",
  "message": "Invalid or expired API key",
  "timestamp": "2026-10-02T12:00:00.000Z"
}

json

{
  "error": "Unauthorized",
  "message": "API key is required. Provide Authorization: Bearer <your-api-key>",
  "timestamp": "2026-10-02T12:00:00.000Z"
}

402 Payment Required

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.

Response fields

statusCode number
HTTP status code (always 402)
message string
The request's price and the balance, with what to do. Send Accept-Language: pt-BR for it in Portuguese.
error string
Error category
errorCode string
Always NOT_ENOUGH_CREDITS
action string
What to do: buy credits or change the plan
creditsAvailable number
Credits the organization can use now, to the hundredth
creditsRequired number
The request's price, which it holds while it runs
planCreditsRemaining number
Credits left in the plan's monthly allowance
purchasedCreditsRemaining number
Credits left from purchases

The balance cannot pay the request

json

{
  "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 Conflict

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.

Retry-After header
Seconds to wait before sending it again, as retryAfter

Response fields

statusCode number
HTTP status code (always 409)
message string
What to do — human-readable
error string
Error category
errorCode string
Always REQUEST_IN_PROGRESS
retryAfter number
Seconds to wait before sending the request again

The same request is still running

json

{
  "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 Payload Too Large

The request body is over 15 MB: errorCode IMAGE_TOO_LARGE. Nothing was charged.

Response fields

success boolean
Always false
errorCode string
Always IMAGE_TOO_LARGE
error string
What to send instead. Accept-Language: pt-BR gets it in Portuguese.
processingTimeMs number
Always 0: no work was done

The body is over the limit

json

{
  "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 Unprocessable Entity

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.

Response fields

success boolean
true if extraction succeeded. Check error field if false.
error string
What went wrong. Only present when success is false.
errorCode "IMAGE_MISSING" or "IMAGE_BASE64_INVALID" or "IMAGE_TOO_LARGE" or "IMAGE_TOO_MANY_PIXELS" or "IMAGE_FORMAT_UNSUPPORTED" or "IMAGE_UNREADABLE" or "IMAGE_URL_NOT_ALLOWED" or "IMAGE_RESOLUTION_TOO_LOW" or "IMAGE_RESOLUTION_TOO_HIGH" or "IMAGE_INVALID" or "PDF_PASSWORD_PROTECTED" or "PDF_UNREADABLE" or "PDF_TOO_MANY_PAGES" or "IMAGE_DOWNLOAD_FAILED" or "IMAGE_NOT_PROCESSABLE" or "DOCUMENT_NOT_RECOGNIZED" or "EXTRACTION_TIMEOUT" or "EXTRACTION_BUSY" or "EXTRACTION_UNAVAILABLE"
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.
processingTimeMs number
How long the extraction took, in milliseconds.
data object
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.
imageResized boolean
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.
originalImageSize object
Size of the image as you sent it, upright. Only present when imageResized is true.
originalImageSize.width number
Width, in pixels.
originalImageSize.height number
Height, in pixels.
finalImageSize object
Size of the image once resized to our standard. Only present when imageResized is true.
finalImageSize.width number
Width, in pixels.
finalImageSize.height number
Height, in pixels.
engine "mini" or "large" or "fast"
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.
creditsCharged number
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).

IMAGE_RESOLUTION_TOO_LOW: the 800×640 sample without resizeImageIMAGE_DOWNLOAD_FAILED: the link answered 404IMAGE_FORMAT_UNSUPPORTED: not an image we read

json

{
  "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
}

json

{
  "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
}

json

{
  "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 Too Many Requests

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.

Response fields

statusCode number
HTTP status code (always 429)
message string
Which limit you hit, and its size. View usage
error string
Error category
retryAfter number
Seconds to wait before sending the request again. A limit per day lasts until midnight UTC, so its wait can be hours.

Too many requests this minuteThe day's limit is reached: it resets at midnight UTC

json

{
  "statusCode": 429,
  "message": "Organization rate limit exceeded (10 requests per minute). Retry after 6 seconds.",
  "error": "Too Many Requests",
  "retryAfter": 6
}

json

{
  "statusCode": 429,
  "message": "Daily quota exceeded (1000 requests per day). Current usage: 1000",
  "error": "Too Many Requests",
  "retryAfter": 43200
}

503 Service Unavailable

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.

503

html

<html>
<head><title>503 Service Temporarily Unavailable</title></head>
<body>
<center><h1>503 Service Temporarily Unavailable</h1></center>
<hr><center>nginx</center>
</body>
</html>

errorCode values

The errorCode of an answer without data says why, as a code your system can handle. This operation's values:

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
NOT_ENOUGH_CREDITS
REQUEST_IN_PROGRESS

bash

#!/usr/bin/env bash
# Your first call: extract the hosted sample certificate (fictitious data).
# Needs DOCSOCR_API_KEY in the environment; create a key in the panel.
set -euo pipefail

REQUEST_ID="first-call-$(date +%s)-$RANDOM" # one id per document

# The API answers within 90 s
curl -sS --max-time 120 https://api.docsocr.com/api/v1/documents/birth-certificate \
  -H "Authorization: Bearer $DOCSOCR_API_KEY" \
  -H "Content-Type: application/json" \
  --data-binary @- <<EOF
{
  "imageType": "url",
  "imageUrl": "https://docsocr.com/samples/certidao-nascimento-exemplo.jpg",
  "requestId": "$REQUEST_ID"
}
EOF

python

"""Your first call: extract the hosted sample certificate (fictitious data).

Needs the requests package and DOCSOCR_API_KEY in the environment.
"""
import os
import uuid

import requests

response = requests.post(
    "https://api.docsocr.com/api/v1/documents/birth-certificate",
    headers={"Authorization": f"Bearer {os.environ['DOCSOCR_API_KEY']}"},
    json={
        "imageType": "url",
        "imageUrl": "https://docsocr.com/samples/certidao-nascimento-exemplo.jpg",
        "requestId": str(uuid.uuid4()),  # one id per document
    },
    timeout=120,  # above the API's 90 s extraction budget
)
answer = response.json()
if response.status_code != 201 or not answer["success"]:
    raise SystemExit(f"{response.status_code} {answer.get('errorCode', '')} {answer.get('message') or answer.get('error')}")
print(answer["data"]["dados_pessoais"]["nome_completo"])

// Your first call: extract the hosted sample certificate (fictitious data).
// Needs Node.js 18+ and DOCSOCR_API_KEY in the environment.
import { randomUUID } from 'node:crypto'

const response = await fetch('https://api.docsocr.com/api/v1/documents/birth-certificate', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.DOCSOCR_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    imageType: 'url',
    imageUrl: 'https://docsocr.com/samples/certidao-nascimento-exemplo.jpg',
    requestId: randomUUID(), // one id per document
  }),
  signal: AbortSignal.timeout(120_000), // above the API's 90 s extraction budget
})
const answer = await response.json()
if (response.status !== 201 || !answer.success) {
  console.error(response.status, answer.errorCode ?? '', answer.message ?? answer.error)
  process.exit(1)
}
console.log(answer.data.dados_pessoais.nome_completo)

php

<?php
// Your first call: extract the hosted sample certificate (fictitious data).
// Needs the curl extension and DOCSOCR_API_KEY in the environment.

$request = curl_init('https://api.docsocr.com/api/v1/documents/birth-certificate');
curl_setopt_array($request, [
    CURLOPT_POST => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_TIMEOUT => 120, // above the API's 90 s extraction budget
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . getenv('DOCSOCR_API_KEY'),
        'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS => json_encode([
        'imageType' => 'url',
        'imageUrl' => 'https://docsocr.com/samples/certidao-nascimento-exemplo.jpg',
        'requestId' => bin2hex(random_bytes(16)), // one id per document
    ]),
]);
$body = curl_exec($request);
if ($body === false) {
    fwrite(STDERR, curl_error($request) . PHP_EOL);
    exit(1);
}
$status = curl_getinfo($request, CURLINFO_RESPONSE_CODE);
$answer = json_decode($body, true);
if ($status !== 201 || empty($answer['success'])) {
    fwrite(STDERR, "$status " . ($answer['errorCode'] ?? '') . ' ' . implode('; ', (array) ($answer['message'] ?? $answer['error'] ?? '')) . PHP_EOL);
    exit(1);
}
echo $answer['data']['dados_pessoais']['nome_completo'], PHP_EOL;

java

// Your first call: extract the hosted sample certificate (fictitious data).
// Needs Java 17+ and DOCSOCR_API_KEY in the environment. Run: java FirstCall.java
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.time.Duration;
import java.util.UUID;

public class FirstCall {
    public static void main(String[] args) throws Exception {
        String body = """
            {
              "imageType": "url",
              "imageUrl": "https://docsocr.com/samples/certidao-nascimento-exemplo.jpg",
              "requestId": "%s"
            }""".formatted(UUID.randomUUID()); // one id per document

        HttpRequest request = HttpRequest.newBuilder(URI.create("https://api.docsocr.com/api/v1/documents/birth-certificate"))
            .timeout(Duration.ofSeconds(120)) // above the API's 90 s extraction budget
            .header("Authorization", "Bearer " + System.getenv("DOCSOCR_API_KEY"))
            .header("Content-Type", "application/json")
            .POST(HttpRequest.BodyPublishers.ofString(body))
            .build();
        HttpResponse<String> response = HttpClient.newHttpClient().send(request, HttpResponse.BodyHandlers.ofString());

        // The answer is JSON: read data.dados_pessoais.nome_completo with your JSON library
        System.out.println(response.body());
        if (response.statusCode() != 201 || !response.body().contains("\"success\":true")) {
            System.exit(1);
        }
    }
}

csharp

// Your first call: extract the hosted sample certificate (fictitious data).
// Needs .NET 8+ and DOCSOCR_API_KEY in the environment. Run: dotnet run FirstCall.cs (.NET 10)
using System.Net.Http.Headers;
using System.Text;
using System.Text.Json;
using System.Text.Json.Nodes;

using var http = new HttpClient { Timeout = TimeSpan.FromSeconds(120) }; // above the API's 90 s extraction budget
http.DefaultRequestHeaders.Authorization =
    new AuthenticationHeaderValue("Bearer", Environment.GetEnvironmentVariable("DOCSOCR_API_KEY"));

var body = new JsonObject
{
    ["imageType"] = "url",
    ["imageUrl"] = "https://docsocr.com/samples/certidao-nascimento-exemplo.jpg",
    ["requestId"] = Guid.NewGuid().ToString(), // one id per document
};
using var content = new StringContent(body.ToJsonString(), Encoding.UTF8, "application/json");
using var response = await http.PostAsync("https://api.docsocr.com/api/v1/documents/birth-certificate", content);
using var answer = JsonDocument.Parse(await response.Content.ReadAsStringAsync());
var root = answer.RootElement;

if ((int)response.StatusCode != 201 || !root.GetProperty("success").GetBoolean())
{
    Console.Error.WriteLine($"{(int)response.StatusCode} {root}");
    return 1;
}
Console.WriteLine(root.GetProperty("data").GetProperty("dados_pessoais").GetProperty("nome_completo").GetString());
return 0;

Try it

Sends this request to the production API, with your key.

API key

The key stays in this browser tab only, and goes only to the API. Create a key in the panel

Message language (Accept-Language)

Body (JSON)

Reading the prices…

Paste your API key to send.

Answer 201

json

{
  "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
}

Extract data from a birth certificate ​

Authentication ​

Parameters ​

Request body ​

Examples ​

Responses ​

201 Created ​

400 Bad Request ​

401 Unauthorized ​

402 Payment Required ​

409 Conflict ​

413 Payload Too Large ​

422 Unprocessable Entity ​

429 Too Many Requests ​

503 Service Unavailable ​

errorCode values ​

Try it

Extract data from a birth certificate

Authentication

Parameters

Request body

Examples

Responses

201 Created

400 Bad Request

401 Unauthorized

402 Payment Required

409 Conflict

413 Payload Too Large

422 Unprocessable Entity

429 Too Many Requests

503 Service Unavailable

errorCode values