API Changelog

​

Extraction creation

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

​

Batch invoice tagging

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

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

​

Tag color

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

POST /tags
{
  "name": "To be reviewed",
  "resourceType": "invoice",
  "color": "#22c558"
}

​

Summary insight

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

​

Shareholders insight

• 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

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

​

Company Verification resources

• 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

• 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

• 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

• 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

• 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

• 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

• 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

• 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

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

​

Income Statement profit/loss grouping

• 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

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

​

Other Resources

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

​

Moratory Interest insight

• Added the Moratory Interest Insight endpoint.
• 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

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

​

BIL reports

• 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

• 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

• 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

• 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

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

​

Invoice

• 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

• 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

• 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

• 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

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

​

File

• 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

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