Create a report

curl --request POST \
  --url https://reporter.sandbox.lerian.net/v1/reports \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "filters": {
    "accounts": {
      "account": {
        "status": {
          "eq": [
            "ACTIVE"
          ]
        }
      }
    }
  },
  "templateId": "00000000-0000-0000-0000-000000000000",
  "institution": "00000000-0000-0000-0000-000000000000",
  "parameters": {
    "dataBase": "2026-08"
  }
}
'

package main

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

func main() {

	url := "https://reporter.sandbox.lerian.net/v1/reports"

	payload := strings.NewReader("{\n  \"filters\": {\n    \"accounts\": {\n      \"account\": {\n        \"status\": {\n          \"eq\": [\n            \"ACTIVE\"\n          ]\n        }\n      }\n    }\n  },\n  \"templateId\": \"00000000-0000-0000-0000-000000000000\",\n  \"institution\": \"00000000-0000-0000-0000-000000000000\",\n  \"parameters\": {\n    \"dataBase\": \"2026-08\"\n  }\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))

}

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    filters: {accounts: {account: {status: {eq: ['ACTIVE']}}}},
    templateId: '00000000-0000-0000-0000-000000000000',
    institution: '00000000-0000-0000-0000-000000000000',
    parameters: {dataBase: '2026-08'}
  })
};

