> ## Documentation Index > Fetch the complete documentation index at: https://docs.usecroma.com/llms.txt > Use this file to discover all available pages before exploring further. # DIAN My Tax Account > Read a person's or company's tax records at Colombia's DIAN: the electronic invoices issued to a person and what third parties reported, by tax year. DIAN (Dirección de Impuestos y Aduanas Nacionales) is Colombia's tax and customs authority. A taxpayer's online account holds what DIAN knows about their year: the electronic invoices issued to them and the information third parties reported (información exógena). These endpoints read that account as the taxpayer's own connection, one tax year at a time. ## Connect your account DIAN answers only to a signed-in person: their DIAN account's document type, number and password. Signed in on their own behalf (`sign_in_as: self`, the default) the connection reads the person's own records; signed in on behalf of a third party they represent at DIAN (`sign_in_as: third_party`, with its NIT in `on_behalf_of_nit`) it reads that company's or person's records. The person and each third party are separate connections. Each query runs as your organization's own connection, so register one before your first query. Register the account once; Croma keeps the session open and reuses it across queries. `POST /co/dian-muisca/connections/v1` Register a connection once. Croma checks it with the source before saving it, and answers with its id and a masked name. | Field | Type | Notes | | - | - | - | | `sign_in_as` | enum | `self` (default) to read the person's own records, or `third_party` to read the records of the company or person whose NIT goes in `on_behalf_of_nit`. Electronic invoices are read only on one's own behalf. Default `self`. | | `on_behalf_of_nit` | string | The third party's NIT, without the verification digit. Required with `third_party`; leave it empty with `self`. | | `document_type` | enum | The document type of the DIAN account holder: `CC`, `CE`, `TI`, `RC`, `PA`, `PEP` or `PPT`. Default `CC`. | | `document_number` | string | **Required.** The document number of the person whose DIAN account this is (the representative's, when signing in for a third party), without dots or commas. | | `password` | string | **Required.** The password of that DIAN account. | | `authorized` | boolean | **Required.** `true`: you confirm you are the account's owner or have the owner's authorization to use it. | ```bash theme={"dark"} curl https://api.croma.run/co/dian-muisca/connections/v1 \ -H "Authorization: Bearer $CROMA_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "document_type": "CC", "document_number": "1234567890", "password": "your-dian-password", "authorized": true }' ``` ```json theme={"dark"} { "data": { "id": "conn_2f8Kq1xVb7Lm0Pz9Rt4Wc3", "source": "dian-muisca", "status": "active", "display_name": "J*** P*** G***", "usage": { "sign_ins_today": 1, "daily_limit": null, "resets_at": "2026-10-01T05:00:00.000Z" }, "available_again_at": null, "created_at": "2026-09-30T20:00:00.000Z", "last_used_at": "2026-09-30T20:00:00.000Z" } } ``` Every query then runs as one of your organization's connections. Croma picks one, keeps its session open between queries, and moves to the next when one reaches its daily allowance. Register more than one to get more capacity a day. To run as a specific one, send its id as `connection_id`. How the flow works, step by step: [Connections](/connections). List and delete them: ```bash theme={"dark"} curl https://api.croma.run/co/dian-muisca/connections/v1 -H "Authorization: Bearer $CROMA_API_KEY" curl -X DELETE https://api.croma.run/co/dian-muisca/connections/v1/conn_2f8Kq1xVb7Lm0Pz9Rt4Wc3 -H "Authorization: Bearer $CROMA_API_KEY" ``` Over [MCP](/mcp-server), the same verbs are the `dian_muisca_connect`, `dian_muisca_list_connections`, `dian_muisca_delete_connection` tools. Connecting from an agent never passes the credentials through the conversation: the agent gets a secure link, and the user enters the account's details in the [Croma console](https://platform.usecroma.com/connections). When a query cannot run as any connection: | Status | Code | Meaning | | - | - | - | | 409 | `connection_required` | The organization has no connection for this source yet. | | 422 | `connection_rejected` | The source no longer accepts the connection's credentials. | | 429 | `connections_exhausted` | Every connection used its daily allowance. `Retry-After` says when one is available again. | | 409 | `connection_exists` | The same account is already connected (on register). | | 422 | `connection_limit_reached` | The organization already has 5 connections for this source (on register). | Credentials are encrypted as soon as they reach Croma, bound to your organization, and can only be opened by the isolated service that signs in to the source on your behalf. They are never returned by the API or shown to anyone. Deleting a connection destroys it permanently. ## Electronic invoices `POST /co/dian-muisca/electronic-invoices/v1` DIAN keeps this report for persons only, so it runs on a connection signed in on its own behalf. A connection signed in for a third party cannot read it, and the job fails. | Field | Type | Notes | | - | - | - | | `year` | integer | **Required.** The tax year (año gravable), from 2023 to the last year that has ended. DIAN publishes a year only after it closes, so the current year is rejected. | | `connection_id` | string | The connection to run as. Each DIAN connection reads its own account's records, so with more than one in your organization it is required; without it the call answers `409 connection_id_required`. | ```bash theme={"dark"} curl https://api.croma.run/co/dian-muisca/electronic-invoices/v1 \ -H "Authorization: Bearer $CROMA_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "year": 2024 }' ``` ## Response | Field | Notes | | - | - | | `year` | Echoes the tax year. | | `cutoff_date` | The date DIAN's figures were cut, `yyyy-mm-dd`, or `null`. | | `taxpayer` | The account holder's `document_type`, `document_number` and `name`, as DIAN prints them. | | `count` | Number of invoices returned. | | `totals` | Sums over the invoices returned, in COP. | | `invoices[]` | One per electronic invoice (below). | Each invoice has `issuer_id`, `issuer_name`, `issued_on`, the `invoiced_amount` with its `credit_notes_amount` and `debit_notes_amount`, the `net_amount` and `deductible_amount` (COP), `payment_method`, `invoice_number` and `cufe`. ```json theme={"dark"} { "data": { "year": 2024, "cutoff_date": "2025-03-14", "taxpayer": { "document_type": "C. C.", "document_number": "1234567890", "name": "JUAN PEREZ GOMEZ" }, "count": 2, "totals": { "invoiced_amount": 1850000, "credit_notes_amount": 0, "debit_notes_amount": 0, "net_amount": 1850000, "deductible_amount": 1850000 }, "invoices": [ { "issuer_id": "900123456", "issuer_name": "ALMACENES EXITO S.A.", "issued_on": "2024-02-10", "invoiced_amount": 1200000, "credit_notes_amount": 0, "debit_notes_amount": 0, "net_amount": 1200000, "deductible_amount": 1200000, "payment_method": "Electrónicos", "invoice_number": "FE-9912", "cufe": "a1b2c3d4e5f6..." } ] } } ``` Every call reads DIAN live as your connection, so the answer is current and is never shared between organizations. This lookup can take longer than a typical request. It is an [async job](/async-jobs). By default the request waits inline and returns `{ data }`, or you can poll / use a `callback_url`. ## Third-party reports `POST /co/dian-muisca/third-party-reports/v1` | Field | Type | Notes | | - | - | - | | `year` | integer | **Required.** The tax year (año gravable), from 2018 to the last year that has ended. DIAN publishes a year only after it closes, so the current year is rejected. | | `connection_id` | string | The connection to run as. Each DIAN connection reads its own account's records, so with more than one in your organization it is required; without it the call answers `409 connection_id_required`. | ```bash theme={"dark"} curl https://api.croma.run/co/dian-muisca/third-party-reports/v1 \ -H "Authorization: Bearer $CROMA_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "year": 2024 }' ``` ## Response | Field | Notes | | - | - | | `year` | Echoes the tax year. | | `cutoff_date` | The date DIAN's figures were cut, `yyyy-mm-dd`, or `null`. | | `generated_at` | When DIAN generated the report, ISO 8601 in Bogotá time (`-05:00`), or `null`. | | `taxpayer` | The account holder's `document_type`, `document_number` and `name`. | | `thresholds[]` | DIAN's summary against the filing thresholds (topes); empty before 2023. | | `count` | Number of reports returned. | | `reports[]` | One per line a third party reported (below). | Each report has `reporter_id` and `reporter_name` (who reported), `reported_id` and `reported_name` (how they reported it; `reported_id` is `null` before 2023), `concept`, `amount` (COP), and `suggested_use` and `additional_info` (`null` before 2023). ```json theme={"dark"} { "data": { "year": 2024, "cutoff_date": "2025-03-14", "generated_at": "2026-10-03T23:24:00-05:00", "taxpayer": { "document_type": "C. C.", "document_number": "1234567890", "name": "JUAN PEREZ GOMEZ" }, "thresholds": [ { "name": "Tope 1 - Ingresos", "amount": 59000000 } ], "count": 1, "reports": [ { "reporter_id": "890900608", "reporter_name": "BANCOLOMBIA S.A.", "reported_id": "1234567890", "reported_name": "JUAN PEREZ GOMEZ", "concept": "Saldo cuentas bancarias", "amount": 4200000, "suggested_use": "Patrimonio", "additional_info": "Cuenta de ahorros ****1234" } ] } } ``` Every call reads DIAN live as your connection, so the answer is current and is never shared between organizations. This lookup can take longer than a typical request. It is an [async job](/async-jobs). By default the request waits inline and returns `{ data }`, or you can poll / use a `callback_url`. Schemas, all response fields, and an interactive playground. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.