> ## Documentation Index
> Fetch the complete documentation index at: https://docs.syntage.com/llms.txt
> Use this file to discover all available pages before exploring further.

# API Changelog

> API updates, documentation changes, and integration-impacting changes

**October 19, 2026**

Leasing regime (606)

Rental-only provisional tax returns of the leasing regime (606), Régimen de Arrendamiento, in which a person declares the rent of real estate, now return their variables.

### Provisional tax return variables

**Affected endpoints:** `GET /tax-returns/{id}/data`

* For rental-only declarations of the leasing regime (606), which pay no ISR other than the rental ISR, `sales_revenue` and `cash_inflow` are the month's rental income, as declared in its "Ingresos del mes": the income collected plus additional income, minus income to decrease. Older declarations print it as "Total de ingresos". These declarations previously returned `404`.
* `cash_outflow`, `number_of_employees`, and `payroll_amount` are not available for these declarations and are `null`.
* A declaration that also declares another detected regime keeps returning that regime's variables. A declaration that also pays an ISR of a regime that is not detected still returns `404`.
* Values for returns extracted before this change are updated as they are reprocessed. No new extraction is required.

**October 19, 2026**

AGAPES regime (622) provisional tax returns

Monthly provisional ISR tax returns of companies (personas morales) under the AGAPES regime (622), Actividades Agrícolas, Ganaderas, Silvícolas y Pesqueras, now return their data.

### Provisional tax return variables

**Affected endpoints:** `GET /tax-returns/{id}/data`

* These declarations previously returned `404`.
* `sales_revenue` and `cash_inflow` are the month's income, as declared in its "Ingresos del periodo".
* `cash_outflow`, `number_of_employees`, and `payroll_amount` are not available for these declarations and are `null`.
* Values for returns extracted before this change are updated as they are reprocessed. No new extraction is required.

**October 19, 2026**

Insight requests that cannot be completed

Insight requests that cannot be completed at the moment now return `503 Service Unavailable` with a `Retry-After` header. They previously returned `500 Internal Server Error`.

### Insights

**Affected endpoints:** insight endpoints under `GET /entities/{entityId}/insights/` and `GET /insights/`

* Wait the number of seconds in `Retry-After` before retrying the same request.
* If the same request keeps returning `503`, request a shorter period, where the endpoint accepts one, instead of retrying it unchanged.
* Avoid sending the same request again while an earlier one is still pending, and avoid immediate retry loops.
* Other server errors still return `500`.

**October 8, 2026**

Digital platforms regime (625)

Provisional and annual tax returns of the digital platforms regime (625), Régimen de las Actividades Empresariales con ingresos a través de Plataformas Tecnológicas, now return their data, and sandbox person entities can use this regime.

### Provisional tax return variables

**Affected endpoints:** `GET /tax-returns/{id}/data`

* For declarations of the digital platforms regime (625), `sales_revenue` and `cash_inflow` are the month's platform income, as declared in its "Ingresos totales del mes".
* `cash_outflow`, `number_of_employees`, and `payroll_amount` are not available for these declarations and are `null`.

### Annual tax return data

**Affected endpoints:** `GET /tax-returns/{id}/data`, `GET /entities/{entityId}/insights/metrics/income-statement`, `GET /entities/{entityId}/insights/metrics/balance-sheet`, `GET /entities/{entityId}/insights/summary`

* Annual tax returns of the digital platforms regime (625) now return their data under `PLATAFORMAS TECNOLÓGICAS`: the year's platform income in total and by type of service, authorized deductions, fiscal result, provisional payments, ISR withheld by the platforms, and the return's tax determination. These returns have no balance sheet, and their income figures are only under `PLATAFORMAS TECNOLÓGICAS`, so `ESTADO DE RESULTADOS` and the other financial statement keys are empty.
* These returns were previously identified as regime 601 and returned empty financial statements. Their tax regime is now 625, including the `taxRegime` reported by the income statement and balance sheet insights. Values for returns extracted before this change are updated as they are reprocessed. No new extraction is required.
* In the `2014` format, the income statement insight returns these returns' income in total and by type of service, authorized deductions, fiscal profit or loss, profit sharing paid, prior-year losses, and taxable profit. The balance sheet insight has no values for them, because the declaration has no balance sheet.
* The summary insight's figures from the latest annual return use these returns' platform income, taxable profit, and fiscal profit or loss. They were previously `0`.

### Sandbox entity creation

**Affected endpoints:** `POST /entities`

* Person entities also accept 625 in the optional `metadata.sandbox.taxRegime` field.
* When the field is omitted, new person entities can also be assigned 625. Existing entities keep their regime.

**September 28, 2026**

Taxable base of invoice line item taxes

Each entry of an invoice line item's `taxes` now includes the taxable base from the CFDI.

### Invoice line items

**Affected endpoints:** `GET /invoices/line-items/{id}`, `GET /invoices/{invoiceId}/line-items`, `GET /entities/{entityId}/invoices/line-items`, `GET /invoices/{id}`, `GET /entities/{entityId}/invoices`

* New `base` field on each `taxes` entry: the `Base` attribute of the CFDI `Traslado` or `Retencion` node, with the decimals of the CFDI.
* Invoice responses include the same `taxes` entries in their `items`, so those entries also include `base`.
* A tax can apply to only part of a line item, so `base` can be lower than `totalAmount`. Use `base` with `factor.amount` to validate `amount` instead of deriving the base from other fields.
* `base` is reported for `rate`, `share`, and `exempt` factor types, and is `null` when the CFDI does not include it.
* `base` is present for line items processed after this change. Line items processed earlier do not include it until their invoice is processed again.

**September 23, 2026**

Provisional tax return variables for IVA-only declarations and zero amounts

Variables of provisional tax returns are now available for IVA-only declarations of companies, and amounts declared as zero are reported as `0`.