fetch('https://reporter.sandbox.lerian.net/v1/reports', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://reporter.sandbox.lerian.net/v1/reports"

payload = {
    "filters": { "accounts": { "account": { "status": { "eq": ["ACTIVE"] } } } },
    "templateId": "00000000-0000-0000-0000-000000000000",
    "institution": "00000000-0000-0000-0000-000000000000",
    "parameters": { "dataBase": "2026-08" }
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

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

print(response.text)

{
  "completedAt": "2026-01-31T15:04:05Z",
  "createdAt": "2026-01-31T15:00:00Z",
  "deletedAt": "2026-02-01T09:00:00Z",
  "filters": {
    "accounts": {
      "account": {
        "status": {
          "eq": [
            "ACTIVE"
          ]
        }
      }
    }
  },
  "id": "00000000-0000-0000-0000-000000000001",
  "metadata": {
    "source": "ledger",
    "tenant": "sandbox"
  },
  "status": "Processing",
  "templateId": "00000000-0000-0000-0000-000000000002",
  "updatedAt": "2026-01-31T15:04:05Z",
  "allInstitutions": false,
  "approvedAt": "2026-03-12T10:00:00Z",
  "approvedBy": "9c1d7e34-2b6a-4f81-90a3-5e7f8d0a1b2c",
  "correctedAt": "2026-03-12T09:40:00Z",
  "correctedBy": "3f9a1c2e-0f5b-4d9a-9b8e-1a2b3c4d5e6f",
  "documentId": "br.bcb.cadoc-4010",
  "documentVersion": "1.0.0",
  "draftVersion": 3,
  "institution": {
    "cnpj": "12ABC34501DE35",
    "id": "00000000-0000-0000-0000-000000000000",
    "name": "Banco Exemplo S.A.",
    "scope": {}
  },
  "openGaps": [
    {
      "field": "saldos_cosif.valor",
      "reason": "a consulta mapeada não devolve esta coluna",
      "required": true
    }
  ],
  "parameters": {
    "dataBase": "2026-08"
  },
  "provenance": {
    "catalog": {
      "bindingVersion": 3,
      "documentId": "br.bcb.cadoc-4010",
      "documentVersion": "1.0.0",
      "subscriptionId": "<string>",
      "institution": {
        "cnpj": "12ABC34501DE35",
        "id": "00000000-0000-0000-0000-000000000000",
        "name": "Banco Exemplo S.A.",
        "scope": {}
      }
    },
    "generatedAt": "2023-11-07T05:31:56Z",
    "artifactChecksum": "e3b0c44298fc1c149afbf4c8996fb924...",
    "artifactSizeBytes": 20480,
    "parameters": {
      "dataBase": "2026-03"
    },
    "template": {
      "category": "cadoc4010",
      "revision": 4,
      "revisionChecksum": "9f2c...",
      "templateId": "7c1e2f40-77d1-4a8a-9d0f-6b0e2c4a1111"
    }
  },
  "subscriptionId": "<string>",
  "templateDescription": "Monthly accounting report",
  "templateOutputFormat": "pdf",
  "warnings": [
    {
      "code": "DATA_SOURCE_UNAVAILABLE",
      "field": "my_database",
      "message": "Data source \"my_database\" is currently unavailable; validation skipped"
    }
  ]
}

{
  "code": "<string>",
  "detail": "Property foo is required but is missing.",
  "errors": [
    {
      "location": "body.templateId",
      "message": "expected string to match 'uuid' format",
      "value": "not-a-uuid"
    }
  ],
  "instance": "https://example.com/error-log/abc123",
  "status": 400,
  "title": "Bad Request",
  "type": "https://example.com/errors/example",
  "upstream": {
    "code": "E4001",
    "message": "account not found at provider"
  }
}

{
  "code": "<string>",
  "detail": "Property foo is required but is missing.",
  "errors": [
    {
      "location": "body.templateId",
      "message": "expected string to match 'uuid' format",
      "value": "not-a-uuid"
    }
  ],
  "instance": "https://example.com/error-log/abc123",
  "status": 400,
  "title": "Bad Request",
  "type": "https://example.com/errors/example",
  "upstream": {
    "code": "E4001",
    "message": "account not found at provider"
  }
}

{
  "code": "<string>",
  "detail": "Property foo is required but is missing.",
  "errors": [
    {
      "location": "body.templateId",
      "message": "expected string to match 'uuid' format",
      "value": "not-a-uuid"
    }
  ],
  "instance": "https://example.com/error-log/abc123",
  "status": 400,
  "title": "Bad Request",
  "type": "https://example.com/errors/example",
  "upstream": {
    "code": "E4001",
    "message": "account not found at provider"
  }
}

{
  "code": "<string>",
  "detail": "Property foo is required but is missing.",
  "errors": [
    {
      "location": "body.templateId",
      "message": "expected string to match 'uuid' format",
      "value": "not-a-uuid"
    }
  ],
  "instance": "https://example.com/error-log/abc123",
  "status": 400,
  "title": "Bad Request",
  "type": "https://example.com/errors/example",
  "upstream": {
    "code": "E4001",
    "message": "account not found at provider"
  }
}

{
  "code": "<string>",
  "detail": "Property foo is required but is missing.",
  "errors": [
    {
      "location": "body.templateId",
      "message": "expected string to match 'uuid' format",
      "value": "not-a-uuid"
    }
  ],
  "instance": "https://example.com/error-log/abc123",
  "status": 400,
  "title": "Bad Request",
  "type": "https://example.com/errors/example",
  "upstream": {
    "code": "E4001",
    "message": "account not found at provider"
  }
}

{
  "code": "<string>",
  "detail": "Property foo is required but is missing.",
  "errors": [
    {
      "location": "body.templateId",
      "message": "expected string to match 'uuid' format",
      "value": "not-a-uuid"
    }
  ],
  "instance": "https://example.com/error-log/abc123",
  "status": 400,
  "title": "Bad Request",
  "type": "https://example.com/errors/example",
  "upstream": {
    "code": "E4001",
    "message": "account not found at provider"
  }
}

{
  "code": "<string>",
  "detail": "Property foo is required but is missing.",
  "errors": [
    {
      "location": "body.templateId",
      "message": "expected string to match 'uuid' format",
      "value": "not-a-uuid"
    }
  ],
  "instance": "https://example.com/error-log/abc123",
  "status": 400,
  "title": "Bad Request",
  "type": "https://example.com/errors/example",
  "upstream": {
    "code": "E4001",
    "message": "account not found at provider"
  }
}

{
  "code": "<string>",
  "detail": "Property foo is required but is missing.",
  "errors": [
    {
      "location": "body.templateId",
      "message": "expected string to match 'uuid' format",
      "value": "not-a-uuid"
    }
  ],
  "instance": "https://example.com/error-log/abc123",
  "status": 400,
  "title": "Bad Request",
  "type": "https://example.com/errors/example",
  "upstream": {
    "code": "E4001",
    "message": "account not found at provider"
  }
}

POST

reports

Create a report

curl --request POST \
  --url https://reporter.sandbox.lerian.net/v1/reports \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "filters": {
    "accounts": {
      "account": {
        "status": {
          "eq": [
            "ACTIVE"
          ]
        }
      }
    }
  },
  "templateId": "00000000-0000-0000-0000-000000000000",
  "institution": "00000000-0000-0000-0000-000000000000",
  "parameters": {
    "dataBase": "2026-08"
  }
}
'

