Skip to content

Attachment (Services)

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

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

Property Value
Product Services (pco.services, API version 2018-11-01)
Resource type Attachment
TypeScript Services.Attachment, attributes Services.AttachmentAttributes, schema Services.AttachmentSchema
Planning Center path /services/v2/media/{media_id}/attachments
Planning Center docs Attachment

How to reach it

Client path Returns Filters Create
pco.services.songs.id(songId).arrangements.id(arrangementId).attachments Collection Yes
pco.services.songs.id(songId).last_scheduled_item.id(itemId).attachments Collection Yes
pco.services.songs.id(songId).last_scheduled_item.id(itemId).selected_attachment Collection No
pco.services.songs.id(songId).last_scheduled_item.id(itemId).selected_background Collection No
pco.services.songs.id(songId).arrangements.id(arrangementId).keys.id(keyId).attachments Collection Yes
pco.services.media.id(mediaId).attachments Collection Yes
pco.services.series.id(seriesId).plans.id(planId).all_attachments Collection attachable_type, extensions No
pco.services.series.id(seriesId).plans.id(planId).attachments Collection Yes
pco.services.service_types.id(serviceTypeId).attachments Collection Yes
pco.services.songs.id(songId).attachments Collection Yes

From a collection, .id(attachmentId) addresses one Attachment: pco.services.media.id(mediaId).attachments.id(attachmentId). Collections support where, include, order, and pagination; single resources have get().

Attributes

On Services.AttachmentAttributes. Every resource also has id and type ('Attachment') next to its attributes.

Name Type Description
allow_mp3_download boolean | null
attachable_type string | null
content string | null
content_type string | null
created_at string | null
deleted_at string | null
display_name string | null
downloadable boolean | null
file_size number | null
file_upload_identifier string | null See details.
filename string | null
filetype string | null
has_preview boolean | null
import_to_item_details boolean | null
licenses_purchased number | null
licenses_remaining number | null
licenses_used number | null
linked_url string | null
page_order string | null The shared order of pages to display for this file in Music Stand. Page numbers start at 1 and 0 inserts a blank page. Blank pages are left out of responses unless the request includes blank_pages=true. A person can override this for themselves with a PageOrder.
pco_type string | null
remote_link string | null
streamable boolean | null
thumbnail_url string | null
transposable boolean | null
updated_at string | null
url string | null
web_streamable boolean | null

Attribute details

file_upload_identifier

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

Relationships and includes

Side-load with include() (or get({ include })) and read with related(resource, name): zooms.

Relationship Type To Includable
administrator To one Person No
attachable To one Plan No
attachment_types To many AttachmentType No
created_by To one Person No
updated_by To one Person No

Querying

Where

where(field, value) for equality; where(field, op, value) with the operators listed.

Field Value type Operators
administrator_id string | number Equality only
attachable_type string Equality only
licenses_purchased number Equality only

Order

order(...) accepts these fields, ascending, or descending with a - prefix: attachable_type, created_at, deleted_at, filename, filetype, size.

Filters

filter(...) names depend on the edge you query through:

Edge Filters
all_attachments on Plan attachable_type, extensions

Edges

Follow these from one Attachment, ref = pco.services.media.id(mediaId).attachments.id(attachmentId):

Edge Leads to Returns Filters Create
ref.zooms Zoom Collection Yes

Writing

Property Value
Create Yes, create() on attachments on Arrangement, attachments on Item, attachments on Key, attachments on Media, attachments on Plan, attachments on ServiceType, attachments on Song
Update Yes, update() on a reference
Delete Yes, delete() on a reference

Create attributes

Typed as Services.AttachmentSchema['create'].

Attribute Type
attachment_type_ids string[]
content string | null
file_upload_identifier string | null
filename string | null
import_to_item_details boolean | null
page_order string | null
remote_link string | null
song_part unknown

Update attributes

Typed as Services.AttachmentSchema['update'].

Attribute Type
attachment_type_ids string[]
content string | null
file_upload_identifier string | null
filename string | null
import_to_item_details boolean | null
page_order string | null
remote_link string | null
song_part unknown

See Writing data.

Actions

Run with ref.action(name, body?). Bodies are untyped: see Planning Center’s docs for each action.

Action Path Description
open POST /services/v2/media/{media_id}/attachments/{attachment_id}/open This action is used to get the attachment file URL.
preview POST /services/v2/media/{media_id}/attachments/{attachment_id}/preview This action is used to get a reduced resolution (preview) version of the attachment.

Example

import type { Services } from '@mackenly/planningcenterkit';

const mediaId = '1'; // Media id

const page = await pco.services.media.id(mediaId).attachments.order('attachable_type').perPage(25).list();
const items: Services.Attachment[] = page.data;

Type to search…

↑↓ navigate↵ selectEsc close