> ## 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}/...`.
</Note>

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