### Provisional tax return variables

**Affected endpoints:** `GET /tax-returns/{id}/data`

* A company (persona moral) can file IVA on a declaration of its own, separate from its ISR declaration. These declarations now return `cash_inflow` and `cash_outflow`, calculated from the declaration's IVA section. They previously returned `404`.
* For IVA-only declarations, `sales_revenue`, `number_of_employees`, and `payroll_amount` are `null`, because these amounts are declared in the ISR declaration for the same period, which is a separate tax return.
* A variable is `0` when the declaration prints the amounts it is derived from as zero, for example on a declaration filed in zeros. A variable is `null` when the declaration does not contain those amounts. Zero amounts were previously reported as `null`.
* Values for returns extracted before this change are updated as they are reprocessed; refresh any values stored by your integration. No new extraction is required.

**September 22, 2026**

Invoice line item taxes

The `taxes` field of invoice line items is no longer marked as deprecated and remains fully supported.

### Invoice line items

**Affected endpoints:** `GET /invoices/line-items/{id}`, `GET /invoices/{invoiceId}/line-items`, `GET /entities/{entityId}/invoices/line-items`

* `taxes` provides the complete tax detail of the line item: one entry per tax in the CFDI, with its tax code, factor type, rate or quota, and amount.
* `retainedTaxes` and `transferredTaxes` provide one amount per tax type and do not include rates. Use `taxes` when you need rates or when a line item applies the same tax at more than one rate.
* The API reference now documents the structure of `taxes` entries, including the values of `type`, `tax`, and `factor.type`.
* `retainedTaxes` and `transferredTaxes` amounts are documented as nullable. An amount is `0` when the line item does not include that tax, and `null` for line items extracted before 2023.
* API responses are unchanged.

**September 18, 2026**

Provisional tax return income variables

Income variables extracted from provisional (monthly) tax returns now follow the net amounts printed on the SAT return.

### Provisional tax return variables

**Affected endpoints:** `GET /tax-returns/{id}/data`

* For regime 601 (Personas Morales), `sales_revenue` is the return's `INGRESOS NOMINALES`: invoiced income plus additional income minus income to decrease. It previously reported only the invoiced income.
* For regime 601, `cash_inflow` now includes the value of exempt activities. It previously omitted them.
* For regimes 612 (PFAE) and 626 (RESICO), `cash_inflow` (and `sales_revenue` for 612) is the return's net collected income, which subtracts income to decrease. It previously ignored that deduction.
* Values for returns extracted before this change are updated as they are reprocessed; refresh any values stored by your integration. No new extraction is required.

**September 16, 2026**

Filter entities by extraction status

### Entities

**Affected endpoints:** `GET /entities`

* New `extractions.status` query parameter: lists the entities with at least one extraction in that status (exact match), for example `GET /entities?extractions.status=waiting` for the entities blocked on a requirement they must fulfil, such as SAT credentials or a Buró de Crédito authorization.
* Combined with the existing `extractions.datasource` parameter, both conditions apply to the same extraction: `GET /entities?extractions.datasource=sat&extractions.status=waiting` lists the entities whose SAT extraction is waiting, not the ones with a SAT extraction and some other waiting extraction.
* The `ExtractionStatus` schema now documents `waiting` and `cancelled`, which were missing.

**September 15, 2026**

Configurable Buró de Crédito / Buró Empresas authorization term

The term a Buró de Crédito / Buró Empresas authorization grants is now set per bureau instead of always being three years.

### Buró de Crédito / Buró Empresas authorizations

**Affected endpoints:** `GET /datasources/mx/buro-de-credito/authorizations`, `GET /datasources/mx/buro-de-credito/authorizations/{id}`, `GET /entities/{entityId}/datasources/mx/buro-de-credito/authorizations`, `POST /entities/{entityId}/datasources/mx/buro-de-credito/authorizations`, `GET /organization/integrations/buro-de-credito`, `PUT /organization/integrations/buro-de-credito`

* Each authorization now includes `validityYears`, the term in years it was signed under. `authorizedUntil` is `authorizedAt` plus that many years, so the two can no longer disagree.
* `POST` derives `authorizedUntil` from the term your organization configured for the entity's bureau: Buró de Crédito for people, Buró Empresas for companies. Organizations that have not set one keep the previous three-year behaviour, and no request field changed.
* Existing authorizations report `validityYears: 3`, the term they were created under. Changing the configured term never alters authorizations that were already granted, in either direction.
* `GET /organization/integrations/buro-de-credito` returns the configured terms as `configuration.physicalAuthorizationValidityYears` (Buró de Crédito) and `configuration.legalAuthorizationValidityYears` (Buró Empresas), each an integer from 1 to 3, or `null` when the organization has not set one. `PUT` on the same path accepts them, with `null` restoring the default. That request replaces the whole configuration object, so send every field you want to keep on each call, not only the one you are changing.
* If your integration recomputes an expiry date by adding three years to `authorizedAt`, read `validityYears` or `authorizedUntil` instead.

**September 14, 2026**

Personal entity favorites

### Entity favorites

**Affected endpoints:** `POST /entities/favorites`, `DELETE /entities/favorites`, `GET /entities`, `GET /entities/{entityId}`

* Add or remove one or more personal favorites with the same JSON body containing 1–100 entity IRIs. Operations are atomic, return `204 No Content` without a response body, and are safe to repeat.
* GET entity list and item responses include the authenticated user's `isFavorite` state by default. When selecting response fields with `properties[]`, include `properties[]=isFavorite` to receive it. Filter collections with `isFavorite=true` or `isFavorite=false`.
* Favorites remain subject to entity access restrictions. Read-only users can manage their own favorites using JWT authentication.

**September 13, 2026**

Company Verification data access documentation

### Company Verification data

**Affected endpoints:** `GET /entities/{entityId}/insights/corporate-structure/current-powers`, `GET /entities/{entityId}/insights/metrics/shareholders`

