API
⌘K
My Developer Account

Attachment

A file, whether it's stored on Planning Center or linked from another location.

Example Request

curl https://api.planningcenteronline.com/services/v2/media/{media_id}/attachments

View in API Explorer →

Example Object

{
  "type": "Attachment",
  "id": "1",
  "attributes": {
    "allow_mp3_download": true,
    "content": "string",
    "content_type": "string",
    "created_at": "2000-01-01T12:00:00Z",
    "deleted_at": "2000-01-01T12:00:00Z",
    "display_name": "string",
    "downloadable": true,
    "file_size": 1,
    "file_upload_identifier": "string",
    "filename": "string",
    "filetype": "string",
    "has_preview": true,
    "import_to_item_details": true,
    "licenses_purchased": 1,
    "licenses_remaining": 1,
    "licenses_used": 1,
    "linked_url": "string",
    "page_order": "string",
    "pco_type": "string",
    "remote_link": "string",
    "streamable": true,
    "thumbnail_url": "string",
    "transposable": true,
    "updated_at": "2000-01-01T12:00:00Z",
    "url": "string",
    "web_streamable": true
  },
  "relationships": {
    "attachable": {
      "data": {
        "type": "Plan",
        "id": "1"
      }
    },
    "attachment_types": {
      "data": [
        {
          "type": "AttachmentType",
          "id": "1"
        }
      ]
    },
    "created_by": {
      "data": {
        "type": "Person",
        "id": "1"
      }
    },
    "updated_by": {
      "data": {
        "type": "Person",
        "id": "1"
      }
    },
    "administrator": {
      "data": {
        "type": "Person",
        "id": "1"
      }
    }
  }
}

Attributes

Name Type Description
allow_mp3_download boolean
content string
content_type string
created_at date_time
deleted_at date_time
display_name string
downloadable boolean
file_size integer
file_upload_identifier string Planning Center File UUID. Required only when creating a file attachment. See the "File Uploads" section of the API documentation for more information. Only available when requested with the `?fields` param
filename string
filetype string
has_preview boolean
id primary_key
import_to_item_details boolean
licenses_purchased integer
licenses_remaining integer
licenses_used integer
linked_url string
page_order string
pco_type string
remote_link string
streamable boolean
thumbnail_url string
transposable boolean
updated_at date_time
url string
web_streamable boolean

Relationships

Name Type Association Type Note
attachable Plan to_one Type will be the type of resource to which it is attached.
attachment_types AttachmentType to_many
created_by Person to_one
updated_by Person to_one
administrator Person to_one

Can Include

Parameter Value Description Assignable
include zooms include associated zooms

Order By

Parameter Value Type Description
order attachable_type string prefix with a hyphen (-attachable_type) to reverse the order
order created_at string prefix with a hyphen (-created_at) to reverse the order
order deleted_at string prefix with a hyphen (-deleted_at) to reverse the order
order filename string prefix with a hyphen (-filename) to reverse the order
order filetype string prefix with a hyphen (-filetype) to reverse the order
order size string prefix with a hyphen (-size) to reverse the order

Query By

Name Parameter Type Description Example
administrator_id where[administrator_id] integer Query on a related administrator ?where[administrator_id]=1
licenses_purchased where[licenses_purchased] integer Query on a specific licenses_purchased ?where[licenses_purchased]=1

Pagination

Name Parameter Type Description
per_page per_page integer how many records to return per page (min=1, max=100, default=25)
offset offset integer get results from given offset

Endpoints

Listing

HTTP Method Endpoint
GET /services/v2/media/{media_id}/attachments

Reading

HTTP Method Endpoint
GET /services/v2/media/{media_id}/attachments/{id}

Creating

HTTP Method Endpoint Assignable Attributes
POST /services/v2/songs/{song_id}/arrangements/{arrangement_id}/attachments
  • attachment_type_ids
  • content
  • file_upload_identifier
  • filename
  • import_to_item_details
  • remote_link
  • page_order

Updating

HTTP Method Endpoint Assignable Attributes
PATCH /services/v2/media/{media_id}/attachments/{id}
  • attachment_type_ids
  • content
  • file_upload_identifier
  • filename
  • import_to_item_details
  • remote_link
  • page_order

Deleting

HTTP Method Endpoint
DELETE /services/v2/media/{media_id}/attachments/{id}

Actions

HTTP Method Endpoint Description
POST https://api.planningcenteronline.com/services/v2/media/{media_id}/attachments/{attachment_id}/open This action is used to get the attachment file URL. It is accessed by `POST`ing to `.../attachments/1/open` This will generate the URL and return it in the `attachment_url` attribute of the `AttachmentActivity`.
POST https://api.planningcenteronline.com/services/v2/media/{media_id}/attachments/{attachment_id}/preview This action is used to get a reduced resolution (preview) version of the attachment. It is accessed by `POST`ing to `.../attachments/1/preview` This will generate the URL and return it in the `attachment_url` attribute of the `AttachmentActivity`. The `has_preview` attribute of an `Attachment` indicates if a preview is available. When a preview is not available this action will return a `Not Found` error with a status code of `404`.

Associations

HTTP Method Endpoint Returns Details Filter By
GET https://api.planningcenteronline.com/services/v2/media/{media_id}/attachments/{attachment_id}/zooms Zoom

Belongs To

HTTP Method Endpoint Association Details Filter By
GET https://api.planningcenteronline.com/services/v2/songs/{song_id}/arrangements/{arrangement_id}/attachments Arrangement
GET https://api.planningcenteronline.com/services/v2/service_types/{service_type_id}/plans/{plan_id}/items/{item_id}/attachments Item
GET https://api.planningcenteronline.com/services/v2/service_types/{service_type_id}/plans/{plan_id}/items/{item_id}/selected_attachment Item
GET https://api.planningcenteronline.com/services/v2/service_types/{service_type_id}/plans/{plan_id}/items/{item_id}/selected_background Item
GET https://api.planningcenteronline.com/services/v2/songs/{song_id}/arrangements/{arrangement_id}/keys/{key_id}/attachments Key
GET https://api.planningcenteronline.com/services/v2/media/{media_id}/attachments Media
GET https://api.planningcenteronline.com/services/v2/service_types/{service_type_id}/plans/{plan_id}/all_attachments Plan
  • attachable_type
  • extensions
GET https://api.planningcenteronline.com/services/v2/service_types/{service_type_id}/plans/{plan_id}/attachments Plan
GET https://api.planningcenteronline.com/services/v2/service_types/{service_type_id}/attachments ServiceType
GET https://api.planningcenteronline.com/services/v2/songs/{song_id}/attachments Song