Execute Query

curl --request POST \
  --url https://api.base39.com.br/v2/queries \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "dataset": "empresas",
  "params": {
    "doc": "<string>"
  },
  "asOfDate": "2024-01-31",
  "mock": true,
  "requestId": "req_123",
  "targetDocument": "57778216000108",
  "cache": false
}
'

import requests

url = "https://api.base39.com.br/v2/queries"

payload = {
    "dataset": "empresas",
    "params": { "doc": "<string>" },
    "asOfDate": "2024-01-31",
    "mock": True,
    "requestId": "req_123",
    "targetDocument": "57778216000108",
    "cache": False
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    dataset: 'empresas',
    params: {doc: '<string>'},
    asOfDate: '2024-01-31',
    mock: true,
    requestId: 'req_123',
    targetDocument: '57778216000108',
    cache: false
  })
};

fetch('https://api.base39.com.br/v2/queries', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.base39.com.br/v2/queries",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'dataset' => 'empresas',
    'params' => [
        'doc' => '<string>'
    ],
    'asOfDate' => '2024-01-31',
    'mock' => true,
    'requestId' => 'req_123',
    'targetDocument' => '57778216000108',
    'cache' => false
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.base39.com.br/v2/queries"

	payload := strings.NewReader("{\n  \"dataset\": \"empresas\",\n  \"params\": {\n    \"doc\": \"<string>\"\n  },\n  \"asOfDate\": \"2024-01-31\",\n  \"mock\": true,\n  \"requestId\": \"req_123\",\n  \"targetDocument\": \"57778216000108\",\n  \"cache\": false\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.base39.com.br/v2/queries")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"dataset\": \"empresas\",\n  \"params\": {\n    \"doc\": \"<string>\"\n  },\n  \"asOfDate\": \"2024-01-31\",\n  \"mock\": true,\n  \"requestId\": \"req_123\",\n  \"targetDocument\": \"57778216000108\",\n  \"cache\": false\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.base39.com.br/v2/queries")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"dataset\": \"empresas\",\n  \"params\": {\n    \"doc\": \"<string>\"\n  },\n  \"asOfDate\": \"2024-01-31\",\n  \"mock\": true,\n  \"requestId\": \"req_123\",\n  \"targetDocument\": \"57778216000108\",\n  \"cache\": false\n}"

response = http.request(request)
puts response.read_body

{
  "object": "query",
  "status": "success",
  "dataset": {
    "object": "dataset",
    "id": "<string>",
    "slug": "<string>",
    "name": "<string>",
    "description": "<string>",
    "cost": 123,
    "upstreams": [
      {
        "object": "page",
        "id": "p_abc123",
        "createdAt": "2024-01-15T10:30:00.000Z",
        "updatedAt": "2024-01-15T14:45:00.000Z",
        "name": "Federal Revenue",
        "description": "<string>",
        "logo": "<string>",
        "slug": "federal-revenue",
        "country": "BR",
        "type": "<string>",
        "url": "<string>",
        "createdBy": {
          "object": "user",
          "id": "u_abc123",
          "apiKeyId": "bsk_abc123"
        },
        "updatedBy": {
          "object": "user",
          "id": "u_abc123",
          "apiKeyId": "bsk_abc123"
        },
        "featured": true
      }
    ]
  },
  "asOfDate": "2025-11-21",
  "createdAt": "2025-11-21T19:00:00.000Z",
  "isMock": false,
  "cacheStatus": "hit",
  "results": [
    {}
  ],
  "rawParams": {},
  "id": "qry_abc123",
  "provider": {
    "object": "provider",
    "id": "<string>",
    "slug": "<string>",
    "name": "<string>"
  },
  "createdBy": {
    "object": "user",
    "id": "usr_abc123",
    "apiKeyId": "bsk_abc123"
  },
  "requestId": "<string>",
  "summary": "<string>",
  "attempts": 123,
  "duration": 123,
  "errorMessage": "<string>",
  "cost": 123,
  "affectedCanonicalTargets": [
    {
      "type": "domain",
      "domain": "serasa",
      "certificate": "fgts",
      "sanction": "ceis",
      "endpoint": "entitiesGetScr"
    }
  ],
  "rawResponseProvider": [
    {}
  ],
  "parent": {
    "type": "dataset_query_id",
    "dataset_query_id": "qry_parent123",
    "company_id": "cmp_123",
    "person_id": "12345678909"
  },
  "export": {
    "type": "file_upload_id",
    "file_upload_id": "fl_abc123",
    "downloadUrl": "https://files.base39.cloud/uploads/org/fl/report.pdf"
  }
}

