Collaborators

A collaborator is someone who promotes your products or services in exchange for rewards. This includes affiliates, ambassadors, referral partners, and influencers. Collaborators are the central identity in Siren’s attribution pipeline. Each collaborator has a unique referral code (an alias) used to track engagements, which flow downstream into conversions and obligations. Collaborators are enrolled in one or more programs and assigned to distributors, which together determine how they earn and what they earn.

The collaborator object

Extended fields (REST only, via ?fields=)

These fields are resolved dynamically by the REST API field resolver system and must be explicitly requested:

Status lifecycle

Accessing collaborator data

# List active collaborators
curl -X GET "https://your-site.com/wp-json/siren/v1/collaborators?status=active" \
  -H "Authorization: Bearer YOUR_TOKEN"

# Get a single collaborator with extended fields
curl -X GET "https://your-site.com/wp-json/siren/v1/collaborators/42?fields=id,fullName,email,programs,referralCode,aliases" \
  -H "Authorization: Bearer YOUR_TOKEN"

use Siren\Collaborators\Core\Datastores\Collaborator\Interfaces\CollaboratorDatastore;

class MyService
{
    protected CollaboratorDatastore $collaborators;

    public function __construct(CollaboratorDatastore $collaborators)
    {
        $this->collaborators = $collaborators;
    }

    public function getActiveCollaborators(): array
    {
        return $this->collaborators->andWhere([
            ['column' => 'status', 'operator' => '=', 'value' => 'active']
        ]);
    }
}

use Siren\Collaborators\Core\Facades\Collaborators;

$active = Collaborators::andWhere([
    ['column' => 'status', 'operator' => '=', 'value' => 'active']
]);

$collaborator = Collaborators::find(42);

Most collaborator records are created as side effects of Siren’s event-driven architecture. When a new affiliate registers or is imported, the system fires domain events that handle record creation, program enrollment, and alias assignment. You should reach for the datastore directly when you need to read collaborator data for display, look up a collaborator to make decisions in custom logic, or manage program membership in a migration script.

PHP domain methods

Looking up by email

getByEmail(string $email) retrieves a single collaborator by email address. Throws RecordNotFoundException if no collaborator exists with that email.

use PHPNomad\Datastore\Exceptions\RecordNotFoundException;

try {
    $collaborator = $this->collaborators->getByEmail('jane@example.com');
    $name = $collaborator->getFullName();
} catch (RecordNotFoundException $e) {
    // No collaborator with that email
}

use Siren\Collaborators\Core\Facades\Collaborators;
use PHPNomad\Datastore\Exceptions\RecordNotFoundException;

try {
    $collaborator = Collaborators::getByEmail('jane@example.com');
    $name = $collaborator->getFullName();
} catch (RecordNotFoundException $e) {
    // No collaborator with that email
}

Looking up by WordPress user ID

getCollaboratorFromUserId(int $userId) finds the collaborator linked to a WordPress user through Siren’s mapping system. This is the bridge between WordPress’s user table and Siren’s collaborator records. Throws RecordNotFoundException if no mapping exists for that user.

// Get the collaborator record for the current WordPress user
$collaborator = $this->collaborators->getCollaboratorFromUserId(
    get_current_user_id()
);

echo $collaborator->getNickname();

use Siren\Collaborators\Core\Facades\Collaborators;

// Get the collaborator record for the current WordPress user
$collaborator = Collaborators::getCollaboratorFromUserId(
    get_current_user_id()
);

echo $collaborator->getNickname();

Under the hood, this method queries the Mappings datastore for a record linking the external user ID to an internal collaborator ID, then fetches the collaborator by that ID.

Listing collaborators in a program

getCollaboratorsInProgram(int $programId, int $limit = 10, int $offset = 0) returns an array of Collaborator models enrolled in the given program. Supports pagination through the limit and offset parameters.

// Get the first 25 collaborators in program 5
$collaborators = $this->collaborators->getCollaboratorsInProgram(5, 25, 0);

foreach ($collaborators as $collaborator) {
    echo $collaborator->getFullName() . ' (' . $collaborator->getEmail() . ')' . PHP_EOL;
}

use Siren\Collaborators\Core\Facades\Collaborators;

// Get the first 25 collaborators in program 5
$collaborators = Collaborators::getCollaboratorsInProgram(5, 25, 0);

foreach ($collaborators as $collaborator) {
    echo $collaborator->getFullName() . ' (' . $collaborator->getEmail() . ')' . PHP_EOL;
}

Managing program membership

addCollaboratorToProgram(int $collaboratorId, int $programId) enrolls a collaborator in a program. Throws DuplicateEntryException if the collaborator is already enrolled.

removeCollaboratorFromProgram(int $collaboratorId, int $programId) removes a collaborator from a program.

use PHPNomad\Datastore\Exceptions\DuplicateEntryException;

try {
    $this->collaborators->addCollaboratorToProgram(12, 5);
} catch (DuplicateEntryException $e) {
    // Already enrolled
}

