📧 Communication Resource Advanced

Direct communication management for specialized scenarios

Communication records store contact methods (email, phone, mobile, fax) for BizEntities, Persons, and Organisations. Most communication management occurs through BizEntity operations. Direct Communication endpoints support bulk imports, cross-entity updates, and contact validation.

4
Endpoints
1
Core DTO
Multiple
Contact Types
3
Entity Links

Usage Notes

When

  • Manage communications independently of BizEntity for bulk imports
  • Query communication records for cross-entity validation
  • Update contact methods across multiple entity associations

Requirements

  • Valid Bearer token with communication permissions

Notes

  • Communications typically created via BizEntity operations; use direct endpoints for specialized scenarios
  • Each communication belongs to exactly ONE entity (BizEntity, Person, or Organisation)
  • One Communication per owning entity (1:1 constraint): Each BizEntityID, PersonID, or OrganisationID can be assigned to at most one Communication record. Attempting to assign a second triggers an "already assigned to another Communication record" error from the service. This rule is enforced in BizEntityService.cs, not in the validator.

Available Endpoints

Core Operations

GET Get Communications Query by ID, external ID, or owning entity
POST Create Communication Create for one entity (1:1 per owner)
PUT Update Communication Replace the entire record (PUT semantics)
DELETE Delete Communication Remove by CommunicationID or ExternalCommunicationId

Core Data Transfer Objects

CommunicationDTO All Communication endpoints Communication structure (10 properties) with multi-channel contact methods (email, phone, mobile, fax), type classification, and entity ownership (BizEntity, Person, Organisation via dual IDs) 
public class CommunicationDTO
{
    public int? CommunicationID { get; set; }
    public string? ExternalCommunicationId { get; set; }
    public int CommunicationTypeID { get; set; }
    public string? Name { get; set; }
    public int? BizEntityID { get; set; }
    public string? ExternalBizEntityId { get; set; }
    public int? PersonID { get; set; }
    public string? ExternalPersonId { get; set; }
    public int? OrganisationID { get; set; }
    public string? ExternalOrganisationId { get; set; }
}

Use Cases & Scenarios

Most communication management occurs through BizEntity operations. Use direct Communication endpoints for bulk contact imports, cross-entity updates, email/phone validation services, or CRM data migration scenarios.

→ See BizEntity Overview for standard entity operations

Business Rules & Constraints

BizEntity Integration & Data Integrity

  • 1:1 with owning entity (service-enforced): Each BizEntityID, PersonID, or OrganisationID can be assigned to at most one Communication record. Attempting to assign a second returns an "already assigned to another Communication record" error.
  • Exclusive ownership: A Communication links to exactly ONE entity (BizEntity, Person, OR Organisation — mutually exclusive).
  • Type classification: CommunicationTypeID is required and must be greater than 0 (e.g. Email=10).
  • BizEntity context: Communication creation and management primarily occur through BizEntity operations for relationship integrity.

What the API Validator Enforces

  • Name is required (NotNull/NotEmpty).
  • CommunicationTypeID must be greater than 0.
  • PersonID, BizEntityID, and OrganisationID must be greater than 0 when supplied (nulls accepted).
  • When identifying an existing record (PUT / DELETE), at least one of CommunicationID or ExternalCommunicationId must be present.
  • Not enforced by the validator (at time of writing): email format, phone format, country-code matching, global uniqueness of contact values. The DTO accepts Name as a plain string for the contact value — supply correct values per your downstream delivery and reporting needs.

Referential Integrity & Management

  • Referential integrity: Cannot delete communication records referenced by active operational workflows
  • Dual ID system: Native IDs for performance, External IDs for third-party system integration
  • External integration: ExternalCommunicationId supports third-party system integration and idempotency