{
  "object": "error",
  "status": 502,
  "code": "upstream_error",
  "message": "Upstream provider returned an error",
  "request_id": "req_abc123",
  "dataset": "scr",
  "query_id": "qry_abc123"
}

POST

queries

Execute Query

curl --request POST \
  --url https://api.base39.com.br/v2/queries \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "dataset": "empresas",
  "params": {
    "doc": "<string>"
  },
  "asOfDate": "2024-01-31",
  "mock": true,
  "requestId": "req_123",
  "targetDocument": "57778216000108",
  "cache": false
}
'

import requests

url = "https://api.base39.com.br/v2/queries"

payload = {
    "dataset": "empresas",
    "params": { "doc": "<string>" },
    "asOfDate": "2024-01-31",
    "mock": True,
    "requestId": "req_123",
    "targetDocument": "57778216000108",
    "cache": False
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    dataset: 'empresas',
    params: {doc: '<string>'},
    asOfDate: '2024-01-31',
    mock: true,
    requestId: 'req_123',
    targetDocument: '57778216000108',
    cache: false
  })
};

fetch('https://api.base39.com.br/v2/queries', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.base39.com.br/v2/queries",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'dataset' => 'empresas',
    'params' => [
        'doc' => '<string>'
    ],
    'asOfDate' => '2024-01-31',
    'mock' => true,
    'requestId' => 'req_123',
    'targetDocument' => '57778216000108',
    'cache' => false
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.base39.com.br/v2/queries"

	payload := strings.NewReader("{\n  \"dataset\": \"empresas\",\n  \"params\": {\n    \"doc\": \"<string>\"\n  },\n  \"asOfDate\": \"2024-01-31\",\n  \"mock\": true,\n  \"requestId\": \"req_123\",\n  \"targetDocument\": \"57778216000108\",\n  \"cache\": false\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.base39.com.br/v2/queries")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"dataset\": \"empresas\",\n  \"params\": {\n    \"doc\": \"<string>\"\n  },\n  \"asOfDate\": \"2024-01-31\",\n  \"mock\": true,\n  \"requestId\": \"req_123\",\n  \"targetDocument\": \"57778216000108\",\n  \"cache\": false\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.base39.com.br/v2/queries")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"dataset\": \"empresas\",\n  \"params\": {\n    \"doc\": \"<string>\"\n  },\n  \"asOfDate\": \"2024-01-31\",\n  \"mock\": true,\n  \"requestId\": \"req_123\",\n  \"targetDocument\": \"57778216000108\",\n  \"cache\": false\n}"

response = http.request(request)
puts response.read_body