* Removed documentation for the obsolete report-level found-entities endpoint.
* The Current Powers insight returns people with currently effective powers from the entity's most recent Company Verification report.
* The API reference now documents the shareholders metrics insight for retrieving shareholder rows from the entity's most recent Company Verification report when available. Manually entered values take precedence for relations that have both sources.

**September 9, 2026**

PFAE financial ratio inputs

### Financial ratios

**Affected endpoints:** `GET /entities/{entityId}/insights/financial-ratios`, `GET /taxpayers/{entityId}/insights/financial-ratios`, `GET /insights/{entityId}/financial-ratios`

* PFAE current assets now include cash, receivables, other current assets, contributions in favor, and inventory. The sum of accounts payable, other liabilities, and contributions payable is used as a proxy for current liabilities because the return does not distinguish liability maturities.
* This corrects `current_ratio`, `quick_ratio`, `cash_ratio`, `net_working_capital_to_sales`, and `sales_to_capital_employed`. Historical years are recalculated on subsequent requests; refresh any values stored by your integration. No new extraction is required.

**September 3, 2026**

Current SAT 69-B blacklist status

SAT 69-B status fields now reflect the RFCs in the current SAT publication.

### SAT 69-B blacklist status

**Affected endpoints:** `GET /entities/{entityId}/invoices`, `GET /invoices/{id}`, `GET /entities/{entityId}/insights/invoicing-blacklist`, `POST /background-checks`, `GET /background-checks/{id}`

* When no current SAT blacklist source lists an RFC, invoice issuer and receiver `blacklistStatus` fields become `null`, and the RFC no longer contributes to the invoicing blacklist insight.
* New SAT background checks no longer report an RFC as listed based only on an earlier publication.

**September 1, 2026**

Export progress webhook events

Export webhook deliveries now focus on customer-relevant changes.

### Export webhooks

**Affected events:** `export.updated`

* `export.updated` is no longer delivered when the export's internal processed-item progress is the only change.
* Trackable export changes continue to deliver the event, without internal processed-item progress in the `changes` payload.

**September 1, 2026**

Legacy insight PDF export removal

Insight report PDFs now use the asynchronous Exports API exclusively.

### Insight report PDFs

**Affected endpoints:** `POST /insights/{entityId}/export`, `POST /exports`

* The legacy `POST /insights/{entityId}/export` endpoint is no longer available.
* To generate an insight report PDF, create an export with `format` set to `pdf` and `uri` set to `/entities/{entityId}/reports/{reportId}?exporting=true`, then poll the export until it finishes and download its `report.insights.pdf` file.

**August 21, 2026**

Tax return data availability errors

Tax return data requests now explain when the declaration has no supported structured data.

### Tax return data

**Affected endpoints:** `GET /tax-returns/{id}/data`

* When the tax return exists but has no supported structured data, the endpoint continues to return `404 Not Found` and now includes the detail `No supported structured data is available for this tax return.`
* Successful responses and their data format are unchanged.

**August 17, 2026**

RPC document structure availability

Registro Público de Comercio (RPC) documents now tell you whether a structure tree is available before you request it.

### RPC documents

**Affected endpoints:** `GET /entities/{entityId}/datasources/mx/rpc/documents`, `GET /entities/{entityId}/datasources/mx/rpc/documents/{documentId}`

* Each document now includes a boolean `hasStructure`. When it is `true`, `GET /entities/{entityId}/datasources/mx/rpc/documents/{documentId}/structure` returns the document's structure tree; when it is `false`, that endpoint returns `404`, so you can skip the call.
* Existing response fields are unchanged.

**August 12, 2026**

Sandbox fiscal profiles

Sandbox entities can now use a stable fiscal profile across tax status and applicable tax-return extractions.

### Sandbox entity creation

**Affected endpoints:** `POST /entities`

* The optional `metadata.sandbox.taxRegime` field selects the simulated fiscal profile for a sandbox entity.
* Person entities accept 605, 612, 621, or 626. Company entities accept 601 or 626.
* When the field is omitted, sandbox selects a stable compatible profile automatically.
* Sandbox has no reserved RFCs; use any valid-format RFC for the selected entity type.
* Production entity creation accepts the optional metadata without changing datasource behavior.

**August 12, 2026**

RPC document structure

Registro Público de Comercio (RPC) documents now expose their filed form as a structured tree, so you can render a document the way it was registered instead of reading the flat `data` object.

### RPC document structure

**Affected endpoints:** `GET /entities/{entityId}/datasources/mx/rpc/documents/{documentId}/structure`

* The new endpoint returns the document's structure-preserving tree. Each node carries its widget `type` and original `label` (plus its element `id` when the registry assigns a stable one), and either a scalar `value` (leaves) or nested `children` (sections and tables); table rows and cells are nested under their table.
* The tree keeps the original field labels (for example "Denominación o razón social") and the empty rows the flat `data` projection drops, so it reflects the filing as registered.
* The tree is derived on demand and returns `404` when the document is not found or its structure is unavailable.
* The `data` field on `GET /entities/{entityId}/datasources/mx/rpc/documents/{documentId}` is unchanged.

**August 7, 2026**

Network insight RFCs

Customer and vendor network insight rows now identify each counterparty by both name and RFC.

### Customer and vendor networks

**Affected endpoints:** `GET /entities/{entityId}/insights/metrics/customer-network`, `GET /entities/{entityId}/insights/metrics/vendor-network`

* Customer network rows now include `customerRfc` alongside `customer`.
* Vendor network rows now include `vendorRfc` alongside `vendor`.
* XLSX exports for both insights include the RFC as a separate column.
* Existing response fields are unchanged.

**July 29, 2026**

RPC documents

The Registro Público de Comercio (RPC) datasource now exposes documents as a resource, grouping the actos that belong to each filing.

