Create or update an external identifier for a project

Creates a new external identifier for a project or updates an existing one if the key matches. This endpoint implements upsert behavior based on the external identifier key.

Business Context: External identifiers enable Elios Fund projects to maintain references to records in external systems. This endpoint allows API consumers to establish or update these cross-system links programmatically.

Upsert Behavior:

• New Key: Creates a new external identifier with the provided key-value pair
• Existing Key: Updates the existing identifier's value for the matching key
• Key Matching: Exact string match on the external identifier key field
• Atomic Operation: Update or create happens in a single database transaction

Request Structure: The request body must contain an externalId object with:

• key: String identifier for the external system (e.g., "salesforce_id")
• value: The actual external identifier value (e.g., "SF001234")

Common Use Cases:

• CRM Integration: Store Salesforce or HubSpot project record IDs
• Design Tool Sync: Link with Sunobi, Scanifly, or Aurora project IDs
• Utility Integration: Store utility application or interconnection numbers
• Partner System Links: Reference partner's internal project identifiers
• Migration Support: Maintain legacy system project references
• Webhook Processing: Store external system IDs from incoming webhooks

Example External Identifier Keys:

• salesforce_project_id: CRM project record identifier
• sunobi_project_uuid: Solar design platform project ID
• utility_app_number: Utility interconnection application number
• partner_ref_id: Partner system's project reference
• legacy_system_id: Previous platform project identifier

Response Information:

• Complete external identifier record including generated reference ID
• Confirmation of key-value pair storage
• Creation/update timestamps for audit purposes
• Source attribution showing API creation

Integration Patterns:

• Webhook Handlers: Store external IDs from incoming webhook payloads
• Data Sync Jobs: Maintain cross-system references during sync operations
• Migration Scripts: Preserve legacy system identifiers during platform migrations
• Partner Integrations: Allow partners to maintain their own project references
• External API Calls: Store response IDs from external system API calls