# Add an Entity Source: https://docs.syntage.com/api-reference/entities/add-an-entity post /entities Add an entity to your organization. If `datasources` contains one or more datasources, Syntage creates first-time extractions for the selected datasources. When a selected datasource has first-time scheduler rules, those rules determine which extractors and options are used. For selected datasources not covered by first-time scheduler rules, Syntage creates first-time extractions for the datasource's available extractors using the options from the request, or the extractor defaults. Omit `datasources` or send an empty array to create the entity without starting extractions. `name` is optional when you provide a valid RFC. If omitted or null, Syntage resolves the entity's legal name from taxpayer data during creation and stores that name on the entity. If no name is available for the RFC, the request fails with a validation error on `name` using the code `rfc_valid_no_name_on_file`; retry with an explicit `name` to create the entity. # Add an entity identifier Source: https://docs.syntage.com/api-reference/entities/add-an-entity-identifier post /entities/{entityId}/identifiers Add a country-specific identifier to an entity. # Create an entity tag Source: https://docs.syntage.com/api-reference/entities/create-an-entity-tag post /entity-tags Create a tag that can be assigned to entities. The created tag is returned with an `/entity-tags/{id}` IRI. # Delete an Entity Source: https://docs.syntage.com/api-reference/entities/delete-an-entity delete /entities/{entityId} Delete an entity and the data associated with that entity. The entity's events stay available for the same 7 days as any other event. # Favorite one or more entities Source: https://docs.syntage.com/api-reference/entities/favorite-multiple-entities post /entities/favorites Requires entity access and applies only to the authenticated user. Repeated requests are safe. Read-only users may use JWT authentication. # List all entities Source: https://docs.syntage.com/api-reference/entities/list-all-entities get /entities List entities in your organization and filter by RFC, name, person type, or dates. # List all entity tags Source: https://docs.syntage.com/api-reference/entities/list-all-entity-tags get /entity-tags List entity tags that can be assigned to entities. # List an entity's events Source: https://docs.syntage.com/api-reference/entities/list-an-entitys-events get /entities/{entityId}/events List recent events for a specific entity. # List an entity's identifiers Source: https://docs.syntage.com/api-reference/entities/list-an-entitys-identifiers get /entities/{entityId}/identifiers List country-specific identifiers for an entity, such as RFC or CURP for Mexico. # List an entity's tags Source: https://docs.syntage.com/api-reference/entities/list-an-entitys-tags get /entities/{entityId}/tags List the tags assigned to a specific entity. # Retrieve an Entity Source: https://docs.syntage.com/api-reference/entities/retrieve-an-entity get /entities/{entityId} Retrieve a single entity by ID, including taxpayer, credential, and tag information when available. # Retrieve an entity tag Source: https://docs.syntage.com/api-reference/entities/retrieve-an-entity-tag get /entity-tags/{id} Retrieve a single entity tag by ID. # Unfavorite one or more entities Source: https://docs.syntage.com/api-reference/entities/unfavorite-multiple-entities delete /entities/favorites Requires entity access and applies only to the authenticated user. Repeated requests are safe. Read-only users may use JWT authentication. # Update an Entity Source: https://docs.syntage.com/api-reference/entities/update-an-entity patch /entities/{entityId} Update an entity. Sending `tags` replaces the entity's existing tag assignments with the provided collection. # Update an entity tag Source: https://docs.syntage.com/api-reference/entities/update-an-entity-tag patch /entity-tags/{id} Update the display name for an entity tag. # List all events Source: https://docs.syntage.com/api-reference/events/list-all-events get /events List recent events for resources in your organization. Events are ordered and paginated with cursor pagination. # Retrieve an event Source: https://docs.syntage.com/api-reference/events/retrieve-an-event get /events/{id} Retrieve a single event by ID, including the event type and resource data captured when the event was created. # Export data Source: https://docs.syntage.com/api-reference/exports/export-data post /exports Create an export from a supported collection URI. The export runs asynchronously and returns an Export resource that can be polled until the generated file is ready. # List all exports Source: https://docs.syntage.com/api-reference/exports/list-all-exports get /exports List the exports created by the authenticated user, newest first. Use this to recover the ID of an export you created earlier. Exports created by other users in your organization are not returned. Results are paginated with cursor pagination. # Retrieve an export Source: https://docs.syntage.com/api-reference/exports/retrieve-an-export get /exports/{id} Retrieve an export and its current processing status. When the export is finished, the response includes the generated file metadata. # Download content Source: https://docs.syntage.com/api-reference/files/download-the-file-content get /files/{id}/download The response includes the `Location` header with the URL to download the file (make sure to follow the redirection). # Retrieve a file Source: https://docs.syntage.com/api-reference/files/retrieve-a-file get /files/{id} Retrieve file metadata, including type, filename, media type, size, and the resource associated with the file. # API Reference Source: https://docs.syntage.com/api-reference/introduction Use the API reference to inspect Syntage endpoints, request parameters, response schemas, and examples. The API lets you work with organization entities and retrieve structured data from SAT, RPC, RUG, Buró de Crédito, Buró Empresas, Infonavit, and more. ## Base URLs | Environment | Base URL | | - | - | | Production | [https://api.syntage.com](https://api.syntage.com) | | Sandbox | [https://api.sandbox.syntage.com](https://api.sandbox.syntage.com) | Use sandbox for development and testing before production. All data returned in sandbox is simulated. See [Environments](/guides/api/environments) for more details. ## Authentication Authenticate API requests with your API key in the `X-Api-Key` header. ```bash theme={null} curl -i 'https://api.syntage.com/entities' \ --header 'Accept: application/ld+json' \ --header 'X-Api-Key: {apiKey}' ``` ## Response format Most API responses use [JSON-LD](https://json-ld.org). Collection responses include `hydra:member` and pagination metadata. See [Pagination](/guides/api/pagination), [Property Filtering](/guides/api/property-filtering), and [Entity URLs](/guides/api/entity-urls) for common API concepts. ## Filtering > [!WARNING] > > Collection endpoints only apply the filter query parameters documented for that endpoint. If you send an unsupported or misspelled filter query parameter, the API ignores it and processes the request as if that parameter was not sent. ## OpenAPI specification Download the [OpenAPI specification](https://api.syntage.com/openapi.yaml) to generate clients or inspect the complete API surface. # Agent skills Source: https://docs.syntage.com/developers/agent-skills Install Syntage's Agent Skills before building an integration with an AI coding assistant. Syntage publishes a set of [Agent Skills](https://agentskills.io) that guide AI coding agents through integration work. The skills tell the agent which documentation to consult and which safety checks to apply; these docs remain the canonical product and API contract. > [!NOTE] > > If you are building a Syntage integration with an AI coding assistant, install these first. An agent working without them will infer endpoints, field names, extractor options, and event types — and inferred integration code is usually plausible enough to pass review while being wrong. ## Install ### Agent Skills clients Install the repository with a compatible Agent Skills client: ```sh theme={null} npx skills add syntagecom/skills ``` Select the skills relevant to your integration when prompted. ### Claude Code Add the Syntage marketplace and install the skill bundle: ```text theme={null} /plugin marketplace add syntagecom/skills /plugin install syntage-skills@syntage ``` ## Available skills | Skill | Use it for | | - | - | | `syntage-api` | API environment selection, authentication, entities, collections, pagination, filters, rate limits, and integration architecture | | `syntage-entity-onboarding` | Embedded entity onboarding, onboarding events, CSP, and sandbox testing | | `syntage-extractions` | Starting, tracking, scheduling, and troubleshooting asynchronous extractions | | `syntage-webhooks` | Webhook endpoint design, signature verification, idempotent event processing, and reconciliation | Invoke a skill explicitly when asking your agent for help: ```text theme={null} Use $syntage-api to add a sandbox Syntage client to this application. ``` ## Safety defaults Every skill applies the same baseline: * Start development and testing in [sandbox](/guides/api/environments), where returned data is simulated. * Do not send production requests, mutate production integration configuration, or open a live onboarding flow without your explicit confirmation. * Keep environment-specific API keys, signing secrets, datasource credentials, and authorizations outside source code, prompts, logs, and generated examples. * Verify endpoints, fields, filters, extractor options, and event types against the current documentation instead of guessing. ## Client metadata `SKILL.md` contains the portable instructions and discovery metadata shared by Agent Skills clients. Optional client adapters enhance supported products without changing those instructions: * `agents/openai.yaml` supplies OpenAI clients such as Codex with display names, short descriptions, and suggested prompts. * `.claude-plugin/marketplace.json` makes all four skills installable as a Claude Code plugin bundle. Clients that do not recognize an adapter continue to use `SKILL.md`. The skills are maintained at [github.com/syntagecom/skills](https://github.com/syntagecom/skills). # Event examples Source: https://docs.syntage.com/developers/event-examples Example event payloads for created, updated, and deleted resource events. Every event has a `type`, the `source` that produced the event, the affected `resource`, and a `data` field. The `data.object` shape depends on the event type. For update events, `data.changes` shows the fields that changed; created events don't include `data.changes`. Deleted events keep the `resource` link but don't include the resource object, so their `data` is an empty array. These examples are shortened to focus on the event structure. ## Timestamps The event's `createdAt` and `updatedAt` use the `YYYY-MM-DD HH:MM:SS` format in UTC, with no timezone designator, for example `2026-06-16 14:30:00`. The format of timestamps inside `data.object` depends on the resource. When a date field changes, `data.changes` reports its `old` and `new` values in ISO 8601 format in UTC, with microseconds: ```json theme={null} "changes": { "updatedAt": { "old": "2026-06-16T14:30:00.000000Z", "new": "2026-06-16T14:31:00.000000Z" } } ``` ## Created event ```json theme={null} { "@id": "/events/018f3f8f-4538-7bbb-b432-9e97e34a564a", "@type": "Event", "id": "018f3f8f-4538-7bbb-b432-9e97e34a564a", "taxpayer": { "@id": "/taxpayers/PEIC211118IS0", "@type": "Taxpayer", "id": "PEIC211118IS0", "name": "Pedro Infante Cruz" }, "type": "invoice.created", "source": "/extractions/91106968-1abd-4d64-85c1-4e73d96fb997", "resource": "/invoices/7c45e9c6-8f7f-4d0e-b6e5-65fef6c8c2f9", "data": { "object": { "id": "7c45e9c6-8f7f-4d0e-b6e5-65fef6c8c2f9", "uuid": "6f3c5312-2849-4525-86f6-c48a54c64c60", "type": "I", "status": "VIGENTE", "total": 1250.0, "createdAt": "2026-06-16 14:30:00", "updatedAt": "2026-06-16 14:30:00" } }, "createdAt": "2026-06-16 14:30:00", "updatedAt": "2026-06-16 14:30:00" } ``` ## Updated event ```json theme={null} { "@id": "/events/018f3f90-189a-7f31-b124-4ea7a938d682", "@type": "Event", "id": "018f3f90-189a-7f31-b124-4ea7a938d682", "taxpayer": { "@id": "/taxpayers/PEIC211118IS0", "@type": "Taxpayer", "id": "PEIC211118IS0", "name": "Pedro Infante Cruz" }, "type": "credential.updated", "source": "/credentials/6a6a1f8d-41c2-4ab9-a2ce-836417ed27de", "resource": "/credentials/6a6a1f8d-41c2-4ab9-a2ce-836417ed27de", "data": { "object": { "id": "6a6a1f8d-41c2-4ab9-a2ce-836417ed27de", "rfc": "PEIC211118IS0", "type": "ciec", "status": "valid", "createdAt": "2026-06-10 09:05:12", "updatedAt": "2026-06-16 14:31:00" }, "changes": { "status": { "old": "pending", "new": "valid" } } }, "createdAt": "2026-06-16 14:31:00", "updatedAt": "2026-06-16 14:31:00" } ``` ## Deleted event ```json theme={null} { "@id": "/events/018f3f91-6ed2-70ba-97e8-b8dd0e61d415", "@type": "Event", "id": "018f3f91-6ed2-70ba-97e8-b8dd0e61d415", "taxpayer": { "@id": "/taxpayers/PEIC211118IS0", "@type": "Taxpayer", "id": "PEIC211118IS0", "name": "Pedro Infante Cruz" }, "type": "link.deleted", "source": "/entities/91106968-1abd-4d64-85c1-4e73d96fb997", "resource": "/entities/91106968-1abd-4d64-85c1-4e73d96fb997", "data": [], "createdAt": "2026-06-16 14:32:00", "updatedAt": "2026-06-16 14:32:00" } ``` # Extraction request examples Source: https://docs.syntage.com/developers/extraction-request-examples Example extraction request bodies for common Syntage resources. Use these examples when creating extractions through the API. Each request uses an entity IRI and an extractor name. Some extractors also accept options that control the period, direction, file types, or provider product. For endpoint details, see [Create an extraction](/api-reference/extractions/create-an-extraction). ## SAT ### Invoices ```json theme={null} { "entity": "/entities/7b3a25a9-a53a-4846-abe6-f2574c9c2d5d", "extractor": "invoice", "options": { "period": { "from": "2024-01-01", "to": "2024-12-31" }, "issued": true, "received": true, "xml": true, "pdf": true } } ``` Set `period.from` and `period.to` explicitly to the range you want to extract. If omitted, `period.from` defaults to the start of the year three years ago and `period.to` defaults to the current date and time. Use `issued` and `received` to control the direction (CFDIs the entity emitted, received, or both), and `xml` and `pdf` to control which file types are downloaded. Keep `xml` and `pdf` enabled. XML downloads count toward SAT's daily download limits; disable `xml` only when you are certain your use case requires it to be disabled. PDF downloads do not count toward those limits. Invoice payments, batch payments, line items, relations, and credit notes are derived from invoice CFDI data. Include type `P` invoices for payment records and type `E` invoices for credit notes when selecting invoice types. ### Tax retentions ```json theme={null} { "entity": "/entities/7b3a25a9-a53a-4846-abe6-f2574c9c2d5d", "extractor": "tax_retention", "options": { "period": { "from": "2024-01-01", "to": "2024-12-31" }, "issued": true, "received": true, "xml": true, "pdf": true } } ``` ### Tax returns Use the extractor for the tax return type you need. | Tax return data | Extractor | | - | - | | Annual returns | `annual_tax_return` | | Provisional monthly returns | `monthly_tax_return` | | RIF returns | `rif_tax_return` | ```json theme={null} { "entity": "/entities/7b3a25a9-a53a-4846-abe6-f2574c9c2d5d", "extractor": "annual_tax_return", "options": { "period": { "from": "2020-01-01", "to": "2024-12-31" } } } ``` Use `monthly_tax_return` or `rif_tax_return` in the same request shape when you need those return types. ### Tax status ```json theme={null} { "entity": "/entities/7b3a25a9-a53a-4846-abe6-f2574c9c2d5d", "extractor": "tax_status" } ``` ### Tax compliance checks ```json theme={null} { "entity": "/entities/7b3a25a9-a53a-4846-abe6-f2574c9c2d5d", "extractor": "tax_compliance" } ``` ### Electronic accounting ```json theme={null} { "entity": "/entities/7b3a25a9-a53a-4846-abe6-f2574c9c2d5d", "extractor": "electronic_accounting", "options": { "period": { "from": "2023-01-01", "to": "2024-12-31" } } } ``` ### SAT certificates ```json theme={null} { "entity": "/entities/7b3a25a9-a53a-4846-abe6-f2574c9c2d5d", "extractor": "sat_certificates" } ``` ## RPC ```json theme={null} { "entity": "/entities/91106968-1abd-4d64-85c1-4e73d96fb997", "extractor": "rpc" } ``` The `rpc` extractor creates RPC entidades, actos, and socios when the registry returns matching data. ## RUG ```json theme={null} { "entity": "/entities/91106968-1abd-4d64-85c1-4e73d96fb997", "extractor": "rug" } ``` The `rug` extractor creates RUG guarantees and operations when the registry returns matching data. ## BIL ```json theme={null} { "entity": "/entities/91106968-1abd-4d64-85c1-4e73d96fb997", "extractor": "bil" } ``` ## Buró de Crédito The entity must have taxpayer data and a valid Buró de Crédito authorization before the extraction can run. ```json theme={null} { "entity": "/entities/91106968-1abd-4d64-85c1-4e73d96fb997", "extractor": "buro_de_credito_report", "options": { "productType": "007" } } ``` The `productType` option controls which Buró de Crédito product is requested. | Entity type | Supported `productType` values | Default | | - | - | - | | Person | `007`, `004`, `INFORME_BURO` | `007` | | Company | `INFORME_BURO`, `RCO` | `INFORME_BURO` | ## Background checks Run a background check for an entity. The `background_check` extractor can be used in one-off extractions and in recurring scheduler rules to keep screening results current for monitored entities. ```json theme={null} { "entity": "/entities/91106968-1abd-4d64-85c1-4e73d96fb997", "extractor": "background_check" } ``` For the resulting records and PDF report, see [Background checks](/resources/other/background-checks). ## Infonavit Check whether an entity's employer registration appears in the Infonavit Créditos Firmes list of firm (overdue) housing-credit obligations. The `infonavit` extractor matches on the entity name, so no SAT credentials are required. ```json theme={null} { "entity": "/entities/91106968-1abd-4d64-85c1-4e73d96fb997", "extractor": "infonavit", "options": {} } ``` The `infonavit` extractor does not accept any options. Send an empty `options` object or omit the field entirely. If the entity does not appear in the list, the extraction still finishes successfully and returns no records. For the resulting records, see [Infonavit overdue credits](/resources/datasources/infonavit/overdue-credits). # Developer overview Source: https://docs.syntage.com/developers/overview Start here when building an integration with the Syntage API. Use the developer docs when you are building an integration, generating an API client, configuring webhooks, or automating workflows with Syntage. Most integrations follow the same pattern: 1. Choose the environment you are testing against. 2. Create or identify the entity. 3. Provide the credential, authorization, or request needed by the data source. 4. Start or schedule an extraction or report workflow. 5. Listen for webhook events or poll the relevant resource. 6. Retrieve records, files, reports, or insights from the API. ## Key developer pages * [Agent skills](/developers/agent-skills) should be installed before you build an integration with an AI coding assistant. * [Environments](/guides/api/environments) explains sandbox and production behavior. * [Integration Flow](/guides/integration-flow) walks through a common credential and extraction workflow. * [Extraction request examples](/developers/extraction-request-examples) shows request bodies for common extraction-backed resources. * [Entity URLs](/guides/api/entity-urls) explains entity-based URLs and legacy RFC-based compatibility. * [Webhooks](/developers/webhooks) explains how to deliver events to your server and manage endpoints from the dashboard or API. * [Validating Webhook Requests](/guides/validating-webhook-requests) shows how to verify webhook signatures. * [Event examples](/developers/event-examples) shows example payloads for created, updated, and deleted events. * [API Reference](/api-reference/introduction) contains endpoint paths, parameters, response schemas, and examples. # Webhooks Source: https://docs.syntage.com/developers/webhooks Deliver Syntage events to your server and manage endpoints from the dashboard or API. Webhooks let Syntage deliver events to your server when resources in your organization change. Use them when your integration needs to react to new credentials, entities, extractions, invoices, files, reports, or other resources without polling the Events API. ## Webhook Endpoints A webhook endpoint is the HTTPS URL where Syntage sends matching events. Each endpoint defines: | Field | Purpose | | - | - | | `url` | The public HTTPS URL that receives event deliveries | | `events` | The event types delivered to the endpoint, such as `extraction.updated` or `invoice.created` | | `enabled` | Whether Syntage should send events to the endpoint | | `contentType` | The payload format, either `application/ld+json` or `application/json` | | `signingSecret` | The secret used to verify delivery signatures | Endpoint URLs must use HTTPS and must resolve to a public network address. Syntage sends each delivery as a `POST` request with `X-Syntage-Signature`, `X-Satws-Signature`, `Content-Digest`, and `Content-Type` headers. Use [Validating Webhook Requests](/guides/validating-webhook-requests) to verify that webhook deliveries came from Syntage. ## Managing webhooks You can manage webhook endpoints from the dashboard or the API. Both act on the same endpoints, so an endpoint created in the dashboard is visible over the API and vice versa. ### From the dashboard Administrators can manage webhooks in the dashboard under [Settings → Webhooks](https://app.syntage.com/settings/webhooks). From there you can: * Create an endpoint by entering its HTTPS URL and selecting the event types to deliver. * Enable or disable an endpoint without deleting it. * View the `signingSecret` used to verify deliveries. * Review recent delivery attempts to monitor endpoint health. ### From the API To manage webhooks programmatically, use the [Webhook Endpoints](/api-reference/webhook-endpoints/list-all-webhook-endpoints) endpoints to create, list, retrieve, update, and delete endpoints, and the [Webhook Requests](/api-reference/webhook-requests/list-all-webhook-requests) endpoints to inspect delivery attempts. ## Event payload Each delivery's body is a single [Event](/resources/core/events) object. The event includes the `type` that occurred, the `source` and `resource` IRIs, and a `data` field. For created and updated events, `data.object` holds the state of the affected resource when the event was created, and update events also include `data.changes` with the old and new values of the fields that changed. Deleted events keep the `resource` IRI but don't include the resource, so their `data` is an empty array. Webhook payload size varies with the underlying resource and may reach tens of megabytes. Configure your endpoint and any reverse proxies to accept large request bodies; we recommend allowing at least 100 MB. This recommendation is not a maximum payload size. See [Event examples](/developers/event-examples) for example payloads of created, updated, and deleted events. ## Webhook Requests A webhook request is a delivery attempt from Syntage to a webhook endpoint. Request records are useful for monitoring delivery health and investigating failures. Syntage records the endpoint URL, related event, response status code, response time, and timestamps. If Syntage cannot get an HTTP response, such as when the request times out after 3 seconds, the recorded `responseStatusCode` is `0`. Deliveries are considered successful when your endpoint returns a `2xx` HTTP status code. Failed deliveries are retried up to 4 times, so your webhook handler should process events idempotently. Webhook delivery order and exactly-once delivery are not guaranteed. Your endpoint may receive events out of order, and the same event may be delivered more than once. Store each event ID and deduplicate your processing; do not assume that the order in which events arrive matches the order in which the underlying changes occurred. # Entity URLs Source: https://docs.syntage.com/guides/api/entity-urls Entity-based URLs use the entity ID for the person or company in your organization whose data you are reading. An entity represents a person or company in your organization. It is the resource that connects that person or company to datasource-specific data, credentials, authorizations, tags, and extracted records. The entity `id` is the stable identifier to use in `{entityId}` path parameters. The entity also includes the RFC under `taxpayer.id` when the entity has Mexican taxpayer information. > [!NOTE] > > Some existing endpoints also support RFC-based URLs such as `/taxpayers/{rfc}/tax-status`, but new endpoints and features are only added under `/entities/{entityId}/...`. ## How entity URLs work Entity-scoped endpoints start with `/entities/{entityId}` when the resource belongs to a specific person or company. For example: | Resource | Entity-based URL | | - | - | | Invoices | `/entities/{entityId}/invoices` | | Tax status | `/entities/{entityId}/tax-status` | | Buró de Crédito authorizations | `/entities/{entityId}/datasources/mx/buro-de-credito/authorizations` | | RPC data | `/entities/{entityId}/datasources/rpc/entidades` | | RUG operaciones | `/entities/{entityId}/datasources/rug/operaciones` | Use the same entity ID across entity-scoped endpoints for that person or company. ## Get an entity ID You can create an entity with [Add an entity](/api-reference/entities/add-an-entity), retrieve a known entity with [Retrieve an entity](/api-reference/entities/retrieve-an-entity), or list entities with [List all entities](/api-reference/entities/list-all-entities). If you only know the RFC, use the entity list endpoint with the `taxpayer.id` filter, then read the entity ID from the `id` field in the response. When filtering by RFC, use the full RFC and confirm the returned entity's `taxpayer.id` matches the RFC you searched for. ```bash theme={null} curl -i 'https://api.syntage.com/entities?taxpayer.id=PEIC211118IS0' \ --header 'Accept: application/ld+json' \ --header 'X-Api-Key: {apiKey}' ``` The `hydra:member` array contains entity resources like this: ```json theme={null} { "@id": "/entities/91106968-1abd-4d64-85c1-4e73d96fb997", "id": "91106968-1abd-4d64-85c1-4e73d96fb997", "type": "person", "taxpayer": { "id": "PEIC211118IS0" } } ``` Store and reuse the entity `id` for future requests. ## Legacy RFC-based URLs Existing RFC-based URLs continue to work for endpoints that already support them. They are compatibility paths, not the URL shape for new API capabilities. New endpoints are only added under `/entities/{entityId}/...`, so new features require an entity ID. For existing integrations that use RFC-based URLs, keep the rest of the path the same and replace the `/taxpayers/{rfc}` prefix with `/entities/{entityId}`. The following examples show common documented replacements. This is not a complete list of every legacy RFC-based URL. | Legacy RFC-based URL | Entity-based URL | | - | - | | `/taxpayers/{rfc}/invoices` | `/entities/{entityId}/invoices` | | `/taxpayers/{rfc}/invoices/payments` | `/entities/{entityId}/invoices/payments` | | `/taxpayers/{rfc}/tax-retentions` | `/entities/{entityId}/tax-retentions` | | `/taxpayers/{rfc}/tax-returns` | `/entities/{entityId}/tax-returns` | | `/taxpayers/{rfc}/tax-compliance-checks` | `/entities/{entityId}/tax-compliance-checks` | | `/taxpayers/{rfc}/tax-status` | `/entities/{entityId}/tax-status` | | `/taxpayers/{rfc}/electronic-accounting-records` | `/entities/{entityId}/electronic-accounting-records` | | `/taxpayers/{rfc}/datasources/rpc/entidades` | `/entities/{entityId}/datasources/rpc/entidades` | | `/taxpayers/{rfc}/datasources/rug/operaciones` | `/entities/{entityId}/datasources/rug/operaciones` | | `/taxpayers/{rfc}/datasources/rug/garantias` | `/entities/{entityId}/datasources/rug/garantias` | For example: ```bash theme={null} curl -i 'https://api.syntage.com/entities/91106968-1abd-4d64-85c1-4e73d96fb997/tax-status' \ --header 'Accept: application/ld+json' \ --header 'X-Api-Key: {apiKey}' ``` # Environments Source: https://docs.syntage.com/guides/api/environments | Name | Description | Base URL | | - | - | - | | **Production** | Use production for live applications and real organization data. Requests in this environment can connect to live datasources, require real credentials or authorizations when a datasource requires them, and return real results. | [https://api.syntage.com](https://api.syntage.com) | | **Sandbox** | Use sandbox for development and testing before production. Sandbox lets you test API requests without real end-user credentials, and all data returned in sandbox is simulated. | [https://api.sandbox.syntage.com](https://api.sandbox.syntage.com) | Each environment uses a different API key. View, copy, or rotate the key for the environment you are using in the [Production dashboard](https://app.syntage.com/settings/api-keys) or [Sandbox dashboard](https://app.sandbox.syntage.com/settings/api-keys). See [Where can I manage API keys?](/using-syntage/faq/organization-billing-and-support#where-can-i-manage-api-keys) for details. ## Create sandbox entities Sandbox does not reserve or publish a fixed set of RFCs. When you create an entity, you can use any RFC that matches the format for its type: 13 characters for a person and 12 characters for a company. The dashboard can generate a valid-format RFC for you, and you can edit it before creating the entity. By default, sandbox assigns the entity a stable simulated fiscal profile. Tax status and applicable tax-return extractions reuse that profile so the generated records remain consistent across extractions. To select a specific profile through the API, add `metadata.sandbox.taxRegime` to `POST /entities`: ```json theme={null} { "name": "Sandbox Professional", "rfc": "SAPA900101A1B", "type": "person", "metadata": { "sandbox": { "taxRegime": 612 } } } ``` Person entities support 605 (Salaries and assimilated income), 612 (PFAE), 621 (RIF), 625 (Digital platforms), and 626 (RESICO). Company entities support 601 (General legal persons law) and 626 (RESICO). Omit `metadata.sandbox.taxRegime` when you do not need a particular profile; sandbox then assigns one of the supported regimes for the entity type when it creates the entity, and keeps it. # Pagination Source: https://docs.syntage.com/guides/api/pagination Collection endpoints return paginated results with navigation links and metadata. The API supports two pagination styles: * **Offset-based pagination** (default) - Navigate using page numbers * **Cursor-based pagination** - Navigate using cursor tokens for large datasets ## Offset-based Pagination The default pagination style. Use page numbers to navigate through results. ### Query Parameters | Parameter | Description | Default | Max | | - | - | - | - | | `itemsPerPage` | Number of items per page | 20 | 1000 | | `page` | Page number | 1 | - | ### Example ```bash theme={null} curl -i 'https://api.syntage.com/events?page=2&itemsPerPage=50' \ --header 'Accept: application/ld+json' \ --header 'X-Api-Key: {apiKey}' ``` ### Response ```json theme={null} { "@context": "/contexts/Event", "@id": "/events", "@type": "hydra:Collection", "hydra:totalItems": 150, "hydra:member": [ // ... items on this page ], "hydra:view": { "@id": "/events?page=2", "@type": "hydra:PartialCollectionView", "hydra:first": "/events?page=1", "hydra:previous": "/events?page=1", "hydra:next": "/events?page=3", "hydra:last": "/events?page=3" } } ``` The `hydra:view` object contains links to navigate the collection: | Field | Description | | - | - | | `hydra:first` | Link to the first page | | `hydra:previous` | Link to the previous page (if available) | | `hydra:next` | Link to the next page (if available) | | `hydra:last` | Link to the last page | ### Considerations * **Best for smaller datasets** - Works well for collections with moderate size * **Page drift** - If items are added or removed while paginating, you may see duplicates or miss items * **Performance** - For large datasets, consider cursor-based pagination ## Cursor-based Pagination Uses opaque cursor tokens instead of page numbers. More efficient for large datasets and provides stable results even when items change during pagination. ### Benefits * **Better performance** - More efficient database queries for large datasets * **Stable results** - No duplicates or missed items when data changes during pagination * **Scalable** - Performance doesn't degrade as you paginate deeper into the collection ### Example Add the `X-Pagination-Style: cursor` header to enable cursor pagination: ```bash theme={null} curl -i 'https://api.syntage.com/entities/{entityId}/invoices?itemsPerPage=10' \ --header 'Accept: application/ld+json' \ --header 'X-Api-Key: {apiKey}' \ --header 'X-Pagination-Style: cursor' ``` The response includes `hydra:next` and `hydra:previous` URIs with the cursor token embedded. To fetch the next page, make a GET request to the `hydra:next` URI. ### Considerations * **No total count by default** - The `hydra:totalItems` field is omitted to improve performance. To include it, add the `X-Pagination-Enable-Partial: 0` header (this may impact response times for large datasets). * **Availability** - Cursor pagination is available on most collection endpoints. # Property Filtering Source: https://docs.syntage.com/guides/api/property-filtering Use the `properties` query parameter to select which fields are returned by a `GET` request. This is useful when you only need a subset of a large response. Syntax: `?properties[]=&properties[][]=` You can request as many properties as you need. For nested objects, use the relation name in brackets. The following example requests `paymentType` from each invoice and `rfc` from the invoice issuer: ```bash theme={null} curl -i 'https://api.syntage.com/entities/{entityId}/invoices?properties[]=paymentType&properties[issuer][]=rfc' \ --header 'Accept: application/ld+json' \ --header 'X-Api-Key: {apiKey}' ``` # Rate Limiting Source: https://docs.syntage.com/guides/api/rate-limiting Syntage applies rate limits to protect API stability and keep service available for all organizations. API keys belonging to the same organization share rate limits, with endpoint-specific limits where applicable. ## Rate limit headers Every API response includes headers that show your current rate limit status. ```bash theme={null} curl -i 'https://api.syntage.com/entities' \ --header 'Accept: application/ld+json' \ --header 'X-Api-Key: {apiKey}' ``` ```http theme={null} HTTP/1.1 200 OK Date: Sun, 29 Nov 2020 19:21:21 GMT X-RateLimit-Limit: 60 X-RateLimit-Remaining: 56 X-RateLimit-Reset: 1606678044 ``` | Header Name | Description | | - | - | | X-RateLimit-Limit | The maximum number of requests you're permitted to make. | | X-RateLimit-Remaining | The number of requests remaining in the current rate limit window. | | X-RateLimit-Reset | The time at which the current rate limit window resets in UTC epoch seconds. | ## Exceeding the limit If you exceed the rate limit, the API returns a [429 Too Many Requests](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/429) response. ```http theme={null} HTTP/1.1 429 Too Many Requests Date: Sun, 29 Nov 2020 19:21:21 GMT X-RateLimit-Limit: 60 X-RateLimit-Remaining: 0 X-RateLimit-Reset: 1606678044 ``` When you receive a `429` response, wait until the time in `X-RateLimit-Reset` before retrying. Avoid retry loops that immediately repeat the same request, because they can continue consuming capacity and delay recovery. ## Current limits You can check your organization's current limits in the [Rate Limit settings page](https://app.syntage.com/en/settings/rate-limit). Syntage may reduce limits to prevent abuse or increase limits to support approved high-traffic operations. To request an increased rate limit, please [contact support](https://support.syntage.com). # Request IDs Source: https://docs.syntage.com/guides/api/request-ids Every API response includes a request ID. Use it when debugging a request, comparing logs, or contacting Syntage support about a specific API call. ## Header The request ID is returned in the `X-Request-ID` response header. ```bash theme={null} curl -i 'https://api.syntage.com/entities' \ --header 'Accept: application/ld+json' \ --header 'X-Api-Key: {apiKey}' ``` ```http theme={null} HTTP/1.1 200 OK Date: Sun, 29 Nov 2020 19:21:21 GMT X-Request-ID: f242e9e0-c1ba-4bbe-ba64-4966c702b5d2 ``` ## When to use it Include the request ID when you contact support or investigate a failed request. It lets Syntage identify the exact API request without relying on timestamps, endpoint names, or partial payload details. > [!NOTE] > > Log the `X-Request-ID` value with your own application logs when possible. This makes it easier to trace a request across your application and Syntage. ## Example ```bash theme={null} curl -i 'https://api.syntage.com/entities/{entityId}/tax-status' \ --header 'Accept: application/ld+json' \ --header 'X-Api-Key: {apiKey}' ``` ```http theme={null} HTTP/1.1 200 OK Date: Sun, 29 Nov 2020 19:21:21 GMT X-Request-ID: f242e9e0-c1ba-4bbe-ba64-4966c702b5d2 Content-Type: application/ld+json ``` # SAT Catalogs Source: https://docs.syntage.com/guides/catalogs SAT catalogs define the codes used in CFDI invoices, payments, retentions, and related SAT data. Syntage returns many SAT fields as catalog codes, so these tables help you interpret common values in API responses. This page includes the SAT catalogs most commonly used when reading invoice and retention data through the API. It is not a replacement for the official SAT catalog files, which may include additional codes and validity rules. ## How to use these catalogs Use the code from the API response to look up its meaning in the relevant catalog. For example, an invoice with `paymentType: "PUE"` uses `c_MetodoPago`, where `PUE` means payment in one installment. Some SAT catalog values are only valid for specific CFDI versions, dates, taxpayer regimes, or document types. When you need complete validation rules, use the official SAT catalog for that field. ## c\_TipoDeComprobante Type of CFDI document. This indicates whether the CFDI is an invoice, credit note, payment complement, payroll receipt, or transfer document. | Code | Description | | - | - | | I | Income (Ingreso) | | E | Egress (Egreso) | | P | Payment (Pago) | | N | Payroll (Nómina) | | T | Merchandise Transfer (Traslado) | ## c\_MetodoPago Payment method for the CFDI. This identifies whether the invoice was paid in one installment or in installments/deferred payment. | Code | Description | | - | - | | PUE | One payment | | PPD | Partial payments | ## c\_FormaPago Payment form used for the transaction, such as cash, electronic transfer, credit card, debit card, or another SAT-defined payment form. | Code | Description | | - | - | | 01 | Cash | | 02 | Payroll check | | 03 | Electronic transfer | | 04 | Credit card | | 05 | Electronic wallet | | 06 | Digital money | | 08 | Pantry vouchers | | 12 | Settlement | | 13 | Payment by subrogation | | 14 | Payment by consignment | | 15 | Condonation | | 17 | Compensation | | 23 | Novation | | 24 | Confusion | | 25 | Debt remittance | | 26 | Prescription or expiration | | 27 | To creditor satisfaction | | 28 | Debit card | | 29 | Service card | | 30 | Aplicación de anticipos | | 31 | Intermediario pagos | | 99 | To define | ## c\_Moneda Currency used in the CFDI. | Code | Description | | - | - | | MXN | Mexican pesos | | USD | US dollar | | EUR | Euro | ## c\_RegimenFiscal Tax regime associated with the issuer or receiver. | Code | Description | | - | - | | 601 | General de Ley Personas Morales | | 603 | Personas Morales con Fines no Lucrativos | | 605 | Sueldos y Salarios e Ingresos Asimilados a Salarios | | 606 | Arrendamiento | | 607 | Régimen de Enajenación o Adquisición de Bienes | | 608 | Demás ingresos | | 609 | Consolidación | | 610 | Residentes en el Extranjero sin Establecimiento Permanente en México | | 611 | Ingresos por Dividendos (socios y accionistas) | | 612 | Personas Físicas con Actividades Empresariales y Profesionales | | 614 | Ingresos por intereses | | 615 | Régimen de los ingresos por obtención de premios | | 616 | Sin obligaciones fiscales | | 620 | Sociedades Cooperativas de Producción que optan por diferir sus ingresos | | 621 | Incorporación Fiscal | | 622 | Actividades Agrícolas, Ganaderas, Silvícolas y Pesqueras | | 623 | Opcional para Grupos de Sociedades | | 624 | Coordinados | | 628 | Hidrocarburos | | 629 | De los Regímenes Fiscales Preferentes y de las Empresas Multinacionales | | 630 | Enajenación de acciones en bolsa de valores | | 625 | Régimen de las Actividades Empresariales con ingresos a través de Plataformas Tecnológicas | | 626 | Régimen Simplificado de Confianza | ## c\_UsoCFDI Intended use of the CFDI declared by the receiver. | Code | Description | | - | - | | G01 | Acquisition of merchandise | | G02 | Refund, discounts or bonuses | | G03 | General expenses | | I01 | Buildings | | I02 | Furniture and office equipment | | I03 | Transport equipment | | I04 | Computer equipment and accessories | | I05 | Dies, molds, dies and tooling | | I06 | Telephone communications | | I07 | Satellite communications | | I08 | Other machinery and equipment | | D01 | Medical, dental and hospital fees | | D02 | Medical expenses for disability or disability | | D03 | Funeral expenses | | D04 | Donations | | D05 | Real interest paid on mortgage loans | | D06 | Voluntary contributions to the SAR | | D07 | Medical expense insurance | | D08 | School transportation expenses | | D09 | Deposits in savings accounts, premiums based on pension plans | | D10 | Payments for educational services | | S01 | No tax effects | | P01 | To define | | CP01 | Payments | | CN01 | Payroll | ## c\_ClaveProdServ Product or service code used in CFDI line items. The full catalog is large and changes over time, so use the official SAT catalog for complete lookup and validation. [Official SAT product and service catalog](https://www.sat.gob.mx/consultas/53693/catalogo-de-productos-y-servicios) ## c\_ClaveUnidad Unit code used in CFDI line items. This identifies the unit of measure for a product or service. | Type | Code | Name | | - | - | - | | Múltiplos / Fracciones / Decimales | H87 | Pieza | | Unidades de venta | EA | Elemento | | Unidades específicas de la industria (varias) | E48 | Unidad de Servicio | | Unidades de venta | ACT | Actividad | | Mecánica | KGM | Kilogramo | | Unidades específicas de la industria (varias) | E51 | Trabajo | | Diversos | A9 | Tarifa | | Tiempo y Espacio | MTR | Metro | | Diversos | AB | Paquete a granel | | Unidades específicas de la industria (varias) | BB | Caja base | | Unidades de venta | KT | Kit | | Unidades de venta | SET | Conjunto | | Tiempo y Espacio | LTR | Litro | | Unidades de empaque | XBX | Caja | | Tiempo y Espacio | MON | Mes | | Tiempo y Espacio | HUR | Hora | | Tiempo y Espacio | MTK | Metro cuadrado | | Diversos | 11 | Equipos | | Mecánica | MGM | Miligramo | | Unidades de empaque | XPK | Paquete | | Unidades de empaque | XKI | Kit (Conjunto de piezas) | | Diversos | AS | Variedad | | Mecánica | GRM | Gramo | | Números enteros / Números / Ratios | PR | Par | | Unidades de venta | DPC | Docenas de piezas | | Unidades de empaque | xun | Unidad | | Tiempo y Espacio | DAY | Día | | Unidades de empaque | XLT | Lote | | Diversos | 10 | Grupos | | Tiempo y Espacio | MLT | Mililitro | | Unidades específicas de la industria (varias) | E54 | Viaje | ## c\_Impuesto Tax type used in transferred or withheld taxes. | Code | Name | | - | - | | 001 | ISR | | 002 | IVA | | 003 | IEPS | ## c\_TipoFactor Tax factor type used to calculate a tax amount. | Type | | - | | Tasa | | Cuota | | Exento | ## c\_TipoRelacion Relationship type used when one CFDI references another CFDI, such as credit notes, substitutions, returns, or advance payments. | Code | Description | | - | - | | 01 | Nota de crédito de los documentos relacionados | | 02 | Nota de débito de los documentos relacionados | | 03 | Devolución de mercancía sobre facturas o traslados previos | | 04 | Sustitución de los CFDI previos | | 05 | Traslados de mercancias facturados previamente | | 06 | Factura generada por los traslados previos | | 07 | CFDI por aplicación de anticipo | | 08 | Factura generada por pagos en parcialidades | | 09 | Factura generada por pagos diferidos | ## Clave de retenciones Retention type used in SAT retention documents. | Code | Description | | - | - | | 01 | Servicios profesionales | | 02 | Regalías por derechos de autor | | 03 | Autotransporte terrestre de carga | | 04 | Servicios prestados por comisionistas | | 05 | Arrendamiento | | 06 | Enajenación de acciones. | | 07 | Enajenación de bienes objeto de la LIEPS, a través de mediadores, agentes, representantes, corredores, consignatarios o distribuidores | | 08 | Enajenación de bienes inmuebles consignada en escritura pública | | 09 | Enajenación de otros bienes, no consignada en escritura pública | | 10 | Adquisición de desperdicios industriales | | 11 | Adquisición de bienes consignada en escritura pública | | 12 | Adquisición de otros bienes, no consignada en escritura pública | | 13 | Otros retiros de AFORE. | | 14 | Dividendos o utilidades distribuidas. | | 15 | Remanente distribuible. | | 16 | Intereses. | | 17 | Arrendamiento en fideicomiso. | | 18 | Pagos realizados a favor de residentes en el extranjero. | | 19 | Enajenación de acciones u operaciones en bolsa de valores. | | 20 | Obtención de premios. | | 21 | Fideicomisos que no realizan actividades empresariales. | | 22 | Planes personales de retiro. | | 23 | Intereses reales deducibles por créditos hipotecarios. | | 24 | Operaciones Financieras Derivadas de Capital | | 25 | Otro tipo de retenciones | | 26 | Servicios tecnológicos | # Embedding Entity Onboarding Source: https://docs.syntage.com/guides/embedding-entity-onboarding This guide explains how to integrate the onboarding experience directly into your application. Use it when you want users to complete onboarding on your own site instead of redirecting them to a Syntage-hosted page. ## Include the onboarding script To get started, add the following script to your application: ```html theme={null} ``` Get your slug from the [Entity Onboarding configuration page](https://app.syntage.com/en/settings/entity-onboarding). ## Start onboarding Once the script is added, you can access the available methods via `window.syntage.onboarding`. To start the onboarding process, use the `init()` method. Specify which data you want to request from users. Example of initialization with `sat` only: ```js theme={null} window.syntage.onboarding.init({ sat: true }); ``` Example of initialization with `buroDeCredito` only: ```js theme={null} window.syntage.onboarding.init({ buroDeCredito: true }); ``` To include both parameters: ```js theme={null} window.syntage.onboarding.init({ sat: true, buroDeCredito: true }); ``` The option values must be boolean. ## Test environment To use onboarding in sandbox, add the sandbox script to your application. The sandbox script displays a warning that onboarding is in test mode. ```html theme={null} ``` ## Event subscriptions The `window.syntage.onboarding` object provides a `subscribe` method to receive onboarding events. To subscribe to the success event, use the following code: ```js theme={null} window.syntage.onboarding.subscribe("syntage.onboarding.success", (_, step) => { console.info("syntage.onboarding.success", step); }); ``` The `step` parameter returns `sat` or `buroDeCredito`. To subscribe to error events, use the following code: ```js theme={null} window.syntage.onboarding.subscribe("syntage.onboarding.error", (_, error) => { console.info("syntage.onboarding.error", error); }); ``` The returned error object contains a `code` and a message. Example of an error: ```json theme={null} { "code": "ERROR_CODE", "step": "sat" } ``` ### Error descriptions * Credential disabled: `credentialDisabled` * Credential invalid: `credentialInvalid` * Generic error: `error` * Unknown error: `unknownError` ## Content Security Policies [Content Security Policies (CSP)](https://content-security-policy.com/) are delivered as a header to your user's browser by your web server. They declare which dynamic resources are allowed to load on your page. If there is a Content Security Policy issue, you will see something similar to the below error: ``` Refused to load the script 'https://onboarding.syntage.com/script.min.js' because it violates the following Content Security Policy directive: "script-src 'self' 'unsafe-eval' 'unsafe-inline'" ... ``` If needed, include Syntage in your CSP configuration: ``` default-src ... https://*.syntage.com frame-src ... https://*.syntage.com ``` ## Tips If the script is not yet loaded when executing `init()`, you can listen for the `entityOnboardingLoaded` event to ensure proper initialization: ```js theme={null} try { window.syntage.onboarding.init({ ... }); } catch { window.addEventListener("entityOnboardingLoaded", (e) => { window.syntage.onboarding.init({ ... }); }); } ``` ### Using with TypeScript ```ts theme={null} type SyntageOnboarding = { onboarding: { init(options: { sat: boolean; buroDeCredito: boolean }): void; destroy(): void; subscribe( event: T, callback: T extends 'syntage.onboarding.success' ? (event: T, step: 'sat' | 'buroDeCredito') => void : ( event: T, error: { code: 'credentialDisabled' | 'credentialInvalid' | 'error' | 'unknownError'; step: 'sat' | 'buroDeCredito'; }, ) => void, ): void; }; }; interface Window { syntage: SyntageOnboarding; } ``` ### Using with React In Next.js, you can use the [script tag](https://nextjs.org/docs/pages/api-reference/components/script) to include this script in your application. When using only React, you can use the [react-helmet](https://www.npmjs.com/package/react-helmet) library to manage scripts. You can also create a custom hook to inject the script into your application: > [!NOTE] > > Use `https://onboarding.sandbox.syntage.com/script.min.js` when testing onboarding in sandbox. ```js theme={null} const useImportWidgetScript = ({ scriptUrl, slug, sandbox }) => { const scriptRef = useRef(null); useEffect(() => { if (!slug || typeof slug !== 'string') { console.error('Invalid slug provided.'); return; } const script = document.createElement('script'); script.async = true; script.src = scriptUrl; script.setAttribute('data-key', slug); if (sandbox) { script.setAttribute('data-sandbox', sandbox); } scriptRef.current = script; document.body.appendChild(script); return () => { if (scriptRef.current) { document.body.removeChild(scriptRef.current); scriptRef.current = null; } }; }, [scriptUrl, slug, sandbox]); }; // Usage useImportWidgetScript({ scriptUrl: "https://onboarding.syntage.com/script.min.js", slug: "YOUR_COMPANY_SLUG", sandbox: false, }); ``` # Integration Flow Source: https://docs.syntage.com/guides/integration-flow This guide describes a common SAT credential and extraction flow. Other datasources may use different credentials, authorizations, or report endpoints, but the same general pattern applies: create or identify the entity, provide the required datasource access, request or schedule data extraction, and listen for webhook events. ## Create and validate a SAT credential Create a SAT credential with [Create a credential](/api-reference/ds-mx-sat-credentials/create-a-credential). After the credential is submitted, use one of these approaches to track validation: * Create a webhook endpoint with [Create a webhook endpoint](/api-reference/webhook-endpoints/create-a-webhook-endpoint) and listen for `credential.updated` events. * Poll [Retrieve a credential](/api-reference/ds-mx-sat-credentials/retrieve-a-credential) until the credential reaches a final status. SAT credential validation usually takes between 10 and 20 seconds. A credential can have one of the following statuses: | Status | Description | | - | - | | `waiting` | Credential validation is temporarily disabled, usually because of an ongoing incident. The credential is validated later. | | `pending` | Credential validation has been requested and is waiting to be processed. | | `valid` | The credential was accepted by SAT and can be used for extractions. | | `invalid` | SAT rejected the credential during validation. | | `disabled` | SAT reported the credential as disabled or otherwise unrecoverable during validation. | | `deactivated` | **Deprecated.** Legacy status retained for existing records. Use `disabled` for credentials that can no longer be used. | | `error` | Credential validation failed because of an unexpected error. | Some credential responses include a `statusReason` object with a more specific reason for the status. For example, an `error` credential can include `statusReason.type: "unsupportedPortableEfirma"` when SAT requires the portable e.firma dynamic-code flow, which Syntage does not support for credential registration. When a SAT credential becomes `valid`, Syntage creates the related entity if it does not already exist. ```mermaid theme={null} sequenceDiagram %%{init: {'securityLevel': 'loose', 'theme': 'base'}}%% autonumber participant Client participant Syntage participant SAT Client->>+Syntage: Create credential (POST /credentials) Syntage-->>-Client: Credential response Syntage->>+SAT: Validate credential SAT-->>-Syntage: Validation result opt webhook endpoint subscribed to credential.updated Syntage->>Client: Send credential.updated event end loop until the credential reaches a final status Client->>Syntage: Retrieve credential (GET /credentials/{id}) Syntage-->>Client: Credential response end ``` ## Extract data After the entity and credential are available, you can request data extraction. Extractions are jobs that retrieve data from a datasource, such as SAT invoices, tax returns, tax status, tax compliance checks, and other supported records. You can create an extraction directly with [Create an extraction](/api-reference/extractions/create-an-extraction). Schedulers can also create recurring or first-time extractions when configured for your organization. All extractions start with a `pending` status while they wait in the queue. When processing starts, the status changes to `running`. You can retrieve the current status with [Retrieve an extraction](/api-reference/extractions/retrieve-an-extraction). You can create webhook endpoints for extraction events and receive notifications when extractions are created or updated. ```mermaid theme={null} sequenceDiagram %%{init: {'securityLevel': 'loose', 'theme': 'base'}}%% autonumber participant Client participant Syntage participant Datasource Client->>+Syntage: Create extraction (POST /extractions) Syntage-->>-Client: Extraction response opt webhooks are enabled Syntage->>Client: Send extraction.created event end Syntage->>Syntage: Start extraction opt extraction status changes Syntage->>Client: Send extraction.updated event end Syntage->>+Datasource: Retrieve data for the entity Datasource-->>-Syntage: Return records opt extraction finishes Syntage->>Client: Send extraction.updated event end ``` After an extraction finishes, use the relevant API reference pages to retrieve the extracted records, reports, insights, or files. # Validating Webhook Requests Source: https://docs.syntage.com/guides/validating-webhook-requests How to validate webhook calls by using the `signingSecret` value. Whenever a webhook is called, an `X-Syntage-Signature` header is sent to help verify it. Its value has the form `t=,s=`. Syntage generates the signature using a hash-based message authentication code (HMAC) with SHA-256 using the `signingSecret` as key, and sends it as a lowercase hexadecimal string. Syntage also sends the same value in the `X-Satws-Signature` header for integrations built before the header was renamed. New integrations should read `X-Syntage-Signature`. To verify the signature you can do the following steps: ## Step 1: Extract the timestamp and signature from the header Split the header, using the `,` character as the separator. The value for the prefix `t` corresponds to the timestamp and `s` corresponds to the signature. ## Step 2: Prepare the signed payload Create the signed payload by concatenating these values without spaces: * the timestamp as a Unix timestamp string, for example `"1656569160"` * the `.` character * the raw request body exactly as received ## Step 3: Determine the expected signature Compute an HMAC with the SHA-256 hash function. Use the endpoint's signing secret as the key and the signed payload as the message. ## Step 4: Compare the signatures Compare the signature in the header to the expected signature. To protect against timing attacks, use a constant-time comparison. You should also reject timestamps outside your tolerance window. ## Examples These examples assume you pass the raw request body exactly as received. Do not parse and re-serialize the JSON before computing the signature. In the JavaScript and Python examples, pass the value of the `X-Syntage-Signature` header as the signature header. ### PHP ```php theme={null} $toleranceSeconds) { throw new RuntimeException('Webhook signature timestamp is outside the tolerance window.'); } $expectedSignature = hash_hmac('sha256', sprintf('%s.%s', $timestamp, $bodyPayload), $signingSecret); $isValid = false; foreach ($signatures as $signature) { if (hash_equals($expectedSignature, $signature)) { $isValid = true; break; } } if (!$isValid) { throw new RuntimeException('Invalid webhook signature.'); } ``` ### JavaScript / TypeScript ```ts theme={null} import { createHmac, timingSafeEqual } from "node:crypto"; function validateSyntageWebhookSignature({ signatureHeader, bodyPayload, signingSecret, now = Math.floor(Date.now() / 1000), }) { if (!bodyPayload) { throw new Error("Missing webhook payload."); } if (!signingSecret) { throw new Error("Missing webhook signing secret."); } const values = new Map(); for (const part of signatureHeader.split(",")) { const separatorIndex = part.indexOf("="); if (separatorIndex === -1) { throw new Error("Malformed webhook signature."); } const key = part.slice(0, separatorIndex); const value = part.slice(separatorIndex + 1); values.set(key, [...(values.get(key) ?? []), value]); } const timestamp = values.get("t")?.[0]; const signatures = values.get("s") ?? []; if (!timestamp || signatures.length === 0) { throw new Error("Missing webhook signature."); } const toleranceSeconds = 300; if (Math.abs(now - Number(timestamp)) > toleranceSeconds) { throw new Error("Webhook signature timestamp is outside the tolerance window."); } const expectedSignature = createHmac("sha256", signingSecret) .update(`${timestamp}.${bodyPayload}`) .digest("hex"); const expectedBuffer = Buffer.from(expectedSignature, "hex"); const isValid = signatures.some((signature) => { const signatureBuffer = Buffer.from(signature, "hex"); return ( signatureBuffer.length === expectedBuffer.length && timingSafeEqual(signatureBuffer, expectedBuffer) ); }); if (!isValid) { throw new Error("Invalid webhook signature."); } } ``` ### Python ```python theme={null} import hashlib import hmac import time def validate_syntage_webhook_signature( signature_header: str, body_payload: bytes, signing_secret: str, now: int | None = None, ) -> None: if not body_payload: raise ValueError("Missing webhook payload.") if not signing_secret: raise ValueError("Missing webhook signing secret.") values: dict[str, list[str]] = {} for part in signature_header.split(","): if "=" not in part: raise ValueError("Malformed webhook signature.") key, value = part.split("=", 1) values.setdefault(key, []).append(value) timestamp = values.get("t", [None])[0] signatures = values.get("s", []) if timestamp is None or not signatures: raise ValueError("Missing webhook signature.") now = now or int(time.time()) tolerance_seconds = 300 if abs(now - int(timestamp)) > tolerance_seconds: raise ValueError("Webhook signature timestamp is outside the tolerance window.") expected_signature = hmac.new( signing_secret.encode("utf-8"), f"{timestamp}.".encode("utf-8") + body_payload, hashlib.sha256, ).hexdigest() if not any(hmac.compare_digest(expected_signature, signature) for signature in signatures): raise ValueError("Invalid webhook signature.") ``` ## Checking the Content-Digest header Each delivery also includes a `Content-Digest` header, as defined in [RFC 9530](https://www.rfc-editor.org/rfc/rfc9530). It contains the SHA-256 digest of the raw request body, encoded in base64 and wrapped in colons: ``` Content-Digest: sha-256=:: ``` To check it, compute the SHA-256 digest of the raw request body, encode the binary digest in standard base64, and compare the result with the value between the colons. The digest confirms that the body was not altered or truncated in transit. It does not prove that the request came from Syntage, because anyone can compute a digest, so always validate the signature as described above. The signature already covers the full body, which makes checking the digest optional. ```php theme={null} $expectedDigest = sprintf('sha-256=:%s:', base64_encode(hash('sha256', $bodyPayload, true))); $isDigestValid = hash_equals($expectedDigest, $_SERVER['HTTP_CONTENT_DIGEST'] ?? ''); ``` ```ts theme={null} import { createHash } from "node:crypto"; const expectedDigest = `sha-256=:${createHash("sha256").update(bodyPayload).digest("base64")}:`; const isDigestValid = contentDigestHeader === expectedDigest; ``` ```python theme={null} import base64 import hashlib expected_digest = f"sha-256=:{base64.b64encode(hashlib.sha256(body_payload).digest()).decode()}:" is_digest_valid = content_digest_header == expected_digest ``` # Widget (Deprecated) Source: https://docs.syntage.com/guides/widget > [!WARNING] > > This widget is deprecated. Existing integrations can continue using it, but new integrations should use [Embedding Entity Onboarding](/guides/embedding-entity-onboarding) instead. The widget script embeds the legacy registration experience in your application. Use this page if your integration already depends on the legacy widget and you need to keep it working or troubleshoot it. ## Add the script Get your `SCRIPT_URL` and `COMPANY_SLUG` from the dashboard under `Widget > Widget script`, then add the script tag to your application. ```html theme={null} ``` The `data-key` value identifies your widget configuration. Keep it aligned with the environment you are using. ## Start and stop registration After the script loads, use `window.Satws.init()` to open the registration experience. ```js theme={null} window.Satws.init(); ``` Use `window.Satws.destroy()` to close and clean up the widget. ```js theme={null} window.Satws.destroy(); ``` ## Sandbox warning To show the legacy sandbox warning, pass `data-sandbox="true"` in the script tag. ```html theme={null} ``` > [!NOTE] > > The `data-sandbox` attribute only controls the warning shown to users. The token and script URL determine whether the widget connects to production or sandbox. ## Events Use `window.Satws.subscribe` to subscribe to widget events. | Event | Description | | - | - | | `registerWithSuccess` | Fired when registration succeeds. | | `errorOnRegister` | Fired when registration fails. | ```js theme={null} window.Satws.subscribe("registerWithSuccess", () => { // Continue your success flow. }); ``` ```js theme={null} window.Satws.subscribe("errorOnRegister", () => { // Show your error state or retry option. }); ``` ## Dynamic loading If you load the widget dynamically in an SPA or through GTM, the script may not be ready when you call `init()`. Listen for `widgetScriptLoaded` before starting registration. ```js theme={null} try { window.Satws.init(); } catch { window.addEventListener("widgetScriptLoaded", () => { window.Satws.init(); }); } ``` ## Troubleshooting * Confirm the script tag uses the `id="satws-widget-id"` attribute. * Confirm `data-key` matches the widget configuration for the environment you are using. * Confirm the widget script is allowed by your Content Security Policy. * Subscribe to `errorOnRegister` so your application can show a useful error state. # Overview Source: https://docs.syntage.com/index Start here for Syntage product documentation, developer guides, API reference, and changelogs. Syntage gives your organization access to business data, analysis, and indicators from trusted Mexican datasources, including SAT, RPC, RUG, Buró de Crédito, Buró Empresas, Infonavit, and more. These docs are organized by audience: * Use **Using Syntage** to understand how Syntage works, including entities, datasources, extractions, and onboarding workflows. * Use **Resource Guide** to learn what each resource represents before you work with it in the dashboard or API. * Use **Developers** for integration guides, environments, webhooks, pagination, request IDs, and API behavior. * Use **API Reference** when you need endpoint paths, parameters, response schemas, and examples. ## Where to start * Start with [Quick start](/using-syntage/get-started/quick-start) if your team is new to Syntage. * Use [Trial best practices](/using-syntage/get-started/trial-best-practices) to plan a pilot or proof of concept. * Start with [Datasources](/using-syntage/datasources) to understand the kinds of information Syntage can retrieve and analyze. * Read [Entities](/using-syntage/entities) and [Extractions](/using-syntage/extractions) to understand how Syntage connects people and companies to retrieved data. * Read [Entities and onboarding](/using-syntage/dashboard/entities-and-onboarding) to understand how your team can add entities and collect required authorizations. * Use [Reports](/using-syntage/dashboard/reports) and [Data](/using-syntage/dashboard/data) to understand where processed analysis and source records appear. * Use [Developer overview](/developers/overview) if you are building an integration. # Entities Source: https://docs.syntage.com/resources/core/entities Entities represent the people and companies your organization works with in Syntage. Use an entity ID to request data, start extractions, manage identifiers, assign entity tags, and review events for that person or company. An entity can be created with a name, type, optional RFC, optional identifiers, and optional datasources to start extracting. If required information is missing, Syntage returns an onboarding URL that can be used to collect the missing information from the entity. ## When Syntage returns an `onboardingUrl` The `POST /entities` response includes `onboardingUrl` only when Syntage still needs input from the entity to complete setup. The most common trigger is an omitted `rfc`. If your request already provides a valid `rfc` (and any other information Syntage needs to resolve the entity), the response omits `onboardingUrl` or returns it as empty because no onboarding step is required. > [!NOTE] > > Returned onboarding URLs do not expire. ## How Entities Are Used 1. Create or retrieve an entity. 2. Store the entity ID returned by Syntage. 3. Use the entity ID when requesting datasource records, creating extractions, listing events, assigning tags, or adding identifiers. 4. If Syntage returns an `onboardingUrl`, send the entity to that URL or embed the onboarding experience in your own site. The entity ID is stable across datasources. A single entity can be connected to SAT credentials, RPC data, RUG data, Buró de Crédito reports, Infonavit data, and more. ## Entity IDs Use the entity ID in new integrations: ```text theme={null} /entities/{entityId} /entities/{entityId}/tax-status /entities/{entityId}/invoices ``` Some older endpoints also accept RFC-based URLs for backwards compatibility. New endpoints and features are only added under entity-based URLs. For endpoint details, see [Entities API Reference](/api-reference/entities/add-an-entity). ## Identifiers Identifiers store country-specific values that can be used by datasources and product workflows. Mexico currently supports: | Country | Identifier | Example | | - | - | - | | `mx` | `rfc` | `XAXX010101000` | | `mx` | `curp` | `BADD110313HCMLNS09` | Identifiers may be supplied when creating an entity or added later with the entity identifiers endpoint. ## Personal favorites Favorites let each user keep a personal selection of entities within their organization. Other users, including administrators, have their own selections. Favoriting an entity does not change its tags or grant access to it; an entity you can no longer access is excluded from your results. ### Favorites API Send `POST /entities/favorites` to add one or more favorites or `DELETE /entities/favorites` to remove them. Both methods accept the same JSON body with entity IRIs: ```json theme={null} {"entities": ["/entities/91106968-1abd-4d64-85c1-4e73d96fb997"]} ``` Supply 1–100 entity IRIs. Repeated IRIs are processed once. Each batch is atomic: if any entity is missing or inaccessible, no favorites change. Successful additions and removals return `204 No Content` without a response body. Repeating an add or removal is safe; adding an existing favorite preserves its timestamps. GET entity list and item responses include `isFavorite` for the authenticated user by default. If you select response fields with `properties[]`, include `properties[]=isFavorite` to receive it; create and update responses do not include this field. Use `GET /entities?isFavorite=true` for favorites or `?isFavorite=false` for other accessible entities. The authenticated user and organization determine whose favorites are changed; neither can be selected in the request. Read-only users can manage their favorites with JWT authentication. Their existing API-key restriction still applies. ## Entity Tags Entity tags are organization-defined labels for grouping and filtering entities. They are useful when your integration needs to treat a set of entities the same way. Common use cases include: | Use case | Example | | - | - | | Extraction schedulers | Run a daily invoice extraction for every entity tagged `Daily invoices`. | | Monitoring | Track high-priority entities separately from the rest of your organization. | | Filtering in Syntage | Filter the entity list in the Syntage dashboard. | | Segmentation in your product | Use tags to build your own dashboards, review queues, or support workflows around tagged entities. | Create entity tags first, then assign them to an entity by updating the entity's `tags` collection. When updating an entity's tags, send the complete list of entity tag IRIs the entity should have. The submitted list replaces the previous assignments. # Events Source: https://docs.syntage.com/resources/core/events Events record meaningful changes to resources in your organization. When something changes, Syntage creates an Event resource. For example, submitting an entity's SAT credential can create credential and entity events, and a completed extraction can create an `extraction.updated` event. Many requests can create more than one event. For example, submitting valid SAT credentials for an entity can create `credential.created`, `credential.updated`, and `link.created` events. Events occur when the state of another resource changes. The state of that resource at the time of the change is embedded in the event's `data` field. For example, a `credential.updated` event contains a Credential, and an `invoice.updated` event contains an Invoice. Deleted events don't include the resource, so their `data` is an empty array. Use the Events endpoints to retrieve recent events directly. Use [webhooks](/developers/webhooks) when you want Syntage to deliver events to your server automatically. > [!NOTE] > > Access to events is only guaranteed for 7 days. > [!NOTE] > > Entity lifecycle events still use the `link.*` event type names for backwards compatibility. ## How Events Are Used 1. Subscribe to [webhooks](/developers/webhooks) when your integration needs to react automatically to resource changes. 2. Store the event ID from each webhook request or Events response so your integration can deduplicate processing. 3. Use `type` to route the event to the correct handler. 4. Use `resource` to retrieve the current version of the changed resource when needed. 5. Use `data.object` when you need the resource state captured at the time the event was created. The Events endpoints are useful for backfills, debugging, and reconciliation. Webhooks are the best fit for ongoing delivery. For implementation details, see [Event examples](/developers/event-examples). ## Event Types The suffix describes the kind of change: | Suffix | Meaning | | - | - | | `.created` | A new resource was created. | | `.updated` | An existing resource changed. | | `.deleted` | A resource was deleted or is no longer available. | | Resource | Event types | | - | - | | Credentials | `credential.created`, `credential.updated`, `credential.deleted` | | Entities | `link.created`, `link.updated`, `link.deleted` | | Files | `file.created` | | Extractions | `extraction.created`, `extraction.updated` | | Exports | `export.created`, `export.updated` | | Invoices | `invoice.created`, `invoice.updated`, `invoice.deleted` | | Invoice payments | `invoice_payment.created`, `invoice_payment.updated` | | Invoice line items | `invoice_line_item.created`, `invoice_line_item.updated` | | Tax returns | `tax_return.created`, `tax_return.updated`, `tax_return.deleted` | | Tax status | `tax_status.created`, `tax_status.updated`, `tax_status.deleted` | | Tax compliance checks | `tax_compliance_check.created`, `tax_compliance_check.updated`, `tax_compliance_check.deleted` | | Tax retentions | `tax_retention.created`, `tax_retention.updated`, `tax_retention.deleted` | | Electronic accounting records | `electronic_accounting_record.created`, `electronic_accounting_record.updated` | | RPC entidades | `rpc_entidades.created`, `rpc_entidades.updated` | | RPC socios | `rpc_socios.created`, `rpc_socios.updated` | | RPC actos | `rpc_acto.created`, `rpc_acto.updated` | | Shareholder relations | `shareholder_relation.created`, `shareholder_relation.updated` | | Shareholder relation sources | `shareholder_relation_source.created` | | RUG garantias | `rug_garantia.created`, `rug_garantia.updated` | | Buró de Crédito reports | `buro_de_credito_report.created`, `buro_de_credito_report.updated` | | Background checks | `background_check.created` | | SAT certificates | `sat_certificate.created`, `sat_certificate.updated` | | Company verification reports | `company_verification_report.created`, `company_verification_report.updated` | # Exports Source: https://docs.syntage.com/resources/core/exports Exports create downloadable files from Syntage data. Use them when your integration needs a file that can be stored, shared, imported into another system, or delivered to an operations team. Creating an export starts asynchronous processing and returns an Export resource. The export keeps track of the requested source data, output format, processing status, and generated file. ## How Exports Work 1. Create an export with the collection URI and output format you need. 2. Store the returned export ID. 3. Retrieve the export until its `status` is `finished` or `failed`. 4. Download the generated file from the File resource referenced by the export. Exports are useful for workflows such as finance reports, invoice handoffs, customer support investigations, back-office review, and scheduled data delivery. ## Viewing your exports Browse your exports in the [dashboard](https://app.syntage.com/settings/exports), or list them with [`GET /exports`](/api-reference/exports/list-all-exports). Both return only the exports you created, not those created by other users in your organization. ## Report PDF exports Besides collection exports in `csv`, `xlsx`, or `json` format, exports can also generate a PDF document of an entity [report](/resources/insights/reports). Set `format` to `pdf` and `uri` to `/entities/{entityId}/reports/{reportId}?exporting=true`; the finished export references a `report.insights.pdf` file. The `exporting=true` query parameter is required and is the only supported query parameter on report URIs. See [Reports](/resources/insights/reports) for the full flow. For endpoint details, see [Exports API Reference](/api-reference/exports/export-data). | Status | Meaning | | - | - | | `pending` | The export has been accepted and is waiting to run. | | `running` | Syntage is building the export file. | | `finished` | The export file is ready to download. | | `failed` | The export could not be completed. Create a new export after correcting the request. | > [!TIP] > > The export response references a File resource when the generated file is ready. Use the file metadata to inspect the filename, media type, and size before downloading it. # Extractions Source: https://docs.syntage.com/resources/core/extractions Extractions are tasks that retrieve data for an entity from a datasource. They are used to collect invoices, tax returns, tax status, tax compliance checks, RPC records, RUG guarantees, Buró de Crédito reports, and other datasource-backed records. An extraction runs asynchronously. Creating one starts or queues the work, and the returned Extraction resource tracks its status, options, timing, errors, and the number of resources created or updated. ## How Extractions Work 1. Create or retrieve the entity you want to extract data for. 2. Start the extraction with the selected datasource and options. 3. Store the returned extraction ID. 4. Retrieve the extraction until its `status` is `finished` or `failed`. 5. Read the extracted data from the related resource endpoints, such as invoices or tax returns. If an equivalent extraction is already `pending` or `running` for the same entity, extractor, and options, Syntage returns `409 Conflict` instead of starting the same work again. The response includes `conflictingExtractors`, the list of extractors whose equivalent extraction is already in progress. Retrieve or wait for those extractions to finish, or remove the listed extractors from the request before retrying. For implementation details, see [Extraction request examples](/developers/extraction-request-examples) or [Create an extraction](/api-reference/extractions/create-an-extraction). ## Scheduled Extractions Use schedulers when the same extraction should run repeatedly, such as a daily invoice extraction or a monthly tax return extraction. A scheduler controls whether the automation is enabled, and scheduler rules define the extractor, options, and cron expression. Extractor names and options are specific to the data you are extracting. For extraction-backed resources, use the resource page to understand what data is collected and the developer examples for request bodies. ## Extraction Status | Status | Description | | - | - | | pending | The initial extraction status. The extraction is enqueued and waiting to be processed. | | waiting | The extraction cannot run yet because a prerequisite is still blocking it, such as missing entity information, authorization, an unavailable credential, or an internal dependency. | | running | The extraction process started and is currently running. The running time varies depending on the extractor type and the entity's transactional volume. Partial data may be available from related resource endpoints during this time. | | finished | The extraction finished successfully. The extracted data is available from the related resource endpoints. | | failed | The extraction couldn't start or failed during the process. Our internal retry policies weren't able to finish the extraction successfully. We may have partial data available, but new extractions should be created to ensure all the entity's data is available. You can check the [extraction error code](#extraction-error-codes) to understand why it failed and determine whether it can be retried or not. | | stopping | The extraction was requested to be stopped by the user. It is in the process of being stopped. | | stopped | The extraction was stopped by the user after it started running. This extraction is included in billing. | | cancelled | The extraction was stopped by the user before it started running. This extraction is not included in billing. | ## Extraction Error Codes | Code | Description | Retryable | | - | - | - | | unrecoverable | The extractor doesn't apply to the entity's type. Older extractions can also have this code when the extraction process failed many times and reached the maximum number of retries. | No | | sat\_unavailable | We detected that SAT itself is down or unresponsive. | Yes | | internal\_error | We detected an internal error in our own infrastructure. | Yes | | undefined | We couldn't determine the error cause and our internal team will investigate it. | Yes | The following codes are no longer assigned to new extractions, but they can still appear on older extractions: | Code | Description | Retryable | | - | - | - | | invalid\_credentials | The taxpayer [Credential](/api-reference/ds-mx-sat-credentials) was no longer valid. | After updating the credential | | login\_failed | We couldn't authenticate the taxpayer with the datasource. | Yes | | datasource\_disabled | The Buró de Crédito integration was disabled for the entity type. | No | ## Retrying Failed Extractions An invalid credential doesn't fail a new extraction. The extraction stays `waiting` until the credential is valid again, and then it resumes automatically. Update the credential instead of creating a new extraction. Failed extractions don't resume, including older ones with `invalid_credentials`: update the credential, and then create a new extraction. Before retrying a failed extraction manually: 1. Check [Syntage Status](https://status.syntage.com/) for an incident affecting the relevant datasource or service. If an incident is active, follow its published instructions and avoid creating additional manual extractions while Syntage manages retries or reprocessing. Depending on the incident, automatic retries may continue. 2. After the incident is resolved, review its latest update before retrying manually, as affected extractions may already be undergoing reprocessing. Not every incident includes automatic reprocessing. 3. If the problem persists after the indicated recovery steps, [contact support](https://support.syntage.com) and include the extraction ID. # Files Source: https://docs.syntage.com/resources/core/files Files are binary or text artifacts produced by Syntage resources, such as PDFs, XML files, CSV exports, and generated reports. Most file records are returned from another resource first. For example, an invoice, tax return, export, background check, or company verification report may include one or more files. Use the file endpoint when you need the file metadata, and use the download endpoint when you need the actual file content. The download response content type depends on the stored file. Common formats include PDF, XML, CSV, XLSX, JSON, and plain text. > [!TIP] > > Use the file metadata to inspect the file type, name, size, and related resource before downloading the content. ## How Files Are Used 1. Get a resource that references a file, such as an invoice, export, tax return, report, or background check. 2. Store the file ID or file IRI if your integration needs to retrieve the file later. 3. Retrieve the file when you need metadata such as filename, media type, size, or related resource. 4. Use the download endpoint when you need the file content. ## Download URLs To download a file, call `GET /files/{id}/download` with the file ID from the file resource. The download response returns a redirect: the `Location` header contains the actual URL where the file content is served. Your HTTP client must follow the redirect to receive the bytes. The redirect URL is short-lived, so request it again each time you need to download. Most HTTP clients follow redirects by default. If yours does not, enable redirect following (for example, `curl -L`) before reading the response body. You can also pass `?redirect=false` to receive a JSON response containing the generated `url`. For endpoint details, see [Files API Reference](/api-reference/files/retrieve-a-file). # Tags Source: https://docs.syntage.com/resources/core/tags Tags are organization-defined labels for resources such as invoices. They are useful for review queues, internal workflows, and grouping resources in your integration. Resource tags are separate from entity tags: | Tag type | Used for | IRI format | | - | - | - | | Resource tags | Supported resources such as invoices | `/tags/{id}` | | Entity tags | Entities | `/entity-tags/{id}` | When applying tags to a resource, send the complete `tags` collection you want the resource to have. The submitted collection replaces the previous collection. > [!NOTE] > > Entity tag operations are listed under Entities because they label entities. This section covers resource tags. ## How Tags Are Used 1. Create a tag for the resource type you want to label. 2. Store the tag IRI returned by Syntage, such as `/tags/{id}`. 3. Update the resource with the complete `tags` collection it should have. 4. Use tags in your own integration to build queues, review states, grouping, or reconciliation workflows. ## Tag Color Both resource tags and entity tags accept an optional `color` on create and update. Use it to render each tag with a consistent color in your dashboards, reports, or exports. * Send a 7-character hexadecimal string in the form `#RRGGBB`. Colors are stored in lowercase. * Omit the field or send `null` to keep the default color (`#a3aab5`). * Changing a tag's color updates every resource that already references the tag. ```json theme={null} POST /tags { "name": "To be reviewed", "resourceType": "invoice", "color": "#22c558" } ``` ## Replacing Tag Assignments When an endpoint accepts a `tags` collection, the request replaces the resource's existing tag assignments. To add one tag without removing the current tags, first retrieve the resource, keep its existing tag IRIs, append the new tag IRI, and send the full list back. For endpoint details, see [Tags API Reference](/api-reference/tags/list-all-tags). # BIL reports Source: https://docs.syntage.com/resources/datasources/bil/reports BIL reports come from Buró de Investigaciones Legales and summarize legal investigation results for an entity. Use them when your integration needs to review legal-risk findings, keep the original vendor report, or show the report PDF in your own product. BIL data is collected by running a BIL extraction. The extraction searches BIL using the entity's name, stores the parsed report data, and attaches the original XML and PDF report files. ## How BIL Reports Work 1. Start a BIL extraction for the entity. 2. Poll the extraction until it reaches a terminal status. 3. List the entity's BIL reports. 4. Retrieve the report by ID when you need the full report data or file references. 5. Download the XML or PDF file through the Files API. ## Requirements The entity must have a name. BIL searches are name-based, so the extraction cannot run for an entity without a name. BIL is a premium datasource. Before the `bil` extractor can run via the API, your organization must have a signed agreement acknowledging responsibility for BIL charges, including charges caused by mistakes or duplicate requests. Without that agreement, `POST /extractions` returns a validation error with the violation: ```json theme={null} { "propertyPath": "extractor", "message": "This extractor does not support creating extractions via API." } ``` If you see this error and the entity already has a name, contact your CSM or [Syntage Support](/using-syntage/faq/organization-billing-and-support#how-do-i-contact-support) to complete the BIL agreement before creating BIL extractions via API. For implementation details, see [Extraction request examples](/developers/extraction-request-examples#bil). ## What BIL searches BIL searches up to 156 sources and groups the findings in the vendor report. The sources cover the following areas: | Source group | Purpose and data available | | - | - | | Local, federal, and labor courts | Finds published proceedings, notifications, bulletins, edicts, parties, dates, and case identifiers when the court makes them available. | | Administrative sources | Checks tax, social-security, consumer, business-registry, procurement, concession, and government sanctions records. | | Political parties and public roles | Checks published party-affiliation rolls, legislators, public officials, PEPs, professional licenses, and other government lists. | | AML, terrorism, and corruption | Checks sanctions, debarment, terrorism, denied-party, shell-bank, and corrupt-practices lists from Mexico and other countries. | | Most wanted | Checks wanted-person, fugitive, detention, sex-offender, and law-enforcement lists. | | International sources | Checks international PEPs, leaks datasets, court records, official gazettes, tax-debtor lists, and records from other countries. | The fields returned for an individual match depend on the source. BIL preserves those findings in `data` and provides the original XML and PDF so you can review the source labels and evidence included in that report. > [!NOTE] > > Source availability and published records can change. A completed report shows the sources and findings returned for that search; it does not guarantee a match in every source listed below. ## BIL source inventory ### Local courts (26) * Tribunales Aguascalientes * Tribunales BCN * Tribunales BCS * Tribunales Colima * Tribunales Campeche * Tribunales Chihuahua * Tribunales Chiapas * Tribunales Ciudad de México * Tribunales Durango * Tribunales Edomex * Tribunales Guanajuato * Tribunales Guerrero * Tribunales Jalisco * Tribunales Michoacán * Tribunales Morelos * Tribunales Nuevo León * Tribunales Querétaro * Tribunales Quintana Roo * Tribunales Sinaloa * Tribunales SLP * Tribunales Sonora * Tribunales Tabasco * Tribunales Tamaulipas/Edictos * Tribunales Veracruz * Tribunales Yucatán * Tribunales Zacatecas ### Federal courts (5) * Suprema Corte de Justicia de la Nación * Expedientes documentales destruidos en la Suprema Corte * Tribunal Federal de Justicia Administrativa (Notificaciones) * Tribunal Federal de Justicia Administrativa (Boletín) * Quiebras y concursos mercantiles (IFECOM) ### Labor courts (7) * Tribunal Laboral de la Federación * Tribunal Laboral de la CDMX * Tribunal Laboral de SLP * Tribunal Laboral del Edomex * Tribunal Laboral de Veracruz * Tribunal Laboral de Sonora * Tribunal Laboral de Zacatecas ### Administrative sources (18) * Estrados SAT/Edictos * Estrados IMSS * PROFECO * SIEM * Proveedores sancionados por SFP * Tribunal de Justicia Administrativa de la CDMX * FOBAPROA * Contribuyentes incumplidos SAT * Operaciones falsas SAT * Contratos CompraNet * Inhabilitados SFP * Sancionados SFP * Contratos del Gobierno Federal (México) * Directorio Estadístico Nacional de Unidades Económicas (DENUE-INEGI) * Sancionados Comisión Nacional Bancaria y de Valores * Concesiones Gobierno Federal (México) * Declaraciones patrimoniales (SFP) * Inhabilitados en estados ### Political parties (10) * Padrón de afiliados PRI * Padrón de afiliados PAN * Padrón de afiliados PRD * Padrón de afiliados PT * Padrón de afiliados Verde * Padrón de afiliados Movimiento Ciudadano * Padrón de afiliados Encuentro Social * Padrón de Humanista * Padrón de afiliados Nueva Alianza * Padrón de afiliados Morena ### Other sources (25) * Legisladores México (diputados/senadores) * Concesiones taxis DF * Cédulas profesionales (SEP) * Licencias suspendidas o canceladas DF * Licencias vigentes (CDMX) * Pensionados ISSSTE * Padrón ISSSTE * Padrón COFEPRIS * Aeropuertos y helipuertos * Personas políticamente expuestas (México) * Funcionarios federales * Sancionados por la COFEPRIS * Padrón de Entidades Suspendidas por la CNBV (PES) * Sindicatos CDMX/federales * Policías autorizados para levantar infracciones en la CDMX * Padrón de exportadores * Padrón de importadores * Comité Normativo Nacional de Consejos de Especialidades Médicas (CONACEM) * Edictos Tribunal Superior de la CDMX * PGJ CDMX (MP) * Archivo Judicial del Estado de México * Trasladados a cárceles de alta seguridad * Publicaciones de sociedades mercantiles * Tarjetas de desempleo * Nómina Gobierno Federal ### Money laundering, terrorism, and corruption (16) * Tesoro de los EUA (OFAC) * Sancionados por el Banco Mundial * Terroristas Al Qaeda * Terroristas Canadá * España (ETA) * Tesoro de Su Majestad (UK) * Prácticas corruptas (FCPA) * OCC Shell Bank * U.S. Department of Commerce Denied Persons * U.S. Government Denied Party * Defense Trade Controls List of Statutorily Debarred Parties * Sancionados UNSC (Australia) * Consejo de Seguridad de la ONU (Irán) * Consejo de Seguridad de la ONU (Costa de Marfil) * Consejo de Seguridad de la ONU (Somalia) * Consejo de Seguridad de la ONU (Libia) ### Most wanted (25) * En México * Por Interpol * Por la DEA * Por el FBI * En Ecuador * En Italia * En Francia * En Argentina * En Brasil * En Guatemala * En Chile * En Belice * En República Dominicana * En Costa Rica * En Sudáfrica * Puerto Rico * Vinculados a un proceso (Estado de México) * Servicio Secreto USA * Homeland Security USA (ICE) * Sex Offender (USA) * Fugitivos (Sheriff USA) * Agresores sexuales en México * United Kingdom * Japón * Europa ### International sources (11) * Líderes mundiales (PEP) * Órdenes de detención en Argentina * Sentenciados en Argentina * PEP (América/Europa) * Offshore Leak * Panama Papers * Bahama Leak * Paradise Papers * Central de detenidos Guatemala * Deudores fiscales UK y España * Capitol Breach Cases (FBI) ### Sources from other countries (13) * Tribunal Supremo de Justicia de Venezuela * Deudores alimentarios de Perú * Tribunal de Justicia de Panamá * Poder Judicial Honduras * Ejecución de penas y medidas de seguridad (Colombia) * Poder Judicial Uruguay * Poder Judicial Chile * España Boletín Oficial BOE * España BORME * España BOEB * Procesos penales en República de El Salvador * Antejuicios Guatemala * UK Court | Field | Description | | - | - | | `fecha` | Date and time reported by BIL for the generated report. | | `investigado` | Name searched and reported by BIL. | | `folio` | BIL report folio. | | `gradoMaximo` | Highest grade returned by BIL for the report. | | `data` | Parsed BIL XML response. The structure follows the vendor response and can vary by report content. | | `xmlFile` | File resource for the original XML response. | | `pdfFile` | File resource for the BIL PDF report. | For endpoint details, see [BIL Reports API Reference](/api-reference/ds-mx-bil-reports/retrieve-a-bil-report). # Authorizations Source: https://docs.syntage.com/resources/datasources/buro-de-credito/authorizations Buró de Crédito authorizations store the consent and identity data required before creating Buró de Crédito report extractions. Buró de Crédito authorizations record the consent, RFC, address, and identity data that Syntage uses when requesting Buró de Crédito reports for an entity. Create an authorization before requesting a Buró de Crédito report. The required taxpayer fields differ for people and companies: | Entity type | Required taxpayer fields | | - | - | | Person | RFC, nationality, birth date, first name, first last name, second last name, and address | | Company | RFC, nationality, trade name, and address | Buró de Crédito requires the authorization address to match its expected Mexico address format. Use the Mexico Addresses resource to normalize addresses before creating an authorization when the source address may not match Buró de Crédito's format. `authorizedAt` must be a past date and `authorizedUntil` is calculated by the API. Use `isValid` on the authorization response to decide whether a report extraction can use the authorization. # Buró de Crédito datasource Source: https://docs.syntage.com/resources/datasources/buro-de-credito/overview Buró de Crédito resources contain credit bureau authorizations and reports for people and companies in Mexico. Buró de Crédito resources let you store the authorization required to consult a person's or company's credit bureau data, run a Buró de Crédito extraction, and retrieve the generated report. ## Resources | Resource | Description | | - | - | | [Own account](/resources/datasources/buro-de-credito/own-account-integration) | Setup flow for organizations that use their own Buró de Crédito or Buró Empresas account in Syntage. | | [Authorizations](/resources/datasources/buro-de-credito/authorizations) | Consent and identity data that allows Syntage to request Buró de Crédito reports for an entity. | | [Reports](/resources/datasources/buro-de-credito/reports) | Credit bureau report data returned by Buró de Crédito, including the generated PDF file. | ## How Buró de Crédito report data is collected Buró de Crédito reports are collected with a Buró de Crédito report extraction. The entity must have taxpayer data and a valid Buró de Crédito authorization before the extraction can run. The selected product type controls which Buró de Crédito product is requested. | Entity type | Supported `productType` values | Default | | - | - | - | | Person | `007`, `004`, `INFORME_BURO` | `007` | | Company | `INFORME_BURO`, `RCO` | `INFORME_BURO` | For implementation details, see [Extraction request examples](/developers/extraction-request-examples#buro-de-credito). # Use your own Buró de Crédito or Buró Empresas account Source: https://docs.syntage.com/resources/datasources/buro-de-credito/own-account-integration Configure your organization's Buró de Crédito or Buró Empresas account in Syntage and request reports through the dashboard. Use this flow when your organization already has a Buró de Crédito account, a Buró Empresas account, or both, and wants to request reports from Syntage with its own credentials. Your organization must finish the Buró approval process and configure its credentials in Syntage before it can request reports with its own account. ## Prerequisites * Your organization has an active Buró de Crédito account for person reports, an active Buró Empresas account for company reports, or both. * Credit report access is enabled for your Syntage organization. * An administrator can configure Buró de Crédito or Buró Empresas credentials in Syntage. ## 1. Configure Buró credentials in Syntage 1. Open the integration settings for the account you are configuring: * [Buró de Crédito integration settings](https://app.syntage.com/settings/integrations/buro-de-credito) for person reports. * [Buró Empresas integration settings](https://app.syntage.com/settings/integrations/buro-empresas) for company reports. 2. Turn on **Use your own credentials**. 3. Enter the **Legal name** exactly as it is registered with Buró. Entities see this name during the authorization process, and it must match the legal entity that holds the Buró account. Both integrations share the same legal name. 4. If your organization is a SOFOM, make sure **Use the authorization text for SOFOM** is selected. It is selected automatically when the legal name declares SOFOM in its entity type, for example `Acme, S.A.P.I. de C.V., SOFOM, E.N.R.`. If you select it manually, the legal name must include SOFOM. 5. Enter the **Username** and **Password** of your organization's account. 6. Click **Save**. Contact your CSM if you need help confirming which credential values Buró provided for your account. ## 2. Get Buró approval for the authorization flow Syntage's digital authorization flow with NIP was developed with Buró de Crédito. Buró still needs to approve your organization before you use this flow with your own Buró de Crédito or Buró Empresas account. Syntage generates the document Buró asks for from your configuration: one slide per authorization step, with your branding, your legal name, and the authorization text your consumers will see. 1. After you save your credentials, Syntage shows the link to your authorization flow. Click **Copy link** to share it, or **Preview flow** to open it. 2. In the document, select the variant Buró needs: **Persona Moral** and **Persona Física con Actividad Empresarial** go to Buró Empresas, and **Persona Física** goes to Buró de Crédito. 3. Send the link to your Buró advisor. If they need a file, click **Descargar PDF** in the document and send the PDF instead. Copy your CSM. 4. Work with Syntage to answer any questions Buró has about the flow. 5. Wait for Buró's approval before using the flow in production. You can open the document again later from **Preview flow** in the **Use your own credentials** section of the integration settings. That button is available only while your changes are saved and new extractions are allowed for that Buró. Until then, use the link from the dialog shown after saving. > [!NOTE] > > If you change the legal name or the username, Syntage shows the link again after you save: send the updated flow to your advisor, because Buró needs to approve it again. Changing only the password does not require a new approval. ## 3. Request Buró reports After the credentials are configured, your organization can request and view Buró reports in Syntage. The report is requested only after the entity or shareholder completes the authorization flow. Use Buró de Crédito credentials for person report products and Buró Empresas credentials for company report products. In the dashboard request flow, both are requested through the **Buró de Crédito Report** datasource and the selected report product type determines which configured credentials are used. ### New entity Use this path when the entity does not exist in Syntage yet. 1. Open [All Entities](https://app.syntage.com/entities). 2. Click **Add entity**. 3. Enter the RFC and continue. 4. Select **Buró de Crédito Report** as one of the datasources. 5. If prompted, select the report product type. Use person products such as `007` or `004` for a person, and company products such as `INFORME_BURO` or `RCO` for a company. 6. Add the entity. 7. Copy the authorization URL. 8. Share the URL only with the person who needs to authorize the Buró report. ### Existing entity Use this path when the entity already exists in Syntage. 1. Open the entity from [All Entities](https://app.syntage.com/entities). 2. Click **Update data**. 3. In the extractor list, select **Buró de Crédito Report**. 4. If prompted, select the report product type. Use person products such as `007` or `004` for a person, and company products such as `INFORME_BURO` or `RCO` for a company. 5. Create the extraction. 6. Copy the authorization URL. 7. Share the URL only with the person who needs to authorize the Buró report. ### Shareholder report Use this path when you need to request a Buró report for a shareholder that is not already connected to an entity. 1. Open the company entity from [All Entities](https://app.syntage.com/entities). 2. Go to the shareholders section. 3. Find the shareholder and click **Add entity**. 4. Confirm the shareholder's RFC and name in the Add entity flow. 5. Select **Buró de Crédito Report** as one of the datasources. 6. Select the report product type. 7. Add the shareholder as an entity. 8. Copy the authorization URL. 9. Share the URL with the shareholder so they can authorize the request. The shareholder report is requested after the shareholder completes the authorization process. If the shareholder is already connected to an entity, open that entity and use **Update data** to request a new Buró de Crédito Report extraction. ## Update your Buró password every 30 days Buró requires the password of your Buró de Crédito and Buró Empresas accounts to be changed every 30 days. Syntage cannot change it for you, so whenever you change the password with Buró, update it in Syntage too: 1. Change the password of your account with Buró. 2. Open the [Buró de Crédito integration settings](https://app.syntage.com/settings/integrations/buro-de-credito) or the [Buró Empresas integration settings](https://app.syntage.com/settings/integrations/buro-empresas). 3. Enter the new **Password**. 4. Click **Save**. Changing only the password does not require a new approval from Buró. If the password expires or the password saved in Syntage stops working, Syntage emails your organization's administrators that the credential is no longer valid, and Buró extractions stay in `Waiting` status. They resume automatically after you save the new password. ## Audit evidence Buró de Crédito may request evidence for a sample of report consultations, including consultations made with your Buró Empresas credentials. When the authorization was completed through the digital NIP flow, export the authorization evidence from Syntage. 1. Open [Buró de Crédito Authorizations](https://app.syntage.com/datasources/mx/buro-de-credito/authorizations). 2. Use the export action, or the audit export action when Buró de Crédito requested an audit file. 3. Send the exported evidence to Buró de Crédito according to its audit instructions. ## Commercial terms The Buró Conexión subscription enables the connection between your Buró de Crédito or Buró Empresas account and your Syntage organization. Report consultation costs are still paid directly to Buró de Crédito. Contact your CSM for current subscription pricing, report limits, and additional report costs. ## Related resources * [Buró de Crédito authorizations](/resources/datasources/buro-de-credito/authorizations) * [Buró de Crédito reports](/resources/datasources/buro-de-credito/reports) * [Extraction request examples](/developers/extraction-request-examples#buro-de-credito) # Reports Source: https://docs.syntage.com/resources/datasources/buro-de-credito/reports Buró de Crédito reports contain credit bureau data generated from the `buro_de_credito_report` extractor. Buró de Crédito reports are created by the `buro_de_credito_report` extractor after Syntage submits the entity's valid authorization to Buró de Crédito. Each report includes the provider, requested product type, provider report ID, parsed provider response, score when the requested product returns one, and generated files such as the report PDF. ## How report data is collected Buró de Crédito reports are collected with the `buro_de_credito_report` extractor. The entity must have taxpayer data and a valid Buró de Crédito authorization. The selected product type controls which Buró de Crédito product is requested. | Entity type | Supported `productType` values | Default | | - | - | - | | Person | `007`, `004`, `INFORME_BURO` | `007` | | Company | `INFORME_BURO`, `RCO` | `INFORME_BURO` | The generated PDF is returned as a file resource in the report's `files` collection. Use the file download endpoint to download the PDF content. For implementation details, see [Extraction request examples](/developers/extraction-request-examples#buro-de-credito). # Infonavit overdue credits Source: https://docs.syntage.com/resources/datasources/infonavit/overdue-credits Infonavit overdue credits come from the Infonavit Créditos Firmes list, which identifies employers with firm (overdue) housing-credit obligations. Use them to check whether an entity's employer registration appears in the list and to add another risk signal to your monitoring workflows. Infonavit data is collected by running an `infonavit` extraction. The extraction matches the entity against the Infonavit list by name, so no SAT credentials are required. Each match is stored as an overdue credit record. ## How Infonavit Overdue Credits Work 1. Start an `infonavit` extraction for the entity. 2. Poll the extraction until it reaches a terminal status. 3. List the entity's Infonavit overdue credits. 4. Retrieve a record by ID when you need its full details. ## Requirements The entity must have a name. Infonavit matching is name-based, so the extraction cannot run for an entity without a name. No SAT credentials or signed agreement are required. The `infonavit` extractor must be enabled for your organization. If it is not enabled, contact your CSM or [Syntage Support](/using-syntage/faq/organization-billing-and-support#how-do-i-contact-support). An entity without any matches finishes the extraction successfully and returns an empty collection. | Field | Description | | - | - | | `nrp` | Employer registration number (Número de Registro Patronal) as published by Infonavit. | | `name` | Employer name as published in the Infonavit Créditos Firmes list. | | `stateCode` | State code reported by Infonavit, when available. | | `stateName` | State name reported by Infonavit, when available. | | `creditCount` | Number of firm housing-credit obligations reported for the employer, when available. | | `firstPublicationDate` | Date the employer first appeared in the Infonavit Créditos Firmes list, when available. | | `year` | Year of the Infonavit Créditos Firmes list in which the employer appears. | For the request body, see [Extraction request examples](/developers/extraction-request-examples#infonavit). For endpoint details, see [List an entity's Infonavit overdue credits](/api-reference/ds-mx-infonavit-overdue-credits/list-an-entitys-infonavit-overdue-credits) and [Retrieve an Infonavit overdue credit](/api-reference/ds-mx-infonavit-overdue-credits/retrieve-an-infonavit-overdue-credit). # RPC actos Source: https://docs.syntage.com/resources/datasources/rpc/actos RPC actos represent commercial registry acts associated with an RPC entity. An acto can include the pre-coded form, act name, NCI, registration dates, document number, modality, extracted data, and a file reference when the registry document is available. Use RPC actos when your integration needs the individual registry filings behind an RPC entity, such as incorporation, appointments, powers, changes, or other registered acts. ## How RPC actos are collected RPC actos are collected with the RPC extraction. After the extraction finishes, the resulting records are available from the entity RPC actos list. Use file downloads when the `file` field is present. For implementation details, see [Extraction request examples](/developers/extraction-request-examples#rpc). # RPC entidades Source: https://docs.syntage.com/resources/datasources/rpc/entidades RPC entidades represent companies or legal entities found in the Registro Publico de Comercio for an entity. An RPC entidade can include the registration folio, legal name, corporate purpose, legal regime, registry office, registration date, related actos, and related socios. Use RPC entidades as the starting point for RPC data. They group the registry acts and shareholder records that were found for the same registered company. ## How RPC entidades are collected RPC entidades are collected with the RPC extraction. After the extraction finishes, the resulting records are available from the entity RPC entidades list. For implementation details, see [Extraction request examples](/developers/extraction-request-examples#rpc). ## Lookup Types | Value | Meaning | | - | - | | `entity` | The RPC entidade was found from the entity search | | `shareholder` | The RPC entidade was found while searching for shareholder-related records | # RPC datasource Source: https://docs.syntage.com/resources/datasources/rpc/overview RPC resources come from the Registro Publico de Comercio, Mexico's public commercial registry. Use RPC data when your integration needs company registration details, registered corporate acts, or shareholder data extracted from registry filings. RPC records are collected by running an RPC extraction. The extraction searches RPC for the entity, stores matching entidades, stores the actos and socios found for each entidade, and attaches available act files as file resources. ## How RPC Data Works 1. Start an RPC extraction for the entity. 2. Poll the extraction until it reaches a terminal status. 3. List the entity's RPC entidades. 4. Retrieve an RPC entidade when you need the company profile, actos, and socios together. 5. Use the RPC actos and socios endpoints when your integration needs individual registry acts or shareholder records. 6. Download referenced files through the Files API when an acto includes a file. ## Requirements The entity must have enough identity data for RPC search. Company entities usually use their legal name and RFC. RPC results can include multiple entidades when the registry returns several matches. For implementation details, see [Extraction request examples](/developers/extraction-request-examples#rpc). # RPC socios Source: https://docs.syntage.com/resources/datasources/rpc/socios RPC socios represent shareholder or partner records found in RPC filings. A socio can include the shareholder status, nationality, names, RFC, CURP, share series, share count, total, value, and the RPC entidade it belongs to. Use RPC socios when your integration needs shareholder data from commercial registry filings. For normalized shareholder workflows, use the Shareholders resources; RPC socios are the underlying datasource records. ## How RPC socios are collected RPC socios are collected with the RPC extraction. After the extraction finishes, retrieve an RPC socio by ID when you need the raw datasource record. For implementation details, see [Extraction request examples](/developers/extraction-request-examples#rpc). # RUG garantías Source: https://docs.syntage.com/resources/datasources/rug/garantias RUG guarantees represent movable collateral guarantees registered in RUG. A guarantee can include the guarantee number, registration and cancellation dates, grantors, creditor, guarantee type, amount, currency, collateral type, collateral description, contract dates, and related operations. Use RUG guarantees when your integration needs the current collateral guarantee record for an entity. Use RUG operations when you need the individual registry acts behind the guarantee. ## How RUG guarantees are collected RUG guarantees are collected with the RUG extraction. After the extraction finishes, the resulting records are available from the entity RUG guarantees list. For implementation details, see [Extraction request examples](/developers/extraction-request-examples#rug). # RUG operaciones Source: https://docs.syntage.com/resources/datasources/rug/operaciones RUG operations represent registry acts associated with a movable collateral guarantee. An operation can include the seat number, operation type, guarantee number, date, grantors, parsed boleta data, and a file reference when the registry document is available. Use RUG operations when your integration needs to review how a guarantee was registered, modified, renewed, cancelled, or otherwise changed in RUG. ## How RUG operations are collected RUG operations are collected with the RUG extraction. After the extraction finishes, the resulting records are available from the entity RUG operations list. Use file downloads when the `file` field is present. For implementation details, see [Extraction request examples](/developers/extraction-request-examples#rug). # RUG datasource Source: https://docs.syntage.com/resources/datasources/rug/overview RUG resources come from Mexico's Registro Unico de Garantias Mobiliarias. Use RUG data when your integration needs movable collateral guarantees, guarantee registration details, or the registry operations associated with a guarantee. RUG records are collected by running a RUG extraction. The extraction searches RUG for the entity, stores guarantees, stores related operations, and attaches available operation files as file resources. The search dimension is the entity acting as grantor or debtor. RUG extractions do not accept asset-level identifiers such as a vehicle VIN, plate number, or serial number. To check whether a specific asset appears as collateral, list the entity's RUG guarantees and inspect the collateral description of each guarantee. ## How RUG Data Works 1. Start a RUG extraction for the entity. 2. Poll the extraction until it reaches a terminal status. 3. List the entity's RUG guarantees or RUG operations. 4. Retrieve a guarantee when you need collateral details and related operations together. 5. Retrieve an operation when you need the registry act metadata, parsed boleta data, or file reference. 6. Download referenced files through the Files API when an operation includes a file. For implementation details, see [Extraction request examples](/developers/extraction-request-examples#rug). # Certificates Source: https://docs.syntage.com/resources/datasources/sat/certificates SAT certificate resources represent e.firma and CSD certificates discovered for an entity. Each certificate includes the serial number, certificate type, issuer, subject, validity dates, SAT status, revocation date when available, and a file reference for the certificate content. List certificates for an entity when you need to inspect which certificates SAT has associated with that entity. Retrieve a certificate by ID when you need the certificate metadata or the file reference for download. ## How SAT certificate data is collected SAT certificate records are collected with the `sat_certificates` extractor. After the extraction finishes, the resulting records are available from the entity SAT certificate list. This lookup requires the entity's RFC, but it does not require a CIEC, e.firma, or entity onboarding. To request it from the dashboard, follow [Request data without credentials](/using-syntage/dashboard/request-data-without-credentials). For implementation details, see [Extraction request examples](/developers/extraction-request-examples#sat-certificates). # Credentials Source: https://docs.syntage.com/resources/datasources/sat/credentials SAT credentials are the CIEC or e.firma credentials Syntage uses to access SAT data for an entity's RFC. After validation, they can be used by SAT extractions to retrieve the data you request. Use the credential `status` to decide whether a credential can be used for new extractions: | Status | Meaning | | - | - | | `pending` | The credential has been received and is waiting for validation | | `valid` | The credential was accepted by SAT and can be used for extractions | | `invalid` | SAT rejected the credential during validation | | `disabled` | SAT reported the credential as disabled or otherwise unrecoverable | | `error` | Validation failed because of an unexpected error | If a credential becomes invalid or validation fails unexpectedly, use the revalidation endpoint after the credential has been corrected or SAT availability has recovered. # Credit notes Source: https://docs.syntage.com/resources/datasources/sat/credit-notes Credit notes represent CFDI relationships where one invoice applies credit to another invoice. Use them to understand how issued credit-note invoices affect the amounts of related invoices. A credit note links the invoice that issued the credit to the invoice where the credit was applied. You can list credit notes across invoices, retrieve a single credit note by ID, or list the credit notes issued by or applied to a specific invoice. Credit notes are extracted from invoice data when SAT returns egress CFDIs and their related invoice information. To retrieve them, run an [`invoice` extraction](/resources/datasources/sat/invoices#extracting-invoice-data) for the entity and include type `E` invoices in the extraction options. # Electronic accounting Source: https://docs.syntage.com/resources/datasources/sat/electronic-accounting Electronic accounting records represent accounting XML files submitted to SAT and the SAT processing information associated with those files. Records include the fiscal period, accounting file type, filename, status, received date, and related files. Use these endpoints to retrieve electronic accounting submissions for an entity or inspect a specific record after an electronic accounting extraction finishes. ## How electronic accounting data is collected Electronic accounting records are collected with the `electronic_accounting` extractor. After the extraction finishes, the resulting records are available from the entity electronic accounting list. For implementation details, see [Extraction request examples](/developers/extraction-request-examples#electronic-accounting). # Invoice batch payments Source: https://docs.syntage.com/resources/datasources/sat/invoice-batch-payments Batch payments are derived from payment receipt CFDIs, also known as type `P` invoices. A batch payment groups one or more [invoice payments](/api-reference/ds-mx-sat-invoice-payments) into the payment transaction reported by SAT. Use batch payments when you need payment-method, currency, bank, operation-number, or transaction-level information. Use invoice payments when you need the amount applied to a specific deferred invoice. Batch payments are extracted from invoice data. To retrieve them, run an [`invoice` extraction](/resources/datasources/sat/invoices#extracting-invoice-data) for the entity and include payment receipt CFDIs by keeping type `P` invoices in the extraction options. # Invoice line items Source: https://docs.syntage.com/resources/datasources/sat/invoice-line-items Invoice line items represent the CFDI concepts, products, or services inside an invoice. They include product identification, description, unit amount, quantity, totals, the tax detail of each CFDI tax node with its factor type and rate or quota, and retained and transferred tax amounts by tax type. Use invoice line items when an integration needs item-level invoice detail instead of only invoice-level totals. You can list line items for one invoice or across all invoices for an entity. Invoice line items are extracted from invoice data. To retrieve them, run an [`invoice` extraction](/resources/datasources/sat/invoices#extracting-invoice-data) for the entity, then list line items after the extraction finishes. # Invoice payments Source: https://docs.syntage.com/resources/datasources/sat/invoice-payments Invoice payments are derived from payment receipt CFDIs, also known as type `P` invoices. A payment receipt records payment activity for a previously issued deferred invoice. Each payment belongs to a [batch payment](/api-reference/ds-mx-sat-invoice-batch-payments) and the invoice it was applied to. Syntage updates the related invoice's `paidAmount`, `dueAmount`, and `fullyPaidAt` fields based on the received payments. Invoice payments are extracted from invoice data. To retrieve them, run an [`invoice` extraction](/resources/datasources/sat/invoices#extracting-invoice-data) for the entity and include payment receipt CFDIs by keeping type `P` invoices in the extraction options. # Invoice relations Source: https://docs.syntage.com/resources/datasources/sat/invoice-relations Invoice relations represent CFDI relationships between invoices, such as substitutions, credit notes, or other SAT-defined relation types. Each relation includes the source invoice, related invoice when Syntage has it, related invoice UUID, and the SAT relation type code. Use invoice relations when an integration needs to explain why one invoice references another invoice. You can retrieve a relation by ID, list relations for an invoice, or list relations for an invoice within an entity. Invoice relations are extracted from invoice data when the CFDI includes related-document metadata. To retrieve them, run an [`invoice` extraction](/resources/datasources/sat/invoices#extracting-invoice-data) for the entity, then list relations after the extraction finishes. # Invoices Source: https://docs.syntage.com/resources/datasources/sat/invoices Invoices represent CFDI documents issued or received by an entity. Invoice records include SAT identifiers, issuer and receiver data, monetary totals, payment status, cancellation status, invoice relationships, file availability, and tags. Use the entity invoice list when you need all invoices extracted for one entity. Retrieve an invoice by ID when you need the full invoice resource, including tags and related invoice metadata. Use the CFDI file endpoint when you need the XML or PDF content for a specific invoice, and use the parsed SAT CFDI endpoint when you need structured CFDI data by invoice UUID. ## How invoice data is collected Invoice records are collected with the `invoice` extractor. The extraction can include issued invoices, received invoices, XML files, and PDF files depending on the selected options. Invoice payments, batch payments, line items, relations, and credit notes are also derived from invoice CFDI data. For implementation details, see [Extraction request examples](/developers/extraction-request-examples#invoices). ### CFDI types included By default, the `invoice` extractor includes every CFDI type the SAT exposes for the entity within the requested period. There is no separate extractor for payroll, payment complements, credit notes, or transfer documents. You can remove any type you do not need when configuring an individual extraction or the extraction scheduler, depending on where the extraction will be created. The `type` field identifies each extracted invoice: | `type` | CFDI | | - | - | | I | Ingreso (income) | | E | Egreso (credit note) | | P | Pago (payment) | | N | Nómina (payroll) | | T | Traslado (transfer) | ### Blacklist status The field `issuer.blacklistStatus` or `receiver.blacklistStatus` is set when the invoice issuer or receiver RFC is found in the [SAT 69-B list](https://omawww.sat.gob.mx/cifras_sat/Paginas/datos/vinculo.html?page=ListCompleta69B.html): | Status | Description | | - | - | | presumed | SAT has identified possible irregularities and started an investigation | | dismissed | SAT dismissed the investigation after reviewing evidence | | definitive | SAT determined that the RFC has confirmed irregularities | | favorable | SAT reversed a definitive status after reviewing additional evidence | ## Identify an entity's customers and suppliers An entity's issued invoices identify its customers, while its received invoices identify its suppliers. Syntage derives these relationships from invoice data rather than exposing customers or suppliers as standalone resources. See [Customers and suppliers](/resources/insights/customers-and-suppliers) to choose between invoice-level records and aggregated concentration insights, and to find the related endpoints. # SAT datasource Source: https://docs.syntage.com/resources/datasources/sat/overview Tax, identity, invoice, and compliance data from Mexico's Servicio de Administracion Tributaria. The SAT datasource contains tax, identity, invoice, and compliance data extracted from Mexico's Servicio de Administracion Tributaria for an entity. Use this section for SAT credentials, invoices, invoice payments, tax returns, tax status, tax compliance checks, tax retentions, electronic accounting records, and SAT certificates. Most SAT records are created by [extractions](/resources/core/extractions): create or schedule an extraction for an entity, wait for it to finish, then read the resulting SAT data from the pages in this section. SAT records often include a `file` or `files` field for XML, PDF, certificate, acknowledgment, or source files. Those fields return file resources; use the [Files](/resources/core/files) page to inspect file metadata or download the content. ## What the SAT datasource does not cover The SAT datasource is limited to the records listed above. Some SAT features do not have a dedicated resource or extractor: * Buzón Tributario status or notifications. Syntage does not expose an endpoint to check whether the buzón tributario is enabled for an RFC, and it does not read messages from the buzón. Compliance information available through Syntage is limited to the [Constancia de Situación Fiscal](/resources/datasources/sat/tax-status) and the [Opinión de Cumplimiento](/resources/datasources/sat/tax-compliance-checks). # Tax compliance checks Source: https://docs.syntage.com/resources/datasources/sat/tax-compliance-checks A tax compliance check maps the content of Opinion de Cumplimiento de Obligaciones Fiscales, an official SAT document that states whether an RFC is complying with its tax obligations. Each tax compliance check is a snapshot of the compliance result at a specific check date. | Result | Meaning | | - | - | | `positive` | The RFC is complying with its tax obligations | | `negative` | SAT reported one or more compliance issues | | `no_obligations` | SAT reported no active tax obligations | | `activity_suspended` | SAT reported suspended business activity | Use the file reference when you need the original PDF document returned by SAT. ## How tax compliance check data is collected Tax compliance checks are collected with the `tax_compliance` extractor. After the extraction finishes, the resulting records are available from the entity tax compliance check list. For implementation details, see [Extraction request examples](/developers/extraction-request-examples#tax-compliance-checks). # Tax retentions Source: https://docs.syntage.com/resources/datasources/sat/tax-retentions Tax retentions represent SAT CFDI withholding and payment-information documents. They include the issuer, receiver, retention code, fiscal period, operation totals, retained tax totals, itemized retained taxes, and CFDI file availability. Use the list endpoint to read tax retentions extracted for an entity. Use the CFDI endpoint when you need the XML or PDF content for a specific tax retention. ## How tax retention data is collected Tax retention records are collected with the `tax_retention` extractor. After the extraction finishes, the resulting records are available from the entity tax retention list. For implementation details, see [Extraction request examples](/developers/extraction-request-examples#tax-retentions). # Tax returns Source: https://docs.syntage.com/resources/datasources/sat/tax-returns Tax returns represent SAT declarations extracted for an entity, including annual, provisional, and RIF returns when available. A tax return contains the filing period, fiscal year, return type, operation number, payment information, source files, and whether ISSIF data is available. Use the PDF download endpoint when you need the original SAT transcript PDF. Use the tax return data endpoint when you need extracted financial variables or parsed return data instead of the tax return metadata. The returned data depends on the return type, fiscal year, tax regime, and the files SAT provides for that return. ## How tax return data is collected Tax returns are collected with different extractors depending on the return type: | Tax return data | Extractor | | - | - | | Annual returns | `annual_tax_return` | | Provisional monthly returns | `monthly_tax_return` | | RIF returns | `rif_tax_return` | After the extraction finishes, the resulting records are available from the entity tax return list. For implementation details, see [Extraction request examples](/developers/extraction-request-examples#tax-returns). # Tax status Source: https://docs.syntage.com/resources/datasources/sat/tax-status Tax status records represent information extracted from the SAT tax status document, also known as the Constancia de Situación Fiscal (CSF). A record can include identity data, RFC, CIF, contact information, fiscal address, economic activities, tax regimes, obligations, and the original PDF file. Use tax status records when an integration needs the current fiscal identity and obligation profile for an entity. Because the source document is a snapshot, a new extraction can create a newer tax status record when SAT data changes. Use the entity-scoped list when you need tax status records for one entity. Use the top-level list when you need to page through tax status records available to your organization. ## How tax status data is collected Tax status records are collected with the `tax_status` extractor. After the extraction finishes, the resulting records are available from the entity tax status list. For implementation details, see [Extraction request examples](/developers/extraction-request-examples#tax-status). ## Obligations, tax regimes, and economic activities Each tax status record includes `obligations[]`, `taxRegimes[]`, and `economicActivities[]`. These arrays can contain multiple items. Every item carries `startDate` and `endDate` fields that follow the same convention: * `startDate` — the date SAT reports the obligation, tax regime, or economic activity started. * `endDate` — the date SAT reports it ended. When `endDate` is `null` (or absent), the obligation, tax regime, or economic activity is still active according to SAT. Use `endDate: null` as the signal that an item is currently in force. Items with a populated `endDate` are historical records SAT keeps on the taxpayer's CSF. ### Economic activity fields Each item in `economicActivities[]` exposes `name`, `order`, `percentage`, `startDate`, and `endDate`. The response does not include a SCIAN code, industry classification, or vulnerable-activity (`actividad vulnerable`) determination. ## Tax status in sandbox Sandbox tax status data follows the entity's simulated fiscal profile. The selected tax regime determines compatible economic activities and obligations, and the same profile is reused by applicable sandbox tax-return extractors. Sandbox has no reserved RFCs. Create a person or company with any valid-format RFC, then either let sandbox assign a stable profile automatically or send `metadata.sandbox.taxRegime` when creating the entity. See [Environments](/guides/api/environments#create-sandbox-entities) for the supported profiles and request example. # Overview Source: https://docs.syntage.com/resources/datasources/syntage/score Syntage Score calculates an internal score for a company entity from SAT tax return and tax compliance data. Syntage Score calculates an internal score for a company entity. The score uses the entity's latest annual tax return and tax compliance data, then exposes the result through the Scores insight. ## Requirements Syntage Score can be calculated for company entities. People are not supported. Before starting a calculation, the entity needs the datasource records used by the score model: | Required data | How to create it | | - | - | | Annual tax return | Run an annual tax return extraction | | Tax compliance check | Run a tax compliance check extraction | If one of the required extractions is still running, wait until it finishes before starting score generation. If the required data is missing or the latest score is already current, the API returns a validation error instead of starting another calculation. ## Starting a calculation Once the required data is available, start score generation for the entity. Syntage creates a pending score calculation and exposes the calculated value through the Scores insight after the calculation finishes. For endpoint details, see [Syntage Score API Reference](/api-reference/ds-syntage-score/calculate-syntage-score). # Customers and suppliers Source: https://docs.syntage.com/resources/insights/customers-and-suppliers Identify an entity's counterparties from invoices and measure how its sales or purchases are distributed among them. Syntage identifies an entity's customers and suppliers from its [SAT invoices](/resources/datasources/sat/invoices). These counterparties are not standalone resources: each one is the issuer or receiver of an invoice associated with the entity. ## How counterparties are identified | Relationship | Invoice direction | Counterparty | | - | - | - | | Customer | Issued by the entity | Receiver | | Supplier | Received by the entity | Issuer | Issued invoices show who buys from the entity. Received invoices show who sells to the entity. Use the individual invoices when you need transaction details, or a concentration view when you need totals and relative share by counterparty. ## Using the dashboard 1. Open [All Entities](https://app.syntage.com/entities) and select the entity. 2. To review individual transactions, open **Data > Invoices**. For an issued invoice, the receiver is the customer; for a received invoice, the issuer is the supplier. Use **Filters** to narrow the table by issuer or receiver name or RFC. 3. To compare totals and share by counterparty, open **Reports** and view the **Customer Concentration** or **Vendor Concentration** insight in a report. Customer and supplier concentration insights aggregate invoice totals by counterparty. Each result includes the counterparty's RFC and name, total invoiced amount, share of the entity's sales or purchases for the selected period, and a transaction series over time. Use these insights when you need to identify dependency on a small number of customers or suppliers. ## Using the API List invoices with `isIssuer=true` to find customers and `isReceiver=true` to find suppliers. To find transactions with one counterparty, filter by `issuer.rfc`, `issuer.name`, `receiver.rfc`, or `receiver.name`. | Task | Endpoint | | - | - | | List and filter invoice records | [`GET /entities/{entityId}/invoices`](/api-reference/ds-mx-sat-invoices/list-all-entities-invoices) | | Measure customer concentration | [`GET /entities/{entityId}/insights/customer-concentration`](/api-reference/customer-concentration-insight/get-customer-invoice-concentration) | | Measure supplier concentration | [`GET /entities/{entityId}/insights/supplier-concentration`](/api-reference/vendor-concentration-insight/get-vendor-invoice-concentration) | # Overview Source: https://docs.syntage.com/resources/insights/overview Insights aggregate entity data into metrics, summaries, and exports that can be used in dashboards and workflows. Insights aggregate data Syntage has already extracted for an entity. They combine invoices, SAT records, credit reports, RPC records, RUG records, and other datasource-backed records into metrics and summaries that are easier to use directly. Most insight endpoints return calculated data for one entity and accept optional `options[...]` query parameters for date ranges, pagination, ordering, or grouping. The exact options are documented on each endpoint page. ## Categories | Category | Examples | | - | - | | Company | Summary, scores, risks, Buró de Crédito summary | | Corporate Structure | Shareholders, current powers | | Revenue | Sales revenue, expenditures, cash flow, accounts payable, accounts receivable | | Financial | Balance sheet, income statement, financial ratios, trial balance | | Clients | Customer concentration, customer network, products and services sold | | Providers | Supplier concentration, vendor network, products and services bought | ## Exports Some insights can be exported as CSV or XLSX files with the insight export endpoint. Use the same `options[...]` filters you would use on the corresponding insight endpoint, and set the `Accept` header to the format you want. For example, export the Shareholders insight with `GET /entities/{entityId}/insights/shareholders/export` and pass the relation direction as `options[relations.relationType]`. ## Reports [Reports](/resources/insights/reports) group insights into a configurable layout for an entity. Use them to view a full credit-review layout in the dashboard or to download it as a PDF document through the [Exports API](/resources/core/exports). # Reports Source: https://docs.syntage.com/resources/insights/reports Reports group entity insights into a configurable layout that can be viewed in the dashboard and downloaded as a PDF. Reports group [insights](/resources/insights/overview) into a named, ordered layout for one entity. The same report definition works for every entity in your organization: open it from the entity's Reports section in the dashboard, or download it as a PDF document with the [Exports API](/resources/core/exports). ## Built-in and custom reports | Type | Who manages it | Visibility | | - | - | - | | Built-in | Syntage; kept up to date automatically and cannot be modified or deleted | Every user | | Custom (personal) | The user who created it | Only the owner | | Custom (organizational) | Admins | Every user in the organization | Built-in reports such as `full_report` cover the standard credit-review layout: company summary, Syntage Score, risk indicators, corporate structure, revenue, financial statements, clients, and providers. Custom reports select and order the insight entries you care about. Create one with `POST /reports`, setting `organizational` to `true` to share it with your organization. Insight entries gated by a feature flag that is disabled for your organization are omitted from the report layout. ## Download a report as a PDF Report PDFs are generated asynchronously through the [Exports API](/resources/core/exports): 1. List your reports with `GET /reports` and store the ID of the report you want. 2. Create an export with `format` set to `pdf` and `uri` set to `/entities/{entityId}/reports/{reportId}?exporting=true`. 3. Retrieve the export until its `status` is `finished`. 4. Download the generated `report.insights.pdf` file from the File resource referenced by the export. ```json theme={null} POST /exports { "format": "pdf", "uri": "/entities/91106968-1abd-4d64-85c1-4e73d96fb997/reports/9137b53f-1abd-4d64-85c1-4e73d96fb997?exporting=true" } ``` The generated PDF renders the report the same way the dashboard shows it to the requesting user: it uses the user's locale, the report's default period, and only the insight sections visible to that user. The `exporting=true` query parameter is required; other query parameters are not supported on report URIs. > [!NOTE] > > PDF generation renders every insight in the report, so it can take a few minutes for entities with large datasets. Poll the export status instead of assuming a fixed completion time. For endpoint details, see the [Reports API Reference](/api-reference/reports/list-reports). # Background checks Source: https://docs.syntage.com/resources/other/background-checks Understand the sources, records, and requirements used in Background Checks. Background Checks provide screening and verification data for an entity. Use these resources to list checks, retrieve a specific check, download its PDF report, and inspect the records found during the check. Records contain the detailed results behind a Background Check. They are organized by category and database so you can review the information that contributed to the check. ## Requirements You can request a Background Check without entity onboarding or SAT credentials. For a company, provide its RFC. For a person, provide both the RFC and CURP. Follow [Request data without credentials](/using-syntage/dashboard/request-data-without-credentials) to create the entity and start the extraction from the dashboard. | Status | Meaning | | - | - | | `pending` | The Background Check is being processed. | | `completed` | The Background Check completed successfully. | | `error` | The Background Check encountered an error. | | Country scope | Meaning | | - | - | | `MX` | Mexico-specific Background Checks. | | `ALL` | International Background Checks across multiple countries. | ## Data returned Each completed check can include: | Data | What it tells you | | - | - | | Category score | The result and severity for an area such as personal identity, legal background, taxes and finances, media alerts, sanctions, or PEP screening. | | Database status | The named database that was consulted, its country scope, and whether the consultation completed. | | Records | Matches returned by a database. Each record contains source-specific sections and fields. | | PDF report | A human-readable summary of the check and its findings. | A database can complete without returning a match. Use database statuses to confirm what was consulted and records to inspect what was found. ## Sources used Syntage combines specialized providers with direct access to authoritative sources. Syntage selects the source for each category; customers do not need to configure a provider or supply provider credentials. | Source | Purpose | Data points available in the Background Check | | - | - | - | | Background Check database catalog | Coordinates searches across judicial, sanctions, PEP, tax, regulatory, and adverse-media databases. | Category scores, database name and status, matched records, and source-specific fields. | | Registro Nacional de Población (RENAPO) | Verifies the identity and CURP status of a person. | CURP, names, surnames, sex, birth date and state, nationality, CURP registration status, probative-document type and data, and the constancia file when available. | | SAT | Verifies tax identity, digital certificates, and Article 69/69-B listings. | RFC status and registered name, certificate status and dates, and published presumed or definitive fictitious-operation status when present. | | OpenSanctions | Screens sanctions, terrorism, wanted-person, and PEP datasets. | Matched name and aliases, identifiers, countries, positions or associations, source dataset, and related dates when provided by the source. | | Adverse-media search | Finds media publications relevant to due diligence. | Article source, title, URL, publication information, and the extracted finding returned for the entity. | RENAPO is used for people and requires the CURP already supplied for the Background Check. Its availability, and the source used for other categories, can depend on your organization's configuration. No separate RENAPO authorization or credentials are required. ## Background Check database catalog The database catalog used for applicable Background Check categories includes the following sources. Availability can change and not every database applies to every entity or country scope. The completed report is the record of which databases were actually consulted. ### Media and PEP * Búsqueda en medios Google RSS * Listas PEP México por nombre ### Mexican judicial sources * Poder Judicial del Estado de México * Poder Judicial de Morelos - Historial * Poder Judicial de Guerrero * Poder Judicial de Jalisco * Poder Judicial MX * Poder Judicial de Tabasco * Poder Judicial de Tabasco - Segunda Instancia * Poder Judicial de Baja California Sur * Poder Judicial de Zacatecas * Poder Judicial de la Federación * Poder Judicial de Quintana Roo * Poder Judicial de Aguascalientes * Poder Judicial de Sonora * Consejo de la Judicatura Federal - Acuerdos * Poder Judicial de Veracruz * Poder Judicial de Morelos Judicial records can include the court or authority, proceeding identifiers, parties, dates, and other fields published by the consulted database. ### Sanctions, exclusions, and international screening * Inter-American Development Bank * Consolidated Screening Lists * United Nations Security Council Consolidated List * Offshore Leaks Database * Office of Foreign Assets Control (OFAC) * Office of Foreign Assets Control (OFAC) by Name * `health-exclusions` * World Bank Debarred Firms * Common Position Terrorist EU * Lista de terroristas de USA These sources can return names and aliases, list or program details, countries, identifiers, dates, and the originating list when those values are published by the source. ### Tax and regulatory sources * SAT * SAT Certificados * Comisión Nacional Bancaria y de Valores Tax and regulatory results can include RFC identity and status, digital-certificate information, published tax-risk records, and regulatory sanctions or exclusions. For broader legal-source coverage, including the complete 156-source inventory, see [BIL reports](/resources/datasources/bil/reports). # Company verification reports Source: https://docs.syntage.com/resources/other/company-verification-reports Company verification reports provide verification metadata, basic profile data, and supporting files for companies. Detailed verification sections are available in the generated report files. These resources let you list reports, retrieve a specific report, retrieve reports for an entity, and download the generated PDF report. To retrieve people with currently effective powers from the entity's most recent report, use the [Current Powers insight](/api-reference/corporate-structure-current-powers-insight/get-current-powers). To retrieve shareholders, use `GET /entities/{entityId}/insights/metrics/shareholders` with `relations.relationType=shareholders`. When Company Verification data is available, the insight uses shareholder rows from the entity's most recent report; manually entered values take precedence for relations that have both Company Verification and manual sources. Use the entity-scoped endpoint when your integration is working from a known entity. For report ID lookups or organization-wide pagination, use the top-level report endpoints. The PDF endpoint returns the generated report document directly. The JSON report resource contains the report metadata and file references available through the API. # Shareholders Source: https://docs.syntage.com/resources/other/shareholders Shareholders represent people or companies that own shares in a company. Use shareholder resources to list the shareholders connected to an entity, add manually collected shareholder information, update shareholder details, and inspect where shareholder information came from. Shareholder relations connect a shareholder to an entity. A relation describes the direction of ownership and can include share counts or ownership percentages. Relation sources identify where the relation information came from. | Concept | Values | | - | - | | Shareholder types | `physical`, `legal`, `unknown` | | Relation types | `shareholders`, `shareholder_of` | | Source types | `manual`, `rpc_socio`, `company_verification` | Manual sources always take precedence over other sources. When the same relation is reported by multiple non-manual sources, the most recent update wins. For the shareholders metrics insight, use `GET /entities/{entityId}/insights/metrics/shareholders` with `relations.relationType=shareholders`. When Company Verification data is available, it uses shareholder rows from the entity's most recent report; manually entered values take precedence for relations that have both sources. Use promotion when a shareholder should become its own entity. Promotion creates an entity for the shareholder so you can connect datasources and continue working with that person or company directly. # Command palette Source: https://docs.syntage.com/using-syntage/dashboard/command-palette Search for pages, entities, RFCs, and entity-specific sections without leaving the keyboard. Use the command palette when you want to move quickly through the Syntage dashboard. It can search dashboard pages, entities, RFCs, data sections, credentials, and report sections from one place. ## Open the command palette You can open the command palette from the dashboard header. | Device | Shortcut | | - | - | | Mac | `Command` + `K` | | Windows or Linux | `Ctrl` + `K` | You can also click **Search or jump to...** in the top navigation. On entity pages, the search icon opens the same command palette with entity-specific options. ## Search and navigate 1. Open the command palette. 2. Type a page name, entity name, RFC, datasource, report section, or data section. 3. Use the arrow keys to move through results. 4. Press `Enter` to open the selected result. ![Command palette showing demo entity search results](https://mintcdn.com/syntage/JpU5H7TBhEaQcMwQ/images/using-syntage/dashboard/command-palette/search-demo-entities-en.png?fit=max\&auto=format\&n=JpU5H7TBhEaQcMwQ\&q=85\&s=16b3d473f3de7932233fd1c4e410f2af) Search includes matching names and related keywords. For example, searching for an RFC can find an entity, and searching for `tax returns` can find the matching data section when that section is available for the current entity. ## Global pages When you are not inside an entity, the command palette can open common dashboard pages: * Home * Entities * Extractions * Exports * Workflows * Settings * Billing * Extraction schedulers * Users * Webhooks * SAT Credentials * Buró de Crédito Authorizations When you are inside an entity, global results are still searchable. The palette prioritizes the current entity first so you can move within the entity before jumping elsewhere. ## Entity results Search by entity name or RFC to open an entity directly. Selecting an entity opens its Reports section. To choose a specific destination for an entity: 1. Search for the entity. 2. Highlight the entity result. 3. Press `Option` + `Enter` on Mac or `Alt` + `Enter` on Windows or Linux. 4. Select the entity destination. Entity destinations include Reports, Extractions, credentials, and available data sections such as Invoices, Payments, Tax returns, Tax status, RPC, RUG, BIL, Buró de Crédito reports, and shareholders when they apply to the entity. ## Current entity shortcuts When you are viewing an entity, the command palette includes shortcuts for that entity: * Reports * Extractions * Data * Credentials Open **Data** to move to datasource-backed records for the current entity. Open **Credentials** to review SAT credentials or Buró de Crédito authorizations for the current entity. ## Current report shortcuts When you are viewing an entity report, the command palette can jump to available report sections. The available results depend on the report sections enabled for the entity and the data your organization has retrieved. Use this when you need to move between summary, financial, risk, bureau, shareholder, or other report sections without scrolling through the report navigation. ## Go back or close Use `Esc` to close the command palette from the main result list. If you are inside a submenu, `Esc` goes back to the main result list. You can also press `Backspace` or `Delete` from an empty submenu search field to go back. ## No matching results If the command palette shows no matching pages or entities: * Check the spelling of the entity name or RFC. * Try a broader term, such as `entities`, `invoices`, `tax returns`, or `credentials`. * Confirm that the entity exists in your organization. * Confirm that the data or report section is available for the entity. # Data Source: https://docs.syntage.com/using-syntage/dashboard/data Understand the raw records and files available for an entity in Syntage. The **Data** section contains the structured records and original files retrieved from datasources. Use it when you need to validate a report, audit a source record, download a document, or build a more detailed analysis. ## Open an entity's data 1. Open [All Entities](https://app.syntage.com/entities). 2. Select the entity by RFC or legal name. 3. Open **Data**. 4. Use the left navigation to move between datasource sections. Records appear as the corresponding [extractions](/using-syntage/extractions) save them. For extractions that retrieve many records, such as invoices or tax returns, a section can show some records while the extraction is still running. Wait until the extraction finishes before treating the section as complete. ## Common data sections | Section | What you can find | | - | - | | Invoices | Issued and received CFDIs, status, dates, counterparties, tax details, totals, XML files, and PDFs | | Invoice line items | Product and service descriptions, quantities, unit codes, taxes, discounts, and totals | | Payments | Payment complements for PPD invoices, payment dates, payment method, previous balance, amount paid, and remaining balance | | Retentions | Withholding certificates issued or received by the entity | | Tax returns | Annual, monthly, provisional, and RIF returns, plus receipts, PDFs, payment proofs, and Excel files where available | | Tax status | Constancia de Situación Fiscal files and SAT identity information | | Tax compliance checks | Opinión de cumplimiento result and PDF | | Electronic accounting | Accounting files retrieved from SAT where available | | RPC | Commercial registry filings, corporate acts, and related PDFs | | RUG | Guarantee records and related documents | | BIL | Legal incident report output when requested | | Buró de Crédito | Credit bureau report data and files when authorized and extracted | ## Find documents Use the **Files** area inside each data section to download source documents. | Document type | Where to look | | - | - | | Invoice XML or PDF | **Data > Invoices > Files** | | Payment or retention files | **Data > Payments** or **Data > Retentions** | | Annual or provisional return files | **Data > Tax returns > Files** | | Constancia de Situación Fiscal | **Data > Tax status > Files** | | Opinión de cumplimiento | **Data > Tax compliance checks > Files** | | RPC, RUG, or BIL documents | Open the relevant public records section and expand the record details | | Buró de Crédito PDF | Open the Buró de Crédito section and review the files | ## Export data Use exports when you need data outside Syntage in CSV, Excel, PDF, or another supported format. 1. Create the export from the relevant report or data section. 2. Open [Exports](https://app.syntage.com/settings/exports). 3. Review the export status, file name, details, and available downloads. 4. Download the file when the export is finished. Exports do not consume extractions because they only package information that has already been retrieved. ## Notifications Syntage sends notifications for selected events, including entity onboarding, first-time extraction completion, export completion, and monitoring events. Notification preferences are user-specific. Each user can review them from [Notifications](https://app.syntage.com/settings/notifications). # Entities and onboarding Source: https://docs.syntage.com/using-syntage/dashboard/entities-and-onboarding Create entities, understand credential and authorization requirements, and troubleshoot onboarding. Creating an entity connects a person or company to the datasources your organization needs. Some requests use entity information only, while others require credentials or authorization. ## Credential and authorization requirements | What the entity provides | Examples | Notes | | - | - | - | | Name or identifiers only | RPC, RUG, BIL, Background Check, INFONAVIT, SAT certificate lookup, Company Verification Report | No credentials or authorization are required, but some reports may have an additional cost | | Credentials or authorization | SAT data that requires credentials, Buró de Crédito | The entity must provide access through a supported authorization flow | Requests that need only a name or identifiers can be useful for preliminary review before you ask the entity to provide credentials or authorization. ## Create an entity without credentials Follow [Request data without credentials](/using-syntage/dashboard/request-data-without-credentials) for the required identifiers and dashboard steps for each datasource. ## Share an onboarding link Use an onboarding link when the requested data requires credentials or authorization from the entity. 1. Open [All Entities](https://app.syntage.com/entities). 2. Open the dropdown next to **Add entity**. 3. Select **Open onboarding page**. 4. Select whether to include Buró de Crédito onboarding. 5. Copy the generated URL and share it with the entity. You can send the URL by email, WhatsApp, or any other communication channel your organization uses. ## Create a personalized onboarding link Use a personalized link when you want the flow to include entity-specific information. 1. Open [All Entities](https://app.syntage.com/entities). 2. Click **Add entity**. 3. Select the datasources you need. 4. Enter the RFC or legal name. 5. Copy the generated onboarding URL and share it with the entity. Personalized links can improve trust because the entity sees a registration flow tied to its own information. ## Customize the onboarding page Administrators can customize the registration page from [Entity Onboarding](https://app.syntage.com/settings/entity-onboarding). Common settings include: * Company name * Privacy policy URL * Company logo * Accent color * eFirma availability, when enabled for your organization After saving changes, open the registration link to verify how the page appears to entities. ## Check whether onboarding was completed Use [SAT Credentials](https://app.syntage.com/datasources/mx/sat/credentials) to review SAT credential registration attempts. 1. Open [SAT Credentials](https://app.syntage.com/datasources/mx/sat/credentials). 2. Filter by RFC. 3. Check whether the status is valid or invalid. 4. Review the creation date if the entity was previously registered. If validation succeeded but the entity does not appear in the expected position in the entity list, filter [All Entities](https://app.syntage.com/entities) by RFC. Existing entities keep their original creation date, so a repeated registration may not move the entity to the top of the list. ## Troubleshoot SAT onboarding If the registration flow reports that the RFC or password is incorrect, ask the entity to confirm: * The RFC is correct * The CIEC password is correct * The password has at least one letter and one number * The password is at least 8 characters and no more than 20 characters * They are using the CIEC password, not the e.firma password, unless e.firma onboarding is enabled * e.firma portable is not enabled If an existing SAT credential later becomes invalid, the entity usually needs to complete onboarding again so Syntage can validate the updated credential. ## Processed entities A processed entity is an RFC that has at least one [extraction](/using-syntage/extractions) during the current month. For plan limits, an entity is counted once per month even if you run multiple extractions for that entity. Creating an entity and processing an entity are different: * Creating an entity happens when the entity completes onboarding or is added to Syntage. * Processing an entity happens when at least one extraction is created for that entity during the month. # Extraction schedulers Source: https://docs.syntage.com/using-syntage/dashboard/extraction-scheduler Configure first-time and recurring extractions for the entities your organization monitors. Extraction schedulers automate [extraction](/using-syntage/extractions) creation. Use them to decide which information Syntage should retrieve when an entity is onboarded and which information should be refreshed on a recurring schedule. ## Scheduler types | Scheduler | Purpose | | - | - | | First time | Runs when an entity is created or onboarded for the first time | | Recurring | Runs periodically for entities that match the scheduler's tags | First-time schedulers help your organization start with the data it needs immediately after onboarding. Recurring schedulers keep selected entities current over time. ## Review first-time extraction rules 1. Open [Extraction Schedulers](https://app.syntage.com/settings/extraction-schedulers). 2. Edit the scheduler named **First time**. 3. Review the configured rules. Each rule defines the extractor and any required parameters, such as period, invoice type, or document type. ## Change first-time extraction rules 1. Open [Extraction Schedulers](https://app.syntage.com/settings/extraction-schedulers). 2. Edit **First time**. 3. Add, edit, or delete rules. 4. Click **Update** to save the scheduler. To disable automatic first-time extractions, turn off **Enable** and save the scheduler. > [!WARNING] > > If you disable the first-time scheduler, new entities will not automatically have data available after onboarding. Your team will need to create extractions manually. ## Create a recurring scheduler 1. Open [Extraction Schedulers](https://app.syntage.com/settings/extraction-schedulers). 2. Click **Add new**. 3. Name the scheduler. 4. Select the tags that identify the entities this scheduler should target. 5. Save the scheduler. 6. Add rules with the extractor, frequency, period, and extractor-specific options. 7. Enable the scheduler. 8. Click **Update**. Use tags carefully. A broad tag can cause the scheduler to run for more entities than intended. ## Cron expressions for scheduler rules Each scheduler rule uses a `cronExpression` field to control when it runs. The field accepts any valid cron string, and named aliases such as `@daily`, `@weekly`, and `@monthly` are also supported. Common examples: | Expression | Runs | | - | - | | `@hourly` | Every hour, at minute `0` | | `@daily` | Every day at midnight | | `@weekly` | Every Sunday at midnight | | `@monthly` | The first day of every month at midnight | | `0 9 * * *` | Every day at 09:00 | | `0 9 * * 1` | Every Monday at 09:00 | | `0 6 1 * *` | The first day of every month at 06:00 | | `0 */6 * * *` | Every 6 hours | Schedules are evaluated in UTC. Convert from local time before saving the rule. ## Disable a recurring scheduler 1. Open [Extraction Schedulers](https://app.syntage.com/settings/extraction-schedulers). 2. Edit the recurring scheduler. 3. Turn off **Enable**. 4. Click **Update**. Return to the scheduler list and confirm the status changed to disabled. ## Estimate monthly usage Recurring extraction usage depends on how many entities match the scheduler, how many rules it has, and how often the rules run. Use this estimate before enabling a scheduler: ```text theme={null} matching entities x total monthly runs ``` For example, if 55 entities match a scheduler and it runs 37 times in a month, the scheduler may create about 2,035 extraction requests for that month. Actual usage depends on the configured rules, datasource availability, plan limits, and whether extractions complete successfully. When you enable a recurring scheduler, Syntage sends an activation email that summarizes the configured rules and the extractions the scheduler is likely to generate. # Plan and billing Source: https://docs.syntage.com/using-syntage/dashboard/plan-and-billing Review plan limits and configure overage limits for processed entities and extractions. [Plan and Billing](https://app.syntage.com/settings/billing) shows the limits included in your plan, current usage, prices, payment methods, and invoices. Administrators can also configure overage limits from this page so the organization can keep operating after a plan limit is reached. ## Plan limits Syntage tracks two monthly plan limits: | Limit | What it counts | | - | - | | Processed entities | Entities (RFCs) with at least one extraction during the current month. Each entity counts once per month. Buró de Crédito and Buró Empresas reports are not counted toward this limit. | | Extractions | Extractions created during the current month. | For the difference between creating and processing an entity, see the [billing FAQ](/using-syntage/faq/organization-billing-and-support#what-does-processed-entity-mean). ## Configure an overage limit An overage limit lets your organization process entities or create extractions beyond the plan limit. Only administrators can configure overage limits. For security reasons, Syntage Support cannot change them on your organization's behalf. 1. Sign in with an administrator account. 2. Open [Plan and Billing](https://app.syntage.com/settings/billing) from **Settings → Organization → Plan and billing**. 3. Under **Plan Limits**, locate **Processed entities** or **Extractions**. 4. Click **Configure**. 5. Enter the overage limit, review the **Maximum estimated cost**, and click **Save**. Processed entities and extractions have separate overage limits. Configure each metric independently; they are also billed separately. ## How the overage limit is counted The value you enter is the number of additional units above your plan allowance, not a new total. The configuration screen shows the **Plan Limit** from your subscription, the **Overage Limit** you enter, and the resulting **Total Limit**: Total Limit = Plan Limit + Overage Limit ## Overage pricing and billing * The **Cost per unit** shown in the configuration screen is the standard overage price for that metric. It can differ from the unit price included in your subscription plan. If your organization negotiated a lower overage price, the negotiated price is the one you are billed. * Configuring or raising an overage limit does not generate a charge by itself. Only the additional units your organization actually consumes are billed. The **Maximum estimated cost** is an estimate assuming you consume the entire overage limit. * Consumed overage units are billed separately and included in your next monthly invoice. ## When the overage limit is fully consumed When usage reaches the total limit, Syntage stops processing additional entities or creating new extractions for the rest of the month. An administrator must raise the overage limit again or upgrade the plan to continue. The overage limit (additional units) is capped at 200% of the plan limit, so the total limit can reach 300% of the plan limit. If you reach the cap, or you exceed your plan's capacity regularly, contact your Customer Success Manager or [Syntage Support](https://support.syntage.com) to upgrade to a higher tier. See [How do I increase my plan?](/using-syntage/faq/organization-billing-and-support#how-do-i-increase-my-plan) ## Availability * Overage configuration is not available on trial plans. * The configuration screen is currently designed for desktop browsers. If the **Configure** option is not usable on a mobile device, use a desktop browser. # Reports Source: https://docs.syntage.com/using-syntage/dashboard/reports Understand the processed report sections available from an entity in the dashboard. Reports are processed views built from the data Syntage has extracted for an entity. They are designed for review, analysis, and decision-making without requiring users to inspect every raw record. ## Open an entity report 1. Open [All Entities](https://app.syntage.com/entities). 2. Select the entity by RFC or legal name. 3. Open **Reports**. 4. Use the date selector to choose the period you want to analyze. The report updates its sections based on the selected date range and the data available for the entity. ## Download a report as a PDF 1. Open the entity report you want to share. 2. Select **Download Report**. 3. Syntage confirms the request and generates the PDF in the background. You receive a [notification](/using-syntage/notifications) when it is ready. 4. Download the file from the notification or from [Exports](https://app.syntage.com/settings/exports). The PDF captures the report as the dashboard shows it: the selected report layout and date range, in your language, with the sections available for the entity. Generation can take a few minutes for entities with large amounts of data. Users with read-only permission cannot download reports. > [!TIP] > > Report PDFs can also be requested through the API. See [Reports](/resources/insights/reports) in the Resource Guide for the export flow. ## Common report sections The available sections depend on the datasources and [extractions](/using-syntage/extractions) completed for the entity. | Section | What it helps review | | - | - | | Entity summary | RFC, legal name, SAT registration, activity, tax regime, address, and high-level financial information | | Syntage Score | A 0 to 1000 indicator of financial health and fiscal compliance | | Risk indicators | Visual signals for operational, fiscal, and financial risk | | RPC acts and assemblies | Public registry filings and related documents | | Shareholders | Shareholder information from RPC or manual updates | | RUG guarantees | Security interests and guarantee records | | Buró de Crédito | Credit bureau reports when authorized and extracted | | Billing and invoices | Revenue, expenses, cash flow, customers, suppliers, payments, and cancelled invoices | | Financial statements | Annual-return financial statement data where available | ## Syntage Score Syntage Score is a high-level financial health indicator from 0 to 1000. It is intended to complement, not replace, your organization's credit and risk policies. | Range | Meaning | | - | - | | 0-249 | Low | | 250-499 | Regular | | 500-749 | Good | | 750-1000 | Excellent | The score uses financial statement, invoice behavior, and fiscal compliance variables, including debt ratios, revenue growth, margins, DSO, DPO, compliance result, and invoice cancellation percentages. ## Report calculations Reports are calculated from the data available in the **Data** section. Some report cards include an information icon that explains the logic, inputs, or interpretation for that specific indicator. Syntage does not expose every proprietary formula behind its indicators. Use the visible report logic and source data to understand what each metric represents. ## Why report values can differ Some values come from different sources and may not match exactly. For example, annual comparison revenue is based on invoice behavior, while annual return revenue comes from the return filed by the taxpayer. Those values can differ because the taxpayer may apply accounting decisions, tax treatments, incentives, exemptions, or adjustments in the annual return. ## Missing financial statement data For companies, Syntage uses the Excel file attached to annual returns when the SAT provides it. For individuals with business activity, Syntage may use the annual return PDF. Financial statement data may be missing when: * The annual return Excel file was filed with zeros * The Excel file is not available because the taxpayer filed audited financial statements through a different SAT flow * The [extraction](/using-syntage/extractions) failed or has not completed To investigate, open **Data > Annual returns > Files** and review the annual return PDF and related files. ## Custom risk thresholds Some risk indicators can be adjusted to match your organization's risk policy. If an indicator has a settings icon, open it from **Reports > Risk indicators**, change the threshold, and save the configuration. # Request data without credentials Source: https://docs.syntage.com/using-syntage/dashboard/request-data-without-credentials Add an entity and request data without asking for CIEC, e.firma, or authorization. You can request RPC, RUG, Background Check, and other data without asking the entity to provide credentials. Syntage still creates an entity record to hold the request and its results, but you do not need to share an onboarding link or collect a CIEC, e.firma, or Buró de Crédito authorization. > [!NOTE] > > Adding an entity creates a record in your organization. It does not mean that the person or company completed entity onboarding. ## Choose a datasource The information you need depends on the datasource and entity type. | Dashboard selection | Information required | Notes | | - | - | - | | [RPC](/resources/datasources/rpc/overview) | Entity name | Searches Mexico's Registro Público de Comercio. | | [RUG](/resources/datasources/rug/overview) | Entity name | Searches Mexico's Registro Único de Garantías Mobiliarias. | | [BIL](/resources/datasources/bil/reports) | Entity name | Searches global blacklists and politically exposed person records. This report may have an additional cost. | | [Background Check](/resources/other/background-checks) | Company: RFC. Person: RFC and CURP. | Does not require a CIEC or e.firma. | | INFONAVIT | Entity name | Searches INFONAVIT's overdue-credit information. | | [SAT certificate lookup](/resources/datasources/sat/certificates) | RFC | Looks up SAT certificate information without a SAT credential. | | [Company Verification Report](/resources/other/company-verification-reports) | Company name | Available only for companies. This report may have an additional cost. | ## Request the data **1. Open Add entity** Open [All Entities](https://app.syntage.com/entities), then click **Add entity**. **2. Identify the entity** Select **Person** or **Company** and enter the requested name and identifiers. For a person's Background Check, enter both the RFC and CURP. **3. Select the data** Select the records or reports you want to request. Review the additional-cost icon before selecting BIL or the Company Verification Report. **4. Create the entity** Submit the request. Syntage creates the entity and starts the selected [extractions](/using-syntage/extractions). **5. Review the results** Open the entity when the extraction finishes. Depending on the selection, the result appears in the entity's [Data](/using-syntage/dashboard/data) or [Reports](/using-syntage/dashboard/reports) section. > [!WARNING] > > If you also select SAT data other than certificate lookup, or Buró de Crédito, the entity must provide credentials or authorization. The dashboard marks these selections as requiring onboarding. ## Request more data later You do not need to add the entity again. Open the existing entity, click **Update data**, select another datasource, and submit the extraction. # Users and permissions Source: https://docs.syntage.com/using-syntage/dashboard/users-and-permissions Manage users, administrators, and extraction permissions. Users should access Syntage with their own login. Administrators manage organization settings, users, permissions, billing configuration, onboarding branding, extraction scheduling, webhooks, and entity access. ## User types | User type | What they can do | | - | - | | Admin | Manage billing, extraction schedulers, users, and all other settings | | Standard | Work with the entities and features allowed by an administrator | | Read Only | View data without making changes or exports | Administrators can also enable entity ownership controls. When ownership controls are enabled, users only see the entities assigned to them. ## Add a user Only administrators can add users. 1. Open [Users](https://app.syntage.com/settings/users). 2. Click **Add user**. 3. Enter the user's name, email, and role. 4. Save the user. The user receives an invitation email. The activation link is time-limited, so resend the invitation if the user does not activate access in time. ## Activate a user A user is active after they follow the invitation email, create their password, and sign in for the first time. If the invitation expired, an administrator can resend it from [Users](https://app.syntage.com/settings/users). ## Make a user an administrator 1. Open [Users](https://app.syntage.com/settings/users). 2. Edit the user. 3. Change **User Type** to **Admin**. 4. Save the user. > [!WARNING] > > Administrator access allows the user to change organization-wide settings. Grant it only to users who need to manage the organization. ## Change the administrator email To replace an administrator: 1. Create the new user, or edit an existing user. 2. Enable administrator permissions for the new administrator. 3. Remove administrator permissions from the previous user, or delete that user if they should no longer have access. Changing administrators does not remove the organization's entities, reports, data, or configuration. ## Limit extraction permissions Administrators can control whether a user can create extractions. 1. Open [Users](https://app.syntage.com/settings/users). 2. Edit the user. 3. Disable the relevant extraction permissions. 4. Save the user. Some permissions are datasource-specific, such as BIL or Buró de Crédito extraction permissions. # Datasources Source: https://docs.syntage.com/using-syntage/datasources Compare the sources Syntage uses, the data they provide, and their access requirements. Syntage connects to official registries and specialized verification providers to retrieve tax, commercial, credit, legal, labor, and compliance data about people and companies in Mexico. Datasources define where information can come from. [Extractions](/using-syntage/extractions) define when Syntage retrieves or refreshes that information for an entity. ## Verification datasource guide | Datasource | Use it for | Data available through Syntage | Requirements and configuration | | - | - | - | - | | [SAT](/resources/datasources/sat/overview) | Tax identity, tax compliance, invoicing, and tax filings. | RFC status and identity, CFDI invoices and related records, returns, compliance checks, retentions, electronic accounting, and digital certificates. | The entity needs an RFC. Most SAT extractions require a valid CIEC or e.firma [credential](/resources/datasources/sat/credentials); the accepted credential depends on the requested data. | | [Registro Público de Comercio (RPC)](/resources/datasources/rpc/overview) | Company registration, corporate acts, and shareholders recorded in Mexico's commercial registry. | Matching registry entities, registered acts, shareholders, act metadata, and available act files. | The entity needs a legal name. An RFC improves identification. SAT credentials are not required. | | [Registro Único de Garantías Mobiliarias (RUG)](/resources/datasources/rug/overview) | Movable collateral guarantees and their registry history. | Guarantees, secured parties and grantors, registration details, related operations, parsed filing data, and available operation files. | The entity needs a name. SAT credentials are not required. | | [Buró de Crédito](/resources/datasources/buro-de-credito/overview) | Credit history and risk information for a person or company. | The selected Buró product response, score when provided, report identifiers, parsed data, and generated report files. | Requires taxpayer identity data, a valid [authorization](/resources/datasources/buro-de-credito/authorizations), and an enabled Buró integration for the organization. The user needs **Can create extractions** plus **Can create Credit Bureau (BDC) extractions** for a person or **Can create Buró Empresas extractions** for a company. | | [Buró Empresas through your own account](/resources/datasources/buro-de-credito/own-account-integration) | Company credit reports requested with your organization's Buró Empresas account. | Company report products such as `INFORME_BURO` and `RCO`, including parsed data and generated report files. | Requires an active Buró Empresas account, Buró approval for Syntage's digital NIP flow, configured organization credentials, the entity's authorization, and organization enablement. The user needs **Can create extractions** and **Can create Buró Empresas extractions**. | | [Buró de Investigaciones Legales (BIL)](/resources/datasources/bil/reports) | Legal, administrative, sanctions, PEP, wanted-person, and international record searches. | Overall risk grade, search folio and date, parsed findings, and the original XML and PDF report covering up to 156 sources. | The entity needs a name, BIL must be enabled for the organization, and the user needs **Can create extractions** and **Can create BIL extractions**. BIL is premium and API requests require a signed charge agreement. SAT credentials are not required. | | [Infonavit Créditos Firmes](/resources/datasources/infonavit/overdue-credits) | Employers with firm overdue housing-credit obligations. | Employer registration number, published name and state, credit count, first publication date, and list year. | The entity needs a name and the datasource must be enabled for the organization. SAT credentials and a signed agreement are not required. | | [Background Checks](/resources/other/background-checks) | Identity, judicial, sanctions, PEP, tax, regulatory, adverse-media, and other due-diligence screening. | Category scores, database statuses, matched records and fields, country scope, and a PDF report. | A company needs an RFC. A person needs an RFC and CURP. No entity onboarding or SAT credentials are required. Source availability is managed by Syntage. | | [Company Verification](/resources/other/company-verification-reports) | Company profile and verification metadata in a generated report. | Report metadata, basic profile data, found entities, supporting files, and the generated PDF with detailed verification sections. | Available for companies when the report is enabled for the organization. Contact your CSM or Syntage Support for availability. | > [!NOTE] > > The sources consulted by a specific report can depend on the entity type, country scope, available registry records, and your organization's configuration. Use the completed report's database statuses and records to confirm which sources were consulted and what they returned. [Insights](/resources/insights/overview), reports, and Syntage Score are derived by Syntage from datasource records. They are analysis products rather than additional external sources. ## Where to read more * Use the linked resource guides above to understand each resource and its fields. * Use [Extractions](/using-syntage/extractions) to understand how datasource-backed data is retrieved and refreshed. * Use [API Reference](/api-reference/introduction) for endpoint paths, request parameters, and response schemas. * Use the [changelog](/changelog) for user-facing product updates. # Entities Source: https://docs.syntage.com/using-syntage/entities Understand entities and how Syntage connects data to people and companies. An entity is the person or company your organization works with in Syntage. Most data in Syntage is connected to an entity, including SAT records, credentials, reports, [extractions](/using-syntage/extractions), insights, events, and tags. Entities give your organization a stable way to connect information from multiple datasources to the same subject. For example, a company can have SAT invoices, RPC filings, RUG guarantees, credit bureau reports, and Syntage insights connected to the same entity. ## Identifiers Entities can have identifiers such as RFC and CURP. For SAT workflows, the RFC identifies the taxpayer. For people, a CURP can also be stored as an identifier when available. ## Tags Tags help organize entities. Your organization can use tags for segmentation, monitoring, filtering entity lists, or targeting [extraction schedulers](/using-syntage/dashboard/extraction-scheduler). ## Developer resources Developers can create, update, and retrieve entities through the API. Start with [Entity URLs](/guides/api/entity-urls) for the current URL model, then use the [Entities API Reference](/api-reference/entities/list-all-entities) for endpoint details. # Extractions Source: https://docs.syntage.com/using-syntage/extractions Understand how Syntage retrieves and refreshes data for an entity. An extraction is the process Syntage uses to retrieve or refresh information from a datasource for an entity. Extractions are how Syntage gets SAT records, invoices, tax returns, RPC filings, RUG guarantees, Buró de Crédito reports, BIL reports, and other datasource-backed information. Syntage is not connected to every datasource in real time. Data appears or updates when an extraction runs. Extractions that retrieve many records, such as invoices or tax returns, save records as they go, so some records can appear in the API and in **Data** while the extraction is still running. Wait until the extraction is finished before treating its data as complete. If an extraction fails, records it saved before failing may remain available, but its data is incomplete. ## How extractions start Extractions can start in several ways: | Trigger | When to use it | | - | - | | First-time extraction rules | Automatically retrieve the standard data your organization needs after an entity is created or onboarded | | Manual update | Refresh a specific entity when your team needs newer information | | Recurring scheduler | Keep selected entities updated on a schedule using tags | | API request | Start an extraction from your own integration | For dashboard setup, read [Extraction schedulers](/using-syntage/dashboard/extraction-scheduler). For developer examples, read [Extraction request examples](/developers/extraction-request-examples). ## Extraction status An extraction moves through statuses while Syntage queues, runs, and finishes the work. In the dashboard, check the status to understand whether Syntage is still retrieving data, waiting for a prerequisite, finished, or unable to complete the extraction. `Waiting` means Syntage cannot run the extraction yet because something still blocks it, such as missing entity information, authorization, an unavailable credential, or an internal dependency. If an extraction fails or remains pending longer than expected, check whether the datasource is available, whether the entity's credential or authorization is valid, and whether the extraction reached a datasource limit. For the exact API status values, billing behavior for stopped or cancelled extractions, and extraction error codes, see the [Extractions resource guide](/resources/core/extractions). ## Extractions, reports, and data Extractions retrieve source information. Syntage then uses that information to populate: * **Reports**, where your team reviews processed indicators, summaries, charts, and analysis * **Data**, where your team reviews source records, raw structured data, and original files * **Exports**, where your team downloads information that Syntage already retrieved Reports are calculated from the records Syntage has saved. While an extraction runs, reports reflect the records saved so far. Some report values, such as the Syntage Score, are recalculated after the extraction finishes and can take a short time to update. Exports do not create new extractions. They package existing Syntage data into downloadable files. ## Usage and billing Extractions can count toward plan usage. A processed entity is an RFC that has at least one extraction during the current month, and extraction counts may also be limited by your plan. You can review usage in [Plan and Billing](https://app.syntage.com/settings/billing) and extraction history in [Extractions](https://app.syntage.com/extractions). ## Technical reference Developers can create and monitor extractions through the API. Use the [Extractions resource guide](/resources/core/extractions) for resource behavior and [Create an extraction](/api-reference/extractions/create-an-extraction) for endpoint details. # Bureaus and compliance Source: https://docs.syntage.com/using-syntage/faq/bureaus-and-compliance Answers for Buró de Crédito, BIL, RUG, blacklists, background checks, and shareholder data. ## How do I request a BIL report? BIL extractions are not always automatic because they can have an additional cost. To request one from the dashboard: 1. Open [All Entities](https://app.syntage.com/entities). 2. Open the entity. 3. Click **Update data**. 4. Select **Buró de Incidencias Legales (BIL)**. 5. Create the extraction. When the report is ready, Syntage sends a notification in the portal and by email. ## Can I review international lists in Syntage? Yes, through BIL where enabled. BIL can include federal, local, labor, administrative, most-wanted, and international sources depending on the report. ## Which blacklists does Syntage use? The support docs describe two main blacklist sources: | Source | Description | | - | - | | SAT 69-B list | SAT list for taxpayers with fiscal inconsistencies | | BIL | External legal incident and blacklist source with additional cost where enabled | Availability can depend on your plan and enabled datasources. ## How do I request a Buró de Crédito report? Buró de Crédito and Buró Empresas reports require authorization from the entity. Depending on your setup, your organization may request reports using Syntage's configured account or your own Buró de Crédito or Buró Empresas account connected to Syntage. If your organization uses its own Buró account, make sure the credentials are configured before requesting reports. See [Use your own Buró de Crédito or Buró Empresas account](/resources/datasources/buro-de-credito/own-account-integration). ## Do I need to update my own Buró credentials? Yes. If your organization uses its own Buró de Crédito or Buró Empresas account, Buró requires its password to be changed every 30 days. After each change, enter the new password in the integration settings in Syntage. Until you do, Buró extractions stay in `Waiting` status. See [Update your Buró password every 30 days](/resources/datasources/buro-de-credito/own-account-integration). ## Is entity authorization required for Buró de Crédito? Yes. Buró de Crédito information requires authorization from the entity. The authorization can be backed by a Buró-authorized NIP or the configured authorization process. Without authorization, Syntage cannot request the report. ## How long does Buró de Crédito / Buró Empresas authorization last? Your organization sets the term, and it can be 1, 2 or 3 years. Organizations that have not changed it are on 3 years. The term is set separately for Buró de Crédito and Buró Empresas. Changing the term only affects authorizations signed afterwards. Each authorization keeps the term it was signed under, so shortening the term does not cut existing authorizations short and lengthening it does not extend them. Once an authorization expires, the entity needs to authorize access again. ## Can Syntage report data back to Buró de Crédito? No. Syntage can request and display Buró de Crédito information where authorized, but it does not report or update data in Buró de Crédito. ## Where can I find Buró de Crédito authorizations for an audit? 1. Open [Buró de Crédito Authorizations](https://app.syntage.com/datasources/mx/buro-de-credito/authorizations). 2. Export the authorization information required for the audit. 3. Send the information to Buró de Crédito according to its instructions. This applies when your organization previously configured its own Buró de Crédito or Buró Empresas credentials in Syntage. ## How does Buró de Crédito identity validation work? For individuals, your organization is responsible for collecting contact information and validating the INE. The authorization request is sent using the provided contact information. For companies, your organization is responsible for identifying the legal representative, collecting contact information, and validating the representative's INE and authority before sending the authorization request. ## Can Syntage generate a RUG boleta? No. Syntage can extract and display RUG information for analysis, but RUG boleta generation must be done through the official RUG process or another authorized channel. ## Why is shareholder structure not updating automatically? Shareholder structure comes from the company's incorporation filing in RPC, when available. That often represents the original shareholder structure. Later changes, such as grants or revocations, may not update automatically. To review and update: 1. Open the entity from [All Entities](https://app.syntage.com/entities). 2. Go to **Reports > Acts and assemblies - RPC**. 3. Download the relevant RPC documents. 4. Go to **Data > Shareholders**. 5. Add, edit, or delete shareholder records as needed. ## What are background checks? Background checks let your organization review public or authorized sources for a person or company. Depending on what is enabled, the check can include public records, legal incidents, lists, and identity-related information. Use background checks as part of a broader review process. They do not replace your organization's legal, compliance, or risk policy. # Entity onboarding Source: https://docs.syntage.com/using-syntage/faq/entities-and-onboarding Answers for creating entities, onboarding links, SAT credentials, and entity visibility. ## How do I add entities to Syntage? Use [All Entities](https://app.syntage.com/entities) and click **Add entity** for dashboard onboarding. The exact flow depends on the datasources you select. * Some datasources can be requested with entity information such as RFC or legal name. * SAT data that needs credentials and Buró de Crédito require an onboarding link or another supported authorization flow. For detailed steps, read [Entities and onboarding](/using-syntage/dashboard/entities-and-onboarding). To request data without credentials, follow [Request data without credentials](/using-syntage/dashboard/request-data-without-credentials). ## Can I consult data without entity authorization? Yes. You can request RPC, RUG, BIL, SAT certificate lookup, Background Check, and INFONAVIT using the entity's name or identifiers. SAT data that requires credentials and Buró de Crédito require authorization from the entity. ## Can entities onboard with e.firma? Yes, provided e.firma onboarding is enabled for your organization. If the option is missing, an administrator can enable it under **Settings → Organization → [Entity Onboarding](https://app.syntage.com/settings/entity-onboarding)**. If the setting is unavailable or the issue persists, contact your CSM or Syntage Support. ## How do I know if an entity completed onboarding? Use [SAT Credentials](https://app.syntage.com/datasources/mx/sat/credentials) to review SAT onboarding attempts: 1. Open [SAT Credentials](https://app.syntage.com/datasources/mx/sat/credentials). 2. Filter by RFC. 3. Review the credential status and creation date. If the credential is valid, the entity completed the SAT credential flow successfully. ## Why does the entity not appear after successful validation? The entity may already exist. If an entity was previously created, a new onboarding attempt does not change the entity's original creation date, so it may not move to the top of the entity list. Filter [All Entities](https://app.syntage.com/entities) by RFC to find it directly. ## Why can't an entity complete SAT onboarding? If the registration flow reports that the RFC or password is incorrect, check: * The RFC is correct. * The CIEC password is correct. * The CIEC password has at least one letter and one number. * The CIEC password has 8 to 20 characters. * The entity is not entering the e.firma password in the CIEC flow. * e.firma portable is not enabled. If your organization supports e.firma onboarding, make sure the entity is using the right onboarding option. ## Why can't I refresh SAT data for an existing entity? The SAT credential may have become invalid. This can happen if the entity changes the SAT password or if e.firma access expires. To check: 1. Open [All Entities](https://app.syntage.com/entities). 2. Open the entity's status details. 3. Look for a SAT credential status such as invalid credential. If the credential is invalid, share the onboarding link again so the entity can update access. ## Do SAT credentials expire? CIEC access does not have a fixed expiration date, but it stops working if the entity changes the SAT password. e.firma validity is determined by SAT. When the e.firma expires, the entity must complete onboarding again with updated e.firma files. ## How do I change the registration page branding? Administrators can update onboarding branding from [Entity Onboarding](https://app.syntage.com/settings/entity-onboarding). Common settings include organization display name, privacy notice URL, logo, button color, and e.firma availability. # Extractions and refreshes Source: https://docs.syntage.com/using-syntage/faq/extractions-and-refreshes Answers for manual extractions, recurring updates, extraction timing, SAT limits, and usage. ## What is an extraction? An extraction is the process Syntage uses to retrieve or refresh information from a datasource for an entity. Read [Extractions](/using-syntage/extractions) for the full concept and how extractions relate to reports, data, exports, usage, and API requests. ## How do I manually update an entity's data? You can create manual extractions from several product areas: * From [All Entities](https://app.syntage.com/entities), open the entity status and choose **Update data**. * From the entity's **Reports** page, click **Update data**. * From the entity menu, open **Extractions** and click **Update data**. Select the extractor, configure any required period or options, and create the extraction. ## How do I keep data updated automatically? Use recurring extraction schedulers. A scheduler can target entities by tag and create extraction rules at the frequency your organization needs. Read [Extraction schedulers](/using-syntage/dashboard/extraction-scheduler) for setup details. ## Why don't I see updated information? The data may not have been extracted yet. Create a manual extraction or configure recurring extractions if your team needs updated information on a schedule. Also check whether the entity's credential or authorization is still valid. Invalid credentials can prevent refreshes. ## How long do extractions take? Extraction times are estimates and depend on datasource availability, SAT load, document volume, invoice volume, and extractor type. Typical ranges from the support docs are: | Extractor | Typical time | | - | - | | Constancia de Situación Fiscal | 1-5 minutes | | Opinión de cumplimiento | 3-15 minutes | | RPC | 1-5 minutes | | RUG | 1-5 minutes | | Electronic accounting | 7-10 minutes | | Buró de Crédito | 1-5 minutes | | BIL | 1-5 minutes | | Tax returns | 3-7 minutes | | Invoices | 5-60 minutes, depending on volume | These times are not guarantees. ## What happens when SAT limits XML downloads? SAT applies daily CFDI XML download limits per RFC. The approximate limit referenced in support docs is around 2,000 XML files per day, but the limit can vary. When the XML limit is reached, Syntage may continue processing available PDF files and can retry XML retrieval later. If your process needs the XML files, try again the next day or configure recurring extractions. ## How can I review monthly extraction usage? You can review extraction usage in: * [Plan and Billing](https://app.syntage.com/settings/billing), under plan limits * [Extractions](https://app.syntage.com/extractions), filtered by month and exported for analysis ## Do exports consume extractions? No. Exports package data Syntage already retrieved. They do not connect to external datasources and do not consume extraction usage. ## Which extractors may have additional costs? Extractor pricing depends on your plan and commercial agreement. Historically, support docs described SAT, RPC, and RUG extractors as included in plan usage, while BIL and some Buró de Crédito report types could have per-report costs. Check your plan and contract terms, or contact your CSM or Syntage Support before enabling extractors that may have additional charges. # Organization, billing, and support Source: https://docs.syntage.com/using-syntage/faq/organization-billing-and-support Answers for organization settings, plan usage, billing, API keys, and support channels. ## Where can I see my current plan? Open [Plan and Billing](https://app.syntage.com/settings/billing). This page shows the limits included in your plan, including processed entities and extractions. ## What does processed entity mean? A processed entity is an RFC that has at least one [extraction](/using-syntage/extractions) during the current month. For plan limits, the entity is counted once for that month even if your organization creates multiple extractions for the same RFC. Creating an entity and processing an entity are different. Creating an entity adds it to Syntage. Processing an entity happens when Syntage creates at least one extraction for it in the month. ## How can I check how many entities I have processed? You can check usage in two places: * [Plan and Billing](https://app.syntage.com/settings/billing) shows processed entity usage under plan limits. * [Extractions](https://app.syntage.com/extractions) lets you filter extractions by month and export the result to review which RFCs were processed. ## What happens when I reach my processed entity limit? When your organization reaches the processed entity limit, Syntage may stop operating normally for additional entities until you increase the plan or enable additional usage. To keep operating, an administrator can configure an overage limit: 1. Open [Plan and Billing](https://app.syntage.com/settings/billing). 2. Locate **Processed entities** or **Extractions** and select **Configure**. 3. Enter the additional units needed, review the estimated cost, and save. Only used additional entities or extractions are billed. For the full flow, pricing, and billing details, see [Plan and billing](/using-syntage/dashboard/plan-and-billing). ## How do I increase my plan? Contact your CSM or Syntage Support to request a plan change. 1. Request the plan increase. 2. Review and sign the service quote. 3. Wait for Syntage to update the plan. 4. Confirm the new limits from [Plan and Billing](https://app.syntage.com/settings/billing). Plan downgrades may require that your organization has remained in the current tier for a minimum period. ## How do I add a payment method? 1. Open [Plan and Billing](https://app.syntage.com/settings/billing). 2. Open **Payment Method**. 3. Enter the card details. 4. Click **Add card**. Notify your CSM or Syntage Support if you need confirmation that the payment method was configured correctly. ## Where can I download invoices issued by Syntage? Open [Plan and Billing](https://app.syntage.com/settings/billing) and select the invoices section. You can review issued invoices, payment status, balance, due dates, and available XML or PDF files. ## Where can I manage API keys? 1. Open [API Keys in Production](https://app.syntage.com/settings/api-keys) or [API Keys in Sandbox](https://app.sandbox.syntage.com/settings/api-keys) for the environment you are using. 2. Find the API key you need. 3. Use the show or hide control to reveal and copy the key. If you need to rotate the key, use **Change**. Rotating the key disables the previous key and creates a new one. > [!WARNING] > > Treat the API key as a secret. Rotating it can break integrations that still use the previous key. Developer setup details are in [Developer overview](/developers/overview). ## How do I contact support? Use the support portal at [support.syntage.com](https://support.syntage.com). Standard support channels include: | Channel | Details | | - | - | | Support portal | [support.syntage.com](https://support.syntage.com) | | WhatsApp | +52 55 6943 7840 | | Email | [soporte@syntage.com](mailto:soporte@syntage.com) | Support is available Monday through Friday during business hours in Mexico City. Critical issues receive priority response. Issues caused by external portals, such as SAT availability or official datasource limits, may depend on the external provider's availability. # Reports, data, and insights Source: https://docs.syntage.com/using-syntage/faq/reports-data-and-insights Answers for reports, files, exports, Syntage Score, financial statements, and report logic. ## What is Syntage Score? Syntage Score is a 0 to 1000 indicator of an entity's financial health and fiscal compliance. It complements, but does not replace, your organization's credit and risk policies. | Score range | Meaning | | - | - | | 0-249 | Low | | 250-499 | Regular | | 500-749 | Good | | 750-1000 | Excellent | ## How is Syntage Score calculated? The support docs describe 13 input variables grouped into financial statements, invoice behavior, and fiscal compliance: * Debt-to-equity ratio * Debt-to-income ratio * Net income * Gross margin * Net margin * Sales growth * Solvency ratio * Acid test * DSO * DPO * Compliance result * Issued invoice cancellation percentage * Received invoice cancellation percentage The exact model and weighting are proprietary. Use the report's visible explanations and source data to understand what each indicator represents. ## Can Syntage share the formulas behind indicators? Syntage does not share every proprietary formula. Many report cards include information icons that explain the calculation inputs or logic at a practical level. Syntage reports are calculated from information available in **Data**. Syntage does not validate formulas or methodologies created by individual organizations outside the product. ## Why are annual comparison revenue and tax return revenue different? They come from different sources. Annual comparison revenue is based on invoice analysis. Annual return revenue is based on what the taxpayer filed in the annual return. These can differ because of accounting decisions, tax treatments, incentives, exemptions, or other adjustments made by the taxpayer. Only the taxpayer can explain why filed revenue differs from invoiced revenue. ## Why are financial statements missing? Financial statement data may be missing when: * The annual return Excel file was filed with zeros. * The annual return Excel file was not available because the taxpayer filed audited financial statements through another SAT process. * The extraction failed or has not completed. For companies, Syntage uses the annual return Excel file when SAT provides it. For individuals with business activity, Syntage may use the annual return PDF. To investigate, open **Data > Annual returns > Files** and review the annual return PDF and related files. ## Where can I find documents? Open the entity from [All Entities](https://app.syntage.com/entities), then go to **Data**. | Document | Common location | | - | - | | Invoice XML or PDF | **Data > Invoices > Files** | | Return PDF, receipt, payment proof, or Excel | **Data > Tax returns > Files** | | Constancia de Situación Fiscal | **Data > Tax status > Files** | | Opinión de cumplimiento | **Data > Tax compliance checks > Files** | | RPC, RUG, or BIL files | Expand the relevant public-record details | | Buró de Crédito PDF | Open the Buró de Crédito section and review files | ## Can I download a report as a PDF? Yes, if you have permission to download reports; users with read-only permission cannot. Open the entity report and select **Download Report**. The PDF is generated in the background and you receive a notification when it is ready to download. See [Download a report as a PDF](/using-syntage/dashboard/reports#download-a-report-as-a-pdf). Report PDFs can also be requested [through the API](/resources/insights/reports). ## How can I see export status? Open [Exports](https://app.syntage.com/settings/exports). The page shows the export status, file name, export details, and available files for download. ## Can report values be customized? Some **Risk indicators** support organization-specific thresholds. Open **Reports > Risk indicators** and look for indicators with a settings control. Not every report or indicator can be customized. ## Does Syntage have notifications? Yes. Notifications can be sent for events such as entity onboarding, first-time extraction completion, export completion, and monitoring events. Notification preferences are user-specific. Review them from [Notifications](https://app.syntage.com/settings/notifications). # Quick start Source: https://docs.syntage.com/using-syntage/get-started/quick-start Create your first entity, invite your team, and review the first data and reports in Syntage. Use this guide when your organization is starting with Syntage through the dashboard. You will invite users, create an entity, complete onboarding, and review the information Syntage retrieves. ## Create or access your organization Go to [app.syntage.com](https://app.syntage.com) and sign in. If your organization has not been created yet, complete the registration flow or contact your Syntage contact so your organization can be set up with the correct plan and permissions. ## Invite your team Each person should use their own user. This keeps permissions, notifications, and auditability tied to the person taking the action. To invite a user: 1. Open [Users](https://app.syntage.com/settings/users). 2. Click **Add user**. 3. Enter the user's name, email, and role. 4. Save the user. The user receives an email invitation to create their password and activate access. ## Create your first entity An entity is the person or company your organization evaluates in Syntage. To create an entity with the dashboard: 1. Open [All Entities](https://app.syntage.com/entities). 2. Click **Add entity**. 3. Select the datasources you need. 4. Enter the entity's RFC or legal name, depending on the selected datasources. 5. Complete the flow or share the onboarding link when the entity needs to authorize access. Some datasources are public and can be requested directly from the dashboard. Private datasources, such as SAT and Buró de Crédito, require authorization from the entity. > [!NOTE] > > For SAT onboarding, the entity provides a CIEC password or e.firma access. Syntage encrypts credential material immediately and uses it to retrieve SAT information for the entity. ## Review reports and data After the first [extractions](/using-syntage/extractions) finish, open the entity from [All Entities](https://app.syntage.com/entities). The entity view is organized around: | Area | Use it for | | - | - | | Reports | Processed indicators, analysis, summaries, and charts for decision-making | | Data | Source records, raw structured data, and original files such as PDFs, XMLs, and Excel files | Reports help teams review an entity quickly. Data gives analysts and operations teams the underlying records used to validate, audit, or build custom analysis. ## Download or export information Many report and data sections support downloads. Use [Exports](https://app.syntage.com/settings/exports) when you need to take data out of Syntage for internal analysis, files, or operational handoffs. Exports do not create new extractions. They download information that Syntage has already retrieved. ## Recommended first test Before using Syntage with production workflows, create at least one test entity, run each datasource your team expects to use, review the resulting reports and data, and confirm your users understand how the information fits your internal process. # Trial best practices Source: https://docs.syntage.com/using-syntage/get-started/trial-best-practices Prepare a trial or pilot so your team can evaluate Syntage with realistic workflows. Use your trial period to validate the full workflow your team expects to run in production: onboarding, extractions, reports, data review, exports, and handoff to internal teams. ## Test with real workflows During the trial, complete at least one end-to-end test: 1. Create an entity. 2. Run the datasources and extractors that matter for your process. 3. Review both **Reports** and **Data**. 4. Download or export the documents your team normally needs. 5. Confirm the output is enough for your credit, risk, legal, onboarding, or operations process. ## Involve the right teams Bring the teams that will use Syntage into the trial early. Depending on your use case, this may include commercial, credit analysis, risk, legal, compliance, product, engineering, or operations. Ask each team to review the parts of Syntage they will rely on, not only the initial onboarding flow. ## Define your entity onboarding process Document how your organization will ask entities to authorize access. A good onboarding process should explain: * Why your organization needs the information * Which datasources you will request * How the entity receives the onboarding link * Who follows up if the entity does not complete onboarding * What your team checks after validation succeeds ## Check extraction results After an entity completes onboarding, Syntage starts the configured first-time [extractions](/using-syntage/extractions). Review the extraction statuses before making decisions with the data. If an extraction fails or remains pending longer than expected, check whether the datasource is available, whether the entity's credential or authorization is valid, and whether the extraction reached a datasource limit. ## Tune recurring extraction rules Recurring extractions keep data current, but they also consume plan usage. Use tags to target the entities that need monitoring and avoid running high-frequency rules for entities that do not need them. For details, read [Extraction schedulers](/using-syntage/dashboard/extraction-scheduler). # Notifications Source: https://docs.syntage.com/using-syntage/notifications Manage dashboard and email notifications for product and workflow updates. Syntage can notify you about product updates and important dashboard activity. Each user controls their own email notification preferences. ## Dashboard notifications Dashboard notifications appear in the app when there is activity you should review. These include product release notes and workflow events such as entities being registered, assigned, or ready to review. Product release notes appear in the dashboard when new changelog entries are published. Open **Release Notes** from the dashboard menu to review current and previous updates. ## Email notifications Email notifications are managed from **Settings > Notifications**. Available email notifications include: | Notification | When it is sent | Default | | - | - | - | | Entity registered | When an entity is registered. This does not mean the report is ready. | Enabled based on your organization configuration | | Entity assigned | When an entity is assigned to you. | Enabled based on your organization configuration | | Report ready | When first-time extractions are complete and the report is ready to review. | Enabled based on your organization configuration | | Product updates | When Syntage publishes a new product release note. | Disabled | You can also subscribe or unsubscribe from product update emails directly from the release notes modal in the dashboard. ## Opt in or out 1. Open the dashboard. 2. Go to **Settings > Notifications**. 3. Turn each email notification on or off. Changes apply only to your user. Other users in the same organization manage their own notification preferences. # Onboarding Source: https://docs.syntage.com/using-syntage/onboarding Understand the ways entities can be connected to Syntage datasources. Onboarding is the process of connecting an entity to the datasources your organization needs. The exact flow depends on the datasource. Some workflows use credentials, some use authorizations, and some use report or [extraction](/using-syntage/extractions) requests. For SAT, onboarding usually means providing a CIEC or e.firma credential so Syntage can validate access and extract SAT data for the entity. For Buró de Crédito, onboarding can involve collecting the authorization required to request a report. ## Ways to onboard * Use the Syntage dashboard when your team can complete onboarding directly in Syntage. * Use embedded entity onboarding when you need the onboarding experience inside your own site instead of redirecting users to Syntage. * Use the API when your integration manages credentials, authorizations, extraction requests, or report requests directly. ## Developer resources * Use [Embedding Entity Onboarding](/guides/embedding-entity-onboarding) when you need to embed the onboarding experience into your own product. * Use [Integration Flow](/guides/integration-flow) for a developer-focused walkthrough of credentials, extractions, webhooks, and retrieved records. * Use [Extractions](/using-syntage/extractions) to understand how data is retrieved after onboarding or authorization. * Use [SAT credentials](/resources/datasources/sat/credentials) to understand SAT credential statuses and revalidation. # Retrieve a background check Source: https://docs.syntage.com/api-reference/background-checks/get-a-specific-background-check get /background-checks/{id} Retrieves one background check, including its score, processing status, country scope, associated files, and links to related records. # List background checks Source: https://docs.syntage.com/api-reference/background-checks/get-all-background-checks get /background-checks Lists background checks available to the organization. Use filters to narrow the list by processing status, country scope, or score. # List an entity's background checks Source: https://docs.syntage.com/api-reference/background-checks/get-an-entitys-background-checks get /entities/{entityId}/background-checks Lists background checks associated with an entity. Use this endpoint when your integration is working from a known entity ID. # Download background check PDF Source: https://docs.syntage.com/api-reference/background-checks/get-background-check-pdf-report get /background-checks/{id}/pdf Downloads the generated PDF report for a background check. The response body is the PDF file itself. # List background check records Source: https://docs.syntage.com/api-reference/background-checks/get-background-check-records get /background-checks/{backgroundCheckId}/records Lists the records found during a background check. Records contain the detailed source data behind the check and are organized by category and database. # Retrieve a company verification report Source: https://docs.syntage.com/api-reference/company-verification-reports/get-a-specific-company-verification-report get /datasources/mx/company-verification/reports/{id} Retrieves one company verification report, including its verification details, metadata, and supporting file references. # List company verification reports Source: https://docs.syntage.com/api-reference/company-verification-reports/get-all-company-verification-reports get /datasources/mx/company-verification/reports Lists company verification reports available to the organization. Use this endpoint when you need to page through reports across entities. # List an entity's company verification reports Source: https://docs.syntage.com/api-reference/company-verification-reports/get-an-entitys-company-verification-reports get /entities/{entityId}/datasources/mx/company-verification/reports Lists company verification reports associated with an entity. Use this endpoint when your integration is working from a known entity ID. # List an entity's RPC actos Source: https://docs.syntage.com/api-reference/ds-mx-rpc-actos/list-an-entitys-rpc-actos get /entities/{entityId}/datasources/mx/rpc/actos List RPC actos extracted for an entity. Use this endpoint when your integration needs individual registry acts rather than the complete RPC entidade response. # Retrieve RPC acto Source: https://docs.syntage.com/api-reference/ds-mx-rpc-actos/retrieve-an-rpc-acto get /rpc/actos/{id} Retrieve one RPC acto by ID, including registry act metadata, parsed act data, and file reference when a registry document is available. # List an entity's RPC entidades Source: https://docs.syntage.com/api-reference/ds-mx-rpc-entidades/list-all-entities-rpc-entidades-data-beta get /entities/{entityId}/datasources/mx/rpc/entidades List RPC entidades extracted for an entity. Use this endpoint after an `rpc` extraction finishes to review the RPC company records found for the entity. # Retrieve RPC entidade Source: https://docs.syntage.com/api-reference/ds-mx-rpc-entidades/retrieve-rpc-entidades-data-beta get /datasources/mx/rpc/entidades/{id} Retrieve one RPC entidade by ID, including the company profile, related actos, and related socios extracted from Registro Publico de Comercio. # Retrieve RPC socio Source: https://docs.syntage.com/api-reference/ds-mx-rpc-socios/retrieve-an-rpc-socio get /datasources/rpc/socios/{id} Retrieve one RPC socio by ID, including shareholder details and the RPC entidade profile it belongs to. # List an entity's RUG guarantees Source: https://docs.syntage.com/api-reference/ds-mx-rug-garantias/list-all-entities-rug-garantias-data-beta get /entities/{entityId}/datasources/rug/garantias List RUG guarantees extracted for an entity. Use this endpoint after a `rug` extraction finishes to review movable collateral guarantees found for the entity. # Retrieve RUG guarantee Source: https://docs.syntage.com/api-reference/ds-mx-rug-garantias/retrieve-rug-garantia-data get /datasources/rug/garantias/{id} Retrieve one RUG guarantee by ID, including collateral details, creditor, grantors, contract dates, and related operations. # List an entity's RUG operations Source: https://docs.syntage.com/api-reference/ds-mx-rug-operaciones/list-all-entities-rug-operaciones-data get /entities/{entityId}/datasources/rug/operaciones List RUG operations extracted for an entity. Use this endpoint after a `rug` extraction finishes to review registry acts related to the entity's guarantees. # Retrieve RUG operation Source: https://docs.syntage.com/api-reference/ds-mx-rug-operaciones/retrieve-rug-operacion-data get /datasources/rug/operaciones/{id} Retrieve one RUG operation by ID, including operation type, seat number, guarantee number, grantors, parsed boleta data, and file reference when available. # List an entity's SAT certificates Source: https://docs.syntage.com/api-reference/ds-mx-sat-certificates/list-an-entitys-sat-certificates get /entities/{entityId}/datasources/mx/sat/certificados List SAT certificates associated with an entity. These digital certificates are used for electronic signatures and digital sealing in Mexico's tax system. # Retrieve a SAT certificate Source: https://docs.syntage.com/api-reference/ds-mx-sat-certificates/retrieve-a-sat-certificate get /datasources/mx/sat/certificados/{id} Retrieve a SAT certificate by ID. The `file` property references the certificate file. Use the file download endpoint to retrieve the certificate content. # Create a credential Source: https://docs.syntage.com/api-reference/ds-mx-sat-credentials/create-a-credential post /credentials Create a SAT credential for an RFC. If the RFC is not already associated with your organization, Syntage creates the related entity association as part of credential creation. # Delete a credential Source: https://docs.syntage.com/api-reference/ds-mx-sat-credentials/delete-a-credential delete /credentials/{id} Delete a SAT credential so it can no longer be used for new extraction work. # List all credentials Source: https://docs.syntage.com/api-reference/ds-mx-sat-credentials/list-all-credentials get /credentials List SAT credentials available to your organization. # Retrieve a credential Source: https://docs.syntage.com/api-reference/ds-mx-sat-credentials/retrieve-a-credential get /credentials/{id} Retrieve a SAT credential by ID, including its credential type, RFC, and validation status. # Revalidate a credential Source: https://docs.syntage.com/api-reference/ds-mx-sat-credentials/revalidate-a-credential post /credentials/{id}/revalidate Request validation for a SAT credential that is not already valid. # List an invoice's applied credit notes Source: https://docs.syntage.com/api-reference/ds-mx-sat-credit-notes/list-all-applied-credit-notes-related-to-the-requested-invoice get /invoices/{invoiceId}/applied-credit-notes List credit notes applied to the requested invoice. # List an invoice's issued credit notes Source: https://docs.syntage.com/api-reference/ds-mx-sat-credit-notes/list-all-issued-credit-notes-related-to-the-requested-invoice get /invoices/{invoiceId}/issued-credit-notes List credit notes issued by the requested invoice. # List an entity's credit notes Source: https://docs.syntage.com/api-reference/ds-mx-sat-credit-notes/list-an-entitys-credit-notes get /entities/{entityId}/invoices/credit-notes List credit notes extracted for an entity. # List credit notes Source: https://docs.syntage.com/api-reference/ds-mx-sat-credit-notes/list-credit-notes get /invoices/credit-notes List credit notes related to invoices. # Retrieve an invoice credit note Source: https://docs.syntage.com/api-reference/ds-mx-sat-credit-notes/retrieve-an-invoice-credit-note get /invoices/credit-notes/{id} Retrieve a credit note by ID, including the issued invoice, applied invoice, amount, and cancellation status. # List an entity's electronic accounting records Source: https://docs.syntage.com/api-reference/ds-mx-sat-electronic-accounting/list-all-entities-electronic-accounting-records get /entities/{entityId}/electronic-accounting-records List electronic accounting records extracted for an entity. # Retrieve an electronic accounting record Source: https://docs.syntage.com/api-reference/ds-mx-sat-electronic-accounting/retrieve-an-electronic-accounting-record get /electronic-accounting-records/{id} Retrieve an electronic accounting record by ID, including fiscal period, accounting file type, status, and related files. # List all invoice batch payments Source: https://docs.syntage.com/api-reference/ds-mx-sat-invoice-batch-payments/list-all-invoice-batch-payments get /invoices/batch-payments List batch payments derived from invoice payment receipts. # List an invoice's batch payments Source: https://docs.syntage.com/api-reference/ds-mx-sat-invoice-batch-payments/list-an-invoices-batch-payments get /invoices/{id}/batch-payments List all batch payments related to the requested invoice. # Retrieve an invoice batch payment Source: https://docs.syntage.com/api-reference/ds-mx-sat-invoice-batch-payments/retrieve-an-invoice-batch-payment get /invoices/batch-payments/{id} Retrieve an invoice batch payment by ID, including transaction-level payment details and related invoice payments. # List an entity's invoice line items Source: https://docs.syntage.com/api-reference/ds-mx-sat-invoice-line-items/list-all-entity-line-items get /entities/{entityId}/invoices/line-items List invoice line items extracted for an entity. # List an invoice's line items Source: https://docs.syntage.com/api-reference/ds-mx-sat-invoice-line-items/list-an-invoices-line-items get /invoices/{invoiceId}/line-items List line items from the requested invoice. # Retrieve an invoice line item Source: https://docs.syntage.com/api-reference/ds-mx-sat-invoice-line-items/retrieve-an-invoice-line-item get /invoices/line-items/{id} Retrieve an invoice line item by ID, including product, quantity, amount, and tax details. # List all invoice payments Source: https://docs.syntage.com/api-reference/ds-mx-sat-invoice-payments/list-all-invoice-payments get /invoices/payments List invoice payments applied to deferred invoices. # List an invoice's payments Source: https://docs.syntage.com/api-reference/ds-mx-sat-invoice-payments/list-an-invoices-payments get /invoices/{id}/payments List payments applied to the requested invoice. # List an entity's invoice payments Source: https://docs.syntage.com/api-reference/ds-mx-sat-invoice-payments/list-entities-invoice-payments get /entities/{entityId}/invoices/payments List invoice payments extracted for an entity. # Retrieve an invoice payment Source: https://docs.syntage.com/api-reference/ds-mx-sat-invoice-payments/retrieve-an-invoice-payment get /invoices/payments/{id} Retrieve an invoice payment by ID, including the deferred invoice, batch payment, amount, balance, and cancellation status. # List an entity's invoice relations Source: https://docs.syntage.com/api-reference/ds-mx-sat-invoice-relations/list-an-entitys-invoice-relations get /entities/{entityId}/invoices/{invoiceId}/relations List invoice relations for an invoice within an entity. # List an invoice's relations Source: https://docs.syntage.com/api-reference/ds-mx-sat-invoice-relations/list-an-invoices-relations get /invoices/{invoiceId}/relations List invoice relations for the requested invoice. # Retrieve an invoice relation Source: https://docs.syntage.com/api-reference/ds-mx-sat-invoice-relations/retrieve-an-invoice-relation get /invoices/relations/{id} Retrieve an invoice relation by ID, including the source invoice, related invoice, related invoice UUID, and SAT relation type. # List an entity's invoices Source: https://docs.syntage.com/api-reference/ds-mx-sat-invoices/list-all-entities-invoices get /entities/{entityId}/invoices List invoices extracted for an entity. # Retrieve a SAT CFDI Source: https://docs.syntage.com/api-reference/ds-mx-sat-invoices/retrieve-a-sat-cfdi get /datasources/mx/sat/cfdis/{uuid} Retrieve parsed SAT CFDI data by invoice UUID. When `X-Async-Process` is set to `1`, the endpoint can return `202 Accepted` while CFDI parsing continues asynchronously. # Retrieve an invoice Source: https://docs.syntage.com/api-reference/ds-mx-sat-invoices/retrieve-an-invoice get /invoices/{id} Retrieve an invoice by ID, including SAT identifiers, issuer and receiver details, totals, payment status, file availability, and invoice relationships. # Retrieve an invoice's CFDI Source: https://docs.syntage.com/api-reference/ds-mx-sat-invoices/retrieve-an-invoices-cfdi get /invoices/{id}/cfdi Retrieve the invoice CFDI in the requested format. By default, this endpoint returns the CFDI parsed from XML to JSON. Set `Accept: text/xml` to retrieve the original XML file, or `Accept: application/pdf` to retrieve the PDF representation when one is available. # Tag an invoice Source: https://docs.syntage.com/api-reference/ds-mx-sat-invoices/tag-an-invoice post /invoices/{id}/tags Add a tag to an invoice. # Tag multiple invoices Source: https://docs.syntage.com/api-reference/ds-mx-sat-invoices/tag-multiple-invoices post /invoices/batch/tags Add one or more tags to up to 100 invoices in a single request. The operation is atomic: if any invoice or tag in the request cannot be found, no invoice is modified. Tags the invoice already has are kept as-is, so retrying the same request is safe. # Untag an invoice Source: https://docs.syntage.com/api-reference/ds-mx-sat-invoices/untag-an-invoice delete /invoices/{invoiceId}/tags/{tagId} Remove a tag from an invoice. # Untag multiple invoices Source: https://docs.syntage.com/api-reference/ds-mx-sat-invoices/untag-multiple-invoices post /invoices/batch/tags/remove Remove one or more tags from up to 100 invoices in a single request. The operation is atomic: if any invoice or tag in the request cannot be found, no invoice is modified. Tags an invoice does not have are ignored, so retrying the same request is safe. # List an entity's tax compliance checks Source: https://docs.syntage.com/api-reference/ds-mx-sat-tax-compliance-checks/list-all-entities-tax-compliance-checks get /entities/{entityId}/tax-compliance-checks List tax compliance checks extracted for an entity. # Retrieve a tax compliance check Source: https://docs.syntage.com/api-reference/ds-mx-sat-tax-compliance-checks/retrieve-a-tax-compliance-check get /tax-compliance-checks/{id} Retrieve a tax compliance check by ID, including the SAT compliance result and source PDF file. # List an entity's tax retentions Source: https://docs.syntage.com/api-reference/ds-mx-sat-tax-retentions/list-all-entities-tax-retentions get /entities/{entityId}/tax-retentions List tax retentions extracted for an entity. # Retrieve a tax retention Source: https://docs.syntage.com/api-reference/ds-mx-sat-tax-retentions/retrieve-a-tax-retention get /tax-retentions/{id} Retrieve a tax retention by ID, including issuer, receiver, retained taxes, fiscal period, totals, and file availability. # Retrieve a tax retention CFDI Source: https://docs.syntage.com/api-reference/ds-mx-sat-tax-retentions/retrieve-a-tax-retention-cfdi get /tax-retentions/{id}/cfdi Retrieve the tax retention CFDI in the requested format. By default, this endpoint returns the CFDI parsed from XML to JSON. Set `Accept: text/xml` to retrieve the original XML file, or `Accept: application/pdf` to retrieve the PDF representation when one is available. # Download a tax return PDF Source: https://docs.syntage.com/api-reference/ds-mx-sat-tax-returns/download-a-tax-return-pdf get /tax-returns/{id}/pdf Download the SAT transcript PDF for a tax return. # List an entity's tax returns Source: https://docs.syntage.com/api-reference/ds-mx-sat-tax-returns/list-all-entities-tax-returns get /entities/{entityId}/tax-returns List tax returns extracted for an entity. # Retrieve a tax return Source: https://docs.syntage.com/api-reference/ds-mx-sat-tax-returns/retrieve-a-tax-return get /tax-returns/{id} Retrieve a tax return by ID, including filing metadata, payment information, file references, and ISSIF availability. # Retrieve tax return data Source: https://docs.syntage.com/api-reference/ds-mx-sat-tax-returns/retrieve-a-tax-return-data get /tax-returns/{id}/data Retrieve extracted data from a tax return. For annual tax returns, there are two available formats: - Financial statements 2022 format - This is available for non-pfae tax returns. Data will only be returned if the SAT provides the XLSX financial statements document. - Financial statements 2014 format - This is available for pfae annual tax returns from 2014 to now, and all other annual tax returns from 2014-2021, as long as we are able to retrieve the PDF. Annual tax returns of the digital platforms regime (625) have no balance sheet, and their income figures are not in the financial statement keys. Their data is under `PLATAFORMAS TECNOLÓGICAS`, as declared in that section of the return: `INGRESOS` (the year's platform income, in total and by type of service), `DEDUCCIONES AUTORIZADAS`, `RESULTADO FISCAL` (fiscal profit or loss, profit sharing, prior-year losses, and taxable profit), `PAGOS PROVISIONALES`, `ISR RETENIDO` (withheld by the platforms), and `DETERMINACIÓN DEL IMPUESTO`, which covers all of the return's income. A value is `null` when the return does not include it. For provisional (monthly) tax returns, the response contains extracted financial variables including sales revenue, cash inflow, cash outflow, number of employees, and payroll amount. The available variables depend on the tax regime (601, 606, 612, 622, 625, 626). For the AGAPES regime (622), sales revenue and cash inflow are the month's income, as declared in its "Ingresos del periodo"; the other variables are not available for these declarations and are `null`. For the digital platforms regime (625), sales revenue and cash inflow are the month's platform income, and for rental-only declarations of the leasing regime (606) the month's rental income; the other variables are not available for these declarations and are `null`. The response format here may change if SAT changes the categories or other formatting in the files they provide. # List an entity's tax status records Source: https://docs.syntage.com/api-reference/ds-mx-sat-tax-status/list-all-entities-tax-status get /entities/{entityId}/tax-status List tax status records extracted for an entity. # List tax status records Source: https://docs.syntage.com/api-reference/ds-mx-sat-tax-status/list-tax-status-records get /tax-status List tax status records available to your organization. # Retrieve a tax status Source: https://docs.syntage.com/api-reference/ds-mx-sat-tax-status/retrieve-a-tax-status get /tax-status/{id} Retrieve a tax status record by ID, including identity, address, activities, regimes, obligations, and the source PDF file. # Start Syntage Score calculation Source: https://docs.syntage.com/api-reference/ds-syntage-score/calculate-syntage-score post /entities/{entityId}/datasources/syntage/score/calculate Start an asynchronous Syntage Score calculation for a company entity. The entity must have the annual tax return and tax compliance data required by the score model. If a required extraction is still running, wait for it to finish before starting the calculation. # Delete an entity tag Source: https://docs.syntage.com/api-reference/entities/delete-an-entity-tag delete /entity-tags/{id} Delete an entity tag. # Tag multiple entities Source: https://docs.syntage.com/api-reference/entities/tag-multiple-entities post /entities/batch/tags Add one or more tags to up to 100 entities in a single request. Tag IRIs are accepted in both the `/entity-tags/{id}` and `/link-tags/{id}` forms. The operation is atomic: if any entity or tag in the request cannot be found, no entity is modified. Tags an entity already has are kept as-is, so retrying the same request is safe. # Untag multiple entities Source: https://docs.syntage.com/api-reference/entities/untag-multiple-entities post /entities/batch/tags/remove Remove one or more tags from up to 100 entities in a single request. Tag IRIs are accepted in both the `/entity-tags/{id}` and `/link-tags/{id}` forms. The operation is atomic: if any entity or tag in the request cannot be found, no entity is modified. Tags an entity does not have are ignored, so retrying the same request is safe. # Create an extraction Source: https://docs.syntage.com/api-reference/extractions/create-an-extraction post /extractions Create an extraction for a specific entity, extractor, and options. If an equivalent extraction is already `pending` or `running` for the same entity, extractor, and options, the API returns `409 Conflict` instead of starting a duplicate. Retrieve the in-progress extraction to track its status rather than retrying the request. # List all extractions Source: https://docs.syntage.com/api-reference/extractions/list-all-extractions get /extractions List extraction tasks and filter them by entity, extractor, status, dates, or SAT rate limit state. # Request the extraction to be stopped Source: https://docs.syntage.com/api-reference/extractions/request-the-extraction-to-be-stopped delete /extractions/{id}/stop Request cancellation for a pending or running extraction. # Retrieve an extraction Source: https://docs.syntage.com/api-reference/extractions/retrieve-an-extraction get /extractions/{id} Retrieve a single extraction, including its extractor, options, status, timing, error code, and data point counts. # Retrieve addresses by postal code Source: https://docs.syntage.com/api-reference/mexico-addresses/retrieve-addresses-by-postal-code get /datasources/mx/addresses/{postalCode} Retrieve Mexico address options for a postal code. Buró de Crédito and Buró Empresas require submitted addresses to match the postal-code address catalog, and a postal code can return multiple neighborhoods. Use this endpoint to retrieve Mexico address options for a five-digit postal code. Buró de Crédito and Buró Empresas require submitted addresses to match the official postal-code address catalog, so use this endpoint when collecting or validating addresses for those workflows. The response can contain multiple neighborhoods for the same postal code. Each item includes the neighborhood, neighborhood type, municipality, state, state code, city, and postal office key. # Create a scheduler rule Source: https://docs.syntage.com/api-reference/scheduler-rules/create-an-scheduler-rule post /schedulers/rules Create a rule that runs an extractor on a scheduler. # Delete a scheduler rule Source: https://docs.syntage.com/api-reference/scheduler-rules/delete-an-scheduler-rule delete /schedulers/rules/{id} Delete a scheduler rule. # Retrieve a scheduler rule Source: https://docs.syntage.com/api-reference/scheduler-rules/retrieve-an-scheduler-rule get /schedulers/rules/{id} Retrieve a scheduler rule by ID. # Update a scheduler rule Source: https://docs.syntage.com/api-reference/scheduler-rules/update-an-scheduler-rule put /schedulers/rules/{id} Update the extractor, options, or cron expression for a scheduler rule. # Create a scheduler Source: https://docs.syntage.com/api-reference/schedulers/create-an-scheduler post /schedulers Create a scheduler that can run one or more extraction rules. # Delete a scheduler Source: https://docs.syntage.com/api-reference/schedulers/delete-an-scheduler delete /schedulers/{id} Delete a scheduler. # List schedulers Source: https://docs.syntage.com/api-reference/schedulers/list-schedulers get /schedulers List all schedulers. # Retrieve a scheduler Source: https://docs.syntage.com/api-reference/schedulers/retrieve-an-scheduler get /schedulers/{id} Retrieve a scheduler by ID, including its rules and tags. # Update a scheduler Source: https://docs.syntage.com/api-reference/schedulers/update-an-scheduler put /schedulers/{id} Update a scheduler's name or enabled state. # Create a new shareholder for an entity Source: https://docs.syntage.com/api-reference/shareholders/create-a-new-shareholder-for-an-entity post /entities/{entityId}/shareholders Adds manually collected shareholder information to an entity. The request creates a shareholder and the relation between that shareholder and the entity. # Delete a shareholder Source: https://docs.syntage.com/api-reference/shareholders/delete-a-shareholder delete /shareholders/{id} Deletes a shareholder resource. # Delete a shareholder relation Source: https://docs.syntage.com/api-reference/shareholders/delete-a-shareholder-relation delete /shareholders/{shareholderId}/relations/{relationId} Deletes the relationship between a shareholder and an entity. # Delete a shareholder relation source Source: https://docs.syntage.com/api-reference/shareholders/delete-a-shareholder-relation-source delete /shareholders/{shareholderId}/relations/{relationId}/sources/{sourceId} Deletes one source from a shareholder relation. # Retrieve a shareholder Source: https://docs.syntage.com/api-reference/shareholders/get-a-specific-shareholder get /shareholders/{id} Retrieves one shareholder by ID. # Retrieve a shareholder relation Source: https://docs.syntage.com/api-reference/shareholders/get-a-specific-shareholder-relation get /shareholders/{shareholderId}/relations/{relationId} Retrieves one shareholder relation by ID. # Retrieve a shareholder relation source Source: https://docs.syntage.com/api-reference/shareholders/get-a-specific-shareholder-relation-source get /shareholders/{shareholderId}/relations/{relationId}/sources/{sourceId} Retrieves one source for a shareholder relation. # List shareholders Source: https://docs.syntage.com/api-reference/shareholders/get-all-shareholders get /shareholders Lists shareholders available to the organization. Use this endpoint when you need to search shareholders across entities. # List an entity's shareholders Source: https://docs.syntage.com/api-reference/shareholders/get-an-entitys-shareholders get /entities/{entityId}/shareholders Lists shareholders connected to an entity. Use filters to narrow the list by shareholder type, name, or RFC. # List shareholder relation sources Source: https://docs.syntage.com/api-reference/shareholders/get-shareholder-relation-sources get /shareholders/{shareholderId}/relations/{relationId}/sources Lists the sources that support a shareholder relation, such as manually entered data or information sourced from RPC. # List shareholder relations Source: https://docs.syntage.com/api-reference/shareholders/get-shareholder-relations get /shareholders/{shareholderId}/relations Lists the entity relationships for a shareholder, including ownership direction and available ownership details. # Promote a shareholder relation Source: https://docs.syntage.com/api-reference/shareholders/promote-a-shareholder-relation post /shareholders/{shareholderId}/relations/{relationId}/promote Promotes a shareholder relation by creating an entity for the shareholder. Use this when the shareholder should be managed as its own person or company in your integration. # Update a shareholder Source: https://docs.syntage.com/api-reference/shareholders/update-a-shareholder patch /shareholders/{id} Updates manually editable shareholder details such as the shareholder's name or RFC. # Update a shareholder relation Source: https://docs.syntage.com/api-reference/shareholders/update-a-shareholder-relation patch /shareholders/{shareholderId}/relations/{relationId} Updates manually editable details for a shareholder relation, such as the number of shares. # Create a tag Source: https://docs.syntage.com/api-reference/tags/create-a-tag post /tags Create a tag for a supported resource type. # Delete a tag Source: https://docs.syntage.com/api-reference/tags/delete-a-tag delete /tags/{id} Delete a tag. # List all tags Source: https://docs.syntage.com/api-reference/tags/list-all-tags get /tags List tags that can be assigned to supported resources. # Update a tag Source: https://docs.syntage.com/api-reference/tags/update-a-tag patch /tags/{id} Update a tag's display name or color. # Accounts Payable Insight Source: https://docs.syntage.com/api-reference/accounts-payable-insight/get-accounts-payable get /entities/{entityId}/insights/accounts-payable Returns accounts payable data showing amounts due and paid over time, including cumulative totals. # Accounts Receivable Insight Source: https://docs.syntage.com/api-reference/accounts-receivable-insight/get-accounts-receivable get /entities/{entityId}/insights/accounts-receivable Returns accounts receivable data showing amounts due and paid over time, including cumulative totals. # Balance Sheet Insight Source: https://docs.syntage.com/api-reference/balance-sheet-insight/get-balance-sheet-metric get /entities/{entityId}/insights/metrics/balance-sheet Returns the entity's balance sheet organized in a tree of categories. The structure of the category tree changes according to: - The tax regime. - The year format (the year when SAT changes the structure, i.e., a breaking change) Supported tax regimes: - **601** (Personas Morales) - **612** (PFAE/Personas Físicas con Actividades Empresariales y Profesionales) Available formats: - **2014** - the data is extracted from annual [tax returns](#tag/TaxReturns) transcript **PDFs**. - **2022** - the data is extracted from annual [tax returns](#tag/TaxReturns) financial statements **XLSXs**. - **audited-financial-statements** - the data is extracted from audited annual [tax returns](#tag/TaxReturns) financial statements **XLSMs**. - **issif-financial-statements** - the data is extracted from Informative Statements on Tax Situation (**ISSIF**) financial statements **XLSMs**. Notes: - The **Comment** field in the response body refers to the content of the **Nota** column in the **XLSX** or **XLSM**. - The **2021** data may be extracted from the 2022 document (in 2022 format). # Buró de Crédito Summary Export Source: https://docs.syntage.com/api-reference/buro-de-credito-summary-insight/export-buro-de-credito-summary get /entities/{entityId}/insights/metrics/buro-de-credito/summary/export Export Buró de Crédito report score summaries for an entity as CSV or XLSX. # Buró de Crédito Summary Insight Source: https://docs.syntage.com/api-reference/buro-de-credito-summary-insight/get-buro-de-credito-summary get /entities/{entityId}/insights/metrics/buro-de-credito/summary List Buró de Crédito report score summaries for an entity. # Cash Flow Insight Source: https://docs.syntage.com/api-reference/cash-flow-insight/get-cash-flow get /entities/{entityId}/insights/cash-flow-stats Inflows and outflows over time, derived from issued and received invoices. # Current Powers Insight Source: https://docs.syntage.com/api-reference/corporate-structure-current-powers-insight/get-current-powers get /entities/{entityId}/insights/corporate-structure/current-powers List the people and companies that hold at least one currently effective power of attorney, drawn from the most recent Company Verification report registered for the entity. Each row carries the identity of a person or company with at least one currently effective power from the entity's most recent Company Verification report. Holders whose powers have all expired are omitted. To retrieve shareholders and the latest capital table from Company Verification, use the shareholders metrics insight at `/entities/{entityId}/insights/metrics/shareholders`. When the entity has no Company Verification report yet, the response is an empty collection (`hydra:totalItems` of `0`). > [!NOTE] > > To export this insight, use [Insight Export](/api-reference/insights/export-an-insight) with `corporate-structure-current-powers` as the insight name. This insight returns people with currently effective powers from the entity's most recent Company Verification report. To retrieve shareholders, use `GET /entities/{entityId}/insights/metrics/shareholders` with `relations.relationType=shareholders`. When Company Verification data is available, that insight uses shareholder rows from the entity's most recent report; manually entered values take precedence for relations that have both sources. # Customer Concentration Insight Source: https://docs.syntage.com/api-reference/customer-concentration-insight/get-customer-invoice-concentration get /entities/{entityId}/insights/customer-concentration Returns the concentration of issued or received invoices by customers. # Customer Network Insight Source: https://docs.syntage.com/api-reference/customer-network-insight/get-customer-network-insight get /entities/{entityId}/insights/metrics/customer-network Customers the entity has sold to, with invoiced totals and cancellation rates per counterparty. # List an entity's BIL reports Source: https://docs.syntage.com/api-reference/ds-mx-bil-reports/list-an-entitys-bil-reports get /entities/{entityId}/datasources/bil/reports List Buró de Investigaciones Legales reports generated for an entity. # Retrieve a BIL report Source: https://docs.syntage.com/api-reference/ds-mx-bil-reports/retrieve-a-bil-report get /datasources/bil/reports/{id} Retrieve a single Buró de Investigaciones Legales report by ID. # Create a Buró de Crédito authorization Source: https://docs.syntage.com/api-reference/ds-mx-buro-de-credito-authorizations/create-a-buro-de-credito-authorization post /entities/{entityId}/datasources/mx/buro-de-credito/authorizations Create a Buró de Crédito authorization for an entity so report extractions can use it # Delete a Buró de Crédito authorization Source: https://docs.syntage.com/api-reference/ds-mx-buro-de-credito-authorizations/delete-a-buro-de-credito-authorization delete /datasources/mx/buro-de-credito/authorizations/{id} Delete a Buró de Crédito authorization by authorization ID # Get a Buró de Crédito authorization Source: https://docs.syntage.com/api-reference/ds-mx-buro-de-credito-authorizations/get-a-buro-de-credito-authorization get /datasources/mx/buro-de-credito/authorizations/{id} Get a single Buró de Crédito authorization by authorization ID # Get Buró de Crédito authorizations Source: https://docs.syntage.com/api-reference/ds-mx-buro-de-credito-authorizations/get-all-buro-de-credito-authorizations get /datasources/mx/buro-de-credito/authorizations List Buró de Crédito authorizations for the organization # Get an entity's Buró de Crédito authorizations Source: https://docs.syntage.com/api-reference/ds-mx-buro-de-credito-authorizations/get-an-entitys-buro-de-credito-authorizations get /entities/{entityId}/datasources/mx/buro-de-credito/authorizations List Buró de Crédito authorizations associated with an entity # Get a Buró de Crédito report Source: https://docs.syntage.com/api-reference/ds-mx-buro-de-credito-reports/get-a-buro-de-credito-report get /datasources/mx/buro-de-credito/reports/{id} Get a single Buró de Crédito report by report ID # Get an entity's Buró de Crédito reports Source: https://docs.syntage.com/api-reference/ds-mx-buro-de-credito-reports/get-an-entitys-buro-de-credito-reports get /entities/{entityId}/datasources/mx/buro-de-credito/reports List Buró de Crédito reports generated for an entity # List an entity's Infonavit overdue credits Source: https://docs.syntage.com/api-reference/ds-mx-infonavit-overdue-credits/list-an-entitys-infonavit-overdue-credits get /entities/{entityId}/datasources/infonavit/overdue-credits List the Infonavit Créditos Firmes records found for an entity. Each record represents an employer registration published in the public Infonavit list of firm (overdue) housing-credit obligations matched to the entity by name. # Retrieve an Infonavit overdue credit Source: https://docs.syntage.com/api-reference/ds-mx-infonavit-overdue-credits/retrieve-an-infonavit-overdue-credit get /datasources/infonavit/overdue-credits/{id} Retrieve a single Infonavit Créditos Firmes record by ID. # Employees Insight Source: https://docs.syntage.com/api-reference/employees-insight/get-employees get /entities/{entityId}/insights/employees Number of employees per period, derived from distinct payroll (CFDI Nómina) recipients. # Expenditures Insight Source: https://docs.syntage.com/api-reference/expenditures-insight/get-expenditures get /entities/{entityId}/insights/expenditures Money the entity has spent over time, aggregated from received income invoices. # Financial Institutions Insight Source: https://docs.syntage.com/api-reference/financial-institutions-insight/get-financial-institutions get /entities/{entityId}/insights/financial-institutions Banks and other financial institutions the entity has transacted with, derived from CFDI payments and third-party accounts on invoices. # Financial Ratios Insight Source: https://docs.syntage.com/api-reference/financial-ratios-insight/get-financial-ratios get /entities/{entityId}/insights/financial-ratios Liquidity, leverage, profitability, and efficiency ratios computed per fiscal year from the entity's annual tax filings. For individuals with business activities (PFAE), current assets are calculated as the sum of cash, accounts and documents receivable, other current assets, contributions in favor, and inventory reported in the annual tax return. The PFAE return does not distinguish between short-term and long-term liabilities. For these ratios, the sum of accounts and documents payable, other liabilities, and contributions payable is used as a proxy for current liabilities. It is not a maturity-based classification. The quick ratio uses `(current assets - inventory) / current liabilities`. Capital intensity uses `total assets / net sales`. # Government Customers Insight Source: https://docs.syntage.com/api-reference/government-customers-insight/get-government-customers get /entities/{entityId}/insights/government-customers The entity's customers that are Mexican federal, state, or municipal government bodies, with each one's share of total revenue. # Income Statement Insight Source: https://docs.syntage.com/api-reference/income-statement-insight/get-metrics-income-statement get /entities/{entityId}/insights/metrics/income-statement Returns the entity's income statement organized in a tree of categories. The structure of the category tree changes according to: - The tax regime. - The year format (the year when SAT changes the structure, i.e., a breaking change) Supported tax regimes: - **601** (Personas Morales) - **612** (PFAE/Personas Físicas con Actividades Empresariales y Profesionales) Available formats: - **2014** - the data is extracted from annual [tax returns](#tag/TaxReturns) transcript **PDFs**. - **2022** - the data is extracted from annual [tax returns](#tag/TaxReturns) financial statements **XLSXs**. - **audited-financial-statements** - the data is extracted from audited annual [tax returns](#tag/TaxReturns) financial statements **XLSMs**. - **issif-financial-statements** - the data is extracted from Informative Statements on Tax Situation (**ISSIF**) financial statements **XLSMs**. Notes: - The **Comment** field in the response body refers to the content of the **Nota** column in the **XLSX** or **XLSM**. - The **2021** data may be extracted from the 2022 document (in 2022 format). - In the **2022** format, matched `Utilidad`/`Pérdida` pairs (`bruta`, `de operación`, `antes de impuestos`, `neta`) are returned under a single grouping parent row, with each side of the pair as an entry in the parent's `children` array. The parent's per-year `Total` reflects the populated side (SAT fills only one side per period). The **2014** format keeps its original grouping behavior. - **Sign convention:** revenue, profit and other inflow lines are returned as positive values; cost, expense, loss, tax and financial-charge lines (for example `Costo de ventas`, `Gastos de operación`, `Pérdida neta`, `Impuestos a la utilidad`, `Intereses a cargo`) are returned as **negative** values. Net or mixed parents (for example `Resultado Integral de Financiamiento`) keep their natural sign. Do not apply additional negation to outflow lines — they already carry the correct sign. See the [2026-06-22 changelog entry](/changelog/2026-06-22-income-statement-outflow-signs) for migration details. # Insight Export Source: https://docs.syntage.com/api-reference/insights/export-an-insight get /entities/{entityId}/insights/{insight}/export Export a supported insight for an entity as CSV or XLSX. Use the same `options[...]` query parameters supported by the corresponding insight endpoint. Unsupported insight names return `404`. # Invoicing Annual Comparison Insight Source: https://docs.syntage.com/api-reference/invoicing-annual-comparison-insight/get-invoicing-annual-comparison-insight get /entities/{entityId}/insights/metrics/invoicing-annual-comparison Year-over-year totals of issued and received invoicing activity, one row per fiscal year. # Invoicing Blacklist Insight Source: https://docs.syntage.com/api-reference/invoicing-blacklist-insight/get-invoicing-blacklist get /entities/{entityId}/insights/invoicing-blacklist Counterparties on the SAT's Artículo 69-B blacklist (EFOS/EDOS) that the entity has transacted with, split between issuers and receivers. # Invoicing Concentration Insight Source: https://docs.syntage.com/api-reference/invoicing-concentration-insight/get-invoicing-concentration get /entities/{entityId}/insights/invoicing-concentration **Deprecated:** Use [Get Customer Invoice Concentration](/api-reference/customer-concentration-insight/get-customer-invoice-concentration) or [Get Vendor Invoice Concentration](/api-reference/vendor-concentration-insight/get-vendor-invoice-concentration) instead. Returns the concentration (top 10) of issued or received invoices. > [!WARNING] > > This endpoint is deprecated. Use the following endpoints instead: > > * [Get Customer Invoice Concentration](/api-reference/customer-concentration-insight/get-customer-invoice-concentration) > * [Get Vendor Invoice Concentration](/api-reference/vendor-concentration-insight/get-vendor-invoice-concentration) # Moratory Interest Insight Source: https://docs.syntage.com/api-reference/moratory-interest-insight/get-moratory-interest get /entities/{entityId}/insights/moratory-interest Returns moratory-interest charges for the entity, aggregated from received financial-institution invoices. The response includes summary KPIs, monthly totals, monthly totals by financial institution, and institution-level totals. If no period is provided, the insight defaults to the last 12 full months. # Products and Services Bought Insight Source: https://docs.syntage.com/api-reference/products-and-services-bought-insight/get-products-and-services-bought get /entities/{entityId}/insights/products-and-services-bought Returns a paginated list of products and services bought by the entity, including transaction details and share percentages. # Products and Services Sold Insight Source: https://docs.syntage.com/api-reference/products-and-services-sold-insight/get-products-and-services-sold get /entities/{entityId}/insights/products-and-services-sold Returns a paginated list of products and services sold by the entity, including transaction details and share percentages. # Create a report Source: https://docs.syntage.com/api-reference/reports/create-a-report post /reports Create a custom report with your own selection of insight entries. Set `organizational` to `true` to share the report with every user in your organization instead of keeping it personal. Reports created through the API are always custom reports: the report-level `builtIn` flag is set only by Syntage and cannot be set through the API. # Delete a report Source: https://docs.syntage.com/api-reference/reports/delete-a-report delete /reports/{id} Delete a custom report. Built-in reports cannot be deleted. Personal reports can only be deleted by their owner; organizational reports can only be deleted by an admin. # List all reports Source: https://docs.syntage.com/api-reference/reports/list-reports get /reports List the reports available to the authenticated user: built-in reports, the user's personal reports, and organizational reports. Insight entries whose feature flags are not enabled for your organization are omitted from the `insights` layout. # Retrieve a report Source: https://docs.syntage.com/api-reference/reports/retrieve-a-report get /reports/{id} Retrieve a report by ID. Use the report ID as the `uri` path segment when requesting a PDF download with the [Exports API](/api-reference/exports/export-data). # Update a report Source: https://docs.syntage.com/api-reference/reports/update-a-report put /reports/{id} Update a custom report's name, insight layout, or organizational visibility. Built-in reports cannot be updated. Personal reports can only be updated by their owner; organizational reports can only be updated by an admin. # Risks Insight Source: https://docs.syntage.com/api-reference/risks-insight/get-risk-calculations get /entities/{entityId}/insights/risks Risk indicators (concentration, foreign-currency exposure, cash-transaction share, insolvency, tax compliance, etc.) computed from the entity's invoicing, payments, and tax-filing data. # RPC Shareholders Insight Source: https://docs.syntage.com/api-reference/rpc-shareholders-insight/get-rpc-shareholders-beta get /entities/{entityId}/insights/rpc-shareholders **Deprecated:** Use [Get Shareholders](/api-reference/shareholders-insight/get-shareholders) instead. Shareholder information is obtained from the Registro Público de Comercio (RPC) and, when available for the entity, from Company Verification reports. When at least one shareholder for the entity has been ingested from a Company Verification report, the response returns only the Company Verification-sourced shareholders, and ownership percentages reflect the values recorded on the verification report. Otherwise, the response falls back to RPC-sourced shareholders, with percentages computed from share counts. Please be aware of the following limitations: - Not all companies are included in the RPC data source. - While some companies are listed in RPC, their shareholder information may not be available. - RPC data only includes initial shareholders and does not reflect changes in the shareholder structure, such as new or removed shareholders. Use Company Verification reports to get an up-to-date cap table. > [!WARNING] > > This endpoint is deprecated. Use [Shareholders Insight](/api-reference/shareholders-insight/get-shareholders) instead. # Sales Revenue Insight Source: https://docs.syntage.com/api-reference/sales-revenue-insight/get-sales-revenue get /entities/{entityId}/insights/sales-revenue Money the entity has earned over time, aggregated from issued income invoices. # Scores Insight Source: https://docs.syntage.com/api-reference/scores-insight/get-scores get /entities/{entityId}/insights/metrics/scores Entity scores aggregated from every configured score source (Syntage Score and any third-party rating providers enabled for the organization). # Syntage Score Distribution Source: https://docs.syntage.com/api-reference/scores-insight/get-syntage-score-distribution get /insights/metrics/scores/syntage/distribution Get the distribution of current Syntage Score values across score buckets. # Shareholders Insight Source: https://docs.syntage.com/api-reference/shareholders-insight/get-shareholders get /entities/{entityId}/insights/shareholders Returns a paginated shareholder insight for an entity. Use `relations.relationType=shareholders` to list the entity's shareholders. Use `relations.relationType=shareholder_of` to list entities that this shareholder owns shares in. When `relations.relationType=shareholders` and Company Verification-sourced shareholder data is available, the response returns Company Verification-sourced shareholder rows from the entity's most recent report instead of older RPC-sourced rows. If a relation has both Company Verification and manual sources, manually entered values take precedence. If no Company Verification-sourced shareholders are available, the response returns the available shareholder relations from other sources such as RPC or manually entered data. This endpoint replaces the deprecated RPC Shareholders insight. > [!NOTE] > > To export this insight, use [Insight Export](/api-reference/insights/export-an-insight) with `shareholders` as the insight name and pass the relation type as `options[relations.relationType]`. # Summary Insight Source: https://docs.syntage.com/api-reference/summary-insight/get-summary get /entities/{entityId}/insights/summary Aggregated profile of the entity combining identity, economic activity, tax regimes, and headline figures from the latest annual tax return. # Trial Balance Insight Source: https://docs.syntage.com/api-reference/trial-balance-insight/get-trial-balance get /entities/{entityId}/insights/trial-balance Returns all trial balances accounts matching on the account catalogs. If not present it will be tagged/grouped as '000 - Undefined'. # Vendor Concentration Insight Source: https://docs.syntage.com/api-reference/vendor-concentration-insight/get-vendor-invoice-concentration get /entities/{entityId}/insights/supplier-concentration Returns the concentration of issued or received invoices by vendors. # Vendor Network Insight Source: https://docs.syntage.com/api-reference/vendor-network-insight/get-vendor-network-insight get /entities/{entityId}/insights/metrics/vendor-network Vendors the entity has purchased from, with invoiced totals and cancellation rates per counterparty. # Create webhook endpoint Source: https://docs.syntage.com/api-reference/webhook-endpoints/create-a-webhook-endpoint post /webhook-endpoints Create a webhook endpoint for your organization. Syntage delivers matching events to the endpoint URL using HTTPS `POST` requests. Delivery attempts are successful when your endpoint returns a `2xx` HTTP status code. A delivery that times out after 3 seconds, fails before Syntage receives a response, or returns a non-`2xx` status code is retried up to 4 times. # Delete webhook endpoint Source: https://docs.syntage.com/api-reference/webhook-endpoints/delete-a-webhook-endpoint delete /webhook-endpoints/{id} Delete a webhook endpoint so Syntage stops sending matching events to it. # List webhook endpoints Source: https://docs.syntage.com/api-reference/webhook-endpoints/list-all-webhook-endpoints get /webhook-endpoints List webhook endpoints configured for your organization. # Retrieve webhook endpoint Source: https://docs.syntage.com/api-reference/webhook-endpoints/retrieve-a-webhook-endpoint get /webhook-endpoints/{id} Get a webhook endpoint by ID. # Update webhook endpoint Source: https://docs.syntage.com/api-reference/webhook-endpoints/update-an-webhook-endpoint put /webhook-endpoints/{id} Replace a webhook endpoint's URL, event subscriptions, enabled state, and content type. # List webhook requests Source: https://docs.syntage.com/api-reference/webhook-requests/list-all-webhook-requests get /webhook-requests List webhook delivery attempts for your organization. # Retrieve webhook request Source: https://docs.syntage.com/api-reference/webhook-requests/retrieve-a-webhook-request get /webhook-requests/{id} Get a webhook delivery attempt by ID. Use the response status code, response time, related event, and endpoint details to investigate delivery behavior. ### How to validate webhook calls by using the `signingSecret` value. Whenever a webhook is called, a `X-Satws-Signature` header is sent to help verify it. Syntage generates a signature using a hash-based message authentication code (HMAC) with SHA-256 using the `signingSecret` as key. To verify the hash you can do the following steps: #### Step 1: Extract the timestamp and signature from the header Split the header, using the ` , ` character as the separator. The value for the prefix `t` corresponds to the timestamp and `s` corresponds to the signature. #### Step 2: Prepare the signed_payload string The signed_payload string is created by concatenating (without spaces): - The timestamp (as a string in Unix format) example: `"1656569160"` - The character `.` (dot) - The actual JSON payload (that is, the request body) #### Step 3: Determine the expected signature Compute an HMAC with the SHA256 hash function. Use the endpoint’s signing secret as the key, and use the signed_payload string as the message. #### Step 4: Compare the signatures Compare the signature (or signatures) in the header to the expected signature. For an equality match, compute the difference between the current timestamp and the received timestamp, then decide if the difference is within your tolerance. To protect against timing attacks, use a constant-time string comparison to compare the expected signature to each of the received signatures. #### Here is a code example using PHP with a constant-time string: ```php function splitString(string $separator, $stringValue): array { return explode($separator, $stringValue); } ## X-Satws-Signature $xSatSignatureHeader = 't=1656569160,s=527124c570b27b3f268777b2ba96a9bbdc4b0ecde2885f688beda528f39c4e23'; list($timestamp, $signature) = array_map(function($signatureParam){ return splitString('=', $signatureParam)[1]; }, splitString(',', $xSatSignatureHeader)); $bodyPayload = '{ "@context": "/contexts/Event", "@id": "/events/88a88df8-5c55-44a4-a222-ef9999c999", "@type": "Event", "id": "88a88df8-5c55-44a4-a222-ef9999c999", "type": "credential.updated", "source": None, "createdAt": "2022-06-29 20:14:09", "updatedAt": "2022-06-29 20:14:09" }'; $signingSecret = '320639996d9eee9178bf89d26cdbc23d'; $hash = hash_hmac('sha256', sprintf('%d.%s', $timestamp, $bodyPayload), $signingSecret); print strcmp($hash, $signature); ``` # Changelog Source: https://docs.syntage.com/changelog Product and API updates for Syntage. Use the changelog that matches the kind of change you want to review. > **[Product](/product-changelog)** > > Dashboard, onboarding, workflow, and user-facing product changes. > **[API](/developer-changelog)** > > API behavior, endpoint, schema, and developer documentation changes. # API Changelog Source: https://docs.syntage.com/developer-changelog API updates, documentation changes, and integration-impacting changes **October 26, 2026** Extraction error codes The extraction error code reference now lists the codes assigned to new failed extractions and explains how to retry failed extractions. ### Extractions **Affected endpoints:** `GET /extractions`, `GET /extractions/{id}` * New failed extractions have the error code `unrecoverable`, `sat_unavailable`, `internal_error`, or `undefined`. `unrecoverable` means the extractor doesn't apply to the entity's type, and the extraction can't be retried. * `invalid_credentials`, `login_failed`, and `datasource_disabled` are no longer assigned to new extractions. They can still appear on older extractions. * An invalid credential doesn't fail an extraction. The extraction stays `waiting` until the credential is valid again, and then it resumes automatically. Use the `waiting` status instead of `invalid_credentials` to detect extractions blocked by a credential. * [Extractions](/resources/core/extractions#retrying-failed-extractions) now explains how to check Syntage Status for active incidents before retrying a failed extraction manually. **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.` 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](/api-reference/moratory-interest-insight/get-moratory-interest). * 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}' ``` # Product updates Source: https://docs.syntage.com/product-changelog Product updates, new datasources, dashboard improvements, and customer-facing workflow changes **June 25, 2026** Audited annual tax returns Syntage now supports audited annual tax returns, also known as declaraciones anuales dictaminadas, as a native source of financial information. A dictamen fiscal is the review and certification of a taxpayer's financial statements by a registered public accountant, filed with SAT through a separate channel from the standard annual tax return. From fiscal year 2022, audited annual tax returns are required for legal entities with accumulated income above about MXN 1.65 billion, updated annually, and for publicly traded companies. Other taxpayers can file them voluntarily. Financial statements are central to credit risk review. Even though only some companies file audited returns, those cases used to interrupt analysis. This integration makes audited annual return data available in the same Syntage workflows as the rest of the entity's information. ### Official audited return Download the official audited annual tax return submitted to SAT from the dashboard or the API. ![Audited annual tax return download available in a Syntage report](https://mintcdn.com/syntage/EcX5i46nqdZk1ibD/images/changelog/audited-annual-returns/official-return.png?fit=max\&auto=format\&n=EcX5i46nqdZk1ibD\&q=85\&s=953207476531c5ef66fc046f89950c50) ### Audited financial statements Balance sheet and income statement reports now use audited annual return data when it is available. ![Financial statement report populated from audited annual return data](https://mintcdn.com/syntage/EcX5i46nqdZk1ibD/images/changelog/audited-annual-returns/financial-statements.png?fit=max\&auto=format\&n=EcX5i46nqdZk1ibD\&q=85\&s=0247d9c9b883d0872f1c6071bf815077) ### Enriched insights Audited data also feeds summary insights, financial ratios, and risk indicators. When both standard and audited information are available for the same period, Syntage prioritizes the audited data. ### Fixes and improvements This release also includes smaller fixes and improvements across report review, insights, and extraction setup. * Financial statement reports now keep format controls available while data loads and use consistent accounting formatting for negative values. * Report tables no longer expand rows that only contain empty child rows, making dense reports easier to scan. * Company Verification insights now better prioritize Company Verification sources for shareholders and registered powers. * Scheduler tag matching and extractor filters now use clearer grouping and copy. * Buró reports now show clearer empty states when a bureau returns no data and keep available reports visible when the response includes usable data. **June 17, 2026** Buró Empresas insight redesign We redesigned the Buró Empresas insight so the most important credit report signals are available directly in the dashboard. You can now review a company's credit behavior without downloading PDFs or switching between tools. ![Buró Empresas insight overview with score, key indicators, charts, and account tables](https://mintcdn.com/syntage/EcX5i46nqdZk1ibD/images/changelog/buro-empresas/overview.png?fit=max\&auto=format\&n=EcX5i46nqdZk1ibD\&q=85\&s=89a6b86dc21cd2aa292e84ebe41537dc) ### Score PYME The new Score PYME section gives you the company's credit score, the score range, the model version used by Buró Empresas, and the reason codes behind the score. ![Score PYME summary card in the Buró Empresas insight](https://mintcdn.com/syntage/EcX5i46nqdZk1ibD/images/changelog/buro-empresas/score-pyme.png?fit=max\&auto=format\&n=EcX5i46nqdZk1ibD\&q=85\&s=d6f37971433797ae8d6397d0aba13018) ### Key indicators The insight now highlights total credit amount, current balance, last payment, and credit inquiry activity, so you can scan the most important signals before opening the full report. ![Key Buró Empresas credit indicators](https://mintcdn.com/syntage/EcX5i46nqdZk1ibD/images/changelog/buro-empresas/key-indicators.png?fit=max\&auto=format\&n=EcX5i46nqdZk1ibD\&q=85\&s=dc6e42965fbaf619d353e7918dbbe7a5) ### Portfolio rating Portfolio rating is now visualized over time, making delinquency and payment-behavior changes easier to review. ![Portfolio rating chart in the Buró Empresas insight](https://mintcdn.com/syntage/EcX5i46nqdZk1ibD/images/changelog/buro-empresas/portfolio-rating.png?fit=max\&auto=format\&n=EcX5i46nqdZk1ibD\&q=85\&s=78cfabbea6ab71a5cb09d803ca194b4d) ### Portfolio balances Balance charts now show how the credit portfolio changes across periods, including total balance and overdue balance. ![Portfolio balance chart in the Buró Empresas insight](https://mintcdn.com/syntage/EcX5i46nqdZk1ibD/images/changelog/buro-empresas/portfolio-balance.png?fit=max\&auto=format\&n=EcX5i46nqdZk1ibD\&q=85\&s=6ccb79db146c11988881b415b3b1db05) ### Credit accounts Credit accounts are split into Active and Paid tabs, with filters for credit type and delinquency status so you can move from summary signals into the account-level detail. ![Buró Empresas credit account table with filters](https://mintcdn.com/syntage/EcX5i46nqdZk1ibD/images/changelog/buro-empresas/accounts-table.png?fit=max\&auto=format\&n=EcX5i46nqdZk1ibD\&q=85\&s=c6af17fdfe678e50a258499cf4267f35) **June 11, 2026** Moratory Interest insight Added a Moratory Interest insight that detects when an entity is paying moratory interest to financial institutions. This gives you an early signal of financial stress that may appear in invoice data before it appears in credit bureau reports. * Shows the latest month, 3-month average, and 12-month accumulated moratory interest amounts. * Highlights recurrence when moratory interest appears in 3 or more of the last 6 months. * Breaks down the financial institutions charging moratory interest. * Adds the signal to risk indicators so affected entities can be flagged in monitoring workflows. See the [API changelog](/developer-changelog#june-17-2026) for the Moratory Interest API update. **June 10, 2026** Extraction and report workflow improvements Improved the workflows around refreshing data, reviewing reports, and understanding extraction activity. * Insights now surface an Update data action when the underlying data can be refreshed. * Extraction history now shows clearer source context, so you can tell why an extraction was created. * Entity assignment notifications are now available in the dashboard. * Datasource extraction settings are now easier to manage from the dashboard. * Insight reports now include an items-per-page selector for large reports. * Disabled users no longer appear as selectable entity owners. * Maintenance settings remain available when a subscription is inactive. **May 28, 2026** Onboarding and report usability improvements Improved onboarding feedback and several report review states. * Entity onboarding now shows clearer errors for invalid RFC values. * Portable e.firma onboarding now shows clearer status and unsupported-credential messages. * Invalid onboarding links now open a not-found state instead of a broken flow. * Unsupported SMS phone numbers now show a direct error message during setup. * Buró de Crédito Reports were redesigned with clearer report summaries, balance charts, and timeline details. * Scrollable tables now center empty states and preserve your row expansion choices more consistently. **May 19, 2026** Improved entity creation and data refresh Updated the experience for adding entities and refreshing entity data with a unified modal across the product. * The same modal is now used when adding a new entity or updating an existing one. * You can select multiple datasources and create the needed extractions in a single action. * The flow is consistent regardless of where it is opened from in the product. **May 8, 2026** Entity setup and integration settings improvements Updated several setup flows to make entity creation, integration settings, and extraction limits easier to understand. * The dashboard can now request Buró and shareholder reports directly from the data refresh flow. * Buró de Crédito and Buró Empresas integration settings were split into clearer configuration areas. * Entity setup now uses clearer RFC and CURP field guidance. * Extraction-limit messaging now explains when a selected action has an additional cost or cannot run. * Webhook setup now shows private-network URL errors inline. * Onboarding links are easier to find from the dashboard. **April 30, 2026** Extraction and report reliability improvements Improved extraction creation, report exports, and insight reliability for larger workflows. * You can now create multiple extractors for an entity in one action when refreshing data. * Report exports now keep historical data visible while a new extraction is waiting. * PDF exports now handle table height and empty-row behavior more consistently. * Excel exports now preserve date columns in a format spreadsheet tools can recognize. * Background Check and Infonavit can now be preselected in onboarding when they are part of the requested setup. * Credit bureau authorization text now adapts for SOFOM organizations. **April 23, 2026** Fiscal compliance omissions Improved how SAT tax compliance omissions are shown in the product, so you can assess an entity's fiscal compliance risk without opening the source PDF. * Surfaces the number and persistence of omissions more clearly. * Makes it easier to distinguish isolated omissions from repeated compliance issues. * Helps credit and risk teams review the tax compliance signal directly in the dashboard. **March 31, 2026** March insight and datasource improvements Improved financial statements, datasource presentation, and several risk signals in the dashboard. * Financial statement insights now include audited-format support and a segmented format control. * Tax-compliance risk indicators now include omission count and threshold details. * Infonavit copy and labels were updated to use Créditos Firmes terminology. * Infonavit risk cards now include clearer context and links to supporting details. * RPC, Background Checks, and Shareholders were removed from beta labeling. * Entity creation now shows a friendlier error when something unexpected prevents creation. **March 19, 2026** Infonavit Créditos Firmes data source Added Infonavit Créditos Firmes as a data source. Syntage can now identify when an entity appears in public Infonavit lists for employers with firm housing-credit obligations. * Helps identify overdue Infonavit obligations without manual searches. * Adds another public-source signal for risk and monitoring workflows. * Makes Infonavit findings available alongside the rest of the entity's data. **February 27, 2026** Entity list and notification improvements Improved how teams filter entities, review datasource status, and manage dashboard notifications. * Entity lists now include datasource and owner filters. * Admins now see owner information in entity lists more consistently. * Dashboard notifications now include dismiss-all support. * Extraction notifications no longer show a redundant View entity action when you are already viewing that entity. * Tax Retention extractions now support date-range filtering. * Buró de Crédito dashboards now include clearer physical-person and legal-person views. * Tax return views now show SIPRED dictaminados downloads when available. **January 5, 2026** Company Verification act and assembly index Company Verification Reports now include an index of acts and assemblies registered in SIGER, giving reviewers a consolidated inventory of company documents and changes. * Shows registered acts and assemblies in one place. * Helps reviewers validate that corporate-history reviews include the relevant documents. * Includes document detail used to review corporate purpose, duration, capital, shareholders, administrators, and powers.