### RPC documents

**Affected endpoints:** `GET /entities/{entityId}/datasources/mx/rpc/documents`, `GET /entities/{entityId}/datasources/mx/rpc/documents/{documentId}`

* `GET /entities/{entityId}/datasources/mx/rpc/documents` returns every document filed under the entity, each with its `actos` nested plus an `actosCount`. Documents are deduplicated by the content hash computed from the filing, so distinct filings that share a `numeroDeDocumento` and `nci` stay separate.
* The collection accepts an optional `?entidade={uuid}` query parameter to scope the documents to a single registry entidade. A malformed id returns `400`, and an entidade that does not belong to the entity returns `404`.
* `GET /entities/{entityId}/datasources/mx/rpc/documents/{documentId}` returns a single document. Its structured `data` field is included only for organizations entitled to it.
* Each document exposes a `fileId`; its PDF is downloaded via `GET /files/{fileId}/download`. The PDF belongs to the document, so every acto under a document resolves to the same file.
* The existing `/datasources/mx/rpc/actos` response is unchanged.

**July 22, 2026**

Optional entity names

Entity creation can now resolve the legal name from the RFC when you do not send a name.

### Entity creation

**Affected endpoints:** `POST /entities`

* The `name` field is now optional when you send a valid `rfc`.
* When `name` is omitted or null, Syntage resolves the entity's legal name during creation and returns the created entity with that name.
* If no name is available for the RFC, the request returns a `400` validation error on `name` with code `rfc_valid_no_name_on_file`. Retry with an explicit `name` to create the entity.
* Sending an explicit `name` is unchanged; Syntage stores the name you provide.

**July 21, 2026**

Stop running exports

You can now stop an export that is still pending or running instead of waiting for it to finish or fail.

### Exports

**Affected endpoints:** `DELETE /exports/{id}/stop`

* Stopping an export responds with `204 No Content`. The export moves to the new `stopping` status and then to `stopped` once the cancellation completes; partial results are discarded.
* `status` on export responses can now also be `stopping` or `stopped` in addition to `pending`, `running`, `finished`, and `failed`.
* Requests for an export that is already `finished`, `failed`, or `stopped` return `409 Conflict`.
* Only collection exports can be stopped. Insight report and Buró de Crédito exports return `409 Conflict`.
* Only the user who created the export can stop it.

**July 20, 2026**

Extraction plan limit errors

Extraction creation now reports which plan limit was reached instead of returning a single combined message.

### Extraction creation

**Affected endpoints:** `POST /extractions`, `POST /extractions/batch`

* Validation errors previously returned one message covering every limit ("...the limit of processed entities or number of extractions"). That message is gone.
* Errors now identify the specific limit reached: the number of extractions in your plan, the number of processed entities in your plan, or a limit that applies to a single extractor.
* When more than one limit is reached by the same request, the response now contains **one violation per limit** rather than a single violation. Consumers that read only the first violation will still work, but will no longer see every reason the request was rejected.
* Extractor-specific limits direct you to contact support, as they are not shown in `GET /account/usage`.

**July 14, 2026**

Batch entity tagging

You can now add or remove tags on up to 100 entities in a single request, matching the batch tagging released for invoices.

### Batch entity tagging

**Affected endpoints:** `POST /entities/batch/tags`, `POST /entities/batch/tags/remove`

* `POST /entities/batch/tags` adds one or more tags to every entity in the request.
* `POST /entities/batch/tags/remove` removes one or more tags from every entity in the request.
* Both endpoints accept up to 100 entity IRIs (`resources`) and 50 tag IRIs per request and respond with the IDs of the affected entities and tags. Tag IRIs are accepted in both the `/entity-tags/{id}` and `/link-tags/{id}` forms.
* Both operations are atomic: if any entity or tag in the request cannot be found, no entity is modified.
* Both operations are idempotent: adding a tag an entity already has, or removing a tag it does not have, succeeds without changes, so requests can be retried safely.
* Unlike `PATCH /entities/{entityId}` with a `tags` array (which replaces the full tag set), these endpoints apply deltas and leave other tags on the entity untouched.

```json theme={null}
POST /entities/batch/tags
{
  "resources": [
    "/entities/91106968-1abd-4d64-85c1-4e73d96fb997",
    "/entities/e58e50e8-4913-4046-b48e-11c53575ee7b"
  ],
  "tags": ["/entity-tags/018d9dd9-459f-768e-bc55-a8a72d0d3e9a"]
}
```

**July 10, 2026**

Extraction conflict responses

Extraction creation now reports an extraction already in progress as a conflict instead of a rate-limit error.

### Extraction creation

**Affected endpoints:** `POST /extractions`, `POST /extractions/batch`

* When an equivalent extraction is already in progress, both endpoints now return `409 Conflict` instead of `429 Too Many Requests`.
* Handle `409` as an extraction conflict. `429` continues to indicate request rate limiting.
* Conflict responses now include `conflictingExtractors`, an array of extractor identifiers that are already in progress. Remove those extractors before retrying the request.

**July 9, 2026**

Batch invoice tagging

You can now add or remove tags on up to 100 invoices in a single request, instead of tagging invoices one at a time.

### Batch invoice tagging

**Affected endpoints:** `POST /invoices/batch/tags`, `POST /invoices/batch/tags/remove`

* `POST /invoices/batch/tags` adds one or more tags to every invoice in the request.
* `POST /invoices/batch/tags/remove` removes one or more tags from every invoice in the request.
* Both endpoints accept up to 100 resource IRIs (`resources`, invoice IRIs on these endpoints) and 50 tag IRIs per request and respond with the IDs of the affected resources and tags.
* Both operations are atomic: if any invoice or tag in the request cannot be found, no invoice is modified.
* Both operations are idempotent: adding a tag an invoice already has, or removing a tag it does not have, succeeds without changes, so requests can be retried safely.

