> ## 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 or create entity by foreign ID

> Fetch an entity by its foreign ID, creating it if it doesn't exist

> [!NOTE]
>
> **Requires the `entities` bundle.** A project without the entities bundle returns `403 database/tables-not-available`. See [Bundles](https://docs.sublay.io/v8/bundles.md).

## Overview

`useFetchOrCreateEntityByForeignId` returns a function that fetches the entity with the foreign ID from your system, or creates it when there is none. The entity it creates carries only the `foreignId`: no title, content or author.

Because the new entity has no author, the project's **Who can create entities without an author** setting decides who may create it: everyone by default. When it is set to **Signed-in users only** (a visitor with no session is refused) or **No one from the client** (only your backend may create it), a refused caller gets `403 entity/authorless-creation-not-allowed` and nothing is created. A suspended user gets `403 user/suspended`. A `foreignId` whose entity was deleted stays taken: the call rejects with `409 entity/foreign-id-taken`. See [Fetch Entity by Foreign ID](https://docs.sublay.io/v8/api-reference/entities/fetch-entity-by-foreign-id.md).

Most hooks resolve to the plain record. This one resolves to `{ entity, created }`, because whether the call created the entity is part of its answer.

## Usage Example

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

function ArticleSocial({ articleId }: { articleId: string }) {
  const fetchOrCreateEntity = useFetchOrCreateEntityByForeignId();

  const load = async () => {
    const { entity, created } = await fetchOrCreateEntity({
      foreignId: articleId,
    });
    console.log(entity, created);
  };

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

## Parameters

**foreignId** `string` *required*

The foreign ID to look up. This is the identifier from your own system.

**include** `EntityIncludeParam`

Optional. Populate related fields, as a single value or an array. Accepted values: `"user"`, `"space"`, `"topComments"`, `"saved"`, `"files"`, `"grants"`.

**topCommentsLimit** `number`

With `"topComments"` included: how many top comments per entity. Server default `1`, maximum `5`. Not sent when `include` doesn't contain `"topComments"`.

**topCommentsSortByReaction** `ReactionType`

With `"topComments"` included: the reaction whose raw count ranks the top comments. Server default `"upvote"`. Not sent when `include` doesn't contain `"topComments"`.

## Returns

**entity** `Entity`

The entity with this foreign ID, existing or just created. See [Entity data model](https://docs.sublay.io/v8/data-models/entity.md).

**created** `boolean`

`true` when this call created the entity (HTTP `201`), `false` when it already existed (HTTP `200`, also when another call created it concurrently).


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