DIAN My Tax Account

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.

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
      }'

{
  "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. List and delete them:

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, 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. 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`.

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.

{
  "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. 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`.

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

{
  "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. By default the request waits inline and returns { data }, or you can poll / use a callback_url.

Full reference

Schemas, all response fields, and an interactive playground.

Get Started

Request types

Monitors

Countries

DIAN My Tax Account

Connect your account

Electronic invoices

Response

Third-party reports

Response

Full reference

​Connect your account

​Electronic invoices

​Response

​Third-party reports

​Response

Full reference

Connect your account

Electronic invoices

Response

Third-party reports

Response