```json theme={null}
POST /invoices/batch/tags
{
  "resources": [
    "/invoices/91106968-1abd-4d64-85c1-4e73d96fb997",
    "/invoices/e58e50e8-4913-4046-b48e-11c53575ee7b"
  ],
  "tags": ["/tags/018d9dd9-459f-768e-bc55-a8a72d0d3e9a"]
}
```

**July 6, 2026**

Tag colors

Resource tags and entity tags now accept an optional display color, so you can render each tag with a consistent color in your integration.

### Tag color

**Affected endpoints:** `POST /tags`, `PATCH /tags/{id}`, `POST /entities/{entityId}/tags`, `PATCH /entity-tags/{id}`

* `TagCreateInput`, `TagUpdateInput`, `EntityTagCreateInput`, and `EntityTagUpdateInput` now accept an optional `color` field.
* Send a 7-character hexadecimal color in the form `#RRGGBB`. Values are validated and stored in lowercase.
* Omit the field or send `null` to fall back to the default color (`#a3aab5`).
* The `Tag` and `EntityTag` response schemas now include the `color` field.

```json theme={null}
POST /tags
{
  "name": "To be reviewed",
  "resourceType": "invoice",
  "color": "#22c558"
}
```

**July 6, 2026**

Structured fiscal address in the Summary insight

The Summary insight now returns the entity's fiscal address as structured components in addition to the existing flattened string.

### Summary insight

**Affected endpoints:** `GET /entities/{entityId}/insights/summary`, `GET /entities/{entityId}/insights/summary/export`

* Added an `address` object with the individual fiscal address components: `streetType`, `streetName`, `streetNumber`, `buildingNumber`, `streetReferences`, `neighborhood`, `locality`, `municipality`, `postalCode`, and `state`. Values come from the entity's latest Tax Status (Constancia de Situación Fiscal).
* `address` is `null` when the entity has no Tax Status yet.
* The existing `fiscalAddress` string is unchanged, so no action is required for current integrations.
* In CSV and XLSX exports, the components appear as `address.<component>` columns.

**June 24, 2026**

Shareholders insight documentation

This update documents the normalized Shareholders insight endpoint and clarifies that the older RPC Shareholders insight should no longer be used for new integrations.

### Shareholders insight

**Affected endpoint:** `GET /entities/{entityId}/insights/shareholders`

* Added API reference documentation for the Shareholders insight.
* The endpoint returns shareholder relations for an entity and supports `relations.relationType=shareholders` and `relations.relationType=shareholder_of`.
* The Shareholders insight is exportable through `GET /entities/{entityId}/insights/{insight}/export` using `shareholders` as the insight name.

### RPC Shareholders insight

**Affected endpoint:** `GET /entities/{entityId}/insights/rpc-shareholders`

* Marked the RPC Shareholders insight documentation as deprecated in favor of the Shareholders insight.
* No API response behavior changed in this documentation update.

**June 23, 2026**

API reference documentation and Shareholder insight updates

This update expands API reference sections with resource overviews, clearer endpoint descriptions, and more complete response field descriptions. It also changes how the RPC Shareholders insight selects sources and computes ownership percentages.

### Company Verification resources

**Affected endpoints:** `GET /datasources/mx/company-verification/reports/{reportId}/found-entities`, `GET /datasources/mx/company-verification/reports/{reportId}/found-entities/{id}`, `GET /datasources/mx/company-verification/reports/{reportId}/found-entities/{foundEntityId}/powers-timeline`, `GET /datasources/mx/company-verification/reports/{reportId}/cap-table-timeline`

* Added documentation for listing found entities in a Company Verification report.
* Added documentation for retrieving a specific found entity with cap-table holdings and powers.
* Added documentation for a found entity's powers timeline.
* Added documentation for a report's cap-table timeline.

### RPC Shareholders insight

**Affected endpoint:** `GET /entities/{entityId}/insights/rpc-shareholders` (also reflected in CSV and XLSX exports)

* When the entity has at least one shareholder ingested from a Company Verification report, the response now returns only the Company Verification-sourced shareholders. Previously, RPC-sourced rows for the same cap table were returned side-by-side and could conflict with the verification snapshot.
* When Company Verification data is present, ownership percentages now reflect the values recorded on the verification report. Previously, the response always returned a synthetic `shares / sum(shares) * 100` value, which produced incorrect percentages for `partes sociales` structures where share counts are zero.
* When the entity has no Company Verification-sourced shareholders, behavior is unchanged: RPC-sourced rows are returned and percentages are computed from share counts.
* **Action required:** integrations that display the `sources` field should be ready to render `company_verification` in addition to `rpc_socio` and `manual`. Integrations that recompute percentages from `shares` should switch to the `percentage` field returned by the API.

### Webhooks

**Affected endpoints:** `GET /webhook-endpoints`, `POST /webhook-endpoints`, `GET /webhook-endpoints/{id}`, `PUT /webhook-endpoints/{id}`, `DELETE /webhook-endpoints/{id}`, `GET /webhook-requests`, `GET /webhook-requests/{id}`

* The API reference now includes a Webhooks overview that explains webhook endpoints, webhook requests, delivery status, and signature verification.
* Webhook endpoint documentation now describes endpoint URL requirements, subscribed events, enabled state, content type, and signing secrets.
* Webhook request documentation now describes delivery attempts, response status codes, response time, endpoint references, and event filters.

### Insights

**Affected endpoints:** `GET /entities/{entityId}/insights/{insight}/export`, `GET /insights/metrics/scores/syntage/distribution`, `GET /entities/{entityId}/insights/metrics/buro-de-credito/summary`, `GET /entities/{entityId}/insights/metrics/buro-de-credito/summary/export`

