API Reference

Engagements

Engagement Lifecycle and Managing Engagements

Wingspan's new Engagements feature revolutionizes how you manage your contingent workforce by replacing our legacy Groups and MemberClient models. Engagements provide a more streamlined, flexible, and scalable approach to handling complex payer-payee relationships.

This section delves into the Engagement Lifecycle and Managing Engagements, outlining their states, transitions, the distinction between Engagements and Contractor Engagements, and best practices for efficient workforce management.

4.1. Engagement vs. Contractor Engagement

  • Engagement:
    • Represents a project, department, or any defined scope of work within your organization.
    • Can include multiple contractors working under the same terms, requirements, and settings.
    • Managed by the payer (you) and is the overarching entity for organizing work relationships.
  • Contractor Engagement (Payer Payee Engagement via API):
    • Represents the association of a specific contractor (payee) with an Engagement.
    • Reflects the contractor's participation, status, and compliance within that Engagement.
    • Managed jointly by the payer and the contractor, focusing on individual compliance and fulfillment of requirements.

4.2. Engagement Lifecycle

The Engagement lifecycle involves managing the Engagement as a whole, including all associated contractors. Engagements transition through various states to reflect their current status within your organization.

Engagement States:

  1. Active

State Definitions and Transitions for Engagements

1. Active
  • Description: The default state of an Engagement upon creation. An Active Engagement is fully operational, allowing you to manage contractors, create payables, and oversee engagement-specific workflows.
  • Capabilities:
    • Manage Contractors: Add or remove contractors to the Engagement.
    • Create and Send Payables: Initiate payments to contractors associated with the Engagement.
    • Manage Requirements: Define and enforce engagement-specific requirements.

In the future, you will be allowed to take actions on an Engagement including archiving and deleting.

When creating or modifying engagements, please keep in mind:

  • Unique Names Required: Engagement names must be unique within your account. This ensures clear identification and prevents confusion when managing multiple engagements.
  • Naming Best Practices:
    • Use descriptive names that clearly indicate the purpose or scope of the engagement (e.g., "Summer Intern Program 2024", "Marketing Campaign Q3").
    • Consider including relevant identifiers like department names or project codes if applicable.
    • Avoid generic names that could be easily confused with other engagements.

4.3. Contractor Engagement Lifecycle

The Contractor Engagement (Payee Engagement) lifecycle focuses on the individual contractor's association with an Engagement. It tracks the contractor's status, compliance with requirements, and eligibility for payments within that Engagement.

Contractor Engagement States:

  1. Active
  2. Inactive (Displayed as Archived in the user interface)
    Note: You cannot delete Contractor Engagements. They remain in the system for compliance and historical record-keeping.

State Definitions and Transitions for Contractor Engagements

1. Active
  • Description: Indicates that the contractor is actively engaged in work under the Engagement.
  • Capabilities:
    • Eligible for Payments: Payables can be created and processed for the contractor within the engagement.
  • Transition to Inactive (Archived):
    • From Active: You can archive a Contractor Engagement if the contractor is no longer working under the Engagement.
2. Inactive (Archived)
  • Description: The Contractor Engagement is no longer active but retains historical data.
  • Capabilities:
    • View Historical Data: Access past transactions and compliance records.
    • Cannot Initiate New Payables: Payments cannot be processed for inactive Contractor Engagements.
    • Preserved Data: All Contractor Engagement information remains accessible.
  • Transition to Active:
    • From Inactive (Archived): Reactivate if the contractor resumes work under the Contractor Engagement. The associated Engagement must be active before the Contractor Engagement can be unarchived.
    • Recalculation of Payment Eligibility: Upon reactivation, the system recalculates the contractor's payment eligibility based on the current settings and requirements of the associated Engagement. The contractor might need to complete new requirements or updated versions of existing requirements.

Payment Eligibility

In addition to the Contractor Engagement status, there is a separate field called Payment Eligibility, which determines whether a contractor is eligible to receive payments within a specific Contractor Engagement.

Payment Eligibility States:

  1. Eligible
  2. Not Eligible

Details:

  • Eligible:

    • The contractor meets all the requirements and is allowed to receive payments.
    • Payments can be processed without restrictions.

  • Not Eligible:

    • The contractor has not fulfilled all requirements or is otherwise restricted from receiving payments.
    • Payments cannot be processed until the contractor becomes eligible.

Important Notes:

  • Automatic Recalculation:

    • When a Contractor Engagement is reactivated, the system automatically recalculates the contractor's payment eligibility.
    • Changes in Engagement requirements or policies can affect eligibility, potentially requiring contractors to complete new or updated requirements.

  • Requirement Compliance:

    • Contractors may need to fulfill new requirements or renew existing ones if they have expired or been updated.

4.4. Lifecycle Interactions

Understanding how the lifecycles of Engagements, Contractor Engagements, and contractors (payees) interact is crucial for effective management.

  • Archiving a Contractor (Payee):
    • Effect on Contractor Engagements:
      • When you archive a contractor, all their associated Contractor Engagements are automatically archived if the action is taken via the Wingspan user interface. API consumers will need to archive all Contractor Engagements prior to archiving a contractor.
    • Restoring a Contractor:
      • When you restore an archived contractor, only the Default Contractor Engagement is restored automatically.
      • Custom Contractor Engagements need to be restored manually if you wish to reactivate them.
  • Archiving an Engagement:
    • Effect on Contractor Engagements:
      • Archiving an Engagement automatically archives all the associated Contractor Engagements.

5. Managing Engagements

Effective management of both Engagements and Contractor Engagements ensures seamless operations and compliance within your contingent workforce. This section covers the creation, default engagements, customization, organization, and best practices.

