---
title: "Connect a DIAN account"
method: POST
path: "/co/dian-muisca/connections/v1"
tags: ["Colombia", "DIAN"]
---

# Connect a DIAN account

`POST /co/dian-muisca/connections/v1`

## Request

- Base URL: `https://api.croma.run`
- URL: `https://api.croma.run/co/dian-muisca/connections/v1`
- Auth: HTTP bearer

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.

Croma checks the account with the source before saving it.

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.

## Request body

- object
  - `sign_in_as` 'self' | 'third_party': How the account signs in: `self` reads the person's own records (a nombre propio); `third_party` reads the records of the person or company whose NIT goes in `on_behalf_of_nit`, which the person represents at DIAN (a nombre de un tercero). Defaults to `self`.
  - `on_behalf_of_nit` string: The NIT of the third party, without the verification digit, dots or dashes. Required when `sign_in_as` is `third_party`; leave empty for `self`.
  - `document_type` 'CC' | 'CE' | 'TI' | 'RC' | 'PA' | 'PEP' | 'PPT': Colombian document type. Defaults to `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, password, required: The password of that DIAN account.
  - `authorized` true, required: Confirms you are the account's owner or have the owner's authorization to use it.

## Response `201`

Connected

- object
  - `data` object
    - `id` string: The connection's id, `conn_…`.
    - `source` string
    - `status` 'active' | 'exhausted' | 'invalid': `exhausted` until its daily allowance resets; `invalid` when the source no longer accepts it.
    - `display_name` string, nullable: The account's name as the source shows it, masked.
    - `usage` object, nullable
      - `sign_ins_today` integer
      - `daily_limit` integer, nullable
      - `resets_at` string, date-time
    - `available_again_at` string, date-time, nullable
    - `created_at` string, date-time
    - `last_used_at` string, date-time, nullable

## Other responses

- `400`: Invalid request body
- `401`: Missing or invalid API key
- `409`: `connection_exists`: the account is already connected
- `422`: `connection_rejected`: the source did not accept the account, or `connection_limit_reached`
- `429`: `connections_exhausted`: the account has no sign-ins left today
- `503`: `connection_unverified`: the source could not check it right now

---

[API](https://skmtc.dev/usecroma/apis/croma-marketplace-api.md) · [All operations](https://skmtc.dev/usecroma/apis/croma-marketplace-api/llms.txt) · [OpenAPI document](https://skmtc.dev/usecroma/apis/croma-marketplace-api/revisions/df016cdb29d7?raw)