Introduction
The SongBoard API is a RESTful API, that allows you automate tasks in SongBoard via code.
With the SongBoard API, you can control your SongBoard portal through your own (and 3rd party) applications such as managing users, events and more.
This documentation will guide you through the endpoints available in the API, to help you to programmatically manage your SongBoard DJ portal.
The API URL
This is the API URL you will use when making REST calls to the API:
Authentication
To use the SongBoard API, you need to authenticate your requests with an API key. You can create and manage your API keys on the "Automation" page using an admin SongBoard account.
Once you have your API key, you must include it in the header of all your API requests using a basic authorization header. The API Key must be set to the username value (the basic authorization password value should be empty).
It's important to keep your API keys secure. Avoid storing your secret keys in publicly accessible places such as source control or in client side code. Instead, you should use secret management services such as Azure Key Vault and perform regular rotations.
All API requests to SongBoard must be made over HTTPS to ensure requests are secure in-transit. Requests made over HTTP or without proper authentication will fail.
API Key
You will need to replace the API key template <API_KEY> above with your own.
API keys can be generated on the "Automation" page using an admin account.
Events
The Event Object
Attributes
id
stringThe unique identifier for this object.
name
stringThe name of the Event.
starts_at
stringThe datetime when the Event starts.
ends_at
stringThe datetime when the Event ends.
dj_arrives_at
stringThe datetime when the DJ should arrive at the Event.
created_at
stringThe datetime that the Event was created.
updated_at
stringThe datetime that the Event was last edited.
Retrieve an Event
Returns
An Event object.
Create an Event
Parameters
name
stringThe name of the Event.
starts_at
stringThe datetime when the Event starts.
ends_at
stringThe datetime when the Event ends.
dj_arrives_at
stringThe datetime when the DJ should arrive at the Event.
template_id
stringThe ID of the Event Template to start this Event from.
join_as_dj
stringWhether or not the user associated with your API Key should join this event as a DJ.
join_as_dj
stringWhether or not the user associated with your API Key should join this event as a DJ.
hosts
CreateEventUser[]The hosts to invite to this event after it is created. Expects an object with first_name (optional), last_name (optional), email (required), and send_email_invitation (defaults to false).
djs
CreateEventUser[]The DJs to invite to this event after it is created. Expects an object with first_name (optional), last_name (optional), email (required), and send_email_invitation (defaults to false).
Returns
An Event object.
Search for Events
Parameters
page_size
numberThe number of items to return (must be between 1 and 100).
page_number
numberThe page offset to apply to the query (will skip page_number * page_size items).
query
numberThe query (searches all searchable fields on the object).
order_by
Array<Order>How the results should be ordered. The Order object has two
properties id for specifying the name of the field to order by and dir to specify the direction (either desc or asc).
Returns
count
numberThe total count of object that match this search (even those who are not returned).
results
Array<Event>An Array of Event objects that are the results of your search.
Users
In SongBoard, there are four types of users: guests, clients, members, and admins.
Admins have full control to create events, update the subscription, and change any workspace settings (e.g., branding, company name, etc...)
Members have access to events where they are assigned as the DJ, but cannot manage the SongBoard workspace or create their own events.
Clients are external users to your company who are invited to plan events. This is the role that is used when you invite hosts to an event. They have edit permissions to most event details, but they have less permissions than a DJ.
Guests are external users to your company who are invited to events. They have limited access (their access can be configured using card permissions).
The User Object
Attributes
id
stringThe unique identifier for this object.
role
stringThe user type this user is. guest for a guest, client for a client, member for a member, and admin for an admin.
The email address associated with the account (used for authentication and email notifications).
first_name
stringThe User's first name (can be null if not set).
last_name
stringThe User's last name (can be null if not set).
created_at
stringThe datetime that the User's account was created.
updated_at
stringThe datetime that the User's account was last edited.
Get Your User
This endpoint returns the User associated with your API Key.
Returns
A User object.
Retrieve a User
This endpoint returns the User associated with the given user's id.
Returns
A User object.
Workspace
In SongBoard, your workspace represents your business and all the customization that goes along with it.
That includes branding (colors, logo), company name, subscription information, and more.
The Workspace Object
Attributes
id
stringThe unique identifier for this object.
name
stringThe name of the company who owns this Workspace.
website_url
stringA link to the company's website.
primary_color
stringThe company's brand color.
created_at
stringThe datetime that the Workspace was created.
updated_at
stringThe datetime that the Workspace was last edited.
Get Your Workspace
This endpoint returns the Workspace associated with your API Key.
Returns
A Workspace object.