Data Models API

This API allows managing data models in the system. It provides endpoints to create, read, update, and delete data models, as well as to perform queries with filtering and pagination options.

The DataModel Object

The DataModel object represents a data model in the system.

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "path": "/ruta/ejemplo",
  "key": "modelo_ejemplo",
  "label": "Modelo de Ejemplo",
  "entityType": "identity",
  "priority": 1,
  "order": null,
  "allowedValues": null,
  "createdAt": "2023-05-01T12:00:00Z",
  "updatedAt": "2023-05-02T14:30:00Z",
  "isSensitive": false,
  "metadata": {
    "descripcion": "Este es un modelo de ejemplo"
  },
  "processing": null
}

Attributes

Valid Entity Types

The entityType field must be one of the following values:

Available Operations

Create a New Data Model

Creates a new data model in the system.

POST /v1/data-models

Input Parameters:

*For entityType: "identity", priority is required and must be greater than or equal to -1.

Request Example:

{
  "path": "/ruta/ejemplo",
  "key": "modelo_ejemplo",
  "label": "Modelo de Ejemplo",
  "entityType": "identity",
  "priority": 1,
  "isSensitive": false,
  "metadata": {
    "descripcion": "Este es un modelo de ejemplo"
  }
}

Successful Response:

{
  "id": "123e4567-e89b-12d3-a456-426614174000"
}

Update a Data Model

Updates an existing data model.

PATCH /v1/data-models/:data_model_id

Path Parameters:

Input Parameters:

Note: isSensitive cannot be updated via PATCH. Use the dedicated make-sensitive endpoint below.

Request Example:

{
  "label": "Updated Example Model",
  "priority": 2
}

Successful Response:

The response will be the updated DataModel object.

Make an Identity Data Model Sensitive

Marks an existing identity DataModel as sensitive and encrypts existing identities for that key.

PUT /v1/data-models/:data_model_id/make-sensitive

Path Parameters:

Successful Response:

The response will be the updated DataModel object (with isSensitive: true).

Save the Processing Definition of a Document Data Model

Saves the processing block of a document data model: the fields to extract, the validation conditions with what is expected of each one, and, for advanced configurations, several document types, validations, logic rules and document rules. In the Hub these are the Details tab (fields to extract) and the Validation tab of the data model. The Document Processing guide explains each part, maps every Hub name to its key and describes the rule grammar. This is the only way to write processing; POST and PATCH never touch it.

PUT /v1/data-models/:data_model_id/processing

Requires the configurations.write permission. Only data models with entityType: "document" accept it.

Path Parameters:

Input Parameters:

Each item of documentTypes:

Each item of fields is a row of the Details tab, of the Validation tab, or of both:

expected is {"op": ..., "value": ...}. Which op each row type accepts:

A condition's key does not need to be among the fields to extract. Keys are unique within a type, so a value that is extracted and checked is one row with purpose: "both".

Request Example:

Two fields to extract and two conditions, on a single type without a description:

{
  "expectedVersion": 1,
  "documentTypes": [
    {
      "key": "acta_constitucion",
      "label": "Acta de constitución",
      "fields": [
        { "key": "razon_social", "type": "string", "description": "Razón social de la compañía" },
        { "key": "fecha_constitucion", "type": "date", "description": "Fecha de constitución" },
        { "key": "es_acta", "type": "boolean", "description": "¿El documento es un acta de constitución de una compañía?",
          "purpose": "validation", "expected": { "op": "is_true" } },
        { "key": "puede_endeudar", "type": "boolean", "description": "¿El acta autoriza al representante a endeudar a la empresa?",
          "purpose": "validation", "expected": { "op": "is_true" } }
      ]
    }
  ]
}

An advanced configuration, with a described type, required fields, a validation and a logic rule:

{
  "expectedVersion": 2,
  "documentTypes": [
    {
      "key": "planilla_luz",
      "label": "Planilla de luz",
      "description": "Planilla mensual del servicio de energía eléctrica con el titular, la dirección del suministro, la fecha de emisión y el total a pagar.",
      "fields": [
        { "key": "titular", "label": "Titular", "type": "string", "description": "Nombre completo del titular de la cuenta", "required": true },
        { "key": "fecha_emision", "label": "Fecha de emisión", "type": "date", "description": "Fecha de emisión de la planilla", "required": true, "minConfidence": 0.85, "format": { "dateOrder": "dmy" } },
        { "key": "monto_total", "label": "Total a pagar", "type": "number", "description": "Total a pagar del periodo", "required": true, "format": { "numberFormat": "us" } }
      ],
      "validations": [
        { "key": "vigente", "label": "Emitida en los últimos 60 días", "severity": "blocking", "rules": { "field": "fecha_emision", "operator": "within_last_days", "value": 60 } }
      ],
      "logic": [
        { "key": "aplica_beneficio", "label": "Total menor a 50", "rules": { "field": "monto_total", "operator": "less_than", "value": 50 } }
      ]
    }
  ],
  "documentRules": { "acceptedTypes": { "anyOf": ["planilla_luz"] } }
}

