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 (-last_scheduled_at) 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
  • 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