> ## Documentation Index
> Fetch the complete documentation index at: https://apidocs.royalti.io/llms.txt
> Use this file to discover all available pages before exploring further.

# DDEX Integration Guide

> Generate and deliver DDEX messages for digital music distribution to DSPs

## Overview

DDEX (Digital Data Exchange) is the industry-standard XML format for communicating music metadata and rights information to Digital Service Providers (DSPs). The Royalti.io API supports generating ERN, MEAD, and PIE messages.

## Authentication

<Note>
  DDEX endpoints require authentication. Some providers also use additional DDEX-specific authentication.
</Note>

## Message Types

### ERN (Electronic Release Notification)

Used for delivering release metadata to DSPs:

```javascript Node.js theme={null}
const response = await fetch('https://api.royalti.io/ddex/ern/generate', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${token}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    productId: 'prod-123',
    providerId: 'spotify',
    messageType: 'NewReleaseMessage'
  })
});
```

### MEAD (Music Enrichment and Description)

Rich metadata for enhanced discovery:

```javascript Node.js theme={null}
const response = await fetch('https://api.royalti.io/ddex/mead/generate', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${token}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    assetId: 'asset-123',
    providerId: 'apple-music',
    includeCredits: true
  })
});
```

### PIE (Party Information Exchange)

Rights holder information:

```javascript Node.js theme={null}
const response = await fetch('https://api.royalti.io/ddex/pie/generate', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${token}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    artistId: 'artist-123',
    providerId: 'universal'
  })
});
```

## DDEX Workflow

<Steps>
  <Step title="Configure Provider">
    Set up delivery credentials and preferences for each DSP.

    ```javascript Node.js theme={null}
    const response = await fetch('https://api.royalti.io/ddex/providers/', {
      method: 'POST',
      headers: {
        'Authorization': `Bearer ${token}`,
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        name: 'Spotify',
        deliveryMethod: 'SFTP',
        credentials: {
          host: 'sftp.spotify.com',
          username: 'your-username',
          password: 'your-password'
          // Credentials are automatically encrypted using PostgreSQL pgcrypto
        }
      })
    });
    ```

    <Info>
      All provider credentials (FTP passwords, API keys, SFTP credentials) are automatically encrypted at rest using PostgreSQL pgcrypto with PGP symmetric encryption. No plaintext credentials are stored in the database.
    </Info>
  </Step>

  <Step title="Generate Message">
    Create DDEX XML from your release data.

    <Note>
      The system automatically validates against XSD schemas and applies business rules.
    </Note>
  </Step>

  <Step title="Validate Message">
    Ensure compliance with DDEX standards.

    ```javascript Node.js theme={null}
    const response = await fetch(`https://api.royalti.io/ddex/messages/${messageId}/validate`, {
      method: 'POST',
      headers: {
        'Authorization': `Bearer ${token}`
      }
    });
    ```
  </Step>

  <Step title="Deliver to Provider">
    Send via SFTP, FTP, API, or HTTP depending on provider requirements.

    ```javascript Node.js theme={null}
    const response = await fetch(`https://api.royalti.io/ddex/messages/${messageId}/deliver`, {
      method: 'POST',
      headers: {
        'Authorization': `Bearer ${token}`
      }
    });
    ```
  </Step>
</Steps>

## Provider-Specific Configuration

Different DSPs have different requirements:

```javascript Node.js theme={null}
const providerConfigs = {
  spotify: {
    deliveryMethod: 'SFTP',
    ernProfile: 'ERN-4',
    territories: ['Worldwide']
  },
  appleMusic: {
    deliveryMethod: 'API',
    ernProfile: 'ERN-4.1',
    requiresPreview: true
  },
  tidal: {
    deliveryMethod: 'HTTP',
    ernProfile: 'ERN-3.8.2',
    audioQuality: 'lossless'
  }
};
```

## Best Practices

### Territory Management

<Warning>
  Ensure territory configurations don't overlap and cover 100% of intended distribution.
</Warning>

### Deal Configuration

Set up usage rights and release dates:

```javascript Node.js theme={null}
const dealConfig = {
  territories: ['US', 'CA', 'GB'],
  usageType: 'PermanentDownload',
  startDate: '2024-06-01',
  priceCategory: 'Mid'
};
```

### Error Handling

Implement comprehensive validation:

```javascript Node.js theme={null}
async function generateAndValidateDDEX(productId, providerId) {
  try {
    // Generate message
    const message = await generateERN(productId, providerId);

    // Validate
    const validation = await validateMessage(message.id);

    if (!validation.isValid) {
      console.error('Validation errors:', validation.errors);
      return { success: false, errors: validation.errors };
    }

    // Deliver
    await deliverMessage(message.id);

    return { success: true, messageId: message.id };
  } catch (error) {
    console.error('DDEX generation failed:', error);
    throw error;
  }
}
```

## Related Endpoints

* [Generate ERN Message](/api-reference/ddex/post-ddex-ern-generate)
* [Validate DDEX Message](/api-reference/ddex/post-ddex-messages-id-validate)
* [Deliver to Provider](/api-reference/ddex/post-ddex-delivery-deliver-id)
* [Configure Provider](/api-reference/ddex/post-ddex-tenant-providers)