5.1. Default Engagements

To simplify onboarding and transactions, Wingspan automatically creates a Default Contractor Engagement for every new payer-payee relationship.

5.1.1. What is a Default Engagement?

  • Description: A basic, system-generated Engagement representing the simplest form of payer-payee relationship.
  • Characteristics:
    • Automatic Creation and Association:
      • Automatically created and added for every contractor you add to your account.
    • Minimal Visibility:
      • Not prominently displayed in the Engagements list to reduce clutter.
      • Visible only in specific contexts, such as when archiving a contractor.
    • Connected to Payer-Payee Status:
      • If you archive a contractor, the Default Engagement is also archived.
      • Restoring a contractor automatically restores the Default Engagement.
    • Limited Customization:
      • Cannot rename the Default Engagement.
      • Cannot add requirements or modify settings.
    • Representation in Pickers:
      • When selecting engagements in various workflows (e.g., creating a payable), the Default Engagement is represented by the contractor's name without specifying an engagement.

5.1.2. How Default Engagements Work

  • Adding a New Contractor:
    • When you invite or add a new contractor to your Wingspan account, a Default Engagement is automatically created and associated with them.
    • This allows for immediate transactions without additional setup.
  • Contractor-Initiated Relationships:
    • If a contractor invites you (the payer) to Wingspan, a Default Contractor Engagement is created for you upon acceptance.
    • We also create a default payer-payee relationship (PayerPayee) between you and the contractor.
    • After registration, you (the payer) become the owner of both the payer account and the Default Engagement.
  • Usage:
    • Ideal for simple engagements where no specific requirements or customizations are needed.
    • Provides a streamlined workflow for immediate payment processing.

5.1.3. Managing Default Engagements

  • Limitations:
    • You cannot rename or add requirements to Default Engagements.
    • Default Engagements are tightly integrated with the contractor's status.
  • Archiving and Restoring:
    • Archiving a contractor will also archive the Default Engagement.
    • Restoring a contractor will automatically restore the Default Engagement.

5.3. Managing Contractor Engagements

Managing Contractor Engagements involves overseeing each contractor's status and compliance within an Engagement, as well as their payment eligibility.

Adding Contractors to an Engagement:

Coming soon

Monitoring Contractor Engagements:

Coming soon

Archiving Contractor Engagements:

Coming soon

5.4. Customizing Engagements

Custom Engagements allow for specific configurations:

  • Requirements:
    • Define what contractors must complete.
    • Adding or deleting requirements affects all associated Contractor Engagements.
      • Adding Requirements:
        • May change contractors' payment eligibility to Not Eligible until they complete the new requirements.
        • Shared Requirements: Some requirements can be shared across multiple engagements. When a contractor completes a shared requirement (e.g., signing a document or completing a background check), it will fulfill that requirement for all connected engagements.
      • Deleting Requirements:
        • Contractors immediately become Eligible if the removed requirement was the only pending item.

5.5. Archiving Engagements and Contractor Engagements

  • Archiving an Engagement:
    • Affects the entire Engagement and all associated Contractor Engagements in terms of transactional capabilities.
    • No new transactions can occur within an archived Engagement.
    • All associated Contractor Engagements are automatically archived
    • All associated Contractor Engagements are automatically archived when archiving an Engagement. Contractor Engagements cannot be unarchived if connected Engagement is archived.
  • Archiving a Contractor Engagement:
    • Specific to an individual contractor within an Engagement.
    • Changes the Contractor Engagement status to Inactive (Archived).
    • Does not affect other contractors within the Engagement.

Frequently Asked Questions

Q1: Can a contractor be part of multiple engagements?

A: Yes, a contractor can be associated with multiple engagements, each with its own Contractor Engagement. This allows for flexibility in assigning contractors to different projects or departments.

Q2: How do Contractor Engagements affect payments?

A: Payments are linked to Contractor Engagements. A contractor must have an Active Contractor Engagement within an Engagement and be Payment Eligible to receive payments related to that Engagement.

Q3: What happens if I archive an Engagement but not the Contractor Engagements?

A: Archiving an Engagement restricts all associated Contractor Engagements from initiating new transactions within that Engagement. The Contractor Engagements remain in their current state for record-keeping.

Q4: Can I have different requirements for contractors within the same Engagement?

A: Requirements are set at the Engagement level and apply to all Contractor Engagements within it. If you need different requirements for specific contractors, consider creating separate engagements.

Q6: What happens to associated contractors if I add or delete a requirement from an Engagement?

A: When you add a requirement to an Engagement:

  • All associated contractors may become Not Eligible for payments until they fulfill the new requirement.
  • Contractors will receive notifications prompting them to complete the new requirement.

When you delete a requirement from an Engagement:

  • Contractors who were Not Eligible due to that requirement may immediately become Eligible for payments.
  • No action is needed from the contractors unless other requirements are still pending.

Q7: Can I delete a Contractor Engagement?

A: No, Contractor Engagements cannot be deleted. They remain in the system for compliance and historical record-keeping. You can archive a Contractor Engagement to deactivate it.

Q8: How do engagements work with contractor bulk uploads?

When performing a contractor bulk upload, you have the option to select an engagement to which all the contractors will be added. If you don't select a specific engagement, all uploaded contractors will be added to the default engagement. This allows for efficient onboarding of multiple contractors to a particular project or department.

Q9: How do engagements work with payable bulk uploads?

Currently, when you upload payables in bulk for a contractor who is part of multiple engagements, the system automatically selects the most recently created, non-archived engagement. We are working on improving this feature to allow you to specify which engagement the payables should be associated with during the upload process. This enhancement will provide more control and accuracy in managing payments across different engagements.