---
title: "Attachment (Services)"
description: "A file, whether it's stored on Planning Center or linked from another location."
---

> Documentation Index
> Fetch the complete documentation index at: https://planningcenterkit.mackenly.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Attachment (Services)

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

| Property | Value |
| --- | --- |
| Product | [Services](/reference/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](https://api.planningcenteronline.com/docs/apps/services/versions/2018-11-01/vertices/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](/guides/querying/); 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](#file-upload-identifier). |
| `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` {#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](/reference/services/person/) | No |
| `attachable` | To one | [Plan](/reference/services/plan/) | No |
| `attachment_types` | To many | [AttachmentType](/reference/services/attachment-type/) | No |
| `created_by` | To one | [Person](/reference/services/person/) | No |
| `updated_by` | To one | [Person](/reference/services/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](/reference/services/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](/reference/services/zoom/) | Collection |  | Yes |

## Writing

| Property | Value |
| --- | --- |
| Create | Yes, `create()` on `attachments` on [Arrangement](/reference/services/arrangement/), `attachments` on [Item](/reference/services/item/), `attachments` on [Key](/reference/services/key/), `attachments` on [Media](/reference/services/media/), `attachments` on [Plan](/reference/services/plan/), `attachments` on [ServiceType](/reference/services/service-type/), `attachments` on [Song](/reference/services/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](/guides/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

```ts
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;
```

Source: https://planningcenterkit.mackenly.com/reference/services/attachment/index.mdx
