openapi: 3.0.2
info:
version: '2020-06-28'
title: Syntage Accounts Payable Insight Background Checks API
contact:
name: Email
email: support@syntage.com
description: "# Introduction\n\nThe Syntage API is organized around [REST](https://en.wikipedia.org/wiki/Representational_State_Transfer).\nOur 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.\n\n# Environments\n\n| Name | Description | Base URL |\n|------|-------------|----------|\n| **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 |\n| **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 |\n\nEach environment has a different API Key for [authentication](#section/Authentication).\n\n# Request IDs\n\nEach API request has an associated request identifier.\nYou can find this value in the response headers, under `X-Request-ID`:\n\n```curl\ncurl -i https://api.syntage.com\nHTTP/1.1 200 OK\nDate: Sun, 29 Nov 2020 19:21:21 GMT\nX-Request-ID: Root=1-6532dcae-169bf139354cd48959f55c55\n```\n\nIf you need to contact us about a specific request, providing the request identifier will ensure the fastest possible resolution.\n\n# Rate Limiting\n\nOur API employs a number of safeguards against bursts of incoming traffic to help maximize its stability.\nThe returned HTTP headers of any API request show your current rate limit status:\n\n```curl\ncurl -i https://api.syntage.com\nHTTP/1.1 200 OK\nDate: Sun, 29 Nov 2020 19:21:21 GMT\nX-RateLimit-Limit: 60\nX-RateLimit-Remaining: 56\nX-RateLimit-Reset: 1606678044\n```\n\n| Header Name | Description |\n|-----------------------|------------------------------------------------------------------------------|\n| X-RateLimit-Limit | The maximum number of requests you're permitted to make. |\n| X-RateLimit-Remaining | The number of requests remaining in the current rate limit window. |\n| X-RateLimit-Reset | The time at which the current rate limit window resets in UTC epoch seconds. |\n\nIf you exceed the rate limit, a [429 Too Many Requests](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/429) response is returned:\n\n```http\nHTTP/1.1 429 Too Many Requests\nDate: Sun, 29 Nov 2020 19:21:21 GMT\nX-RateLimit-Limit: 60\nX-RateLimit-Remaining: 0\nX-RateLimit-Reset: 1606678044\n```\n\nWe may reduce limits to prevent abuse, or increase limits to enable high-traffic operations.\nYou can check your current limits in the [dashboard](https://app.syntage.com/settings/usage).\nTo request an increased rate limit, please [contact support](https://support.syntage.com/).\n# Pagination\nWhen 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.\nAll endpoints that support this operation have a query parameter defined by:\n - `itemsPerPage` The number of items per page (default: 20, max: 1000)\n - `page` The collection page number\n\n```bash\n \"hydra:totalItems\": 1,\n \"hydra:view\": {\n \"@id\": \"/events?page=1\",\n \"@type\": \"hydra:PartialCollectionView\",\n \"hydra:first\": \"/events?page=1\",\n \"hydra:next\": \"/events?page=2\",\n \"hydra:last\": \"/events?page=3\"\n },\n```\n## Cursor Pagination\nCursor 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.\n### Benefits of Cursor Pagination:\n1. **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.\n2. **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.\n3. **Flexibility:** Cursors can be used to navigate forwards and backwards in the collection without impacting performance.\n\n### How to Use Cursor Pagination:\nTo use cursor pagination with our API, follow these instructions:\n1. 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.\n2. 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.\n3. 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.\n4. You can continue making requests to the `hydra:next` and `hydra:previous` URIs to navigate through the paginated results, based on your requirements.\nMake 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`.\nBy 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.\n\n### Considerations About Cursor Pagination:\n\n - 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.\n\n - 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.\n\nIf you require the `hydra:totalItems` count, please consider the potential impact on API response times.\n### Example\n```bash\n curl -i 'https://api.syntage.com/entities/{entityId}/invoices?itemsPerPage=10' \\\n --header 'Accept: application/ld+json' \\\n --header 'X-Api-Key: {apiKey}' \\\n --header 'X-Pagination-Style: cursor' \\\n --header 'X-Pagination-Enable-Partial: 0'\n```\n**Note:** We only support cursor pagination for the following endpoints:\n - `GET /entities/{entityId}/invoices`\n - `GET /entities/{entityId}/invoices/line-items`\n - `GET /entities/{entityId}/invoices/{invoiceId}/line-items`\n - `GET /invoices/{invoiceId}/line-items`\n - `GET /entities/{entityId}/invoices/payments`\n\nFeel free to reach out if you have any further questions or need additional assistance!\n\n# Property Filtering\nThe property filter adds the possibility to select the properties for GET operations.\nSyntax: `?properties[]=<property>&properties[<relation>][]=<property>`\nYou 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.\n```curl\n curl -i https://api.syntage.com/entities/{entityId}/invoices?properties[]=paymentType&properties[issuer]=rfc\n```\n# Filtering\n**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.\n\n# API Versioning Guide\nGuidance on changes between versions.\n## Version: 2020-01-01 to 2020-06-28\n### **Invoice**\n_**Affected Endpoints:** `GET /invoices/{id}` and `GET /entities/{entityId}/invoices`_\n- The `amount` property has been removed from API responses. Use the `total` property instead.\n- 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}`.\n- 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}`.\n\n### **Entity (Formerly Link)**\n_**Affected Endpoint:** `GET /entities`_\n- Filtering entities by `status` is removed. Use `credential.status` instead. For example, utilize `GET /entities?credential.status[]=active` instead of `GET /entities?status[]=active`.\n\n### **Tax Return**\n_**Affected Endpoints:** `GET /tax-returns/{id}` and `GET /entities/{entityId}/tax-returns`_\n- 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}`.\n- 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}`.\n\n### **Event**\n_**Affected Endpoints:** `GET /events` and `GET /events/{id}`_\n- For events associated to an `tax-return`, the `@iri` property now directs to `/tax-returns/{id}` instead of the previous `/tax-returns/{operationNumber}`.\n- For events associated to an `invoice`, the `@iri` property now directs to `/invoices/{id}` instead of the previous `/invoices/{uuid}`.\n\n### **Extraction**\n_**Affected Endpoints:** `GET /extractions` and `GET /extractions/{id}`_\n- The `periodFrom` property has been removed. Use `options.period.from` instead.\n- The `periodTo` property has been removed. Use `options.period.to` instead.\n\n### **File**\n_**Affected Endpoint:** `GET /file/{id}`_\n- For files associated to an `tax-return`, the `@iri` property now directs to `/tax-returns/{id}`, instead of the previous `/tax-returns/{operationNumber}`.\n- For files associated to an `invoice`, the `@iri` property now directs to `/invoices/{id}`, instead of the previous `/invoices/{uuid}`.\n\n### Trying Out This Version\nIf you want to test this version, you can do so by making any request with the `Accept-Version` header pointing to the latest version:\n```curl\n curl -i 'https://api.syntage.com/entities/{entityId}/invoices' \\\n --header 'Accept-Version: 2020-06-28' \\\n --header 'X-Api-Key: {apiKey}'\n```\n"
servers:
- url: https://api.syntage.com
description: Production
- url: https://api.sandbox.syntage.com
description: Sandbox
security:
- ApiKey: []
tags:
- 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
'
paths:
/background-checks:
get:
tags:
- Background Checks
operationId: GetBackgroundChecks
summary: List background checks
description: 'Lists background checks available to the organization. Use filters to narrow the list by processing status, country scope, or score.
'
parameters:
- $ref: '#/components/parameters/collectionCursorNextPageParam'
- $ref: '#/components/parameters/collectionCursorPreviousPageParam'
- $ref: '#/components/parameters/collectionLimit'
- $ref: '#/components/parameters/backgroundCheckStatusFilter'
- $ref: '#/components/parameters/backgroundCheckCountryFilter'
- $ref: '#/components/parameters/orderScore'
- $ref: '#/components/parameters/orderCreatedAt'
- $ref: '#/components/parameters/orderUpdatedAt'
responses:
'200':
description: Background Checks
content:
application/ld+json:
schema:
type: object
allOf:
- $ref: '#/components/schemas/Collection'
- type: object
properties:
'@context':
default: /contexts/BackgroundCheck
'@id':
example: /background-checks
hydra:member:
type: array
items:
$ref: '#/components/schemas/BackgroundCheck'
'401':
$ref: '#/components/responses/Unauthorized'
/background-checks/{id}:
get:
tags:
- Background Checks
operationId: GetBackgroundCheck
summary: Retrieve a background check
description: 'Retrieves one background check, including its score, processing status, country scope, associated files, and links to related records.
'
parameters:
- $ref: '#/components/parameters/resourceId'
responses:
'200':
description: Background Check
content:
application/ld+json:
schema:
type: object
allOf:
- type: object
properties:
'@context':
default: /contexts/BackgroundCheck
'@id':
example: /background-checks/91ab5678-1234-5678-9abc-def012345678
- $ref: '#/components/schemas/BackgroundCheck'
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
/background-checks/{id}/pdf:
get:
tags:
- Background Checks
operationId: GetBackgroundCheckPdf
summary: Download background check PDF
description: 'Downloads the generated PDF report for a background check. The response body is the PDF file itself.
'
parameters:
- $ref: '#/components/parameters/resourceId'
responses:
'200':
description: Background Check PDF Report
content:
application/pdf:
schema:
type: string
format: binary
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
/entities/{entityId}/background-checks:
get:
tags:
- Background Checks
operationId: GetEntityBackgroundChecks
summary: List an entity's background checks
description: 'Lists background checks associated with an entity. Use this endpoint when your integration is working from a known entity ID.
'
parameters:
- $ref: '#/components/parameters/entityId'
- $ref: '#/components/parameters/collectionCursorNextPageParam'
- $ref: '#/components/parameters/collectionCursorPreviousPageParam'
- $ref: '#/components/parameters/collectionLimit'
- $ref: '#/components/parameters/backgroundCheckStatusFilter'
- $ref: '#/components/parameters/backgroundCheckCountryFilter'
- $ref: '#/components/parameters/orderScore'
- $ref: '#/components/parameters/orderCreatedAt'
- $ref: '#/components/parameters/orderUpdatedAt'
responses:
'200':
description: Entity Background Checks
content:
application/ld+json:
schema:
type: object
allOf:
- $ref: '#/components/schemas/Collection'
- type: object
properties:
'@context':
default: /contexts/BackgroundCheck
'@id':
example: /entities/91ab5678-1234-5678-9abc-def012345678/background-checks
hydra:member:
type: array
items:
$ref: '#/components/schemas/BackgroundCheck'
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
/background-checks/{backgroundCheckId}/records:
get:
tags:
- Background Checks
operationId: GetBackgroundCheckRecords
summary: List background check records
description: 'Lists the records found during a background check. Records contain the detailed source data behind the check and are organized by category and database.
'
parameters:
- $ref: '#/components/parameters/backgroundCheckId'
- $ref: '#/components/parameters/collectionCursorNextPageParam'
- $ref: '#/components/parameters/collectionCursorPreviousPageParam'
- $ref: '#/components/parameters/collectionLimit'
- $ref: '#/components/parameters/backgroundCheckCategoryFilter'
- $ref: '#/components/parameters/orderCreatedAt'
- $ref: '#/components/parameters/orderUpdatedAt'
responses:
'200':
description: Background Check Records
content:
application/ld+json:
schema:
type: object
allOf:
- $ref: '#/components/schemas/CursorCollection'
- type: object
properties:
'@context':
default: /contexts/BackgroundCheckRecord
'@id':
example: /background-checks/91ab5678-1234-5678-9abc-def012345678/records
hydra:member:
type: array
items:
$ref: '#/components/schemas/BackgroundCheckRecord'
hydra:search:
type: object
properties:
'@type':
type: string
default: hydra:IriTemplate
hydra:template:
example: /background-checks/91ab5678-1234-5678-9abc-def012345678/records{?category}
hydra:variableRepresentation:
type: string
default: BasicRepresentation
hydra:mapping:
type: array
items:
type: object
properties:
'@type':
type: string
default: IriTemplateMapping
variable:
type: string
property:
type: string
required:
type: boolean
default: false
example:
- '@type': IriTemplateMapping
variable: category
property: category
required: false
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
components:
schemas:
BackgroundCheckDatabaseStatus:
type: object
required:
- id
- database
- category
- status
properties:
id:
type: string
format: uuid
description: Unique database status ID
example: 64ef1234-5678-9012-cdef-345678901234
database:
allOf:
- $ref: '#/components/schemas/BackgroundCheckDatabase'
description: Database checked by the provider
category:
allOf:
- $ref: '#/components/schemas/BackgroundCheckCategory'
description: Category checked in this database
status:
type: string
description: Provider status for this database check
example: completed
BackgroundCheckCountry:
type: string
enum:
- MX
- ALL
description: 'Country scope for background check:
- **MX**: Mexico-specific background checks
- **ALL**: International background checks across multiple countries
'
example: MX
Collection:
allOf:
- $ref: '#/components/schemas/HydraView'
- type: object
properties:
hydra:search:
type: object
properties:
'@type':
type: string
hydra:template:
type: string
hydra:variableRepresentation:
type: string
hydra:mapping:
type: array
items:
type: object
properties:
'@type':
type: string
variable:
type: string
property:
type: string
required:
type: boolean
updatedAt:
type: string
description: Date and time the resource was last updated
example: '2020-01-01T12:15:00.000Z'
BackgroundCheckRecordSectionField:
type: object
required:
- id
- name
- value
properties:
id:
type: string
format: uuid
description: Unique field ID
example: 37ef1234-5678-9012-cdef-345678901234
name:
type: string
description: Display name for the field
example: Full Name
value:
type: string
description: Value returned for the field
example: Juan Manuel Perez Gonzalez
BackgroundCheckDatabase:
type: object
required:
- id
- name
- country
properties:
id:
type: string
format: uuid
description: Unique background check database ID
example: 55f01234-5678-9012-cdef-345678901234
name:
type: string
description: Display name of the database
example: Mexico Criminal Records Database
country:
allOf:
- $ref: '#/components/schemas/BackgroundCheckCountry'
description: Country covered by this database
CollectionLimit:
type: integer
default: 20
minimum: 1
maximum: 1000
BackgroundCheck:
type: object
required:
- id
- link
- country
- score
- status
- scores
- databaseStatuses
- files
- createdAt
- updatedAt
properties:
'@id':
type: string
format: iri-reference
description: Background Check IRI reference
example: /background-checks/91ab5678-1234-5678-9abc-def012345678
'@type':
type: string
default: BackgroundCheck
id:
type: string
format: uuid
description: Unique background check ID
example: 91ab5678-1234-5678-9abc-def012345678
link:
type: string
format: iri-reference
description: Entity associated with the background check
example: /entities/91ab5678-1234-5678-9abc-def012345678
country:
allOf:
- $ref: '#/components/schemas/BackgroundCheckCountry'
description: Country scope for the background check
score:
type: number
format: float
description: Overall score returned by the background check provider
example: 85.5
status:
allOf:
- $ref: '#/components/schemas/BackgroundCheckStatus'
description: Processing status for the background check
scores:
type: array
items:
$ref: '#/components/schemas/BackgroundCheckScore'
description: Scores returned for each background check category
databaseStatuses:
type: array
items:
$ref: '#/components/schemas/BackgroundCheckDatabaseStatus'
description: Status information for each database checked by the provider
files:
type: array
items:
$ref: '#/components/schemas/File'
description: Files produced by the background check, including PDF reports when available
createdAt:
$ref: '#/components/schemas/createdAt'
updatedAt:
$ref: '#/components/schemas/updatedAt'
createdAt:
type: string
description: Date and time the resource was created
example: '2020-01-01T12:15:00.000Z'
BackgroundCheckStatus:
type: string
enum:
- pending
- completed
- error
description: 'Status of the background check:
- **pending**: Background check is being processed
- **completed**: Background check has been completed successfully
- **error**: Background check encountered an error during processing
'
example: completed
BackgroundCheckCategory:
type: string
enum:
- affiliations_and_insurances
- alert_in_media
- behavior
- business_background
- criminal_record
- driving_licenses
- international_background
- legal_background
- personal_identity
- professional_background
- traffic_fines
- vehicle_information
- vehicle_permits
- taxes_and_finances
- politically_exposed_person
- credit_history
- document_validation
- unknown
description: 'Category of background check:
- **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
- **vehicle_permits**: Vehicle permits and registrations
- **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
- **unknown**: Unknown or unclassified category
'
example: criminal_record
File:
type: object
properties:
'@id':
type: string
format: iri-reference
description: File IRI reference
example: /files/91106968-1abd-4d64-85c1-4e73d96fb997
'@type':
type: string
description: JSON-LD resource type
default: File
example: File
id:
type: string
format: uuid
description: Unique file ID
example: 91106968-1abd-4d64-85c1-4e73d96fb997
type:
type: string
description: File category, such as an invoice CFDI XML or PDF
example: invoice.cfdi.xml
resource:
type: string
description: IRI of the resource that produced or owns the file
example: /invoices/7c45e9c6-8f7f-4d0e-b6e5-65fef6c8c2f9
mimeType:
type: string
description: Media type of the file content
example: text/xml
extension:
type: string
description: File extension for the stored content
example: xml
size:
type: integer
description: File size in bytes
example: 40544
filename:
type: string
description: Suggested filename for the file content
example: 6f3c5312-2849-4525-86f6-c48a54c64c60.xml
createdAt:
$ref: '#/components/schemas/createdAt'
updatedAt:
$ref: '#/components/schemas/updatedAt'
BackgroundCheckScore:
type: object
required:
- id
- category
- score
- status
- recordsCount
properties:
id:
type: string
format: uuid
description: Unique category score ID
example: 73de0123-4567-8901-bcde-f23456789012
category:
allOf:
- $ref: '#/components/schemas/BackgroundCheckCategory'
description: Category this score applies to
score:
type: number
format: float
description: Score returned for this background check category
example: 92.3
status:
type: string
description: Provider status for this category check
example: clean
recordsCount:
type: integer
description: Number of records found for this category
example: 3
CursorCollection:
type: object
properties:
'@context':
type: string
'@id':
type: string
'@type':
type: string
default: hydra:Collection
hydra:member:
type: array
items:
type: object
hydra:view:
type: object
description: Pagination information
properties:
'@id':
type: string
format: iri-reference
description: Current page IRI reference
'@type':
type: string
default: hydra:PartialCollectionView
hydra
# --- truncated at 32 KB (39 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/syntage/refs/heads/main/openapi/syntage-background-checks-api-openapi.yml