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, at the resize's price; 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). A value that cannot be right, such as a CPF whose check digits do not match, comes as it was read, with a warning in warnings. When the image is not a birth certificate, when nothing can be read from it or when no engine can answer, the status is still 201, with success: false, an errorCode and nothing charged: DOCUMENT_NOT_RECOGNIZED (another document, or an image with nothing to read) and IMAGE_NOT_PROCESSABLE need another image; EXTRACTION_BUSY, EXTRACTION_TIMEOUT and EXTRACTION_UNAVAILABLE may pass when you send the same request again later.
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: an answer with data costs the price of the engine that answers it, as GET /documents/prices lists it for each document: without engine, never more than the dearer of the standard engines; with "engine": "fast", never more than fast's. 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-languageThe language of the messages in refusals, errors and warnings:
pt-BRfor Portuguese, English otherwise.
Request body
The certificate image, at a public URL or in base64: imageType says which.
Content-Type: application/json
imageType"url": the image is atimageUrl."base64": the image is inimageBase64.requestIdYour ID for this request, up to 128 characters: letters, digits,
_,-,.and:. Put no personal data in it. The samerequestIdwith 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.imageUrlPublic URL of the certificate image: a direct link that opens without a login.
imageBase64The 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.resizeImageResize an image outside our standard (1344 to 2048 px on the long side) to fit it, instead of refusing it: the resize's price is then added to the extraction's, and the answer says
imageResized: true. The request needs both prices available while it runs (GET /documents/priceslists them for each document). 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.engineAsk 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
{
"imageType": "url",
"imageUrl": "https://docsocr.com/samples/certidao-nascimento-exemplo.jpg",
"requestId": "6f1c2a9e-3b7d-4e5f-9a8b-1c2d3e4f5a6b"
}{
"imageType": "base64",
"imageBase64": "data:image/jpeg;base64,/9j/4AAQSkZJRgABAQAAAQABAAD/2wBDAAgGBgcG...",
"requestId": "0b9d4c7e-58a1-4f2b-8c3d-6e7f8a9b0c1d"
}{
"imageType": "url",
"imageUrl": "https://docsocr.com/samples/certidao-nascimento-exemplo-800x640.jpg",
"requestId": "9a8b7c6d-5e4f-4a3b-9c2d-1e0f9a8b7c6d",
"resizeImage": true
}{
"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-Replayedtruewhen the answer is the one kept for a repeat: the same answer as the first time, at no charge, without the engines. Absent otherwise.X-RateLimit-LimitThe size of the request limit closest to refusing: per minute, per hour or per day
X-RateLimit-RemainingRequests left in that limit now
X-RateLimit-ResetSeconds until
X-RateLimit-Remaininggoes up; 0 when nothing is counted
Response fields
successtrueif extraction succeeded. Checkerrorfield iffalse.errorWhat went wrong. Only present when success is false.
errorCodeWhy the extraction failed, as a code you can handle in your code.
errorexplains it in plain words. Only present when success is false.processingTimeMsHow long the extraction took, in milliseconds.
dataExtracted certificate data. Contains all fields found in the document — name, birth date, parents, registration info, and more. When
successis false, every field is empty.warningsValues of
datato check on the document. A value that cannot be right, such as a CPF whose check digits do not match, comes as it was read, with a warning here; the request is charged as any other. Only present when there is one.warnings[].codeWhat is wrong with the value, as a code you can handle in your code.
warnings[].fieldThe field of
datait is about, as a dotted path.warnings[].messageWhat is wrong and what to do, in plain words.
imageResizedtruewhen the image was outside our standard (1344 to 2048 px on the long side) and was resized to fit it, asresizeImageasked: the resize's price was added to the extraction's. Only present when it happened.originalImageSizeSize of the image as you sent it, upright. Only present when imageResized is true.
originalImageSize.widthWidth, in pixels.
originalImageSize.heightHeight, in pixels.
finalImageSizeSize of the image once resized to our standard. Only present when imageResized is true.
finalImageSize.widthWidth, in pixels.
finalImageSize.heightHeight, in pixels.
engineThe engine that answered with data:
miniorlargefor the standard engines, orfastwhen the request asked for it and fast answered. Only present when an engine answered.creditsChargedCredits 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).
{
"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
}{
"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
}{
"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-00",
"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"
}
},
"warnings": [
{
"code": "INVALID_CPF",
"field": "dados_pessoais.cpf",
"message": "The value read is not a valid CPF: it is returned as read. Check it on the document."
}
],
"engine": "mini",
"creditsCharged": 1
}{
"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
}{
"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
}{
"success": false,
"processingTimeMs": 2410,
"error": "The image shows a marriage certificate, which this endpoint does not read. Send it to POST /documents/marriage-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.
X-RateLimit-LimitThe size of the request limit closest to refusing: per minute, per hour or per day
X-RateLimit-RemainingRequests left in that limit now
X-RateLimit-ResetSeconds until
X-RateLimit-Remaininggoes up; 0 when nothing is counted
Response fields
statusCodeHTTP status code (always 400)
messageWhat to fix, one line per problem
errorError category
{
"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
errorError category (always
Unauthorized)messageWhat went wrong with the key. Manage API keys
timestampWhen the request was refused, in UTC
{
"error": "Unauthorized",
"message": "Invalid or expired API key",
"timestamp": "2026-10-02T12:00:00.000Z"
}{
"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 the resize's 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.
X-RateLimit-LimitThe size of the request limit closest to refusing: per minute, per hour or per day
X-RateLimit-RemainingRequests left in that limit now
X-RateLimit-ResetSeconds until
X-RateLimit-Remaininggoes up; 0 when nothing is counted
Response fields
statusCodeHTTP status code (always 402)
messageThe request's price and the balance, with what to do. Send
Accept-Language: pt-BRfor it in Portuguese.errorError category
errorCodeAlways
NOT_ENOUGH_CREDITSactionWhat to do: buy credits or change the plan
creditsAvailableCredits the organization can use now, to the hundredth
creditsRequiredThe request's price, which it holds while it runs
planCreditsRemainingCredits left in the plan's monthly allowance
purchasedCreditsRemainingCredits left from purchases
{
"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-AfterSeconds to wait before sending it again, as
retryAfterX-RateLimit-LimitThe size of the request limit closest to refusing: per minute, per hour or per day
X-RateLimit-RemainingRequests left in that limit now
X-RateLimit-ResetSeconds until
X-RateLimit-Remaininggoes up; 0 when nothing is counted
Response fields
statusCodeHTTP status code (always 409)
messageWhat to do — human-readable
errorError category
errorCodeAlways
REQUEST_IN_PROGRESSretryAfterSeconds to wait before sending the request again
{
"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
successAlways
falseerrorCodeAlways
IMAGE_TOO_LARGEerrorWhat to send instead.
Accept-Language: pt-BRgets it in Portuguese.processingTimeMsAlways 0: no work was done
{
"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.
X-RateLimit-LimitThe size of the request limit closest to refusing: per minute, per hour or per day
X-RateLimit-RemainingRequests left in that limit now
X-RateLimit-ResetSeconds until
X-RateLimit-Remaininggoes up; 0 when nothing is counted
Response fields
successtrueif extraction succeeded. Checkerrorfield iffalse.errorWhat went wrong. Only present when success is false.
errorCodeWhy the extraction failed, as a code you can handle in your code.
errorexplains it in plain words. Only present when success is false.processingTimeMsHow long the extraction took, in milliseconds.
dataExtracted certificate data. Contains all fields found in the document — name, birth date, parents, registration info, and more. When
successis false, every field is empty.warningsValues of
datato check on the document. A value that cannot be right, such as a CPF whose check digits do not match, comes as it was read, with a warning here; the request is charged as any other. Only present when there is one.warnings[].codeWhat is wrong with the value, as a code you can handle in your code.
warnings[].fieldThe field of
datait is about, as a dotted path.warnings[].messageWhat is wrong and what to do, in plain words.
imageResizedtruewhen the image was outside our standard (1344 to 2048 px on the long side) and was resized to fit it, asresizeImageasked: the resize's price was added to the extraction's. Only present when it happened.originalImageSizeSize of the image as you sent it, upright. Only present when imageResized is true.
originalImageSize.widthWidth, in pixels.
originalImageSize.heightHeight, in pixels.
finalImageSizeSize of the image once resized to our standard. Only present when imageResized is true.
finalImageSize.widthWidth, in pixels.
finalImageSize.heightHeight, in pixels.
engineThe engine that answered with data:
miniorlargefor the standard engines, orfastwhen the request asked for it and fast answered. Only present when an engine answered.creditsChargedCredits 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).
{
"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, at the resize's price.",
"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
}{
"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
}{
"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. Wait the Retry-After seconds, the same number as retryAfter, and send it again. The X-RateLimit-* headers name the limit that refused. A limit per day resets at midnight UTC.
Retry-AfterSeconds to wait before sending it again, as
retryAfterX-RateLimit-LimitThe size of the request limit closest to refusing: per minute, per hour or per day
X-RateLimit-RemainingRequests left in that limit now
X-RateLimit-ResetSeconds until
X-RateLimit-Remaininggoes up; 0 when nothing is counted
Response fields
statusCodeHTTP status code (always 429)
messageWhich limit you hit, and its size. View usage
errorError category
retryAfterSeconds to wait before sending the request again, the same as the
Retry-Afterheader. A limit per day lasts until midnight UTC, so its wait can be hours.
{
"statusCode": 429,
"message": "Organization rate limit exceeded (10 requests per minute). Retry after 6 seconds.",
"error": "Too Many Requests",
"retryAfter": 6
}{
"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.
<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_MISSINGIMAGE_BASE64_INVALIDIMAGE_TOO_LARGEIMAGE_TOO_MANY_PIXELSIMAGE_FORMAT_UNSUPPORTEDIMAGE_UNREADABLEIMAGE_URL_NOT_ALLOWEDIMAGE_RESOLUTION_TOO_LOWIMAGE_RESOLUTION_TOO_HIGHIMAGE_INVALIDPDF_PASSWORD_PROTECTEDPDF_UNREADABLEPDF_TOO_MANY_PAGESIMAGE_DOWNLOAD_FAILEDIMAGE_NOT_PROCESSABLEDOCUMENT_NOT_RECOGNIZEDEXTRACTION_TIMEOUTEXTRACTION_BUSYEXTRACTION_UNAVAILABLENOT_ENOUGH_CREDITSREQUEST_IN_PROGRESS
#!/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"""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
// 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;// 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);
}
}
}// 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.
The key stays in this browser tab only, and goes only to the API. Create a key in the panel
Reading the prices…
Paste your API key to send.
{
"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
}