> ## Documentation Index > Fetch the complete documentation index at: https://docs.syntage.com/llms.txt > Use this file to discover all available pages before exploring further. # Create an extraction > 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. ## OpenAPI ````yaml post /extractions openapi: 3.0.2 info: version: '2020-06-28' title: Syntage API contact: name: Email email: support@syntage.com description: > # Introduction The Syntage API is organized around [REST](https://en.wikipedia.org/wiki/Representational_State_Transfer). Our API has predictable resource-oriented URLs, accepts form-encoded request bodies, returns [JSON-LD](https://json-ld.org) responses, and uses standard HTTP response codes, authentication, and verbs. # Environments | Name | Description | Base URL | |------|-------------|----------| | **Sandbox** | The Sandbox environment is dedicated to development and testing. In this environment, no real taxpayer credentials are required and all interaction with the SAT is simulated generating life-like data, allowing you to pull test data from all endpoints. | https://api.sandbox.syntage.com | | **Production** | The Production environment is dedicated to live applications with real connections to the SAT. In this environment, real taxpayer credentials are required, and you will pull real fiscal data directly from the SAT. | https://api.syntage.com | Each environment has a different API Key for [authentication](#section/Authentication). # Request IDs Each API request has an associated request identifier. You can find this value in the response headers, under `X-Request-ID`: ```curl curl -i https://api.syntage.com HTTP/1.1 200 OK Date: Sun, 29 Nov 2020 19:21:21 GMT X-Request-ID: Root=1-6532dcae-169bf139354cd48959f55c55 ``` If you need to contact us about a specific request, providing the request identifier will ensure the fastest possible resolution. # Rate Limiting Our API employs a number of safeguards against bursts of incoming traffic to help maximize its stability. The returned HTTP headers of any API request show your current rate limit status: ```curl curl -i https://api.syntage.com 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. | If you exceed the rate limit, a [429 Too Many Requests](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/429) response is returned: ```http 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 ``` We may reduce limits to prevent abuse, or increase limits to enable high-traffic operations. You can check your current limits in the [dashboard](https://app.syntage.com/settings/usage). To request an increased rate limit, please [contact support](https://support.syntage.com/). # Pagination When issuing a GET request on a collection containing more than 1 page (e.g. [/events](#operation/ListEvent)), a collection is returned. Links to the first, the last, previous and the next page in the collection are displayed as well as the number of total items in the collection. All endpoints that support this operation have a query parameter defined by: - `itemsPerPage` The number of items per page (default: 20, max: 1000) - `page` The collection page number ```bash "hydra:totalItems": 1, "hydra:view": { "@id": "/events?page=1", "@type": "hydra:PartialCollectionView", "hydra:first": "/events?page=1", "hydra:next": "/events?page=2", "hydra:last": "/events?page=3" }, ``` ## Cursor Pagination Cursor pagination is a technique used for navigating through large datasets efficiently. It allows you to retrieve a specific subset of results from a collection by using a cursor value that represents the position within the collection. The cursor serves as a reference point for fetching the next or previous set of results. ### Benefits of Cursor Pagination: 1. **Efficient Navigation:** Cursor pagination eliminates the need to fetch the entire dataset at once, making it more scalable and faster. You can retrieve data in smaller, manageable chunks based on the cursor values. 2. **Consistent Results:** Each page of results in cursor pagination is stable and doesn't change even if new items are added or removed from the collection. This ensures that you get consistent and reliable results. 3. **Flexibility:** Cursors can be used to navigate forwards and backwards in the collection without impacting performance. ### How to Use Cursor Pagination: To use cursor pagination with our API, follow these instructions: 1. Make a request to retrieve the initial page of results. The response will be a JSON-LD document that includes a `hydra:next` attribute with the URI for the next page. The URI already includes the cursor attribute. 2. To retrieve the next page of results, make a GET request to the URI provided in the `hydra:next` attribute. This URI will automatically include the cursor value for the next page. 3. If you want to navigate to the previous page, you can use the `hydra:previous` attribute in the JSON-LD response. It will contain the URI for the previous page, including the cursor value. 4. You can continue making requests to the `hydra:next` and `hydra:previous` URIs to navigate through the paginated results, based on your requirements. Make sure to update your request headers to include the necessary headers for JSON-LD content negotiation, such as `Accept: application/ld+json` or `Content-Type: application/ld+json`. By following these instructions, you can effectively navigate through the paginated results using the cursor values provided in the `hydra:next` and `hydra:previous` attributes, without the need to manually include the cursor in your requests. This simplifies the pagination process and enhances the usability of our API. ### Considerations About Cursor Pagination: - By default, the API uses offset-based pagination (except for a few endpoints that we will list below). If you want to switch to cursor pagination, you need to include an additional header in your request. Set the `X-Pagination-Style` header with the value `"cursor"` to enable cursor pagination. If not specified, the API will assume offset-based pagination. - After enabling cursor pagination, the API response will no longer include the `hydra:totalItems` field by default. Retrieving the total count can be resource intensive and impact response times, especially for large datasets. However, if you need the `hydra:totalItems` information, you can include an additional header in your request. Set the `X-Pagination-Enable-Partial` header with the value `0` to indicate that the response should include extra information, including the `hydra:totalItems` count. Please be aware that enabling this feature may impact API response times, as the backend needs to perform a count operation on the dataset. If you require the `hydra:totalItems` count, please consider the potential impact on API response times. ### Example ```bash 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' \ --header 'X-Pagination-Enable-Partial: 0' ``` **Note:** We only support cursor pagination for the following endpoints: - `GET /entities/{entityId}/invoices` - `GET /entities/{entityId}/invoices/line-items` - `GET /entities/{entityId}/invoices/{invoiceId}/line-items` - `GET /invoices/{invoiceId}/line-items` - `GET /entities/{entityId}/invoices/payments` Feel free to reach out if you have any further questions or need additional assistance! # Property Filtering The property filter adds the possibility to select the properties for GET operations. Syntax: `?properties[]=&properties[][]=` You can add as many properties as you need. The following example shows how to select `paymentType` and `issuer.rfc` when fetching a list of invoices. ```curl curl -i https://api.syntage.com/entities/{entityId}/invoices?properties[]=paymentType&properties[issuer]=rfc ``` # 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. # API Versioning Guide Guidance on changes between versions. ## Version: 2020-01-01 to 2020-06-28 ### **Invoice** _**Affected Endpoints:** `GET /invoices/{id}` and `GET /entities/{entityId}/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 `/entities/{entityId}/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}`. ### **Entity (Formerly Link)** _**Affected Endpoint:** `GET /entities`_ - Filtering entities by `status` is removed. Use `credential.status` instead. For example, utilize `GET /entities?credential.status[]=active` instead of `GET /entities?status[]=active`. ### **Tax Return** _**Affected Endpoints:** `GET /tax-returns/{id}` and `GET /entities/{entityId}/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 mentioned endpoint. To find a tax return using its `operationNumber`, filter the collection at `/entities/{entityId}/tax-returns?operationNumber[]={operationNumber}`. - Previously, the `@iri` property for a tax return pointed to the resource using `operationNumber`, like `/tax-returns/{operationNumber}`. Now, it directs to its `id`, like `/tax-returns/{id}`. ### **Event** _**Affected Endpoints:** `GET /events` and `GET /events/{id}`_ - For events associated to an `tax-return`, the `@iri` property now directs to `/tax-returns/{id}` instead of the previous `/tax-returns/{operationNumber}`. - For events associated to an `invoice`, the `@iri` property now directs to `/invoices/{id}` instead of the previous `/invoices/{uuid}`. ### **Extraction** _**Affected Endpoints:** `GET /extractions` and `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 an `tax-return`, the `@iri` property now directs to `/tax-returns/{id}`, instead of the previous `/tax-returns/{operationNumber}`. - For files associated to an `invoice`, the `@iri` property now directs to `/invoices/{id}`, instead of the previous `/invoices/{uuid}`. ### Trying Out This Version If you want to test this version, you can do so by making any request with the `Accept-Version` header pointing to the latest version: ```curl curl -i 'https://api.syntage.com/entities/{entityId}/invoices' \ --header 'Accept-Version: 2020-06-28' \ --header 'X-Api-Key: {apiKey}' ``` servers: - url: https://api.syntage.com description: Production - url: https://api.sandbox.syntage.com description: Sandbox security: - ApiKey: [] tags: - name: Events description: > 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. Use the Events endpoints to retrieve recent events directly. Use [webhooks](/api-reference/webhooks/overview) when you want Syntage to deliver events to your server automatically. Access to events is only guaranteed for 7 days. Entity lifecycle events still use the `link.*` event type names for backwards compatibility. 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` | - name: Exports description: > Export invoices data in csv or xlsx format. Once you requested an export you will receive an email with a link to download the generated file - name: Files description: | Files associated to resources - name: DS MX SAT Credentials - name: DS MX SAT Certificates - name: Entities description: > An Entity is a resource that represents a person or company. Entities can be added via Add Entity, or automatically when a credential is validated (when the status becomes "valid"). This resource controls your access to data and allows you to create new extractions. When an Entity is deleted, all data related to the entity is deleted as well. - name: Extractions description: > 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, BIL 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. Create an extraction with the entity IRI, extractor name, and extractor 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 the same extraction is already pending or running for the same entity, extractor, and options, Syntage returns a duplicate extraction response instead of starting the same work again. ## Options Options containing a period (`.`) in the name like `period.from` are a way to denote object paths. For example, `period.from` should actually be sent as: ```json { "options": { "period": { "from": "2020-01-01", "to": "2020-12-31" } } } ``` Extractor names and options are specific to the data you are extracting. For extraction-backed resources, use the resource overview page for the extractor name, required credentials, supported options, and the endpoint where the extracted records can be read. # Extraction status | Status | Description | | ------ | ----------- | | pending | The initial extraction status. The extraction is enqueued and waiting to be processed. | | waiting | The extraction does not meet the requirements to begin. | | running | The extraction process started and is currently running. The running time varies depending on the extractor type and the entity's transactional volume. You may find partial data available in our API endpoints during this time. | | finished | The extraction finished successfully. All data is available to be retrieved from our API 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 in our API endpoints, but new extractions should be created to ensure all the entity's data is available. You can check the [extraction error code](#section/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 | | ---- | ----------- | --------- | | invalid_credentials | The SAT [Credential](#tag/Credentials) is no longer valid. | No | | login_failed | We couldn't log in with the SAT credential. | Yes | | unrecoverable | The extraction process failed many times, and we reached a maximum number of retries. | Yes | | 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 | - name: DS MX SAT Invoices description: > 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 endpoint when you need the XML or PDF content for a specific invoice. ### Blacklist status The field `issuer.blacklistStatus` or `receiver.blacklistStatus` is set while the invoice issuer or receiver RFC appears in a current [SAT 69-B publication source](https://www.sat.gob.mx/minisitio/DatosAbiertos/contribuyentes_publicados.html). It is `null` when the RFC is absent from all current sources, even if the RFC appeared in an earlier publication: | 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 | - name: DS MX SAT Invoice Line Items - name: DS MX SAT Invoice Relations description: > 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. - name: DS MX SAT Tax Retentions - name: DS MX SAT Credit Notes - name: DS MX RPC Entidades description: > RPC entidades are company records extracted from the Registro Publico de Comercio. They group registration profile data, related registry acts, and shareholder records found for an entity. - name: DS MX RPC Actos description: > RPC actos are commercial registry acts associated with an RPC entidade. They can include extracted act data and file references for registry documents. - name: DS MX RPC Socios description: | RPC socios are shareholder or partner records found in RPC filings. - name: Scheduler Rules - name: Schedulers - name: DS MX SAT Invoice Batch Payments description: > Batch payments are derived from payment receipt CFDIs, also known as type `P` invoices. A batch payment groups one or more 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. - name: DS MX SAT Invoice Payments description: > 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 and the invoice it was applied to. Syntage updates the related invoice's `paidAmount`, `dueAmount`, and `fullyPaidAt` fields based on the received payments. - name: DS MX SAT Electronic Accounting - name: DS MX SAT Tax Returns - name: DS MX SAT Tax Compliance Checks description: > 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 | - name: DS MX SAT Tax Status - name: Cash Flow Insight - name: Balance Sheet Insight - name: Income Statement Insight - name: Invoicing Concentration Insight - name: Customer Concentration Insight - name: Vendor Concentration Insight - name: Employees Insight - name: Expenditures Insight - name: Financial Institutions Insight - name: Financial Ratios Insight - name: Government Customers Insight - name: Invoicing Blacklist Insight - name: Risks Insight - name: Sales Revenue Insight - name: Summary Insight - name: Trial Balance Insight - name: Shareholders Insight - name: RPC Shareholders Insight - name: Customer Network Insight - name: Vendor Network Insight - name: Invoicing Annual Comparison Insight - name: Scores Insight - name: Insight Exports description: | Insight exports return supported entity insights as CSV or XLSX files. - name: Reports description: > Reports group entity insights into a configurable layout. A report is rendered in the dashboard's Reports section and can be downloaded as a PDF document with the [Exports API](/api-reference/exports/export-data). Built-in reports are created and kept up to date by Syntage and cannot be modified or deleted. Custom reports are personal by default; organizational reports are shared with every user in the organization. - name: Webhook Endpoints description: > Webhook endpoints tell Syntage where to deliver events for your organization. Each endpoint includes the HTTPS delivery URL, subscribed event types, enabled state, payload content type, and signing secret. - name: Webhook Requests description: > Webhook requests are delivery attempts from Syntage to a webhook endpoint. Use them to monitor delivery status, inspect failed deliveries, and connect an event to the endpoint that received it. - name: DS Syntage Score description: > Syntage Score calculates an internal score for a company entity from SAT annual tax return data and tax compliance data. - name: DS MX RUG Operaciones description: > RUG operations are registry acts associated with a movable collateral guarantee. They include operation metadata, guarantee numbers, grantors, parsed boleta data, and file references when available. - name: DS MX RUG Garantias description: > RUG guarantees are movable collateral guarantees registered in Mexico's Registro Unico de Garantias Mobiliarias. - name: DS MX Buró de Crédito Reports description: > Buró de Crédito reports contain credit bureau data generated for an entity by the `buro_de_credito_report` extractor. Reports include the selected product type, provider report ID, parsed provider response, score when available, and generated files such as the report PDF. - name: DS MX Buró de Crédito Authorizations description: > Buró de Crédito authorizations store the consent, RFC, address, and identity data required before Syntage can request Buró de Crédito reports for an entity. - name: Background Checks description: > Background checks provide comprehensive verification and screening data for entities. These checks gather information from various databases and sources to assess risk, verify identity, and provide insights into an entity's background across multiple categories. ### Check Categories Background checks are organized into specific categories: - **personal_identity**: Identity verification and personal information - **criminal_record**: Criminal background and legal history - **legal_background**: Legal proceedings and court records - **business_background**: Business registration and commercial activity - **professional_background**: Professional licenses and certifications - **credit_history**: Credit and financial history - **taxes_and_finances**: Tax compliance and financial records - **affiliations_and_insurances**: Professional affiliations and insurance records - **driving_licenses**: Driving licenses and vehicle permits - **vehicle_information**: Vehicle ownership and registration - **traffic_fines**: Traffic violations and fines - **alert_in_media**: Media mentions and public records - **behavior**: Behavioral patterns and risk indicators - **international_background**: International records and verification - **politically_exposed_person**: PEP (Politically Exposed Person) screening - **document_validation**: Document authenticity verification ### Check Status - **pending**: Background check is being processed - **completed**: Background check has been completed successfully - **error**: Background check encountered an error during processing ### Supported Countries - **MX**: Mexico-specific background checks - **ALL**: International background checks across multiple countries - name: Company Verification Reports description: > Company Verification Reports provide verification of company details and supporting files extracted from trusted sources. Use these endpoints to retrieve reports for a specific entity, list all reports, or download the generated PDF report. - name: Shareholders description: > Shareholders represent individuals or entities that own shares in a company. This resource provides information about shareholders, their relationships with entities, and the sources of shareholder information. ### Shareholder Types - **physical**: Individual person shareholders - **legal**: Corporate entity shareholders - **unknown**: When the shareholder type cannot be determined ### Relation Types - **shareholders**: Indicates the entity's shareholders - **shareholder_of**: Indicates entities that this shareholder owns shares in ### Source Types - **manual**: Manually entered shareholder information - **rpc_socio**: Information sourced from RPC (Registro Público de Comercio) - **company_verification**: Cap-table shareholders synced from a company verification report - name: DS MX Infonavit Overdue Credits description: > Infonavit overdue credits are employer registrations found in the Infonavit Créditos Firmes list of firm (overdue) housing-credit obligations, matched to an entity by name by the `infonavit` extractor. Records include the employer registration number (NRP), reported state, credit count, and publication dates. paths: /extractions: post: tags: - Extractions summary: Create an extraction description: > 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. operationId: CreateExtraction requestBody: $ref: '#/components/requestBodies/ExtractionCreate' responses: '202': $ref: '#/components/responses/Extraction' '400': $ref: '#/components/responses/ConstraintViolation' '401': $ref: '#/components/responses/Unauthorized' '409': $ref: '#/components/responses/DuplicateExtraction' x-codeSamples: - lang: bash label: Invoice source: >- curl --request POST 'https://api.syntage.com/extractions' --header 'Content-Type: application/json' --header 'X-API-Key: YOUR_API_KEY' --data '{"entity":"/entities/7b3a25a9-a53a-4846-abe6-f2574c9c2d5d","extractor":"invoice","options":{"period":{"from":"2024-01-01","to":"2024-12-31"},"types":["I","E","P"],"issued":true,"received":true,"pdf":true,"xml":true}}' - lang: bash label: Tax retention source: >- curl --request POST 'https://api.syntage.com/extractions' --header 'Content-Type: application/json' --header 'X-API-Key: YOUR_API_KEY' --data '{"entity":"/entities/7b3a25a9-a53a-4846-abe6-f2574c9c2d5d","extractor":"tax_retention","options":{"period":{"from":"2024-01-01","to":"2024-12-31"},"issued":true,"received":true}}' - lang: bash label: Annual tax return source: >- curl --request POST 'https://api.syntage.com/extractions' --header 'Content-Type: application/json' --header 'X-API-Key: YOUR_API_KEY' --data '{"entity":"/entities/7b3a25a9-a53a-4846-abe6-f2574c9c2d5d","extractor":"annual_tax_return","options":{"period":{"from":"2020-01-01","to":"2024-12-31"}}}' - lang: bash label: Monthly tax return source: >- curl --request POST 'https://api.syntage.com/extractions' --header 'Content-Type: application/json' --header 'X-API-Key: YOUR_API_KEY' --data '{"entity":"/entities/7b3a25a9-a53a-4846-abe6-f2574c9c2d5d","extractor":"monthly_tax_return","options":{"period":{"from":"2024-01-01","to":"2024-12-31"}}}' - lang: bash label: RIF tax return source: >- curl --request POST 'https://api.syntage.com/extractions' --header 'Content-Type: application/json' --header 'X-API-Key: YOUR_API_KEY' --data '{"entity":"/entities/7b3a25a9-a53a-4846-abe6-f2574c9c2d5d","extractor":"rif_tax_return","options":{"period":{"from":"2024-01-01","to":"2024-12-31"}}}' - lang: bash label: Electronic accounting source: >- curl --request POST 'https://api.syntage.com/extractions' --header 'Content-Type: application/json' --header 'X-API-Key: YOUR_API_KEY' --data '{"entity":"/entities/7b3a25a9-a53a-4846-abe6-f2574c9c2d5d","extractor":"electronic_accounting","options":{"period":{"from":"2023-01-01","to":"2024-12-31"}}}' - lang: bash label: RPC source: >- curl --request POST 'https://api.syntage.com/extractions' --header 'Content-Type: application/json' --header 'X-API-Key: YOUR_API_KEY' --data '{"entity":"/entities/91106968-1abd-4d64-85c1-4e73d96fb997","extractor":"rpc","options":{"nameThreshold":0.9,"nameLimit":25}}' - lang: bash label: Buró de Crédito report source: >- curl --request POST 'https://api.syntage.com/extractions' --header 'Content-Type: application/json' --header 'X-API-Key: YOUR_API_KEY' --data '{"entity":"/entities/91106968-1abd-4d64-85c1-4e73d96fb997","extractor":"buro_de_credito_report","options":{"productType":"INFORME_BURO"}}' - lang: bash label: Tax status source: >- curl --request POST 'https://api.syntage.com/extractions' --header 'Content-Type: application/json' --header 'X-API-Key: YOUR_API_KEY' --data '{"entity":"/entities/7b3a25a9-a53a-4846-abe6-f2574c9c2d5d","extractor":"tax_status"}' - lang: bash label: Tax compliance source: >- curl --request POST 'https://api.syntage.com/extractions' --header 'Content-Type: application/json' --header 'X-API-Key: YOUR_API_KEY' --data '{"entity":"/entities/7b3a25a9-a53a-4846-abe6-f2574c9c2d5d","extractor":"tax_compliance"}' - lang: bash label: SAT certificates source: >- curl --request POST 'https://api.syntage.com/extractions' --header 'Content-Type: application/json' --header 'X-API-Key: YOUR_API_KEY' --data '{"entity":"/entities/7b3a25a9-a53a-4846-abe6-f2574c9c2d5d","extractor":"sat_certificates"}' - lang: bash label: BIL source: >- curl --request POST 'https://api.syntage.com/extractions' --header 'Content-Type: application/json' --header 'X-API-Key: YOUR_API_KEY' --data '{"entity":"/entities/91106968-1abd-4d64-85c1-4e73d96fb997","extractor":"bil"}' - lang: bash label: RUG source: >- curl --request POST 'https://api.syntage.com/extractions' --header 'Content-Type: application/json' --header 'X-API-Key: YOUR_API_KEY' --data '{"entity":"/entities/91106968-1abd-4d64-85c1-4e73d96fb997","extractor":"rug"}' - lang: bash label: Background Check source: >- curl --request POST 'https://api.syntage.com/extractions' --header 'Content-Type: application/json' --header 'X-API-Key: YOUR_API_KEY' --data '{"entity":"/entities/91106968-1abd-4d64-85c1-4e73d96fb997","extractor":"background_check"}' - lang: bash label: Infonavit source: >- curl --request POST 'https://api.syntage.com/extractions' --header 'Content-Type: application/json' --header 'X-API-Key: YOUR_API_KEY' --data '{"entity":"/entities/91106968-1abd-4d64-85c1-4e73d96fb997","extractor":"infonavit"}' components: requestBodies: ExtractionCreate: required: true content: application/json: schema: $ref: '#/components/schemas/ExtractionRequest' responses: Extraction: description: Extraction resource response content: application/ld+json: schema: allOf: - type: object properties: '@context': type: string default: /contexts/Extraction - $ref: '#/components/schemas/Extraction' ConstraintViolation: description: Validation error content: application/ld+json: schema: type: object properties: '@context': type: string default: /contexts/ConstraintViolation '@type': type: string default: ConstraintViolation hydra:title: type: string default: An error occurred hydra:description: type: string description: Concatenated violation messages example: 'exampleField: This value should not be blank.' violations: type: array items: type: object properties: propertyPath: type: string description: Property access path example: exampleField message: type: string description: Validaton error message example: This value should not be blank. code: type: string nullable: true description: Machine-readable validation code when available example: rfc_valid_no_name_on_file Unauthorized: description: Unauthorized content: application/json: schema: type: object properties: message: type: string DuplicateExtraction: description: > One or more requested extractions are already `pending` or `running` for the same entity, extractor, and options. The response lists the extractors whose equivalent extraction is already in progress; remove them before retrying the request. content: application/ld+json: schema: type: object required: - conflictingExtractors properties: conflictingExtractors: type: array description: Extractors whose equivalent extraction is already in progress. minItems: 1 uniqueItems: true items: $ref: '#/components/schemas/ExtractionExtractor' schemas: ExtractionRequest: oneOf: - $ref: '#/components/schemas/InvoiceExtractionRequest' - $ref: '#/components/schemas/TaxRetentionExtractionRequest' - $ref: '#/components/schemas/AnnualTaxReturnExtractionRequest' - $ref: '#/components/schemas/MonthlyTaxReturnExtractionRequest' - $ref: '#/components/schemas/RifTaxReturnExtractionRequest' - $ref: '#/components/schemas/ElectronicAccountingExtractionRequest' - $ref: '#/components/schemas/RpcExtractionRequest' - $ref: '#/components/schemas/BuroDeCreditoReportExtractionRequest' - $ref: '#/components/schemas/TaxStatusExtractionRequest' - $ref: '#/components/schemas/TaxComplianceExtractionRequest' - $ref: '#/components/schemas/SatCertificatesExtractionRequest' - $ref: '#/components/schemas/BilExtractionRequest' - $ref: '#/components/schemas/RugExtractionRequest' - $ref: '#/components/schemas/BackgroundCheckExtractionRequest' - $ref: '#/components/schemas/InfonavitExtractionRequest' discriminator: propertyName: extractor mapping: invoice: '#/components/schemas/InvoiceExtractionRequest' tax_retention: '#/components/schemas/TaxRetentionExtractionRequest' annual_tax_return: '#/components/schemas/AnnualTaxReturnExtractionRequest' monthly_tax_return: '#/components/schemas/MonthlyTaxReturnExtractionRequest' rif_tax_return: '#/components/schemas/RifTaxReturnExtractionRequest' electronic_accounting: '#/components/schemas/ElectronicAccountingExtractionRequest' rpc: '#/components/schemas/RpcExtractionRequest' buro_de_credito_report: '#/components/schemas/BuroDeCreditoReportExtractionRequest' tax_status: '#/components/schemas/TaxStatusExtractionRequest' tax_compliance: '#/components/schemas/TaxComplianceExtractionRequest' sat_certificates: '#/components/schemas/SatCertificatesExtractionRequest' bil: '#/components/schemas/BilExtractionRequest' rug: '#/components/schemas/RugExtractionRequest' background_check: '#/components/schemas/BackgroundCheckExtractionRequest' infonavit: '#/components/schemas/InfonavitExtractionRequest' Extraction: type: object properties: '@id': type: string format: iri-reference description: Extraction IRI reference example: /extractions/91106968-1abd-4d64-85c1-4e73d96fb997 '@type': type: string description: JSON-LD resource type default: Extraction id: type: string format: uuid description: Unique extraction ID example: 91106968-1abd-4d64-85c1-4e73d96fb997 taxpayer: $ref: '#/components/schemas/Taxpayer' extractor: $ref: '#/components/schemas/ExtractionExtractor' options: $ref: '#/components/schemas/ExtractionOptions' status: $ref: '#/components/schemas/ExtractionStatus' startedAt: type: string format: date-time description: Time when the _status_ changed from **pending** to **running** nullable: true finishedAt: type: string format: date-time description: >- Time when the _status_ changed from **running** to **finished** or **failed** nullable: true rateLimitedAt: $ref: '#/components/schemas/ExtractionRateLimitedAt' errorCode: $ref: '#/components/schemas/ExtractionErrorCode' createdDataPoints: $ref: '#/components/schemas/ExtractionCreatedDataPoints' updatedDataPoints: $ref: '#/components/schemas/ExtractionUpdatedDataPoints' createdAt: $ref: '#/components/schemas/createdAt' updatedAt: $ref: '#/components/schemas/updatedAt' ExtractionExtractor: type: string description: >- Extractor to run, which retrieves resources from the corresponding datasource enum: - invoice - monthly_tax_return - annual_tax_return - rif_tax_return - tax_status - tax_retention - tax_compliance - electronic_accounting - sat_certificates - rpc - buro_de_credito_report - bil - rug - background_check - infonavit InvoiceExtractionRequest: title: Invoice extraction allOf: - $ref: '#/components/schemas/ExtractionEntityTarget' - type: object required: - extractor properties: extractor: type: string enum: - invoice options: $ref: '#/components/schemas/InvoiceExtractionOptions' TaxRetentionExtractionRequest: title: Tax retention extraction allOf: - $ref: '#/components/schemas/ExtractionEntityTarget' - type: object required: - extractor properties: extractor: type: string enum: - tax_retention options: $ref: '#/components/schemas/TaxRetentionExtractionOptions' AnnualTaxReturnExtractionRequest: title: Annual tax return extraction allOf: - $ref: '#/components/schemas/ExtractionEntityTarget' - type: object required: - extractor properties: extractor: type: string enum: - annual_tax_return options: $ref: '#/components/schemas/AnnualTaxReturnExtractionOptions' MonthlyTaxReturnExtractionRequest: title: Monthly tax return extraction allOf: - $ref: '#/components/schemas/ExtractionEntityTarget' - type: object required: - extractor properties: extractor: type: string enum: - monthly_tax_return options: $ref: '#/components/schemas/MonthlyTaxReturnExtractionOptions' RifTaxReturnExtractionRequest: title: RIF tax return extraction allOf: - $ref: '#/components/schemas/ExtractionEntityTarget' - type: object required: - extractor properties: extractor: type: string enum: - rif_tax_return options: $ref: '#/components/schemas/RifTaxReturnExtractionOptions' ElectronicAccountingExtractionRequest: title: Electronic accounting extraction allOf: - $ref: '#/components/schemas/ExtractionEntityTarget' - type: object required: - extractor properties: extractor: type: string enum: - electronic_accounting options: $ref: '#/components/schemas/ElectronicAccountingExtractionOptions' RpcExtractionRequest: title: RPC extraction allOf: - $ref: '#/components/schemas/ExtractionEntityTarget' - type: object required: - extractor properties: extractor: type: string enum: - rpc options: $ref: '#/components/schemas/RpcExtractionOptions' BuroDeCreditoReportExtractionRequest: title: Buró de Crédito report extraction allOf: - $ref: '#/components/schemas/ExtractionEntityTarget' - type: object required: - extractor properties: extractor: type: string enum: - buro_de_credito_report options: $ref: '#/components/schemas/BuroDeCreditoReportExtractionOptions' TaxStatusExtractionRequest: title: Tax status extraction allOf: - $ref: '#/components/schemas/ExtractionEntityTarget' - type: object required: - extractor properties: extractor: type: string enum: - tax_status TaxComplianceExtractionRequest: title: Tax compliance extraction allOf: - $ref: '#/components/schemas/ExtractionEntityTarget' - type: object required: - extractor properties: extractor: type: string enum: - tax_compliance SatCertificatesExtractionRequest: title: SAT certificates extraction allOf: - $ref: '#/components/schemas/ExtractionEntityTarget' - type: object required: - extractor properties: extractor: type: string enum: - sat_certificates BilExtractionRequest: title: BIL extraction allOf: - $ref: '#/components/schemas/ExtractionEntityTarget' - type: object required: - extractor properties: extractor: type: string enum: - bil RugExtractionRequest: title: RUG extraction allOf: - $ref: '#/components/schemas/ExtractionEntityTarget' - type: object required: - extractor properties: extractor: type: string enum: - rug BackgroundCheckExtractionRequest: title: Background Check extraction allOf: - $ref: '#/components/schemas/ExtractionEntityTarget' - type: object required: - extractor properties: extractor: type: string enum: - background_check InfonavitExtractionRequest: title: Infonavit extraction allOf: - $ref: '#/components/schemas/ExtractionEntityTarget' - type: object required: - extractor properties: extractor: type: string enum: - infonavit Taxpayer: type: object properties: '@id': type: string format: iri-reference description: Taxpayer IRI reference example: /taxpayers/PEIC211118IS0 '@type': type: string default: Taxpayer id: $ref: '#/components/schemas/TaxpayerID' personType: $ref: '#/components/schemas/TaxpayerPersonType' registrationDate: type: string format: date description: Taxpayer registration date name: $ref: '#/components/schemas/TaxpayerName' ExtractionOptions: type: object description: >- Options are specific to the selected extractor. Select the schema matching the extractor; extractors not listed here do not accept options. anyOf: - $ref: '#/components/schemas/InvoiceExtractionOptions' - $ref: '#/components/schemas/TaxRetentionExtractionOptions' - $ref: '#/components/schemas/AnnualTaxReturnExtractionOptions' - $ref: '#/components/schemas/MonthlyTaxReturnExtractionOptions' - $ref: '#/components/schemas/RifTaxReturnExtractionOptions' - $ref: '#/components/schemas/ElectronicAccountingExtractionOptions' - $ref: '#/components/schemas/RpcExtractionOptions' - $ref: '#/components/schemas/BuroDeCreditoReportExtractionOptions' ExtractionStatus: type: string enum: - pending - waiting - running - finished - failed - stopping - stopped - cancelled ExtractionRateLimitedAt: type: string format: date-time description: > This field returns a date when the taxpayer reached the max amount of downloaded CFDI files allowed by SAT in a range of 24hrs. You should retry this extraction 24hrs later. If your taxpayer has not reached the max amount this value should be `NULL` example: '2019-01-03T21:10:40.000Z' ExtractionErrorCode: type: string description: | [Extraction error code](#section/Extraction-error-codes) nullable: true example: null enum: - invalid_credentials - login_failed - unrecoverable - sat_unavailable - internal_error - undefined ExtractionCreatedDataPoints: type: integer description: > This is the number of created resources. For example, if 1 invoice was created with its XML and PDF file this value should be 3. And If you previously extracted all the resources and there are no more resources to create this value is 0. example: 3 ExtractionUpdatedDataPoints: type: integer description: > When your taxpayer has resources by a previous extraction and new extraction found changes between our data and Sat data it would update this resource. For example, when a new extraction finds a Canceled invoice which you previously extracted as an Active invoice. example: 2 createdAt: type: string description: Date and time the resource was created example: '2020-01-01T12:15:00.000Z' updatedAt: type: string description: Date and time the resource was last updated example: '2020-01-01T12:15:00.000Z' ExtractionEntityTarget: title: Entity target type: object required: - entity properties: entity: type: string format: iri-reference description: Entity IRI reference example: /entities/7b3a25a9-a53a-4846-abe6-f2574c9c2d5d InvoiceExtractionOptions: title: Invoice extraction options type: object additionalProperties: false properties: period: $ref: '#/components/schemas/ExtractionPeriodOptions' types: type: array description: CFDI types to extract. Defaults to every supported type. minItems: 1 uniqueItems: true items: type: string enum: - I - E - P - 'N' - T example: - I - E - P issued: type: boolean description: Whether to extract CFDIs issued by the entity. default: true received: type: boolean description: Whether to extract CFDIs received by the entity. default: true complement: type: integer description: Complement filter passed to SAT. default: -1 pdf: type: boolean description: Whether to download PDF files. default: true xml: type: boolean description: Whether to download XML files. default: true TaxRetentionExtractionOptions: title: Tax retention extraction options type: object additionalProperties: false properties: period: $ref: '#/components/schemas/ExtractionPeriodOptions' issued: type: boolean description: Whether to extract tax retentions issued by the entity. default: true received: type: boolean description: Whether to extract tax retentions received by the entity. default: true complement: type: integer description: Complement filter passed to SAT. default: -1 AnnualTaxReturnExtractionOptions: title: Annual tax return extraction options type: object additionalProperties: false properties: period: $ref: '#/components/schemas/ExtractionPeriodOptions' files: type: object additionalProperties: false description: Tax return file types to download. properties: tax_return.ack_receipt: type: boolean description: Whether to download the filing acknowledgment receipt. default: true tax_return.transcript: type: boolean description: Whether to download the tax return transcript. default: true tax_return.payment_receipt: type: boolean description: Whether to download the payment receipt. default: true tax_return.financial_statements: type: boolean description: Whether to download financial statements. default: true tax_return.audited_financial_statements: type: boolean description: Whether to download audited financial statements. default: true MonthlyTaxReturnExtractionOptions: title: Monthly tax return extraction options type: object additionalProperties: false properties: period: $ref: '#/components/schemas/ExtractionPeriodOptions' files: type: object additionalProperties: false description: Tax return file types to download. properties: tax_return.ack_receipt: type: boolean description: Whether to download the filing acknowledgment receipt. default: true tax_return.transcript: type: boolean description: Whether to download the tax return transcript. default: true tax_return.payment_receipt: type: boolean description: Whether to download the payment receipt. default: true tax_return.financial_statements: type: boolean description: Whether to download financial statements. default: true RifTaxReturnExtractionOptions: title: RIF tax return extraction options type: object additionalProperties: false properties: period: $ref: '#/components/schemas/ExtractionPeriodOptions' ElectronicAccountingExtractionOptions: title: Electronic accounting extraction options type: object additionalProperties: false properties: period: $ref: '#/components/schemas/ExtractionPeriodOptions' RpcExtractionOptions: title: RPC extraction options type: object additionalProperties: false properties: nameThreshold: type: number format: float minimum: 0.75 maximum: 1 description: >- Minimum name similarity for matching RPC entities. Higher values require a closer match. When omitted, the RPC datasource uses its default threshold of 0.75. example: 0.9 nameLimit: type: integer minimum: 1 maximum: 100 description: >- Maximum number of matching RPC entities to return, ordered from most to least similar. When omitted, the RPC datasource uses its default page size. example: 25 BuroDeCreditoReportExtractionOptions: title: Buró de Crédito report extraction options type: object additionalProperties: false properties: productType: type: string description: >- Buró de Crédito product to request. Supported values depend on whether the entity is a person or company. When omitted, the organization's configured default applies. enum: - '007' - '004' - INFORME_BURO - RCO example: INFORME_BURO legalScoreCode: type: string description: >- Score code used for a company report. The only supported value is `012`. enum: - '012' default: '012' legalAmbiguity: type: string minLength: 1 description: >- Ambiguity indicator saved with the extraction and used for a company report. When omitted, the organization's configured legal ambiguity applies, falling back to `R` when unset. TaxpayerID: type: string minLength: 12 maxLength: 13 description: RFC (Registro Federal de Contribuyentes) example: PEIC211118IS0 TaxpayerPersonType: type: string enum: - physical - legal example: physical TaxpayerName: type: string minLength: 1 maxLength: 254 description: Taxpayer name example: Pedro Infante Cruz ExtractionPeriodOptions: title: Extraction period type: object additionalProperties: false properties: from: type: string description: >- Start of the extraction period. Accepts a date or relative date expression. Defaults to the start of the year three years ago. example: '2024-01-01' to: type: string description: >- End of the extraction period. Must be later than `from` and cannot be a future date. Defaults to the current date and time. example: '2024-12-31' securitySchemes: ApiKey: type: apiKey in: header name: X-API-Key description: > Your API key is available in the [Production](https://app.syntage.com/settings/api-keys) and [Sandbox](https://app.sandbox.syntage.com/settings/api-keys) dashboards. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.