Quickstart
Three steps to a birth certificate's data as JSON.
1. Create an API key
In the panel, under API Keys, create a key for your workspace. Keep it like a password: it goes in the Authorization header of every request. See Authentication.
2. Make your first call
This code sends the sample certificate we host, with fictitious data. Put your key in the DOCSOCR_API_KEY environment variable and run:
#!/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;Rather not write code? Use the reference's Try it or the Postman collection.
3. Read the answer
The extraction answers with status 201 and a JSON body:
success:truewhen the answer carries the certificate's data;data: the certificate's fields, with Portuguese, accented keys such asdados_pessoais.nome_completoandfiliação.genitor_1.nome_completo. They are all in Birth certificate fields;engine: the engine that answered;creditsCharged: what the request cost.
With success: false, no engine could answer: the errorCode says why, and nothing was charged. An image that cannot be used is refused with 422, also at no charge. The codes are in Errors.
A marriage certificate
The marriage certificate has its own endpoint, POST /documents/marriage-certificate, which takes the request the same way. This code sends the sample marriage certificate, with fictitious data, and prints both spouses, in the order the certificate prints them:
#!/usr/bin/env bash
# Extract the hosted sample marriage certificate (fictitious data).
# Needs DOCSOCR_API_KEY in the environment; create a key in the panel.
set -euo pipefail
REQUEST_ID="marriage-$(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/marriage-certificate \
-H "Authorization: Bearer $DOCSOCR_API_KEY" \
-H "Content-Type: application/json" \
--data-binary @- <<EOF
{
"imageType": "url",
"imageUrl": "https://docsocr.com/samples/certidao-casamento-exemplo.jpg",
"requestId": "$REQUEST_ID"
}
EOF"""Extract the hosted sample marriage 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/marriage-certificate",
headers={"Authorization": f"Bearer {os.environ['DOCSOCR_API_KEY']}"},
json={
"imageType": "url",
"imageUrl": "https://docsocr.com/samples/certidao-casamento-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')}")
# The spouses in the order the certificate prints them
print(answer["data"]["cônjuge_1"]["nome_completo"])
print(answer["data"]["cônjuge_2"]["nome_completo"])// Extract the hosted sample marriage 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/marriage-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-casamento-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)
}
// The spouses in the order the certificate prints them
console.log(answer.data['cônjuge_1'].nome_completo)
console.log(answer.data['cônjuge_2'].nome_completo)<?php
// Extract the hosted sample marriage certificate (fictitious data).
// Needs the curl extension and DOCSOCR_API_KEY in the environment.
$request = curl_init('https://api.docsocr.com/api/v1/documents/marriage-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-casamento-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);
}
// The spouses in the order the certificate prints them
echo $answer['data']['cônjuge_1']['nome_completo'], PHP_EOL;
echo $answer['data']['cônjuge_2']['nome_completo'], PHP_EOL;// Extract the hosted sample marriage certificate (fictitious data).
// Needs Java 17+ and DOCSOCR_API_KEY in the environment. Run: java MarriageCertificate.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 MarriageCertificate {
public static void main(String[] args) throws Exception {
String body = """
{
"imageType": "url",
"imageUrl": "https://docsocr.com/samples/certidao-casamento-exemplo.jpg",
"requestId": "%s"
}""".formatted(UUID.randomUUID()); // one id per document
HttpRequest request = HttpRequest.newBuilder(URI.create("https://api.docsocr.com/api/v1/documents/marriage-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.cônjuge_1 and data.cônjuge_2 with your JSON library
System.out.println(response.body());
if (response.statusCode() != 201 || !response.body().contains("\"success\":true")) {
System.exit(1);
}
}
}// Extract the hosted sample marriage certificate (fictitious data).
// Needs .NET 8+ and DOCSOCR_API_KEY in the environment. Run: dotnet run MarriageCertificate.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-casamento-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/marriage-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;
}
// The spouses in the order the certificate prints them
var data = root.GetProperty("data");
Console.WriteLine(data.GetProperty("cônjuge_1").GetProperty("nome_completo").GetString());
Console.WriteLine(data.GetProperty("cônjuge_2").GetProperty("nome_completo").GetString());
return 0;The fields are in Marriage certificate fields. A birth certificate sent to that endpoint is refused at no cost, with a message that names the endpoint that reads it; the same holds the other way around.
Next steps
Each guide carries its code in the same six languages. The language you pick in one block holds for the others.
- Image standard: formats, limits, a local file in base64 and
resizeImage. - Engines and prices: the fast engine and the price of each answer.
- Request IDs and retries: how to repeat a request without paying twice, and how to handle errors.
- API reference: each operation, with its code and Try it.