Skip to main content

Somebody Functions

To manage somebody entities, use the functions exported by the Somebody adapter.

Importing the adapter​

To use the functions of the Somebody adapter, import it as shown:
import { somebodyAdapter } from 'epicenter-libs';

The somebodyAdapter namespace exports functions that make calls to the Somebody API.

learn more

For descriptions of the objects used by the Somebody adapter functions, read Somebody entities.

Create​

The create() function adds a somebody entity to an account.

Permissions​

Requires a role of FACILITATOR or higher.

Function description​

  • Constructs a POST request to the /somebody endpoint.
  • Creates a somebody record associated with the specified scope.
  • Accepts an email address and optional name fields.
  • Returns the newly created Somebody object.
Function signature
export async function create(
    email: string,
    scope: GenericScope,
    optionals: {
        givenName?: string;
        familyName?: string;
    } & RoutingOptions = {},
): Promise<Somebody>

Parameters​

  • email (string) – Email address of the person being added
  • scope (GenericScope) – Scope of the somebody entity
    • scopeBoundary – Identifies the type of scope by one of the values of the SCOPE_BOUNDARY enum.
    • scopeKey (string) – Unique identifier of the scope. For example, if scopeBoundary is GROUP, the scopeKey should be the corresponding group key.
  • optionals (Type: { givenName?: string; familyName?: string } & RoutingOptions):
    • givenName? (string) – Given name of the person
    • familyName? (string) – Family name of the person
    • RoutingOptions – Additional routing options

Return value​

Returns a promise that resolves to a Somebody object representing the newly added person.

Usage example​

import { somebodyAdapter, SCOPE_BOUNDARY } from 'epicenter-libs';

const email = 'test@test.com';

const scope = {
    scopeBoundary: SCOPE_BOUNDARY.GROUP,
    scopeKey: '0000017dd3bf540e5ada5b1e058f08f20461',
};

const somebody = await somebodyAdapter.create(email, scope, {
    givenName: 'Person',
    familyName: 'Family',
});

Retrieve​

Get somebody​

The get() function retrieves a somebody entity by its key.

Permissions​

Requires a role of PARTICIPANT or higher.

Function description​

  • Constructs a GET request to the /somebody/{SOMEBODY_KEY} endpoint.
  • Retrieves the Somebody object associated with the specified key.
  • If the entity does not exist, the function returns undefined.
Function signature
export async function get(
    somebodyKey: string,
    optionals: RoutingOptions = {},
): Promise<Somebody | undefined>

Parameters​

  • somebodyKey (string) – Unique identifier of the Somebody entity
  • optionals (RoutingOptions):

Return value​

Returns a promise that resolves to a Somebody object, or undefined if the entity is not found.

Usage example​

import { somebodyAdapter } from 'epicenter-libs';

const somebodyKey = '0000017dd3bf540e5ada5b1e058f08f20461';

const somebody = await somebodyAdapter.get(somebodyKey);

Get somebodies by scope​

The inScope() function retrieves all somebody entities within a specified scope.

Permissions​

Requires a role of PARTICIPANT or higher.

Function description​

  • Constructs a GET request to the /somebody/in/{SCOPE_BOUNDARY}/{SCOPE_KEY} endpoint.
  • Retrieves all Somebody objects in the specified scope.
  • Supports pagination using the first and max parameters.
  • Returns a paginated list of Somebody objects.
Function signature
export async function inScope(
    scope: GenericScope,
    optionals: {
        first?: number;
        max?: number;
    } & RoutingOptions = {},
): Promise<Page<Somebody> | undefined>

Parameters​

  • scope (GenericScope) – Scope associated with the somebodies
    • scopeBoundary – Identifies the type of scope by one of the values of the SCOPE_BOUNDARY enum.
    • scopeKey (string) – Unique identifier of the scope. For example, if scopeBoundary is GROUP, the scopeKey should be the corresponding group key.
  • optionals (Type: { first?: number; max?: number } & RoutingOptions):
    • first? (number) – Index of the first result to return
    • max? (number) – Maximum number of results to return (maximum of 300, default 300)
    • RoutingOptions – Additional routing options

Return value​

Returns a promise that resolves to a Page<Somebody> containing Somebody objects, or undefined if no results are found.

Usage example​

import { somebodyAdapter, SCOPE_BOUNDARY } from 'epicenter-libs';

const scope = {
    scopeBoundary: SCOPE_BOUNDARY.GROUP,
    scopeKey: '0000017dd3bf540e5ada5b1e058f08f20461',
};

const somebodies = await somebodyAdapter.inScope(scope, {
    first: 0,
    max: 100,
});

Get somebody by email​

The byEmail() function retrieves a somebody entity within a specified scope by email address.

Permissions​

Requires a role of PARTICIPANT or higher.

Function description​

  • Constructs a GET request to the /somebody/with/{SCOPE_BOUNDARY}/{SCOPE_KEY}/{EMAIL} endpoint.
  • Retrieves the Somebody object associated with the specified email and scope.
  • If no matching entity is found, the function returns undefined.
Function signature
export async function byEmail(
    email: string,
    scope: GenericScope,
    optionals: RoutingOptions = {},
): Promise<Somebody | undefined>

Parameters​

  • email (string) – Email address of the Somebody entity to retrieve
  • scope (GenericScope) – Scope associated with the somebody
    • scopeBoundary – Identifies the type of scope by one of the values of the SCOPE_BOUNDARY enum.
    • scopeKey (string) – Unique identifier of the scope. For example, if scopeBoundary is GROUP, the scopeKey should be the corresponding group key.
  • optionals (RoutingOptions):

Return value​

Returns a promise that resolves to a Somebody object, or undefined if no matching entity is found.

Usage example​

import { somebodyAdapter, SCOPE_BOUNDARY } from 'epicenter-libs';

const scope = {
    scopeBoundary: SCOPE_BOUNDARY.GROUP,
    scopeKey: '0000017dd3bf540e5ada5b1e058f08f20461',
};

const somebody = await somebodyAdapter.byEmail('test@test.com', scope);