* The API reference now includes an Insights overview that explains how insight endpoints are organized and how `options[...]` query parameters are used.
* The API reference now documents the entity-based insight export endpoint for downloading supported insights as CSV or XLSX files.
* The API reference now includes Syntage Score distribution and Buró de Crédito summary insight endpoints.

### Syntage Score

**Affected endpoint:** `POST /entities/{entityId}/datasources/syntage/score/calculate`

* The API reference now explains the annual tax return and tax compliance data required before calculating Syntage Score for an entity.
* The calculate endpoint documentation now makes clear that the endpoint starts score generation and returns `201 Created` when the calculation is queued.

### Buró de Crédito resources

**Affected endpoints:** `GET /entities/{entityId}/datasources/mx/buro-de-credito/reports`, `GET /datasources/mx/buro-de-credito/reports/{id}`, `GET /datasources/mx/buro-de-credito/authorizations`, `GET /entities/{entityId}/datasources/mx/buro-de-credito/authorizations`, `POST /entities/{entityId}/datasources/mx/buro-de-credito/authorizations`, `GET /datasources/mx/buro-de-credito/authorizations/{id}`, `DELETE /datasources/mx/buro-de-credito/authorizations/{id}`

* The API reference now explains how Buró de Crédito reports are created with the `buro_de_credito_report` extractor.
* Buró de Crédito report documentation now describes the main response fields, including the provider, product type, provider report ID, parsed report data, score, generated files, and timestamps.
* The API reference now includes the organization-level endpoint for listing Buró de Crédito authorizations.
* Buró de Crédito authorization documentation now describes the consent, RFC, address, validity, origin, and entity identity fields returned by the API.
* The create authorization endpoint now documents the person and company request bodies in more detail.

### RPC resources

**Affected endpoints:** `GET /entities/{entityId}/datasources/mx/rpc/entidades`, `GET /datasources/mx/rpc/entidades/{id}`, `GET /entities/{entityId}/datasources/mx/rpc/actos`, `GET /rpc/actos/{id}`, `GET /datasources/rpc/socios/{id}`

* Added an RPC overview page that explains how RPC records relate to entities, extractions, actos, socios, and file downloads.
* Added overview pages for RPC entidades, actos, and socios.
* Added documentation for listing RPC actos extracted for an entity.
* Added documentation for retrieving an RPC acto by ID.
* Added documentation for retrieving an RPC socio by ID.
* Updated RPC entidade endpoint documentation to use the current `/datasources/mx/rpc/entidades` and `/entities/{entityId}/datasources/mx/rpc/entidades` paths.
* Expanded RPC entidade, acto, and socio response field descriptions.

### RUG resources

**Affected endpoints:** `GET /entities/{entityId}/datasources/rug/operaciones`, `GET /datasources/rug/operaciones/{id}`, `GET /entities/{entityId}/datasources/rug/garantias`, `GET /datasources/rug/garantias/{id}`

* Added a RUG overview page that explains how RUG guarantees, operations, extractions, and file downloads fit together.
* Added overview pages for RUG operations and RUG guarantees.
* Expanded RUG operation and guarantee endpoint descriptions.
* Expanded RUG operation and guarantee response field descriptions.

### SAT resources

**Affected endpoints:** `GET /credentials`, `POST /credentials`, `GET /credentials/{id}`, `DELETE /credentials/{id}`, `POST /credentials/{id}/revalidate`, `GET /entities/{entityId}/invoices`, `GET /invoices/{id}`, `POST /invoices/{id}/tags`, `DELETE /invoices/{invoiceId}/tags/{tagId}`, `GET /invoices/{id}/cfdi`, `GET /datasources/mx/sat/cfdis/{uuid}`, `GET /invoices/payments`, `GET /invoices/payments/{id}`, `GET /entities/{entityId}/invoices/payments`, `GET /invoices/{id}/payments`, `GET /invoices/batch-payments`, `GET /invoices/batch-payments/{id}`, `GET /invoices/{id}/batch-payments`, `GET /entities/{entityId}/invoices/line-items`, `GET /invoices/{invoiceId}/line-items`, `GET /invoices/line-items/{id}`, `GET /invoices/relations/{id}`, `GET /invoices/{invoiceId}/relations`, `GET /entities/{entityId}/invoices/{invoiceId}/relations`, `GET /invoices/credit-notes`, `GET /entities/{entityId}/invoices/credit-notes`, `GET /invoices/credit-notes/{id}`, `GET /invoices/{invoiceId}/issued-credit-notes`, `GET /invoices/{invoiceId}/applied-credit-notes`, `GET /entities/{entityId}/tax-retentions`, `GET /tax-retentions/{id}`, `GET /tax-retentions/{id}/cfdi`, `GET /entities/{entityId}/tax-returns`, `GET /tax-returns/{id}`, `GET /tax-returns/{id}/pdf`, `GET /tax-returns/{id}/data`, `GET /tax-status`, `GET /entities/{entityId}/tax-status`, `GET /tax-status/{id}`, `GET /entities/{entityId}/tax-compliance-checks`, `GET /tax-compliance-checks/{id}`, `GET /entities/{entityId}/electronic-accounting-records`, `GET /electronic-accounting-records/{id}`, `GET /entities/{entityId}/datasources/mx/sat/certificados`, `GET /datasources/mx/sat/certificados/{id}`