{
  "object": "query",
  "status": "success",
  "dataset": {
    "object": "dataset",
    "id": "<string>",
    "slug": "<string>",
    "name": "<string>",
    "description": "<string>",
    "cost": 123,
    "upstreams": [
      {
        "object": "page",
        "id": "p_abc123",
        "createdAt": "2024-01-15T10:30:00.000Z",
        "updatedAt": "2024-01-15T14:45:00.000Z",
        "name": "Federal Revenue",
        "description": "<string>",
        "logo": "<string>",
        "slug": "federal-revenue",
        "country": "BR",
        "type": "<string>",
        "url": "<string>",
        "createdBy": {
          "object": "user",
          "id": "u_abc123",
          "apiKeyId": "bsk_abc123"
        },
        "updatedBy": {
          "object": "user",
          "id": "u_abc123",
          "apiKeyId": "bsk_abc123"
        },
        "featured": true
      }
    ]
  },
  "asOfDate": "2025-11-21",
  "createdAt": "2025-11-21T19:00:00.000Z",
  "isMock": false,
  "cacheStatus": "hit",
  "results": [
    {}
  ],
  "rawParams": {},
  "id": "qry_abc123",
  "provider": {
    "object": "provider",
    "id": "<string>",
    "slug": "<string>",
    "name": "<string>"
  },
  "createdBy": {
    "object": "user",
    "id": "usr_abc123",
    "apiKeyId": "bsk_abc123"
  },
  "requestId": "<string>",
  "summary": "<string>",
  "attempts": 123,
  "duration": 123,
  "errorMessage": "<string>",
  "cost": 123,
  "affectedCanonicalTargets": [
    {
      "type": "domain",
      "domain": "serasa",
      "certificate": "fgts",
      "sanction": "ceis",
      "endpoint": "entitiesGetScr"
    }
  ],
  "rawResponseProvider": [
    {}
  ],
  "parent": {
    "type": "dataset_query_id",
    "dataset_query_id": "qry_parent123",
    "company_id": "cmp_123",
    "person_id": "12345678909"
  },
  "export": {
    "type": "file_upload_id",
    "file_upload_id": "fl_abc123",
    "downloadUrl": "https://files.base39.cloud/uploads/org/fl/report.pdf"
  }
}

{
  "object": "error",
  "status": 502,
  "code": "upstream_error",
  "message": "Upstream provider returned an error",
  "request_id": "req_abc123",
  "dataset": "scr",
  "query_id": "qry_abc123"
}

Authorizations

Authorization

string

header

required

OAuth2 Authorization Code flow

Query Parameters

expand

string

Comma-separated fields to expand (e.g., "dataset")

fields

string

Comma-separated optional response fields. Supports "summary.short", "summary.long", and "summary.mdx".

Body

application/json

dataset

string

required

Dataset slug to query

Example:

"empresas"

params

object

required

Query parameters. Varies by dataset.

Show child attributes

asOfDate

string

Logical reference date for the query (YYYY-MM-DD)

Example:

"2024-01-31"

mock

Enable mock mode. Use true/"default" for default example, or specify example key (e.g., "outro_exemplo")

Example:

true

requestId

string

Request ID

Example:

"req_123"

targetDocument

string

Target document (CNPJ/CPF) for property mapping. Used when the query result does not contain the document identifier.

Example:

"57778216000108"

cache

boolean

default:true

Enable caching. Set to false to bypass cache and force fresh data.

Example:

false

parent

object

Parent dataset query reference. Child queries persist zero cost.

Show child attributes

export

enum<string> | null

Export task dataset summary PDF. "background" starts async export; "wait" returns the download URL.

Available options:

background,

wait,

null

Response

Query results

object

enum<string>

required

Object type identifier

Available options:

query

Example:

"query"

status

enum<string>

required

Query execution status

Available options:

success,

partial_success,

error,

pending

dataset

object

required

Dataset being queried (minimal reference)

Show child attributes

asOfDate

string

required

Date for which data is queried

Example:

"2025-11-21"

createdAt

string<date-time>

required

Query creation timestamp

Example:

"2025-11-21T19:00:00.000Z"

isMock

boolean

required

Whether this is a mock query (testing mode)

Example:

false

cacheStatus

enum<string>

required

Available options:

hit,

miss

results

object[]

required

Query results. Each item follows the schema defined by the dataset being queried.

rawParams

object

required

Raw query parameters used for this query

string

Query execution ID

Example:

"qry_abc123"

provider

object

Provider used for the query

Show child attributes

createdBy

object

Principal who created this query

Show child attributes

requestId

string

summary

Rendered query summary markdown or MDX when requested via ?fields=summary.short, summary.long, summary.mdx, and/or summary.mdx-list. Single format → string. Multiple formats → object { short, long, mdx, "mdx-list" }.

attempts

number

duration

number

Query duration in milliseconds

errorMessage

string

cost

number

Query cost in cents (0 for cached queries)

affectedCanonicalTargets

object[]

Canonical entity query targets impacted by this dataset execution.

Show child attributes

rawResponseProvider

object[] | null

Raw provider response captured during query execution.

parent

object

Parent dataset query reference

Show child attributes

export

object

PDF export generated for this query

Show child attributes