Create or Update Export Configuration

Create a new export configuration or update the existing one for the authenticated user.

This endpoint allows you to configure automated score export jobs that will calculate and export scores for your specified collections, targets, and perspectives at regular intervals.

Upsert Behavior:

• If no configuration exists for the user, a new configuration will be created
• If a configuration already exists, it will be completely replaced with the new values
• This is an idempotent operation - calling it multiple times with the same data produces the same result
• Each user can have only one export configuration at a time

Configuration Fields:

Run Interval (runInterval):

• Optional field - defaults to WEEKLY if not specified
• Valid values: SIX_HOURS, TWELVE_HOURS, DAILY, WEEKLY
• Determines how frequently the export job executes:
  • SIX_HOURS: Every 6 hours (minimum interval)
  • TWELVE_HOURS: Every 12 hours
  • DAILY: Once every 24 hours
  • WEEKLY: Once every 168 hours (7 days)
• The scheduler checks periodically, so execution may occur shortly after the interval elapses

Enabled State (enabled):

• Required field - must be explicitly set to true or false
• When true: Job will automatically run based on the configured runInterval
• When false: Job will not execute, even if the interval has elapsed
• You can disable a job without deleting the configuration

Collections (collectionIds):

• Required field - must be provided (can be empty array [])
• List of Prewave Collection IDs to include in the export
• All targets within these collections will be included in the export
• Collections are validated for user access when the job executes (not at configuration time)
• Empty collections or collections with no accessible targets will be skipped during execution
• To get collection IDs: Use endpoints from the Collections API:
  • GET /public/v1/collections - List all accessible collections (returns id field for each collection)
  • GET /public/v1/collections/{collectionId} - Get a specific collection by ID

Targets (targetIds):

• Required field - must be provided (can be empty array [])
• List of specific Target IDs to include in addition to collection targets
• Targets from collections and individual target IDs are combined (union operation) with no duplicates
• Useful for including specific targets that may not be in any collection
• Target access is validated when the job executes
• To get target IDs: Use endpoints from the Suppliers API:
  • GET /public/v2/suppliers/sites - List all supplier sites (returns prewaveTargetId field for each supplier)
  • GET /public/v2/suppliers/sites/find-by-identifier?prewaveId={targetId} - Get a specific supplier by ID

Perspectives (perspectiveIds):

• Required field - must be provided and must contain at least one perspective ID (cannot be empty array [])
• List of Perspective IDs for which scores should be calculated
• ⚠️ Critical: If perspectiveIds is empty, the configuration will be saved successfully, but no scores will be generated during job execution. The endpoint will not return an error, but the export job will produce no results.
• Scores are calculated for each combination of (target × perspective)
• All specified perspectives must be accessible to the user (validated at execution time)
• Example: If you have 10 targets and 2 perspectives, 20 score calculations will be performed

Components (includeComponents):

• Required field - must be explicitly set to true or false
• When true: Export results include detailed score components and subcomponents
• When false: Only top-level scores and risk levels are included
• Enabling components increases response size but provides granular score breakdowns
• Affects the structure of data returned by GET /public/v1/enterprise-export/scores

Validation and Execution:

Configuration-Time Validation:

• Basic request validation (JSON format, field types)
• Run interval must be one of the valid enum values
• All required fields must be present

Execution-Time Validation:

• Collection access is validated when the job runs (not when configuration is saved)
• Target access is validated during execution
• Perspective access is validated during execution
• If validation fails during execution, the job will fail and errors will be available via GET /public/v1/enterprise-export/scores/errors

After Configuration:

1. Immediate Effect: Configuration is saved immediately upon successful request
2. Job Scheduling: If enabled is true, the job will be scheduled based on:
   • The configured runInterval
   • The time since the last execution (if any)
3. First Execution: If this is a new configuration or the first time enabling:
   • The job will run when the scheduler next checks (typically within an hour)
   • Or immediately if the interval has already elapsed
4. Results Availability: After successful execution:
   • Use GET /public/v1/enterprise-export/scores to retrieve score results
   • Use GET /public/v1/enterprise-export/scores/errors to check for any errors
5. Configuration Updates: Use GET /public/v1/enterprise-export/scores/config to verify your configuration

Best Practices:

• Start Small: Begin with a small set of collections/targets and perspectives to test the configuration
• Monitor Results: Check the scores endpoint after the first execution to verify everything works
• Check Errors: Regularly review the errors endpoint to identify any issues
• Frequency: Choose an appropriate runInterval based on your data freshness requirements
• Components: Only enable includeComponents if you need detailed score breakdowns (increases data size)
• Empty Lists: You can provide empty arrays for collectionIds or targetIds if you only want to use one type. However, perspectiveIds must contain at least one ID - if empty, no scores will be generated.

Important Notes:

• The configuration is user-specific - each user manages their own export configuration
• Jobs run asynchronously - execution may take time depending on the number of targets and perspectives
• Previous configuration is completely replaced - all fields are updated, not merged
• Validation happens at execution time, not configuration time - invalid IDs will cause execution failures
• If a job fails due to access issues, fix the configuration and the next scheduled run will attempt again

Required Permission: ACCESS_ENTERPRISE_EXPORT_API

        Defines the time interval for running the export job.
        Options include SIX_HOURS, TWELVE_HOURS, DAILY, and WEEKLY.
        Defaults to WEEKLY if not specified.

        Indicates whether to include score components and subcomponents in the export result.
        If true, components will be included.

{
  "runInterval": "WEEKLY",
  "enabled": true,
  "collectionIds": [
    123,
    456,
    789
  ],
  "targetIds": [
    101,
    202,
    303,
    102006215
  ],
  "perspectiveIds": [
    1,
    2,
    3
  ]
}

        Defines the time interval for running the export job.
        Options include SIX_HOURS, TWELVE_HOURS, DAILY, and WEEKLY.
        Defaults to WEEKLY if not specified.

        Indicates whether to include score components and subcomponents in the export result.
        If true, components will be included.

{
  "runInterval": "WEEKLY",
  "enabled": true,
  "collectionIds": [
    123,
    456,
    789
  ],
  "targetIds": [
    101,
    202,
    303,
    102006215
  ],
  "perspectiveIds": [
    1,
    2,
    3
  ]
}