package main

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

func main() {

	url := "https://reporter.sandbox.lerian.net/v1/reports"

	payload := strings.NewReader("{\n  \"filters\": {\n    \"accounts\": {\n      \"account\": {\n        \"status\": {\n          \"eq\": [\n            \"ACTIVE\"\n          ]\n        }\n      }\n    }\n  },\n  \"templateId\": \"00000000-0000-0000-0000-000000000000\",\n  \"institution\": \"00000000-0000-0000-0000-000000000000\",\n  \"parameters\": {\n    \"dataBase\": \"2026-08\"\n  }\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))

}

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    filters: {accounts: {account: {status: {eq: ['ACTIVE']}}}},
    templateId: '00000000-0000-0000-0000-000000000000',
    institution: '00000000-0000-0000-0000-000000000000',
    parameters: {dataBase: '2026-08'}
  })
};

fetch('https://reporter.sandbox.lerian.net/v1/reports', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://reporter.sandbox.lerian.net/v1/reports"

payload = {
    "filters": { "accounts": { "account": { "status": { "eq": ["ACTIVE"] } } } },
    "templateId": "00000000-0000-0000-0000-000000000000",
    "institution": "00000000-0000-0000-0000-000000000000",
    "parameters": { "dataBase": "2026-08" }
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

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

print(response.text)

{
  "completedAt": "2026-01-31T15:04:05Z",
  "createdAt": "2026-01-31T15:00:00Z",
  "deletedAt": "2026-02-01T09:00:00Z",
  "filters": {
    "accounts": {
      "account": {
        "status": {
          "eq": [
            "ACTIVE"
          ]
        }
      }
    }
  },
  "id": "00000000-0000-0000-0000-000000000001",
  "metadata": {
    "source": "ledger",
    "tenant": "sandbox"
  },
  "status": "Processing",
  "templateId": "00000000-0000-0000-0000-000000000002",
  "updatedAt": "2026-01-31T15:04:05Z",
  "allInstitutions": false,
  "approvedAt": "2026-03-12T10:00:00Z",
  "approvedBy": "9c1d7e34-2b6a-4f81-90a3-5e7f8d0a1b2c",
  "correctedAt": "2026-03-12T09:40:00Z",
  "correctedBy": "3f9a1c2e-0f5b-4d9a-9b8e-1a2b3c4d5e6f",
  "documentId": "br.bcb.cadoc-4010",
  "documentVersion": "1.0.0",
  "draftVersion": 3,
  "institution": {
    "cnpj": "12ABC34501DE35",
    "id": "00000000-0000-0000-0000-000000000000",
    "name": "Banco Exemplo S.A.",
    "scope": {}
  },
  "openGaps": [
    {
      "field": "saldos_cosif.valor",
      "reason": "a consulta mapeada não devolve esta coluna",
      "required": true
    }
  ],
  "parameters": {
    "dataBase": "2026-08"
  },
  "provenance": {
    "catalog": {
      "bindingVersion": 3,
      "documentId": "br.bcb.cadoc-4010",
      "documentVersion": "1.0.0",
      "subscriptionId": "<string>",
      "institution": {
        "cnpj": "12ABC34501DE35",
        "id": "00000000-0000-0000-0000-000000000000",
        "name": "Banco Exemplo S.A.",
        "scope": {}
      }
    },
    "generatedAt": "2023-11-07T05:31:56Z",
    "artifactChecksum": "e3b0c44298fc1c149afbf4c8996fb924...",
    "artifactSizeBytes": 20480,
    "parameters": {
      "dataBase": "2026-03"
    },
    "template": {
      "category": "cadoc4010",
      "revision": 4,
      "revisionChecksum": "9f2c...",
      "templateId": "7c1e2f40-77d1-4a8a-9d0f-6b0e2c4a1111"
    }
  },
  "subscriptionId": "<string>",
  "templateDescription": "Monthly accounting report",
  "templateOutputFormat": "pdf",
  "warnings": [
    {
      "code": "DATA_SOURCE_UNAVAILABLE",
      "field": "my_database",
      "message": "Data source \"my_database\" is currently unavailable; validation skipped"
    }
  ]
}

{
  "code": "<string>",
  "detail": "Property foo is required but is missing.",
  "errors": [
    {
      "location": "body.templateId",
      "message": "expected string to match 'uuid' format",
      "value": "not-a-uuid"
    }
  ],
  "instance": "https://example.com/error-log/abc123",
  "status": 400,
  "title": "Bad Request",
  "type": "https://example.com/errors/example",
  "upstream": {
    "code": "E4001",
    "message": "account not found at provider"
  }
}

{
  "code": "<string>",
  "detail": "Property foo is required but is missing.",
  "errors": [
    {
      "location": "body.templateId",
      "message": "expected string to match 'uuid' format",
      "value": "not-a-uuid"
    }
  ],
  "instance": "https://example.com/error-log/abc123",
  "status": 400,
  "title": "Bad Request",
  "type": "https://example.com/errors/example",
  "upstream": {
    "code": "E4001",
    "message": "account not found at provider"
  }
}

{
  "code": "<string>",
  "detail": "Property foo is required but is missing.",
  "errors": [
    {
      "location": "body.templateId",
      "message": "expected string to match 'uuid' format",
      "value": "not-a-uuid"
    }
  ],
  "instance": "https://example.com/error-log/abc123",
  "status": 400,
  "title": "Bad Request",
  "type": "https://example.com/errors/example",
  "upstream": {
    "code": "E4001",
    "message": "account not found at provider"
  }
}

{
  "code": "<string>",
  "detail": "Property foo is required but is missing.",
  "errors": [
    {
      "location": "body.templateId",
      "message": "expected string to match 'uuid' format",
      "value": "not-a-uuid"
    }
  ],
  "instance": "https://example.com/error-log/abc123",
  "status": 400,
  "title": "Bad Request",
  "type": "https://example.com/errors/example",
  "upstream": {
    "code": "E4001",
    "message": "account not found at provider"
  }
}

{
  "code": "<string>",
  "detail": "Property foo is required but is missing.",
  "errors": [
    {
      "location": "body.templateId",
      "message": "expected string to match 'uuid' format",
      "value": "not-a-uuid"
    }
  ],
  "instance": "https://example.com/error-log/abc123",
  "status": 400,
  "title": "Bad Request",
  "type": "https://example.com/errors/example",
  "upstream": {
    "code": "E4001",
    "message": "account not found at provider"
  }
}

{
  "code": "<string>",
  "detail": "Property foo is required but is missing.",
  "errors": [
    {
      "location": "body.templateId",
      "message": "expected string to match 'uuid' format",
      "value": "not-a-uuid"
    }
  ],
  "instance": "https://example.com/error-log/abc123",
  "status": 400,
  "title": "Bad Request",
  "type": "https://example.com/errors/example",
  "upstream": {
    "code": "E4001",
    "message": "account not found at provider"
  }
}

{
  "code": "<string>",
  "detail": "Property foo is required but is missing.",
  "errors": [
    {
      "location": "body.templateId",
      "message": "expected string to match 'uuid' format",
      "value": "not-a-uuid"
    }
  ],
  "instance": "https://example.com/error-log/abc123",
  "status": 400,
  "title": "Bad Request",
  "type": "https://example.com/errors/example",
  "upstream": {
    "code": "E4001",
    "message": "account not found at provider"
  }
}

{
  "code": "<string>",
  "detail": "Property foo is required but is missing.",
  "errors": [
    {
      "location": "body.templateId",
      "message": "expected string to match 'uuid' format",
      "value": "not-a-uuid"
    }
  ],
  "instance": "https://example.com/error-log/abc123",
  "status": 400,
  "title": "Bad Request",
  "type": "https://example.com/errors/example",
  "upstream": {
    "code": "E4001",
    "message": "account not found at provider"
  }
}

Authorizations

Authorization

string

header

required

JWT bearer token issued by the identity provider.

Headers

X-Idempotency

string

Client-provided idempotency key that prevents duplicate report creation

Body

application/json

Report input

filters

object

required

Filter conditions grouped by data source, table, and field.

Show child attributes

Example:

{
  "accounts": {
    "account": { "status": { "eq": ["ACTIVE"] } }
  }
}

templateId

string

required

Template identifier used to generate the report.

Example:

"00000000-0000-0000-0000-000000000000"

institution

string

The institution the report reads for: an institution id, or "all" to read every institution's rows in one report. Absent, a tenant with no institution reads everything, a tenant with one takes it, and a tenant with several is refused.

Example:

"00000000-0000-0000-0000-000000000000"

parameters

object

Generation parameters keyed by parameter name, answering what the template declares. A parameter the template does not declare is refused; a declared one that is required and absent is refused unless it carries a default. At most 50 parameters, each value at most 512 characters.

Show child attributes

Example:

{ "dataBase": "2026-08" }

Response

Created

completedAt

string<date-time> | null

required

Time when report generation completed, when available.

Example:

"2026-01-31T15:04:05Z"

createdAt

string<date-time>

required

Time when the report was created.

Example:

"2026-01-31T15:00:00Z"

deletedAt

string<date-time> | null

required

Time when the report was soft-deleted, when applicable.

Example:

"2026-02-01T09:00:00Z"

filters

object

required

Filter conditions grouped by data source, table, and field.

Show child attributes

Example:

{
  "accounts": {
    "account": { "status": { "eq": ["ACTIVE"] } }
  }
}

string

required

Stable report identifier.

Example:

"00000000-0000-0000-0000-000000000001"

metadata

object

required

Additional report metadata keyed by attribute name.

Show child attributes

Example:

{ "source": "ledger", "tenant": "sandbox" }

status

string

required

Current report generation status.

Example:

"Processing"

templateId

string

required

Template snapshot source identifier.

Example:

"00000000-0000-0000-0000-000000000002"

updatedAt

string<date-time>

required

Time when the report was last updated.

Example:

"2026-01-31T15:04:05Z"

allInstitutions

boolean

The caller chose every institution, so the report read every institution's rows unscoped.

Example:

false

approvedAt

string<date-time>

When the report was approved, when it was.

Example:

"2026-03-12T10:00:00Z"

approvedBy

string

Who approved it, as the Access Manager subject identifier the bearer token named. Absent until approval; never blank on a Final, because an approval whose actor the request did not identify is refused.

Example:

"9c1d7e34-2b6a-4f81-90a3-5e7f8d0a1b2c"

correctedAt

string<date-time>

When the draft was last corrected, when it was.

Example:

"2026-03-12T09:40:00Z"

correctedBy

string

Who last corrected it, as the Access Manager subject identifier the bearer token named. Absent until the first correction; never blank on a report that has one, because a correction whose actor the request did not identify is refused.

Example:

"3f9a1c2e-0f5b-4d9a-9b8e-1a2b3c4d5e6f"

documentId

string

Curated document this report generates.

Example:

"br.bcb.cadoc-4010"

documentVersion

string

Pinned version of the document it was generated against.

Example:

"1.0.0"

draftVersion

integer<int64>

Version of the draft; a correction or an approval must present the one it read.

Example:

3

institution

object

The institution the report read for, frozen when it was requested: its scope is the part applied to the tables the report reads. Absent on a report that read for no institution.

Show child attributes

openGaps

object[]

What a regulatory Draft still cannot fill, computed on read from the same stored state the approval refusal reads, each field flagged required or not. Present when a Draft is read by id; absent on a Final, on a non-regulatory report, and in the list endpoint, which does not compute it. Absent means unknown, an empty list means nothing is missing, and only a required gap refuses an approval.

Show child attributes

parameters

object

Generation parameters recorded with the report, when supplied.

Show child attributes

Example:

{ "dataBase": "2026-08" }

provenance

object

Everything this report was made of, frozen — what answers, months later, why it says what it says.

Option 1
Option 2

Show child attributes

subscriptionId

string

Subscription this report files under; present only on the regulatory flow.

templateDescription

string

Description copied from the template when the report was created.

Example:

"Monthly accounting report"

templateOutputFormat

string

Output format selected for the generated report.

Example:

"pdf"

warnings

object[] | null

Non-fatal filter-validation warnings returned when a data source is unavailable and the filter could not be checked against its schema

Show child attributes

Example:

[
  {
    "code": "DATA_SOURCE_UNAVAILABLE",
    "field": "my_database",
    "message": "Data source \"my_database\" is currently unavailable; validation skipped"
  }
]

Getting started

Templates API

Template Builder API

Reports API

Deadlines API

Data Sources API

Institutions API

Regulatory Catalog API

Regulatory Subscriptions API

Regulatory Bindings API

Regulatory Reports API

Metrics API

Streaming API

Error handling

Events

Create a report

Authorizations

Headers

Body

Response