Link Identities with an Endpoint

What you'll build

You will learn how to create a custom endpoint that links an anonymous user identity to an authenticated user identity, enabling identity resolution when users sign up or log in.

1. Prerequisites

You will need an Endpoint in MonetizationOS
You will need a secret API key for your preview environment

2. Create the endpoint

Navigate to the Endpoints section to create a new endpoint. Configure it with the following settings:

Name: Link Identities
Method: POST
Path: /link-identities
Access Level: Secret Key

See Endpoints for more information on creating an endpoint

3. Update the workflow

Update the endpoint's workflow to link an anonymous identity to an authenticated identity:

Endpoint Workflow

import type {  } from "./src/lib/workflow-types/genericDocsWorkflowTypes";

interface LinkIdentitiesPayload {
  ?: string;
  ?: string;
}

const :  = async ({ ,  }) => {
  const { ,  } =
    (await .()) as LinkIdentitiesPayload;

  if (! || !) {
    return .(
      {
        : "'anonymousIdentifier' and 'userIdentifier' are required",
      },
      { : 400 },
    );
  }

  const  = await ..({
    : ,
    : "anonymous",
  });

  // Check if the link already exists to avoid creating duplicate links between users
  if (.(() => .. === )) {
    return .({
      : "Success",
    });
  }

  // Create link
  await ..({
    : "copy_once",
    : { : , : "anonymous" },
    : { : , : "authenticated" },
    : "conversion",
    : { : false },
  });

  return .({ : "Success" });
};

export default ;

4. Call the endpoint

Send a POST request with the following payload to link identities. You can copy the full endpoint URL directly from the endpoint's Workflow tab in the dashboard.

Payload

{
  "anonymousIdentifier": "my_anon_id",
  "userIdentifier": "my_auth_user_id"
}

Example Request

curl --request POST \
  --url https://api.monetizationos.com/api/v1/envs/<environmentId>/endpoints/link-identities \
  --header 'X-MOS-Key: Bearer <secret-key>' \
  --header 'content-type: application/json' \
  --data '{"anonymousIdentifier":"my_anon_id","userIdentifier":"my_auth_user_id"}'

Result

The endpoint will link the anonymous identity to the authenticated identity. If the link already exists, it returns successfully without creating a duplicate.