VSCO Job Worksheets API
The Job Worksheets API from VSCO — 2 operation(s) for job worksheets.
OpenAPI Specification
openapi: 3.0.0
info:
title: VSCO Workspace Brands Job Worksheets API
termsOfService: https://terms-of-service.vsco.page/
description: This API is for interacting with a single Studio using <a href="https://workspace.vsco.co/settings/api" target="_blank">an API Key</a>.
contact:
name: VSCO Workspace Support
url: https://help.workspace.vsco.co/
email: workspace-support@vsco.co
version: v2.0.0
x-logo:
url: https://workspace.vsco.co/static/Images/Public/Logo.Black.vsco.svg
altText: VSCO Workspace
servers:
- url: https://tave.io/v2
description: Legacy Táve API production environment
- url: https://workspace.vsco.co/api/v2
description: Workspace API production environment
security:
- ApiKeyAuth: []
- BearerAuth: []
tags:
- name: Job Worksheets
paths:
/job/-/worksheet:
post:
summary: Create a Job using a Worksheet
description: 'Jobs are complex entities that have many dependent entities. That causes an issue to arrise when there is an error creating a dependent entity, causing your Job to be invalid and requiring you to go through and delete each item you already created.
The Job Worksheet allows you to create a Job with its primary dependent entities in one request that will rollback all of the newly created entities automatically as one transaction if the request fails.'
operationId: createResourceJobWorksheet
tags:
- Job Worksheets
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/JobWorksheet'
responses:
'201':
description: Job Worksheet response.
content:
application/json:
schema:
$ref: '#/components/schemas/JobWorksheet'
'400':
$ref: '#/components/responses/validationError'
'429':
$ref: '#/components/responses/tooManyRequestsError'
/job/{jobId}/worksheet:
get:
summary: Get a Job Worksheet on a given Job
operationId: getResourceJobWorksheet
tags:
- Job Worksheets
parameters:
- $ref: '#/components/parameters/jobIdInPath'
responses:
'200':
description: Fetch a Job Worksheet entity on a specific job
content:
application/json:
schema:
$ref: '#/components/schemas/JobWorksheet'
'400':
$ref: '#/components/responses/validationError'
'429':
$ref: '#/components/responses/tooManyRequestsError'
components:
schemas:
Note:
title: Note
description: Additional notes about a specific entity.
type: object
required:
- contentHtml
properties:
links:
$ref: '#/components/schemas/Links'
id:
$ref: '#/components/schemas/Id'
created:
$ref: '#/components/schemas/ServerTimestamp'
modified:
$ref: '#/components/schemas/ServerTimestamp'
hidden:
$ref: '#/components/schemas/IsHidden'
authorId:
$ref: '#/components/schemas/NullableId'
contactId:
$ref: '#/components/schemas/NullableId'
contentHtml:
type: string
minLength: 1
maxLength: 1000000000
nullable: true
date:
$ref: '#/components/schemas/NullableDate'
jobId:
$ref: '#/components/schemas/NullableId'
Link:
title: Hypermedia Link Relationship
description: 'The target URL indicated in the `href` property is related to the
current resource according to the defined semantics of the link
property name.'
type: object
required:
- href
properties:
href:
description: The hypertext reference to the API resource at tave.io.
type: string
format: uri
managerHref:
description: The URL to this item inside the Manager application at workspace.vsco.co.
type: string
format: uri
clientHref:
description: The URL to this item in Client Access, if available.
type: string
format: uri
NullableTime:
title: A time that could be null instead
description: A time string using 24-hour format (seconds are ignored)
type: string
format: time
nullable: true
example: '14:00:00'
CustomFieldValue:
title: Custom Field Value
type: object
required:
- fieldId
properties:
id:
$ref: '#/components/schemas/Id'
created:
$ref: '#/components/schemas/ServerTimestamp'
modified:
$ref: '#/components/schemas/ServerTimestamp'
hidden:
$ref: '#/components/schemas/IsHidden'
fieldId:
title: Entity Identifier
description: A lowercase [ULID](https://github.com/ulid/spec) entity identifier
type: string
format: ulid
example: 01h35ccwymj5ctckp8px1azhg6
value:
type: string
nullable: true
MoneyAmount:
title: Numeric representing an amount in the studio's currency
type: integer
minimum: -99999999999
maximum: 99999999999
example: 200
NullableDate:
title: A date that could be null instead
description: 'A date string consisting of year, month and day in the timezone of the
event if specified or the studio.'
type: string
format: date
nullable: true
example: '2020-04-10'
Event:
title: Event
description: https://help.workspace.vsco.co/en/articles/347132-event-types
type: object
additionalProperties: false
properties:
links:
$ref: '#/components/schemas/Links'
id:
$ref: '#/components/schemas/Id'
created:
$ref: '#/components/schemas/ServerTimestamp'
modified:
$ref: '#/components/schemas/ServerTimestamp'
hidden:
$ref: '#/components/schemas/IsHidden'
allDay:
type: boolean
default: false
nullable: true
channel:
type: string
enum:
- InPerson
- Phone
- Virtual
default: InPerson
confirmed:
type: boolean
default: false
nullable: true
descriptionHtml:
type: string
nullable: true
maxLength: 1073741824
endDate:
$ref: '#/components/schemas/NullableDate'
endTime:
$ref: '#/components/schemas/NullableTime'
endUtc:
allOf:
- readOnly: true
- $ref: '#/components/schemas/NullableDateTime'
externalMappings:
nullable: true
type: array
items:
$ref: '#/components/schemas/ExternalMapping'
galleryId:
$ref: '#/components/schemas/NullableId'
jobId:
$ref: '#/components/schemas/NullableId'
location:
type: object
nullable: true
properties:
id:
$ref: '#/components/schemas/NullableId'
address:
$ref: '#/components/schemas/Address'
name:
type: string
nullable: true
maxLength: 255
phoneNumber:
title: Representation of a phone number
type: object
nullable: true
properties:
id:
allOf:
- readOnly: true
description: The ID of the phone number, if any. This is a unique identifier for the phone number and is generated by the API. It is not the phone number itself.<br> <br> Most phone numbers will not have an ID, as they are usually stored in the database as an E.164 string. We are in the process of refactoring our database to normalize phone numbers to use this representation, and as such, some phone numbers may have an ID.
- $ref: '#/components/schemas/NullableId'
formatted:
description: While this ASCII value is writable, it will be parsed by `libphonenumber` and should thus be considered a lossy value. You can preview how we'll parse it using <a href="https://giggsey.com/libphonenumber/" target="_blank">their website</a>.<br> <br> If `countryCode` or `dialCode` are not provided, the Studio's default country will be assumed.<br> <br> If the value is not parseable, `formatted` will return the original value and `dialCode`, `e164`, `extension`, and `telUri` will all be `null`.<br> <br> If `e164` or `uriTel` are provided, `formatted` will be ignored and replaced with the studio's local formatting of the number.
type: string
example: (800) 560-8283 x123
pattern: ^[ -~]+$
maxLength: 24
nullable: true
e164:
description: An ASCII <a href="https://www.twilio.com/docs/glossary/what-e164" target="_balnk">E.164 representation</a> of the phone number.<br> <br> When writing to the API, you can provide an extension by appending `x` and the extension to the end of the phone. Future reads will move the extension to the `extension` and `telUri` properties, since it isn't strictly a part of the E.164 specification.<br> <br> <b>This is the prefered field for writing to phone fields in the API.</b><br> <br> Will be `null` if the original `formatted` value was not parseable.
type: string
example: 18005608283
pattern: ^\+[1-9]\d{1,14}(x{1,6})?$
maxLength: 24
nullable: true
extension:
description: The number's extension, if any. If provided in a write operation, it will be included in future `e164` and `telUri` values as well.<br> <br> Will be `null` if the original `formatted` value was not parseable.
type: number
format: integer
example: 123
minimum: 1
maximum: 999999
nullable: true
telUri:
description: A <a href="https://tools.ietf.org/html/rfc3966" target="_blank">RFC 3966</a> representation of the phone number. This and `e164` are the prefered formats for writing to phone fields in the API. This value will be parsed and only the number and extension will be applied.<br> <br> Will be `null` if the original `formatted` value was not parseable.
type: string
example: tel:+1-800-560-8283;ext=123
format: rfc3966
nullable: true
dialCode:
type: number
format: integer
example: 1
minimum: 1
maximum: 999
nullable: true
readOnly: true
countryCode:
description: The country code of the phone number. This is a two-letter country code as defined by <a href="https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2" target="_blank">ISO 3166-1 alpha-2</a>. Providing this in a write operation with user-provided `formatted` value may improve our ability to parse the number.<br> <br> If the property is not normalized (it has no `id` after save), then this will be `null` if the original `formatted` value was not parseable, even if `countryCode` was provided.
type: string
example: US
pattern: ^[a-z]{2}$
maxLength: 2
nullable: true
readOnly:
type: boolean
readOnly: true
startDate:
$ref: '#/components/schemas/NullableDate'
startTime:
$ref: '#/components/schemas/NullableTime'
startUtc:
allOf:
- readOnly: true
- $ref: '#/components/schemas/NullableDateTime'
timezoneName:
type: string
nullable: true
description: A VSCO Workspace approved timezone name. If `timezoneId` is provided then this will be ignored.
timezoneId:
$ref: '#/components/schemas/NullableId'
typeId:
$ref: '#/components/schemas/NullableId'
virtualUrl:
type: string
format: uri
nullable: true
Error:
description: An error.
type: object
properties:
type:
description: A namespace URI uniquely identifying the error type.
type: string
enum:
- unknown
- quota-limit
- not-implemented
title:
description: A short description of the error encountered.
type: string
example: Bad Request
detail:
description: A longer description of of the error encountered.
type: string
example: There was a problem with your request. Please see `info` for more information.
status:
description: The HTTP status code associated with this error.
type: integer
example: 400
Company:
allOf:
- title: Company
description: A company entity
type: object
properties:
kind:
type: string
enum:
- company
accountBalance:
allOf:
- readOnly: true
description: The account balance of this company.
- $ref: '#/components/schemas/MoneyAmount'
accountNumber:
type: string
maxLength: 50
nullable: true
brandId:
allOf:
- description: The default brand the company belongs to.
- $ref: '#/components/schemas/NullableId'
cellPhone:
$ref: '#/components/schemas/Event/properties/phoneNumber'
creditBalance:
allOf:
- readOnly: true
description: The credit amount associated with this company.
- $ref: '#/components/schemas/MoneyAmount'
fax:
$ref: '#/components/schemas/Event/properties/phoneNumber'
mailingAddress:
$ref: '#/components/schemas/Address'
name:
type: string
description: Company name.
maxLength: 255
phone:
$ref: '#/components/schemas/Event/properties/phoneNumber'
primaryContactFirstName:
type: string
maxLength: 48
nullable: true
primaryContactLastName:
type: string
maxLength: 48
nullable: true
startingCost:
allOf:
- description: The cost of this person in software used prior to VSCO Workspace.
nullable: true
- $ref: '#/components/schemas/MoneyAmount'
startingRevenue:
allOf:
- description: The revenue from this person in software used prior to VSCO Workspace.
nullable: true
- $ref: '#/components/schemas/MoneyAmount'
tollFree:
$ref: '#/components/schemas/Event/properties/phoneNumber'
vendorRoleId:
description: 'This is a vendor and defines the default job role does this
contact have when added to a job.'
type: string
format: ulid
nullable: true
- $ref: '#/components/schemas/Contact'
Location:
allOf:
- title: Location
description: A Location entity
type: object
properties:
kind:
type: string
enum:
- location
name:
type: string
description: Location name.
maxLength: 255
phone:
$ref: '#/components/schemas/Event/properties/phoneNumber'
tollFree:
$ref: '#/components/schemas/Event/properties/phoneNumber'
- $ref: '#/components/schemas/Contact'
NullableId:
title: Entity Identifier that might be null instead
description: A ULID entity identifier that is nullable.
type: string
format: ulid
nullable: true
example: 01fqcr215r79p3h19crqbpzwzh
ExternalMapping:
title: External Mapping
description: 'This is used to relate a unique entity id in an external system to an
entity inside of VSCO Workspace. These objects can not be updated currently.'
type: object
required:
- id
- url
properties:
id:
type: string
minLength: 1
maxLength: 64
url:
description: The url to the remote item.
type: string
format: uri
minLength: 12
maxLength: 255
ServerTimestamp:
title: Server Timestamp
description: A server timestamp (always in UTC)
type: string
format: date-time
readOnly: true
example: '2020-08-01T17:32:32Z'
Person:
allOf:
- title: Person
description: A person entity
type: object
properties:
kind:
type: string
enum:
- person
accountBalance:
allOf:
- readOnly: true
description: The account balance of this person.
- $ref: '#/components/schemas/MoneyAmount'
anniversary:
$ref: '#/components/schemas/NullableDate'
anonymized:
type: boolean
description: 'This person requested to be anonymized so personally identifiable
information has been anonymized.'
default: false
readOnly: true
bestDayToCall:
type: string
enum:
- weekdays
- weekends
- mondays
- tuesdays
- wednesdays
- thursdays
- fridays
- saturdays
- sundays
- null
nullable: true
bestTimeToCall:
type: string
enum:
- mornings
- afternoons
- evenings
- null
nullable: true
birthdate:
$ref: '#/components/schemas/NullableDate'
brandId:
allOf:
- description: The default brand the person belongs to.
- $ref: '#/components/schemas/NullableId'
cellPhone:
$ref: '#/components/schemas/Event/properties/phoneNumber'
companyName:
type: string
maxLength: 128
nullable: true
contactPreference:
type: string
enum:
- email
- cell-phone
- home-phone
- work-phone
- null
nullable: true
creditBalance:
allOf:
- readOnly: true
description: The credit amount associated with this contact.
- $ref: '#/components/schemas/MoneyAmount'
email:
type: string
format: email
nullable: true
fax:
$ref: '#/components/schemas/Event/properties/phoneNumber'
firstName:
type: string
maxLength: 48
nullable: true
gender:
type: string
enum:
- male
- female
- null
nullable: true
homePhone:
$ref: '#/components/schemas/Event/properties/phoneNumber'
jobTitle:
type: string
maxLength: 64
nullable: true
lastName:
type: string
maxLength: 48
nullable: true
maidenName:
type: string
maxLength: 48
nullable: true
mailingAddress:
$ref: '#/components/schemas/Address'
name:
type: string
description: This is used as the combination of firstName and lastName fields.
maxLength: 255
readOnly: true
previousClient:
type: boolean
nullable: true
privacyOptIn:
type: boolean
description: Contact has Opted-In to Marketing and Processing
default: false
nullable: true
requireStrictPrivacy:
type: boolean
description: Require Strict Privacy (e.g. subject to Europe's GDPR)
default: false
nullable: true
salutation:
type: string
enum:
- mr
- miss
- mrs
- ms
- dr
- null
nullable: true
schoolGradYear:
type: integer
minimum: 1900
maximum: 2100
nullable: true
schoolName:
type: string
maxLength: 255
nullable: true
sport:
type: string
maxLength: 255
nullable: true
startingCost:
allOf:
- description: The cost of this person in software used prior to VSCO Workspace.
nullable: true
- $ref: '#/components/schemas/MoneyAmount'
startingRevenue:
allOf:
- description: The revenue from this person in software used prior to VSCO Workspace.
nullable: true
- $ref: '#/components/schemas/MoneyAmount'
teamName:
type: string
maxLength: 255
nullable: true
teamPosition:
type: string
maxLength: 255
nullable: true
vendorRoleId:
description: 'This is a vendor and defines the default job role does this
contact have when added to a job.'
type: string
format: ulid
nullable: true
workPhone:
$ref: '#/components/schemas/Event/properties/phoneNumber'
- $ref: '#/components/schemas/Contact'
Job:
title: Job
description: https://help.workspace.vsco.co/en/articles/639878-leads-jobs-and-job-stages
type: object
properties:
links:
$ref: '#/components/schemas/Links'
id:
$ref: '#/components/schemas/Id'
created:
$ref: '#/components/schemas/ServerTimestamp'
modified:
$ref: '#/components/schemas/ServerTimestamp'
accountBalance:
allOf:
- readOnly: true
description: The account balance for this job.
- $ref: '#/components/schemas/MoneyAmount'
bookingDate:
$ref: '#/components/schemas/NullableDate'
brandId:
$ref: '#/components/schemas/NullableId'
closed:
description: 'Whether or not the lead or job is closed. A closed reason might be
provided as well.'
type: boolean
example: false
closedReasonId:
$ref: '#/components/schemas/NullableId'
closedDate:
$ref: '#/components/schemas/NullableDate'
closedReasonName:
type: string
nullable: true
readOnly: true
completedDate:
$ref: '#/components/schemas/NullableDate'
contactFormId:
$ref: '#/components/schemas/NullableId'
creditBalance:
allOf:
- readOnly: true
description: The credit amount associated with this job.
- $ref: '#/components/schemas/MoneyAmount'
customFields:
type: array
nullable: true
items:
$ref: '#/components/schemas/CustomFieldValue'
customNumber:
type: string
maxLength: 32
deprecated: true
readOnly: true
nullable: true
eventDate:
$ref: '#/components/schemas/NullableDate'
externalMappings:
nullable: true
type: array
items:
$ref: '#/components/schemas/ExternalMapping'
fulfillmentDate:
$ref: '#/components/schemas/NullableDate'
guestCount:
type: integer
minimum: 0
maximum: 99999999999
nullable: true
inquiryDate:
$ref: '#/components/schemas/NullableDate'
jobTypeId:
$ref: '#/components/schemas/NullableId'
jobTypeName:
type: string
nullable: true
readOnly: true
lastClientActivity:
allOf:
- readOnly: true
- $ref: '#/components/schemas/NullableDateTime'
leadConfidence:
type: string
enum:
- low
- medium
- high
- null
nullable: true
leadDecisionExpectedByDate:
$ref: '#/components/schemas/NullableDate'
leadMaxBudget:
title: Numeric representing an amount in the studio's currency
type: integer
minimum: -99999999999
maximum: 99999999999
nullable: true
leadNotes:
type: string
maxLength: 1000000000
nullable: true
leadRating:
type: integer
minimum: 1
maximum: 5
nullable: true
leadSourceId:
$ref: '#/components/schemas/NullableId'
leadSourceName:
type: string
nullable: true
readOnly: true
leadStatusId:
$ref: '#/components/schemas/NullableId'
leadStatusName:
type: string
nullable: true
readOnly: true
leadStatusChangedAt:
allOf:
- readOnly: true
- $ref: '#/components/schemas/NullableDateTime'
name:
description: Name of the job that will override the title.
type: string
nullable: true
nextInteractionDate:
allOf:
- readOnly: true
- $ref: '#/components/schemas/NullableDate'
nextInteractionItem:
type: string
format: uri
nullable: true
readOnly: true
pinned:
$ref: '#/components/schemas/Pinned'
primarySessionId:
allOf:
- readOnly: true
- $ref: '#/components/schemas/NullableId'
previousInteractionDate:
allOf:
- readOnly: true
- $ref: '#/components/schemas/NullableDate'
previousInteractionItem:
type: string
format: uri
nullable: true
readOnly: true
sample:
description: Whether or not the lead or job is a sample job.
type: boolean
example: false
readOnly: true
stage:
description: Specifies the stage that the job is in.
type: string
enum:
- lead
- booked
- fulfillment
- completed
example: booked
staleDate:
allOf:
- readOnly: true
- $ref: '#/components/schemas/NullableDate'
title:
description: Generated title of the job
type: string
readOnly: true
nullable: true
totalCost:
allOf:
- readOnly: true
- $ref: '#/components/schemas/MoneyAmount'
totalProfit:
allOf:
- readOnly: true
- $ref: '#/components/schemas/MoneyAmount'
totalRevenue:
allOf:
- readOnly: true
- $ref: '#/components/schemas/MoneyAmount'
webLead:
description: Whether or not the lead or job came from a contact form.
type: boolean
default: false
example: false
workflowId:
$ref: '#/components/schemas/NullableId'
workflowName:
type: string
nullable: true
readOnly: true
Address:
description: Represents an address.
type: object
nullable: true
additionalProperties: false
properties:
links:
$ref: '#/components/schemas/Links'
id:
$ref: '#/components/schemas/Id'
created:
$ref: '#/components/schemas/ServerTimestamp'
modified:
$ref: '#/components/schemas/ServerTimestamp'
hidden:
$ref: '#/components/schemas/IsHidden'
name:
type: string
maxLength: 255
readOnly: true
nullable: true
streetAddress:
type: string
maxLength: 512
nullable: true
village:
type: string
maxLength: 255
nullable: true
city:
type: string
maxLength: 255
nullable: true
state:
type: string
maxLength: 255
nullable: true
postalCode:
type: string
maxLength: 255
nullable: true
country:
type: string
maxLength: 2
nullable: true
latitude:
type: number
readOnly: true
nullable: true
longitude:
type: number
readOnly: true
nullable: true
googlePlaceId:
type: string
maxLength: 255
readOnly: true
nullable: true
timezone:
type: string
readOnly: true
nullable: true
Links:
title: Link Relationships
description: 'Each property defines a hypertext link relationship as indicated by a
link object or array of link objects. The target URL of each hypertext
link relationship is related to the current resource according to the
defined semantics of the link relationship property name.'
readOnly: true
required:
- self
type: object
example: "\"self\": {\n \"href\": \"https://example.com/object-endpoint/03c41781-f06f-4402-a5d9-1c30ccb4db29\",\n \"title\": \"Example Link Relationship\",\n \"type\": \"application/json\",\n}"
properties:
self:
allOf:
- title: Self
description: The target URL is the current resource's own location.
- $ref: '#/components/schemas/Link'
IsHidden:
title: Hidden attribute
description: Whether or not the object is hidden.
type: boolean
example: false
readOnly: true
JobWorksheetContact:
title: Job Worksheet Contact
type: object
required:
- contact
properties:
links:
$ref: '#/components/schemas/Links'
id:
$ref: '#/components/schemas/Id'
created:
$ref: '#/components/schemas/ServerTimestamp'
modified:
$ref: '#/components/schemas/ServerTimestamp'
hidden:
$ref: '#/components/schemas/IsHidden'
externalMappings:
nullable: true
type: array
items:
$ref: '#/components/schemas/ExternalMapping'
client:
type: boolean
default: false
nullable: true
attendingAllEvents:
type: boolean
default: false
nullable: true
attendingAllSessions:
type: boolean
default: true
nullable: true
jobRoles:
nullable: true
type: array
items:
$ref: '#/components/schemas/NullableId'
roleKinds:
type: array
items:
type: string
enum:
- client
- customer
- team
- subject
- vendor
readOnly: true
contact:
oneOf:
- $ref: '#/components/schemas/Person'
- $ref: '#/components/schemas/Company'
- $ref: '#/components/schemas/Location'
discriminator:
propertyName: kind
mapping:
person: Person.yaml
company: Company.yaml
location: Location.yaml
Pinned:
title: Whether or not the entity is favorited.
type: boolean
default: false
nullable: true
Contact:
title: Contact common fields
description: Contact common fields that all kinds share
type: object
required:
- kind
properties:
links:
$ref: '#/components/schemas/Links'
id:
$ref: '#/components/schemas/Id'
created:
$ref: '#/components/schemas/ServerTimestamp'
modified:
$ref: '#/components/schemas/ServerTimestamp'
hidden:
$ref: '#/components/schemas/IsHidden'
address:
$ref: '#/components/schemas/Address'
cha
# --- truncated at 32 KB (37 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/vsco/refs/heads/main/openapi/vsco-job-worksheets-api-openapi.yml