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

# 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](https://docs.syntage.com/api-reference/entities/add-an-entity.md), retrieve a known entity with [Retrieve an entity](https://docs.syntage.com/api-reference/entities/retrieve-an-entity.md), or list entities with [List all entities](https://docs.syntage.com/api-reference/entities/list-all-entities.md).

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}'
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.