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,
    "attachable_type": "string",
    "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
attachable_type string
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
attachable_type where[attachable_type] string

Query on a specific attachable_type

 ?where[attachable_type]=string
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 POSTing 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 POSTing 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

    filter attachments by their attachable_type as specified in the attachable_type parameter. Default: ["ServiceType", "Plan", "Item", "Media", "Song", "Arrangement", "Key"]. e.g. ?filter=attachable_type&attachable_type=Plan,ServiceType

  • extensions

    filter to attachments with a file extension specified in the extensions parameter. e.g. ?filter=extensions&extensions=pdf,txt
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