Use the [production schemas](/reference/schemas/) for field names and types. Keep clinical decisions in the authorized source system. The API cannot infer missing diagnoses, doses, or professional identities.

## Patient and professional are different people

Within `usuarios[]`, `tipoDocumentoIdentificacion` and `numDocumentoIdentificacion` identify the **patient**.

Inside a service, the same field names identify the **professional who provided that service**, where those fields apply. Map them from an active workspace specialist. Do not copy the patient's identity into a service's professional fields.

Use the [health professionals](/reference/#health-professionals) and [patients](/reference/#patients) endpoints to manage the two records separately.

## Provider and site

Read the workspace's [RIPS context](/reference/operations/rips-packages-get-context/). Map `codPrestador` from the configured provider or site. Keep leading zeroes. A provider code is not a free-text label or the professional's document number.

## Identifiers and dates

| Value                             | Representation                                                                  |
| --------------------------------- | ------------------------------------------------------------------------------- |
| Resource IDs                      | Opaque strings; preserve exactly                                                |
| Document numbers and codes        | Strings; preserve leading zeroes                                                |
| Administrative timestamps         | UTC ISO 8601                                                                    |
| Civil dates, including birth date | `YYYY-MM-DD`                                                                    |
| RIPS service time                 | Local `YYYY-MM-DD HH:mm`                                                        |
| Native RIPS money fields          | JSON numbers                                                                    |
| Invoice amounts                   | Decimal strings recommended; JSON numbers also accepted where the schema allows |

Do not convert a RIPS local service time to UTC. Do not add thousands separators to numeric amounts.

## Source profiles and original files

The package input includes source profile metadata. The current schema lists `native-d558206`, `ministry-v003-20260715`, and `history`. Select the profile that matches your actual input. Do not label historical data as current without mapping it.

Draft input can preserve the original JSON text and additional source fields. This supports corrections; it does not mean those fields pass the current validation rules. The validation response identifies native and ministry field conditions.

## Medication catalogs

Read [catalog metadata](/reference/operations/catalog-get-medication-metadata/) before you use a pinned CUM or IUM catalog. Search results are paginated with `after` and return `next`; stop when `next` is null. A catalog may omit display names. Never infer dosage or another clinical field from a presentation name.

This API does not publish a search endpoint for every clinical catalog. Use the required official source for codes not covered by the API.

## Lists and archived records

| Resource family                  | Request                                               | Response                                  |
| -------------------------------- | ----------------------------------------------------- | ----------------------------------------- |
| Master records and RIPS packages | `limit` (default 100, max 500), `offset` (default 0)  | `items`, `total`, `limit`, `offset`       |
| Health invoices and notes        | `page` (default 1), `pageSize` (default 100, max 500) | `items`, `totalCount`, `page`, `pageSize` |
| Medication search                | `limit` (default 50, max 100), `after`                | Results and `next` cursor                 |

Lists omit archived records unless you request `includeArchived=true` where supported. Archive operations retain the business record. Use the corresponding restore operation to reactivate it.