> ## 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 own tax records at Colombia's DIAN: the electronic invoices issued to them and what third parties reported about them, 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, used on their own behalf. 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 |
| - | - | - |
| `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, 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, so an agent can connect the user's account in conversation.

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). |

<Note>
  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.
</Note>

## Electronic invoices

`POST /co/dian-muisca/electronic-invoices/v1`

| Field | Type | Notes |
| - | - | - |
| `year` | integer | **Required.** The tax year (año gravable). DIAN offers electronic invoices from 2023 onward. |
| `connection_id` | string | Optional. Run as this connection (`conn_…`). Empty lets Croma pick among your organization's connections, moving to the next one when one reaches its daily allowance. |

```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_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_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..."
      }
    ]
  }
}
```

<Note>
  Every call reads DIAN live as your connection, so the answer is current and
  is never shared between organizations.
</Note>

<Note>
  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`.
</Note>

## Third-party reports

`POST /co/dian-muisca/third-party-reports/v1`

| Field | Type | Notes |
| - | - | - |
| `year` | integer | **Required.** The tax year (año gravable). Third-party reports go back to 2018. |
| `connection_id` | string | Optional. Run as this connection (`conn_…`). Empty lets Croma pick among your organization's connections, moving to the next one when one reaches its daily allowance. |

```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`. |
| `taxpayer` | The account holder's `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",
    "taxpayer": { "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"
      }
    ]
  }
}
```

<Note>
  Every call reads DIAN live as your connection, so the answer is current and
  is never shared between organizations.
</Note>

<Note>
  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`.
</Note>

<Card title="Full reference" icon="code" href="/api-reference/overview">
  Schemas, all response fields, and an interactive playground.
</Card>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.