API
⌘K
My Developer Account

Arrangement

Each arrangement belongs to a song and is a different version of that song.

Example Request

curl https://api.planningcenteronline.com/services/v2/songs/{song_id}/arrangements

View in API Explorer →

Example Object

{
  "type": "Arrangement",
  "id": "1",
  "attributes": {
    "archived_at": "2000-01-01T12:00:00Z",
    "bpm": 1.42,
    "chord_chart": "string",
    "chord_chart_chord_color": 1,
    "chord_chart_columns": 1,
    "chord_chart_font": "string",
    "chord_chart_font_size": 1,
    "chord_chart_key": "string",
    "created_at": "2000-01-01T12:00:00Z",
    "has_chord_chart": true,
    "has_chords": true,
    "length": 1,
    "lyrics": "string",
    "lyrics_enabled": true,
    "meter": "string",
    "name": "string",
    "notes": "string",
    "number_chart_enabled": true,
    "numeral_chart_enabled": true,
    "print_margin": "string",
    "print_orientation": "string",
    "print_page_size": "string",
    "sequence": [],
    "sequence_full": [],
    "sequence_short": [],
    "updated_at": "2000-01-01T12:00:00Z"
  },
  "relationships": {
    "updated_by": {
      "data": {
        "type": "Person",
        "id": "1"
      }
    },
    "created_by": {
      "data": {
        "type": "Person",
        "id": "1"
      }
    },
    "song": {
      "data": {
        "type": "Song",
        "id": "1"
      }
    }
  }
}

Attributes

Name Type Description
archived_at date_time
bpm float
chord_chart string A string of lyrics and chords. Supports standard and ChordPro formats.
chord_chart_chord_color integer
chord_chart_columns integer
chord_chart_font string
chord_chart_font_size integer Possible Values: `10`, `11`, `12`, `13`, `14`, `15`, `16`, `18`, `20`, `22`, `24`, `26`, `28`, `32`, `36`, `42`, `48`
chord_chart_key string
created_at date_time
has_chord_chart boolean
has_chords boolean
id primary_key
length integer
lyrics string
lyrics_enabled boolean
meter string Possible Values: - `2/2` - `2/4` - `3/2` - `3/4` - `4/2` - `4/4` - `5/4` - `6/4` - `3/8` - `6/8` - `7/4` - `7/8` - `9/8` - `12/4` - `12/8`
name string
notes string
number_chart_enabled boolean
numeral_chart_enabled boolean
print_margin string Possible Values: - `0.0in` - `0.25in` - `0.5in` - `0.75in` - `1.0in`
print_orientation string Possible Values: - `Portrait` - `Landscape`
print_page_size string Possible Values: - `Widescreen (16x9)` - `Fullscreen (4x3)` - `A4` - `Letter` - `Legal` - `11x17`
sequence array An array of strings containing a label and a number describing the section: ['Verse 1', 'Chorus 1', 'Verse 2']
sequence_full array
sequence_short array
updated_at date_time

Relationships

Name Type Association Type Note
updated_by Person to_one
created_by Person to_one
song Song to_one

Can Include

Parameter Value Description Assignable
include keys include associated keys
include sections include associated sections

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/{song_id}/arrangements

Reading

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

Creating

HTTP Method Endpoint Assignable Attributes
POST /services/v2/songs/{song_id}/arrangements
  • bpm
  • chord_chart
  • chord_chart_chord_color
  • chord_chart_columns
  • chord_chart_font
  • chord_chart_font_size
  • chord_chart_key
  • length
  • lyrics_enabled
  • meter
  • name
  • notes
  • number_chart_enabled
  • numeral_chart_enabled
  • print_margin
  • print_orientation
  • print_page_size
  • sequence

Updating

HTTP Method Endpoint Assignable Attributes
PATCH /services/v2/songs/{song_id}/arrangements/{id}
  • bpm
  • chord_chart
  • chord_chart_chord_color
  • chord_chart_columns
  • chord_chart_font
  • chord_chart_font_size
  • chord_chart_key
  • length
  • lyrics_enabled
  • meter
  • name
  • notes
  • number_chart_enabled
  • numeral_chart_enabled
  • print_margin
  • print_orientation
  • print_page_size
  • sequence

Deleting

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

Actions

HTTP Method Endpoint Description
POST https://api.planningcenteronline.com/services/v2/songs/{song_id}/arrangements/{arrangement_id}/assign_tags Used to assign tags to an arrangement.

Associations

HTTP Method Endpoint Returns Details Filter By
GET https://api.planningcenteronline.com/services/v2/songs/{song_id}/arrangements/{arrangement_id}/attachments Attachment
GET https://api.planningcenteronline.com/services/v2/songs/{song_id}/arrangements/{arrangement_id}/keys Key
GET https://api.planningcenteronline.com/services/v2/songs/{song_id}/arrangements/{arrangement_id}/sections ArrangementSections
GET https://api.planningcenteronline.com/services/v2/songs/{song_id}/arrangements/{arrangement_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}/arrangement Item
GET https://api.planningcenteronline.com/services/v2/songs/{song_id}/arrangements Song