// Remove from a different program
$this->collaborators->removeCollaboratorFromProgram(12, 3);

use Siren\Collaborators\Core\Facades\Collaborators;
use PHPNomad\Datastore\Exceptions\DuplicateEntryException;

try {
    Collaborators::addCollaboratorToProgram(12, 5);
} catch (DuplicateEntryException $e) {
    // Already enrolled
}

// Remove from a different program
Collaborators::removeCollaboratorFromProgram(12, 3);

These methods manage the junction table that links collaborators to programs. In most cases, program enrollment happens automatically through Siren’s event pipeline, but these methods are useful for migration scripts or custom enrollment logic.

Aliases

Aliases are the codes that identify a collaborator in tracking links and coupon systems. A collaborator can have multiple aliases over time — for example, if they change their tracking slug — and the system keeps a historical record so that old links continue to resolve correctly. For a focused reference on the alias datastore, including all query methods and historical lookups, see Aliases.

Each alias has a type (such as “tracking” or “coupon”), a code string, and an issued date. The alias datastore returns the most-recently issued alias by default, but accepts an optional DateTime parameter to look up who owned a particular code at a specific point in history.

Alias model

The Alias model (Siren\Collaborators\Core\Models\Alias) has the following fields:

Accessing the alias datastore

use Siren\Collaborators\Core\Datastores\CollaboratorAliases\Interfaces\CollaboratorAliasesDatastore;

class MyService
{
    protected CollaboratorAliasesDatastore $aliases;

    public function __construct(CollaboratorAliasesDatastore $aliases)
    {
        $this->aliases = $aliases;
    }
}

use Siren\Collaborators\Core\Facades\CollaboratorAliases;

$alias = CollaboratorAliases::getAliasByCode('janedoe', 'tracking');

Looking up an alias by code

getAliasByCode(string $code, string $type, ?DateTime $before = null) finds the alias record matching a specific code and type. Since the same code can be reassigned over time, this returns the most-recently issued match. Pass a DateTime to the $before parameter to find who owned the code at that point in history. Throws RecordNotFoundException if no matching alias exists.

use Siren\Collaborators\Core\Facades\CollaboratorAliases;

// Who currently owns this tracking code?
$alias = CollaboratorAliases::getAliasByCode('janedoe', 'tracking');
$collaboratorId = $alias->getCollaboratorId();

// Who owned it on January 1st?
$alias = CollaboratorAliases::getAliasByCode(
    'janedoe',
    'tracking',
    new DateTime('2025-01-01')
);

Getting a collaborator’s current alias

getAliasForCollaborator(int $id, string $type, ?DateTime $before = null) retrieves the alias of a given type for a specific collaborator. Returns the most-recently issued alias of that type. Like getAliasByCode, the $before parameter supports historical lookups. Throws RecordNotFoundException if the collaborator has no alias of that type.

use Siren\Collaborators\Core\Facades\CollaboratorAliases;

// Get this collaborator's current tracking alias
$alias = CollaboratorAliases::getAliasForCollaborator(12, 'tracking');
echo $alias->getCode(); // e.g. "janedoe"

// Get their coupon alias
$couponAlias = CollaboratorAliases::getAliasForCollaborator(12, 'coupon');
echo $couponAlias->getCode(); // e.g. "JANE20"

Practical example: displaying a collaborator’s dashboard info

This example retrieves a collaborator from the currently logged-in WordPress user and displays their tracking link.

use Siren\Collaborators\Core\Facades\Collaborators;
use Siren\Collaborators\Core\Facades\CollaboratorAliases;
use PHPNomad\Datastore\Exceptions\RecordNotFoundException;

try {
    $collaborator = Collaborators::getCollaboratorFromUserId(get_current_user_id());
    $alias = CollaboratorAliases::getAliasForCollaborator(
        $collaborator->getId(),
        'tracking'
    );

    echo 'Welcome, ' . esc_html($collaborator->getFullName()) . '!';
    echo 'Your referral link: https://example.com/?ref=' . urlencode($alias->getCode());
} catch (RecordNotFoundException $e) {
    echo 'No collaborator account found for this user.';
}

Relationships

• Programs (enrollment). Collaborators are enrolled in one or more programs, which define how referrals are tracked and how rewards are calculated. Program enrollment is managed through the programs field on create and update, or through the addToProgram and removeFromProgram bulk actions.
• Distributors (assignment). Collaborators are assigned to distributors, which represent the products or services they promote. The distributors and distributorId extended fields expose these assignments.
• Engagements (downstream). When a collaborator’s referral code is used, the system creates an engagement attributed to that collaborator. Engagements feed into the conversion pipeline.
• Obligations (downstream). Approved conversions generate obligations recording what is owed to the collaborator. The unfulfilledObligationCount and fulfilledObligationCount extended fields provide at-a-glance totals.
• Aliases. Each collaborator has one or more alias codes (including their referral code) used for tracking. The aliases extended field returns the full set.

REST endpoints

See the individual endpoint pages in the sidebar for full request and response details, or browse the all REST endpoints reference.