📤 Distribution Requests

Management of album distribution requests to digital platforms (DSPs)

Resource Overview

Distribution Requests represent requests to distribute albums to streaming platforms like Spotify, Apple Music, Amazon Music, etc. Each request includes territory configuration, target DSPs and process status.

Base Endpoint
/distribution-requests
Resource Type
distribution-requests
User Scope
Owner-restricted

Schema

Required Attributes

Field Type Description Validations Editable
request-type string Type of distribution request required, in:delivery,update,redelivery,takedown ✓

Auto-managed Attributes

Field Type Description Auto Value Editable
date date Request date Current date System
status string Distribution status pending System

Read-only Attributes

Field Type Description
id string Unique identifier
created-at datetime Creation date
updated-at datetime Last update date

Relationships

Relationship Type Description Required
album BelongsTo Album to distribute Required
countries BelongsToMany Target countries for distribution Required
dsps BelongsToMany Target streaming platforms Required

Smart Creation Logic

Album Completeness Validation

Before creating a Distribution Request, the album must be complete with all required metadata, tracks, artwork, and necessary relationships.

✅ Automatic Assignments

  • • User: Auto-assigned to authenticated user
  • • Date: Auto-assigned to current date
  • • Status: Auto-assigned to "pending" or "preapproved" (for white label users who can "pre-approve" and "reject" Distribution Requests)

🔍 Validations

  • • Album Completeness: Validates complete metadata
  • • Uniqueness: No duplicate requests per album
  • • Request Type: Accepts "delivery", "update", "redelivery" and "takedown"
  • • Update Prerequisites: Update requests require at least one delivery request with "sent" status
  • • User Ownership: Only own albums

API Endpoints

GET /distribution-requests

Get list of distribution requests for the authenticated user

Query Parameters

  • • filter[album]=1 - Filter by specific album
  • • filter[status]=pending - Filter by status
  • • filter[request-type]=delivery - Filter by type
  • • include=album,countries,dsps - Include relationships
  • • page[number]=1&page[size]=20 - Pagination

Success Response

200 OK 
{
  "data": [
    {
      "type": "distribution-requests",
      "id": "1",
      "attributes": {
        "date": "2024-08-21",
        "request-type": "delivery",
        "status": "pending",
        "created-at": "2024-08-21T10:30:00Z",
        "updated-at": "2024-08-21T10:30:00Z"
      },
      "relationships": {
        "album": {
          "data": {
            "type": "albums",
            "id": "1"
          }
        }
      }
    },
    {
      "type": "distribution-requests",
      "id": "2",
      "attributes": {
        "date": "2024-08-20",
        "request-type": "delivery",
        "status": "preapproved",
        "created-at": "2024-08-20T15:45:00Z",
        "updated-at": "2024-08-20T16:30:00Z"
      },
      "relationships": {
        "album": {
          "data": {
            "type": "albums",
            "id": "2"
          }
        }
      }
    }
  ],
  "meta": {
    "page": {
      "currentPage": 1,
      "from": 1,
      "lastPage": 1,
      "perPage": 20,
      "to": 2,
      "total": 2
    }
  }
}
GET /distribution-requests/{id}

Obtener una distribution request específica

Success Response

200 OK 
{
  "data": {
    "type": "distribution-requests",
    "id": "1",
    "attributes": {
      "date": "2024-08-21",
      "request-type": "delivery",
      "status": "pending",
      "created-at": "2024-08-21T10:30:00Z",
      "updated-at": "2024-08-21T10:30:00Z",
      "deleted-at": null
    },
    "relationships": {
      "album": {
        "data": {
          "type": "albums",
          "id": "1"
        }
      }
    }
  }
}
POST /distribution-requests

Crear nueva distribution request

Request Body

{
  "data": {
    "type": "distribution-requests",
    "attributes": {
      "request-type": "delivery"
    },
    "relationships": {
      "album": {
        "data": {
          "type": "albums",
          "id": "1"
        }
      }
    }
  }
}

Success Response

201 Created 
{
  "data": {
    "type": "distribution-requests",
    "id": "3",
    "attributes": {
      "date": "2024-08-21",
      "request-type": "delivery",
      "status": "pending",
      "created-at": "2024-08-21T12:00:00Z",
      "updated-at": "2024-08-21T12:00:00Z",
      "deleted-at": null
    },
    "relationships": {
      "album": {
        "data": {
          "type": "albums",
          "id": "1"
        }
      }
    }
  }
}
POST /distribution-requests/{id}/preapprove

Preapprove a distribution request

Success Response

200 OK 
{
  "data": {
    "type": "distribution-requests",
    "id": "1234",
    "attributes": {
        "status": "pending",
        "request-type": "delivery",
        "date": "2025-07-02",
        "created-at": "2025-07-02T17:40:03+00:00",
        "updated-at": "2026-01-27T19:13:13+00:00"
    }
}
POST /distribution-requests/{id}/reject

Reject a distribution request

Success Response

200 OK 
{
  "data": {
    "type": "distribution-requests",
    "id": "1234",
    "attributes": {
        "status": "rejected",
        "request-type": "delivery",
        "date": "2025-07-02",
        "created-at": "2025-07-02T17:40:03+00:00",
        "updated-at": "2026-01-27T19:13:13+00:00"
    }
}

Distribution Flow

For White Label Users with Preapproval Capabilities

📝

1. Create Request

Submit distribution request with album reference

✋

2. Preapproval / Rejection

Request awaits pre-approval or rejection

⏳

3. Pending Status

If previously pre-approved, request awaits QA approval for distribution

🚀

4. Sent / Rejected

Album sent to DSPs or request rejected

For White Label Users without Preapproval Capabilities

📝

1. Create Request

Submit distribution request with album reference

⏳

2. Pending Status

Request awaits QA approval for distribution

🚀

3. Sent / Rejected

Album sent to DSPs or request rejected

Distribution Status Values

Active States

  • • preapproved - Awaiting for admin user pre-approval / rejection. (Available only for users with preapproval capabilities).
  • • pending - Awaiting QA approval for distribution
  • • sent - Successfully sent to DSPs

Error States

  • • rejected - Request rejected

Use Cases

🎵 Album Distribution

Distribute a completed album to all major streaming platforms

# Create distribution request for album
POST /distribution-requests

# Monitor distribution status
GET /distribution-requests/1

# Include related data
GET /distribution-requests/1?include=album,countries,dsps

🌍 Territory Management

Control which countries and regions receive the distribution

# Get requests with country targeting
GET /distribution-requests?include=countries

# Filter by specific territories
GET /distribution-requests?filter[countries]=1,2,3

📊 Status Monitoring

Track distribution progress and handle approvals

# Monitor pending requests
GET /distribution-requests?filter[status]=pending

# Check sent distributions
GET /distribution-requests?filter[status]=sent

# Review rejected distributions
GET /distribution-requests?filter[status]=rejected