Working with Projects

A Project groups Conversations for one job, claim, or installation. All their recordings, photos, and documents are then in one place. If a job has only one Conversation, a Project is not necessary. Go to Creating a Conversation.

Create a Project

POST /v1/projects
Authorization: Bearer {access_token}
Content-Type: application/json

{
  "name": "123 Main St — Kitchen Remodel",
  "externalId": "job-48213",
  "status": "InProgress",
  "tags": ["Priority"],
  "address": "123 Main St, Springfield, IL",
  "contactIds": ["contact-uuid"]
}

Only name is required. Each Project name must be unique in your organization. If the name exists, you get 400 Project name already exists.
externalId is your own ID for the Project, for example a job number in your system.
status is NotStarted, InProgress, or Completed. The default is NotStarted.
tags are tag names. LiveSwitch creates a tag if it does not exist.
contactIds must be Contacts in the same organization.

The response has four URLs:

URL	Who can open it
`projectUrl`	Users who log in to LiveSwitch.
`projectEmbeddedUrl`	The same, without the header and navigation. Use it in an iframe.
`projectShareUrl`	Anyone who has the URL. No login, read-only. Every Project has it as soon as it exists.
`projectEmbeddedShareUrl`	The same, without the header and navigation.

Add Conversations to a Project

Link a Conversation to a Project when you create the Conversation. Use one of these fields in POST /v1/conversations:

Field	What it does
`projectId`	Links to the Project with this ID. If you send it, LiveSwitch ignores `projectExternalId`.
`projectExternalId`	Links to the Project with this `externalId`. If no Project has it, the request fails and nothing is created.
`projectAutoCreate`	If `true` and no Project has the `projectExternalId`, LiveSwitch creates the Project. `projectExternalId` is then required.
`projectName`	The name for an auto-created Project. The default is `Project [external id]`.

See Creating a Conversation for the full request.

Update a Project

PUT /v1/projects/{id}
Authorization: Bearer {access_token}
Content-Type: application/json

{
  "status": "Completed",
  "tags": ["Priority", "Reviewed"]
}

Send only the fields that you want to change. Two fields replace the full list:

tags replaces all tags on the Project.
contactIds replaces all Contacts on the Project.

To keep the current tags or Contacts, do not send these fields.

List Projects

GET /v1/projects?status=InProgress&page=1&pageSize=25
Authorization: Bearer {access_token}

Parameter	What it does
`status`	Returns only Projects with this status.
`externalId`	Returns the Project with this `externalId`.
`contactId`	Returns only Projects with this Contact.
`page`, `pageSize`, `where`, `order`	Pages, filters, and sort order. See List, filter, and sort.

Where to go next

Run an AI report on all the media in a Project: Sparky AI Reports.
Show a Project in your application: Embedding media in a CRM.