> ## Documentation Index
> Fetch the complete documentation index at: https://docs.sublay.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Fetch entity by foreign ID

> Fetch a single entity by its foreign ID

<Note>
  **Requires the `entities` bundle.** A project without the entities bundle returns `403 database/tables-not-available`. See [Bundles](/v8/bundles).
</Note>

## Overview

`useFetchEntityByForeignId` returns a function that fetches an entity using the foreign ID from your system. Optionally auto-creates the entity if it does not yet exist.

## Usage Example

```tsx theme={null}
import { useFetchEntityByForeignId } from "@sublay/react-js";

function ArticleSocial({ articleId }: { articleId: string }) {
  const fetchEntity = useFetchEntityByForeignId();

  const load = async () => {
    const entity = await fetchEntity({
      foreignId: articleId,
      createIfNotFound: true,
    });
    console.log(entity);
  };

  return <button onClick={load}>Load</button>;
}
```

## Parameters

<ParamField path="foreignId" type="string" required>
  The foreign ID to look up. This is the identifier from your own system.
</ParamField>

<ParamField path="createIfNotFound" type="boolean">
  If `true`, automatically creates a new entity with this foreign ID when one does not exist.
</ParamField>

<ParamField path="include" type="string | EntityInclude[]">
  Optional. Populate related fields. Accepted values: `"user"`, `"space"`, `"topComments"`, `"saved"`, `"files"`, `"grants"`.
</ParamField>

<ParamField path="topCommentsLimit" type="number">
  With `"topComments"` included: how many top comments per entity. Server default `1`, maximum `5`. Not sent when `include` doesn't contain `"topComments"`.
</ParamField>

<ParamField path="topCommentsSortByReaction" type="ReactionType">
  With `"topComments"` included: the reaction whose raw count ranks the top comments. Server default `"upvote"`. Not sent when `include` doesn't contain `"topComments"`.
</ParamField>

## Returns

<ResponseField name="Entity" type="Entity">
  The fetched (or newly created) entity. See [Entity data model](/v8/data-models/entity).
</ResponseField>


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