API
⌘K
My Developer Account

Song

A song

Example Request 

curl https://api.planningcenteronline.com/services/v2/songs

View in API Explorer →

Example Object 

{
  "type": "Song",
  "id": "1",
  "attributes": {
    "admin": "string",
    "author": "string",
    "ccli_number": 1,
    "copyright": "string",
    "created_at": "2000-01-01T12:00:00Z",
    "hidden": true,
    "last_scheduled_at": "2000-01-01T12:00:00Z",
    "last_scheduled_short_dates": "string",
    "notes": "string",
    "themes": "string",
    "title": "string",
    "updated_at": "2000-01-01T12:00:00Z"
  },
  "relationships": {}
}

Attributes

Name Type Description
admin string
author string
ccli_number integer
copyright string
created_at date_time
hidden boolean
id primary_key
last_scheduled_at date_time
last_scheduled_short_dates string
notes string
themes string
title string

The name of the song.

When setting this value on a create you can pass a CCLI number and Services will fetch the song metadata for you.
updated_at date_time

Order By

Parameter Value Type Description
order created_at string

prefix with a hyphen (-created_at) to reverse the order
order last_scheduled_at string

prefix with a hyphen (-lastscheduledat) to reverse the order
order title string

prefix with a hyphen (-title) to reverse the order
order updated_at string

prefix with a hyphen (-updated_at) to reverse the order

Query By

Name Parameter Type Description Example
author where[author] string

Query on a specific author

 ?where[author]=string
ccli_number where[ccli_number] integer

Query on a specific ccli_number

 ?where[ccli_number]=1
hidden where[hidden] boolean

Query on a specific hidden

 ?where[hidden]=true
themes where[themes] string

Query on a specific themes

 ?where[themes]=string
title where[title] string

Query on a specific title

 ?where[title]=string

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/songs

Reading

HTTP Method Endpoint
GET /services/v2/songs/{id}

Creating

HTTP Method Endpoint Assignable Attributes
POST /services/v2/songs
  • title
  • admin
  • author
  • copyright
  • ccli_number
  • hidden
  • themes

Updating

HTTP Method Endpoint Assignable Attributes
PATCH /services/v2/songs/{id}
  • title
  • admin
  • author
  • copyright
  • ccli_number
  • hidden
  • themes

Deleting

HTTP Method Endpoint
DELETE /services/v2/songs/{id}

Actions

HTTP Method Endpoint Description
POST https://api.planningcenteronline.com/services/v2/songs/{song_id}/assign_tags

Used to assign tags to a song.

Associations

HTTP Method Endpoint Returns Details Filter By
GET https://api.planningcenteronline.com/services/v2/songs/{song_id}/arrangements Arrangement
GET https://api.planningcenteronline.com/services/v2/songs/{song_id}/attachments Attachment
GET https://api.planningcenteronline.com/services/v2/songs/{song_id}/last_scheduled_item Item

The Song's most recently scheduled Item in a given Service Type. Requires a service_type query parameter. e.g. ?service_type=789
GET https://api.planningcenteronline.com/services/v2/songs/{song_id}/song_schedules SongSchedule
  • after

    Fetch schedules after the included after iso8601 date param. e.g. ?filter=after&after=2020-01-01T00:00:00Z

  • before

    Fetch schedules before the included before iso8601 date param. e.g. ?filter=before&before=2020-01-01T00:00:00Z

  • most_recent

    Fetch the N most recent schedules by also including an amount param. e.g. ?filter=most_recent&amount=3

  • most_recent_with_upcoming

    Fetch the N most recent schedules by also including an amount param. Includes upcoming dates. e.g. ?filter=most_recent_with_upcoming&amount=3

  • three_most_recent
GET https://api.planningcenteronline.com/services/v2/songs/{song_id}/tags Tag

Belongs To

HTTP Method Endpoint Association Details Filter By
GET https://api.planningcenteronline.com/services/v2/service_types/{service_type_id}/plans/{plan_id}/items/{item_id}/song Item
GET https://api.planningcenteronline.com/services/v2/songs Organization