* Added a SAT overview page that explains how SAT resources relate to entities, extractions, and file downloads.
* Added overview pages for credentials, invoice line items, invoice relations, credit notes, tax retentions, tax returns, tax status, electronic accounting records, and SAT certificates.
* Added extraction guidance to SAT resource overviews so each extraction-backed resource explains the extractor to use and where to read the extracted records.
* Updated the Extractions overview to focus on the extraction workflow instead of duplicating extractor-specific option lists.
* Expanded the existing invoice, invoice payment, invoice batch payment, and tax compliance check overviews with clearer resource descriptions.
* Updated endpoint summaries and descriptions to consistently use `List` and `Retrieve` wording and entity-based language.
* Added documentation for listing credit notes extracted for an entity.
* Added documentation for invoice relations, tax return PDF downloads, parsed SAT CFDI retrieval, and the top-level tax status list.
* Corrected the documented credit-note retrieve path to use `/invoices/credit-notes/{id}`.
* Corrected the documented invoice line item retrieve path to use `/invoices/line-items/{id}`.
* Added field descriptions for SAT certificate, credential, invoice payment, invoice batch payment, invoice line item, tax retention, tax return, tax compliance check, tax status, and tax regime response fields.
* Renamed the SAT certificate documentation pages from `get` slugs to `list` and `retrieve` slugs, with redirects from the previous documentation URLs.

**June 22, 2026**

Income Statement API updates

### Income Statement profit/loss grouping

This update changes the Income Statement insight response shape.

**Affected endpoint:** `GET /entities/{entityId}/insights/metrics/income-statement`

* In the **2022** format and the audited income-statement formats, each matched `Utilidad` (profit) and `Pérdida` (loss) pair is now returned under a single grouping parent row instead of as two top-level rows. The pair appears as two entries inside the parent's `children` array, and the parent's per-year `Total` reflects the populated side.
* The four pairs that are grouped match the long-standing **2014** format behavior: `bruta`, `de operación`, `antes de impuestos`, and `neta`. The `operaciones continuas` pair is intentionally left flat.
* **Breaking change for consumers of JSON, CSV, and XLSX exports of the 2022 and audited formats.** Integrations that read profit/loss rows by category name at the top level must now read them from the grouping parent's `children` array, or sum the parent's `Total` directly. The **2014** format response is unchanged.
* The grouping parent itself has no underlying SAT concept path. Its `Total` is computed from its children, and child rows keep their original categories and totals.

### Income Statement outflow sign convention

This update changes the sign convention of the Income Statement insight values.

**Affected endpoints:** `GET /entities/{entityId}/insights/metrics/income-statement` (`2022` and `audited-financial-statements` formats; also reflected in the CSV and XLSX exports)

* Cost, expense, loss, tax, and financial-charge lines are now returned as **negative** values, matching the long-standing `2014` format. Previously these outflow lines were returned positive in the `2022` and `audited-financial-statements` formats.
* Revenue, profit, and other inflow lines remain positive. Net or mixed sections keep their natural sign.
* **Action required:** integrations that consumed these formats as positive magnitudes and applied their own sign must stop negating outflows themselves. The values already carry the correct sign. The absolute magnitude of every line is unchanged.

**June 18, 2026**

Other Resources documentation updates

This documentation update improves the API reference section for specialized ownership, background screening, company verification, and address lookup workflows.

### Other Resources

**Affected endpoint:** `GET /datasources/mx/addresses/{postalCode}`

* Mexico address lookup has moved from Miscellaneous into Other Resources.
* Shareholders, background checks, and company verification reports now include overview pages that explain the purpose of each resource group.
* Shareholders, background checks, and company verification report endpoint titles now use consistent `List`, `Retrieve`, and `Download` wording, with expanded endpoint and field descriptions.
* Mexico address lookup documentation now explains that Buró de Crédito and Buró Empresas addresses must match the postal-code address catalog, that a postal code can return multiple neighborhoods, and describes the address fields returned by the endpoint.

**June 17, 2026**

Insight API updates

This update adds the Moratory Interest insight endpoint and updates supported options for existing insight endpoints.

### Moratory Interest insight

**Affected endpoint:** `GET /entities/{entityId}/insights/moratory-interest`

