Skip to main content
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.
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:
ResourceEntity-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, retrieve a known entity with Retrieve an entity, or list entities with 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. 
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: 
{
  "@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 URLEntity-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: 
curl -i 'https://api.syntage.com/entities/91106968-1abd-4d64-85c1-4e73d96fb997/tax-status' \
  --header 'Accept: application/ld+json' \
  --header 'X-Api-Key: {apiKey}'