Successful Response:

The updated DataModel object. Its processing holds the definition with the defaults filled in. A field to extract is stored without purpose, so it is the same object as a field saved before this key existed.

The server also derives two things from the conditions, which you see when you read the data model back:

• each row with purpose validation or both becomes a blocking validation of its type, with the key __expected_<field key>, added after your own validations;
• with at least one condition, documentRules.unrecognizedFiles is invalid: a file that matches none of the types is invalid instead of needs_review. It only applies when there is a recognition step.

Both are managed by the server. They are dropped from any body you send and derived again, so a GET followed by a PUT of the same processing stores the same definition, and a hand-edited __expected_* validation is replaced by the one its row produces. A user key can never start with _, so these never collide with yours.

Four more fields are managed by the server (they are ignored if you send them):

Validation errors:

Every problem is reported at once, in a single 400 with errorSubCode: "PROCESSING_DEFINITION_INVALID". Each entry of details.errors has a code, a path (a JSON pointer into the body you sent) and a message:

{
  "code": "BadRequestError",
  "message": "The processing definition has 2 problems",
  "details": {
    "errorSubCode": "PROCESSING_DEFINITION_INVALID",
    "errors": [
      { "code": "PROCESSING_UNKNOWN_FIELD", "path": "/documentTypes/0/validations/0/rules/field", "message": "Field 'fecha' is not defined in type 'planilla_luz'" },
      { "code": "PROCESSING_OPERATOR_TYPE_MISMATCH", "path": "/documentTypes/0/logic/0/rules/operator", "message": "Operator 'greater_than' does not apply to a 'string' field" }
    ]
  }
}

Other errors of this endpoint:

Test a Processing Definition

Runs a definition against one uploaded file and returns the result. Nothing is stored: no document, no results and no images. It is what Test with a file does in the Hub.

POST /v1/data-models/:data_model_key/processing/test

Requires the configurations.write permission. Unlike the PUT, this route takes the data model key, not its id; it is the same key as the documents it applies to.

Path Parameters:

Form Parameters (multipart/form-data):

Successful Response:

{
  "persisted": false,
  "definitionHash": "sha256:5d1c...",
  "modelId": "model-id",
  "now": "2026-10-21T15:00:00Z",
  "attempts": 1,
  "modelCalls": 2,
  "file": {
    "outcome": "processed",
    "documentType": { "key": "planilla_luz", "label": "Planilla de luz", "confidence": 1.0, "minConfidence": 0.6 },
    "fields": [ "..." ],
    "validations": [ "..." ],
    "logic": [ "..." ],
    "status": "valid",
    "statusReasons": [],
    "pages": [ { "page": 2, "width": 1240, "height": 1600, "mimeType": "image/jpeg", "imageBase64": "..." } ],
    "pageCount": 2,
    "crops": []
  },
  "pagesTruncated": false,
  "pageCount": 2,
  "document": { "status": "valid", "statusReasons": [], "acceptedTypes": { "...": "..." }, "validations": [] },
  "mode": "both",
  "extraction": {
    "current": true,
    "status": "extracted",
    "values": { "valor_pagar": 42.75, "fecha_emision": "2026-10-15", "valor_mayor_50": false },
    "evidence": { "...": "..." }
  },
  "validation": {
    "current": true,
    "status": "valid",
    "valid": true,
    "reasons": [],
    "rows": [ "..." ],
    "otherRules": []
  }
}

file has the same shape as one attachment's result in the Documents API (section "Get the Processing Results of a Document"), except that page images come inline as base64 and there are no crops. At most 10 page images come back: first the pages where a value was found (values to review before the rest), then the lowest-numbered pages, all in page order. pageCount, in file and at the top, is the number of pages in the file, and pagesTruncated is true when there were more than 10 page images.

mode, extraction and validation are the same as for one attachment in the Documents API, computed with the tested definition: mode is extraction, validation or both, and a block is null when the definition has no part of that kind. current is always true, and pageUrl and cropUrl in the blocks are null, because the pages come inline. With a single file, a document that needs several types will usually not be satisfied.

Errors:

Get a Data Model

Retrieves the information of a specific data model.

GET /v1/data-models/:data_model_id

Path Parameters:

Successful Response:

The response will be a complete DataModel object.

Delete a Data Model

Deletes a data model from the system.

DELETE /v1/data-models/:data_model_id

Path Parameters:

Successful Response:

Status code 204 (No Content) if the deletion was successful.

List Data Models

Retrieves a paginated list of data models with filtering and sorting options.

GET /v1/data-models

Query Parameters:

Successful Response:

The response will be a paginated list of DataModel objects.

Error Handling

The API may return the following error codes:

Errors will include a descriptive message in the response body.