* Added the [Moratory Interest Insight endpoint](https://docs.syntage.com/api-reference/moratory-interest-insight/get-moratory-interest.md).
* The endpoint returns moratory interest charges for an entity, including summary KPIs, monthly totals, monthly totals by financial institution, and institution-level totals.
* The Summary insight risk indicators can include `moratoryInterest` when the Moratory Interest insight is enabled.

### Expenditures and Sales Revenue insights

**Affected endpoints:** `GET /entities/{entityId}/insights/expenditures`, `GET /entities/{entityId}/insights/sales-revenue`

* The `products` value has been removed from the allowed values of the `options[type]` query parameter on both endpoints. Requests that previously sent `options[type]=products` were already returning the same response as `options[type]=total`, so existing integrations that rely on that response continue to work without changes.
* For product-level breakdowns, use the Products and Services insight endpoints (`GET /entities/{entityId}/insights/products-and-services-bought` and `GET /entities/{entityId}/insights/products-and-services-sold`).
* The `dimension` and `label` field descriptions in the response schemas have been updated to reflect that `products` is no longer a supported grouping.

**June 16, 2026**

API documentation updates

This documentation update expands the API reference and guides for entity-based integrations, core resources, and BIL reports. Existing RFC-based endpoints remain available where they were already supported. New API features are documented with entity-based URLs and require entity IDs.

### BIL reports

**Affected endpoints:** `GET /entities/{entityId}/datasources/bil/reports`, `GET /datasources/bil/reports/{id}`

* The API reference now includes the endpoint for listing BIL reports generated for an entity.
* The API reference now includes the endpoint for retrieving a single BIL report by report ID.
* BIL report documentation now describes the main response fields, including the report folio, searched name, maximum grade, parsed vendor response, XML file, and PDF file.

### Entities, identifiers, tags, and events

**Affected endpoints:** `GET /entities`, `POST /entities`, `GET /entities/{entityId}`, `PATCH /entities/{entityId}`, `DELETE /entities/{entityId}`, `GET /entities/{entityId}/events`, `GET /entities/{entityId}/identifiers`, `POST /entities/{entityId}/identifiers`, `GET /entities/{entityId}/tags`, `POST /entity-tags`, `GET /entity-tags/{id}`, `PATCH /entity-tags/{id}`, `DELETE /entity-tags/{id}`, `GET /tags`, `POST /tags`, `PATCH /tags/{id}`, `DELETE /tags/{id}`

* The API reference now includes entity overview and endpoint pages that explain how entities are created, retrieved, updated, deleted, and used as the parent resource for datasource records.
* Entity identifier documentation now explains how RFC and CURP identifiers can be supplied when creating an entity or added later.
* Entity tag and tag documentation now explain how tags can be used for segmentation, extraction scheduler targeting, monitoring, and filtering entities in your own product.
* Entity event documentation now explains how to retrieve events for a specific entity in addition to using webhook delivery.

### Files and exports

**Affected endpoints:** `GET /files/{id}`, `GET /files/{id}/download`, `POST /exports`, `GET /exports/{id}`

* File documentation now explains file metadata, file types, filenames, MIME types, and when to use the download endpoint for file content.
* Export documentation now explains the asynchronous export workflow from creation through terminal statuses.
* Export documentation now shows that completed exports return a file reference that can be downloaded through the file download endpoint.

### Extractions, schedulers, and scheduler rules

**Affected endpoints:** `GET /extractions`, `GET /extractions/{id}`, `POST /extractions/{id}/stop`, `GET /schedulers`, `POST /schedulers`, `GET /schedulers/{id}`, `PATCH /schedulers/{id}`, `DELETE /schedulers/{id}`, `POST /schedulers/rules`, `GET /schedulers/rules/{id}`, `PATCH /schedulers/rules/{id}`, `DELETE /schedulers/rules/{id}`

* Extraction documentation now covers the extraction lifecycle, statuses, retry behavior, duplicate extraction behavior, and datasource-specific extractor descriptions.
* BIL is now included in the documented extractor list.
* Scheduler and scheduler rule documentation now explains recurring extraction behavior in more detail.

### Guides

**Affected area:** Guides navigation and conceptual documentation

* The guides now include entity-based URL guidance that explains entity IDs and legacy RFC-based URL compatibility.
* The environments guide now describes Sandbox and Production behavior across Syntage datasources.
* Request ID and rate limiting guides now include response header examples and troubleshooting use cases.
* Property filtering guidance now includes syntax examples for selecting fields from resources and related objects.
* SAT catalog documentation now includes the catalog areas covered by the API and examples of common CFDI catalog values.
* Webhook validation guidance now includes PHP, JavaScript/TypeScript, and Python examples for verifying request signatures.
* Updated the integration flow guide to explain credential validation, extraction creation, extraction status tracking, webhook delivery, and file retrieval as a connected workflow.
* Clarified that embedded entity onboarding is for integrations that need the onboarding experience inside their own site instead of redirecting to Syntage.
* Kept deprecated widget documentation available for existing widget users while pointing new integrations to embedded entity onboarding.
* Updated introductory documentation to describe Syntage's API across SAT, RUG, RPC, BIL, Buró de Crédito, Buró Empresas, Infonavit, and more.

**June 28, 2020**

API version 2020-06-28

This version removes deprecated response fields and updates several resource identifiers to use stable API IDs.

### Invoice

**Affected endpoints:** `GET /invoices/{id}`, `GET /taxpayers/{taxpayerId}/invoices`

* The `amount` property has been removed from API responses. Use the `total` property instead.
* Retrieval by invoice's `uuid` at `/invoices/{id}` is now removed. To retrieve an invoice, use the invoice's `id` at the specified endpoint. To find an invoice using its `uuid`, filter the invoice collection at `/taxpayers/{taxpayerId}/invoices?uuid[]={uuid}`.
* Previously, the `@iri` property for an invoice pointed to the resource using `uuid`, like `/invoices/{uuid}`. Now, it points using its `id`, like `/invoices/{id}`.

### Link

**Affected endpoint:** `GET /links`

* Filtering links by `status` is removed. Use `credential.status` instead. For example, use `GET /links?credential.status[]=active` instead of `GET /links?status[]=active`.

### Tax Return

**Affected endpoints:** `GET /tax-returns/{id}`, `GET /taxpayers/{taxpayerId}/tax-returns`

* Retrieval by tax return's `operationNumber` at `/tax-returns/{id}` is removed. To retrieve a tax return, use the tax return's `id` at the specified endpoint. To find a tax return using its `operationNumber`, filter the collection at `/taxpayers/{taxpayerId}/tax-returns?operationNumber[]={operationNumber}`.
* Previously, the `@iri` property for a tax return pointed to the resource using `operationNumber`, like `/tax-returns/{operationNumber}`. Now, it points to its `id`, like `/tax-returns/{id}`.

### Event

**Affected endpoints:** `GET /events`, `GET /events/{id}`

* For events associated to a `tax-return`, the `@iri` property now points to `/tax-returns/{id}` instead of the previous `/tax-returns/{operationNumber}`.
* For events associated to an `invoice`, the `@iri` property now points to `/invoices/{id}` instead of the previous `/invoices/{uuid}`.

### Extraction

**Affected endpoints:** `GET /extractions`, `GET /extractions/{id}`

* The `periodFrom` property has been removed. Use `options.period.from` instead.
* The `periodTo` property has been removed. Use `options.period.to` instead.

### File

**Affected endpoint:** `GET /file/{id}`

* For files associated to a `tax-return`, the `@iri` property now points to `/tax-returns/{id}` instead of the previous `/tax-returns/{operationNumber}`.
* For files associated to an `invoice`, the `@iri` property now points to `/invoices/{id}` instead of the previous `/invoices/{uuid}`.

### Test this version

Send the `Accept-Version` header with any request to test this API version:

```bash theme={null}
curl -i 'https://api.syntage.com/taxpayers/{taxpayerId}/invoices' \
  --header 'Accept-Version: 2020-06-28' \
  --header 'X-Api-Key: {apiKey}'
```


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