SkySlope Documents API
The Documents API from SkySlope — 5 operation(s) for documents.
OpenAPI Specification
openapi: 3.1.3
info:
x-logo:
url: https://s3.amazonaws.com/cdn.skyslope.com/forms/forms-logo-w-top-padding.png
href: https://skyslope.com/
altText: SkySlope
title: SkySlope Partnership API Reference Agents, Listings Documents API
version: 1.0.0
description: "# Introduction\n The SkySlope Forms API is organized around [REST](https://en.wikipedia.org/wiki/Representational_state_transfer).\n Our API has predictable resource-oriented URLs, accepts JSON-encoded request bodies, returns JSON-encoded responses,\n and uses standard HTTP response codes, authentication, and verbs.<br/><br/>\n NOTE: Endpoints marked with an asterisk (*) will be available to our partners in the near future.\n # Authentication\n This API uses [OAuth 2.0 authorization code flow](https://www.oauth.com/oauth2-servers/server-side-apps/authorization-code/)\n to obtain an access token that can be used to authenticate subsequent API requests.\n ## Access Tokens\n ### Request\n To obtain an access token, first redirect the user to the authorization endpoint:\n ```\n https://accounts.skyslope.com/oauth2/authorize?\n response_type=code\n &client_id={YOUR_CLIENT_ID}\n &redirect_uri={YOUR_REDIRECT_URI}\n &scope=forms.files\n &state={RANDOM_STATE_VALUE}\n &code_challenge={CODE_CHALLENGE}\n &code_challenge_method=S256\n ```\n After the user authorizes your application, they'll be redirected back to your redirect URI with an authorization code.\n Exchange this code for an access token by making a POST request to the token endpoint:\n ```\n POST /oauth2/token HTTP/1.1\n Host: accounts.skyslope.com\n Content-Type: application/x-www-form-urlencoded\n \n grant_type=authorization_code\n &client_id={YOUR_CLIENT_ID}\n &client_secret={YOUR_CLIENT_SECRET}\n &code={AUTHORIZATION_CODE}\n &redirect_uri={YOUR_REDIRECT_URI}\n &code_verifier={CODE_VERIFIER}\n ```\n ### Usage\n Authentication to the API is performed by including your access token in the **Authorization** header of your\n API requests with the Bearer authentication scheme:\n ```\n GET /partner/api/files HTTP/1.1\n Host: forms.skyslope.com\n Authorization: Bearer {YOUR_ACCESS_TOKEN}\n ```\n All API requests must be made over [HTTPS](https://en.wikipedia.org/wiki/HTTPS). Calls made over plain HTTP will fail.\n API requests without authentication will also fail.\n ## Refresh Tokens\n Refresh tokens allow you to obtain new access tokens without requiring the user to re-authenticate. When you first\n complete the OAuth flow, you'll receive both an access token and a refresh token.\n ### Request\n To receive a refresh token, include the `offline_access` scope in your initial authorization request:\n ```\n https://accounts.skyslope.com/oauth2/authorize?\n response_type=code\n &client_id={YOUR_CLIENT_ID}\n &scope=forms.files offline_access\n &redirect_uri={YOUR_REDIRECT_URI}\n ```\n ### Usage\n When your access token expires, make a POST request to the token endpoint:\n ```\n POST /oauth2/token HTTP/1.1\n Host: accounts.skyslope.com\n Content-Type: application/x-www-form-urlencoded\n \n grant_type=refresh_token\n &client_id={YOUR_CLIENT_ID}\n &client_secret={YOUR_CLIENT_SECRET}\n &refresh_token={YOUR_REFRESH_TOKEN}\n ```\n This will return a new access token and refresh token pair.\n ### Security Best Practices\n - Store refresh tokens securely on your backend server, never on client side\n - Encrypt refresh tokens at rest using strong encryption\n - Rotate refresh token on each use\n - Set up monitoring for unusual refresh token usage patterns\n - If a refresh token is compromised, revoke it immediately using the token revocation endpoint\n - Implement automatic cleanup of unused refresh tokens"
termsOfService: https://skyslope.com/terms-conditions/
contact:
name: Support
url: https://support.skyslope.com/hc/en-us
email: support@skyslope.com
servers:
- url: https://forms.skyslope.com/partner/api
description: Production server
- url: https://staging-forms.skyslope.com/partner/api
description: Staging server
- url: https://integ-forms.skyslope.com/partner/api
description: Integration server
tags:
- name: Documents
paths:
/documents/{documentId}:
get:
summary: Get Document
tags:
- Documents
description: 'Retrieve the details and field definitions for a document by its id.<div style="color: rgba(38, 50, 56, 0.5); border-bottom: 1px solid rgba(38, 50, 56, 0.3); padding-bottom: 1px;">REQUIRED SCOPES:</div><div style="display: inline-flex; gap: 5px; padding: 5px;"><div style="border-radius: 2px; border: 1px solid rgba(128,128,255,0.5); background-color: rgba(64,64,255,0.25); padding: 0px 5px;">forms.documents</div><div style="border-radius: 2px; border: 1px solid rgba(128,128,255,0.5); background-color: rgba(64,64,255,0.25); padding: 0px 5px;">forms.documents.read</div></div>'
parameters:
- schema:
type: integer
minimum: 1
default: 1
in: query
name: page
required: false
description: The page number of fields to retrieve.
- schema:
type: integer
minimum: 1
maximum: 500
default: 10
in: query
name: pageSize
required: false
description: The number of fields returned per page.
- schema:
type: integer
minimum: 1
in: path
name: documentId
required: true
description: The id of the document to retrieve.
responses:
'200':
description: Default Response
content:
application/json:
schema:
type: object
description: An object containing the details of the document.
properties:
id:
type: number
description: The id of the document.
formName:
type: string
description: The name of the document.
formId:
type:
- 'null'
- number
description: The id of the form.
formVersionId:
type: number
description: The id of the form version.
fileId:
type: number
description: The id of the file that the document belongs to.
formURL:
type: string
description: The URL to the form in storage.
thumbnailURL:
type: string
description: The url of the thumbnail of the document.
pageCount:
type:
- 'null'
- number
description: The number of pages in the document.
documentType:
type: string
description: The type of the document.
createdBy:
type: string
description: The id of the user who created the document.
updatedBy:
type:
- 'null'
- string
description: The id of the user who last updated the document.
createdOn:
type: string
description: The date and time the document was created.
updatedOn:
type: string
description: The date and time the document was last updated.
ownedBy:
type: string
description: The id of the user who owns the document.
page:
type: number
description: The current page number.
pageSize:
type: number
description: The number of fields returned per page.
totalItems:
type: number
description: The total number of fields on the document.
totalPages:
type: number
description: The total number of pages available.
fields:
type: array
description: A paginated array of the fields defined on the document.
items:
type: object
properties:
id:
type: string
description: The unique identifier for the field.
name:
type: string
description: The name of the field.
dataRef:
type: string
description: The data reference key for the field.
type:
type: string
description: The field type (e.g. "text", "checkbox").
originalType:
type: string
description: The original field type as defined in the form template.
xCoordinate:
type: number
description: The X coordinate position of the field on the page.
yCoordinate:
type: number
description: The Y coordinate position of the field on the page.
width:
type: number
description: The width of the field.
height:
type: number
description: The height of the field.
pageNumber:
type: number
description: The zero-based page number the field appears on.
fontSize:
type: number
description: The font size for the field.
isReadOnly:
type: boolean
description: Evaluates to true if the field is read-only.
isTabbable:
type: boolean
description: Evaluates to true if the field is reachable via tab.
isFirstAggregateField:
type: boolean
description: Evaluates to true if the field is the first in an aggregate group.
isGlobal:
type: boolean
description: Evaluates to true if the field is globally scoped across forms.
isOptional:
type: boolean
description: Evaluates to true if the field is optional.
isDefaultToday:
type: boolean
description: Evaluates to true if the field defaults to today's date.
digisignAllowOverrideIsOptional:
type: boolean
description: Evaluates to true if DigiSign is allowed to override the optional setting.
format:
type:
- 'null'
- string
description: The format string applied to the field value.
order:
type:
- 'null'
- number
description: The tab order of the field.
clientType:
type:
- 'null'
- string
description: The contact type associated with the field.
position:
type:
- 'null'
- number
description: The position of the field within its group.
entityDisplayRule:
type:
- 'null'
- string
description: Display rule controlling field visibility.
fieldDisplay:
type:
- 'null'
- string
description: Additional display metadata for the field.
listingFieldName:
type:
- 'null'
- string
description: The listing field name mapped to this field.
listingTableName:
type:
- 'null'
- string
description: The listing table name mapped to this field.
referenceListingFieldName:
type:
- 'null'
- string
description: The reference listing field name mapped to this field.
group:
type:
- 'null'
- object
description: The field group this field belongs to.
domainFieldMetaData:
type:
- 'null'
- object
description: Domain-specific metadata for the field.
associatedDataRefs:
type: array
description: Data references associated with this field.
items:
type: string
example:
id: 211469
formName: Purchase Agreement Form
formId: null
formVersionId: 28081
fileId: 582186
formURL: https://s3.us-west-2.amazonaws.com/example-bucket/forms/28081.pdf
thumbnailURL: https://s3.us-west-2.amazonaws.com/example-bucket/thumbnails/28081.png
pageCount: 3
documentType: Forms
createdBy: 00u1j6qlmwclWMB9O357
updatedBy: null
createdOn: '2024-01-15T10:30:00Z'
updatedOn: '2026-02-02T18:32:58Z'
ownedBy: 00u1j6qlmwclWMB9O357
page: 1
pageSize: 10
totalItems: 1
totalPages: 1
fields:
- id: Text1-482.70001220703125-104.5369873046875-0
name: Text1
dataRef: Text1
type: text
originalType: textinputblock
xCoordinate: 482.70001220703125
yCoordinate: 104.5369873046875
width: 92.16796875
height: 11.880000114440918
pageNumber: 0
fontSize: 8
isReadOnly: false
isTabbable: true
isFirstAggregateField: false
isGlobal: false
isOptional: false
isDefaultToday: false
digisignAllowOverrideIsOptional: true
format: null
order: null
clientType: null
position: null
entityDisplayRule: null
fieldDisplay: null
listingFieldName: null
listingTableName: null
referenceListingFieldName: null
group: null
domainFieldMetaData: null
associatedDataRefs: []
default:
description: An object containing the error that occurred.
content:
application/json:
schema:
type: object
description: An object containing the error that occurred.
properties:
code:
type: string
description: A code that represents the error that occurred.
message:
type: string
description: A description of the error that occurred.
errors:
type: array
description: An array of the errors that occurred.
items:
type: string
traceId:
type: string
description: A request correlation ID.
patch:
summary: Update Document
tags:
- Documents
description: 'Update the field values of a document. Only the fields supplied in the request body will be updated; existing values of other fields are preserved.<div style="color: rgba(38, 50, 56, 0.5); border-bottom: 1px solid rgba(38, 50, 56, 0.3); padding-bottom: 1px;">REQUIRED SCOPES:</div><div style="display: inline-flex; gap: 5px; padding: 5px;"><div style="border-radius: 2px; border: 1px solid rgba(128,128,255,0.5); background-color: rgba(64,64,255,0.25); padding: 0px 5px;">forms.documents</div></div>'
requestBody:
content:
application/json:
schema:
type: object
additionalProperties: true
description: A JSON object containing the document field data references and their values to be updated. Only the fields supplied will be updated; existing values of other fields are preserved.
description: A JSON object containing the document field data references and their values to be updated. Only the fields supplied will be updated; existing values of other fields are preserved.
parameters:
- schema:
type: integer
minimum: 1
in: path
name: documentId
required: true
description: The id of the document to update.
responses:
'200':
description: Default Response
content:
application/json:
schema:
type: object
properties:
documentId:
type: number
description: The id of the document that was updated.
didAddendumsChange:
type: boolean
description: Evaluates to true if the number of addendum pages changed as a result of the update.
example:
documentId: 123456
didAddendumsChange: false
default:
description: An object containing the error that occurred.
content:
application/json:
schema:
type: object
description: An object containing the error that occurred.
properties:
code:
type: string
description: A code that represents the error that occurred.
message:
type: string
description: A description of the error that occurred.
errors:
type: array
description: An array of the errors that occurred.
items:
type: string
traceId:
type: string
description: A request correlation ID.
delete:
summary: Delete Document.
tags:
- Documents
description: 'Delete a document.<div style="color: rgba(38, 50, 56, 0.5); border-bottom: 1px solid rgba(38, 50, 56, 0.3); padding-bottom: 1px;">REQUIRED SCOPES:</div><div style="display: inline-flex; gap: 5px; padding: 5px;"><div style="border-radius: 2px; border: 1px solid rgba(128,128,255,0.5); background-color: rgba(64,64,255,0.25); padding: 0px 5px;">forms.documents</div></div>'
parameters:
- schema:
type: integer
minimum: 1
in: path
name: documentId
required: true
description: The id of the document to delete.
responses:
'200':
description: Default Response
content:
application/json:
schema:
type: object
required:
- documentId
properties:
documentId:
type: number
description: The id of the document that was deleted from the file.
example:
documentId: 123456
default:
description: An object containing the error that occurred.
content:
application/json:
schema:
type: object
description: An object containing the error that occurred.
properties:
code:
type: string
description: A code that represents the error that occurred.
message:
type: string
description: A description of the error that occurred.
errors:
type: array
description: An array of the errors that occurred.
items:
type: string
traceId:
type: string
description: A request correlation ID.
/files/{fileId}/documents:
get:
summary: Get File Documents
tags:
- Documents
description: 'Retrieve the documents metadata for a file. To download documents with proper branding and data stamping, use the /files/:fileId/documents/download or /files/:fileId/documents/download/pdf endpoints.<div style="color: rgba(38, 50, 56, 0.5); border-bottom: 1px solid rgba(38, 50, 56, 0.3); padding-bottom: 1px;">REQUIRED SCOPES:</div><div style="display: inline-flex; gap: 5px; padding: 5px;"><div style="border-radius: 2px; border: 1px solid rgba(128,128,255,0.5); background-color: rgba(64,64,255,0.25); padding: 0px 5px;">forms.documents</div><div style="border-radius: 2px; border: 1px solid rgba(128,128,255,0.5); background-color: rgba(64,64,255,0.25); padding: 0px 5px;">forms.documents.read</div></div>'
parameters:
- schema:
type: integer
minimum: 1
in: path
name: fileId
required: true
description: The id of the file to retrieve documents for.
responses:
'200':
description: Default Response
content:
application/json:
schema:
type: object
description: An object containing the documents found for the file.
properties:
totalRecords:
type: number
description: The total number of documents found for the file.
documents:
type: array
description: An array containing the documents found for the file.
items:
type: object
properties:
id:
type: number
description: The id of the document.
formName:
type: string
description: The name of the document.
formId:
type: number
description: The id of the form.
formVersionId:
type: number
description: The id of the form version.
fileId:
type: number
description: The id of the file that the document belongs to.
thumbnailURL:
type: string
description: The url of the thumbnail of the document.
pageCount:
type:
- 'null'
- number
description: The number of pages in the document.
documentType:
type: string
description: The type of the document.
createdBy:
type: string
description: The id of the user who created the document.
updatedBy:
type: string
description: The id of the user who last updated the document.
createdOn:
type: string
description: The date and time the document was created.
updatedOn:
type: string
description: The date and time the document was last updated.
ownedBy:
type: string
description: The id of the user who owns the document.
example:
totalRecords: 1
documents:
- id: 123456
formName: Purchase Agreement Form
formId: 789
formVersionId: 1011
fileId: 456789
thumbnailURL: https://example.com/thumbnails/form-12345.png
pageCount: 5
documentType: Forms
createdBy: 00u123456789abcdef
updatedBy: 00u123456789abcdef
createdOn: '2024-01-15T10:30:00Z'
updatedOn: '2024-01-15T10:30:00Z'
ownedBy: 00u123456789abcdef
default:
description: An object containing the error that occurred.
content:
application/json:
schema:
type: object
description: An object containing the error that occurred.
properties:
code:
type: string
description: A code that represents the error that occurred.
message:
type: string
description: A description of the error that occurred.
errors:
type: array
description: An array of the errors that occurred.
items:
type: string
traceId:
type: string
description: A request correlation ID.
patch:
summary: Add Documents to File
tags:
- Documents
description: 'Add one or more documents to a file.<div style="color: rgba(38, 50, 56, 0.5); border-bottom: 1px solid rgba(38, 50, 56, 0.3); padding-bottom: 1px;">REQUIRED SCOPES:</div><div style="display: inline-flex; gap: 5px; padding: 5px;"><div style="border-radius: 2px; border: 1px solid rgba(128,128,255,0.5); background-color: rgba(64,64,255,0.25); padding: 0px 5px;">forms.files</div><div style="border-radius: 2px; border: 1px solid rgba(128,128,255,0.5); background-color: rgba(64,64,255,0.25); padding: 0px 5px;">forms.documents</div></div>'
requestBody:
content:
application/json:
schema:
type: object
additionalProperties: false
required:
- formIds
properties:
formIds:
type: array
description: An array of the Form Ids of the Forms to add to the file.
minItems: 1
items:
type: integer
description: A Form Id of the Form to add to the file.
required: true
parameters:
- schema:
type: integer
minimum: 1
in: path
name: fileId
required: true
description: The id of the file to add the documents to.
responses:
'200':
description: Default Response
content:
application/json:
schema:
type: object
properties:
documentIds:
type: array
description: An array of the documentIds that were added to the file.
items:
type: number
example:
documentIds:
- 1
- 2
- 3
default:
description: An object containing the error that occurred.
content:
application/json:
schema:
type: object
description: An object containing the error that occurred.
properties:
code:
type: string
description: A code that represents the error that occurred.
message:
type: string
description: A description of the error that occurred.
errors:
type: array
description: An array of the errors that occurred.
items:
type: string
traceId:
type: string
description: A request correlation ID.
/documents/signed/{fileId}:
get:
summary: Get Signed Documents
tags:
- Documents
description: 'Retrieve the signed documents for a file.<div style="color: rgba(38, 50, 56, 0.5); border-bottom: 1px solid rgba(38, 50, 56, 0.3); padding-bottom: 1px;">REQUIRED SCOPES:</div><div style="display: inline-flex; gap: 5px; padding: 5px;"><div style="border-radius: 2px; border: 1px solid rgba(128,128,255,0.5); background-color: rgba(64,64,255,0.25); padding: 0px 5px;">forms.documents</div><div style="border-radius: 2px; border: 1px solid rgba(128,128,255,0.5); background-color: rgba(64,64,255,0.25); padding: 0px 5px;">forms.documents.read</div></div>'
parameters:
- schema:
type: integer
minimum: 1
in: path
name: fileId
required: true
description: The id of the file to retrieve signed documents for.
responses:
'200':
description: Default Response
content:
application/json:
schema:
type: object
description: An object containing the signed documents found for the authenticated user.
properties:
totalRecords:
type: number
description: The total number of signed documents found for the authenticated user.
documents:
type: array
description: An array containing the signed documents found for the authenticated user.
items:
type: object
properties:
documentId:
type: number
description: The id of the document.
documentName:
type: string
description: The name of the document.
filename:
type: string
description: The name of the file that the document belongs to.
pageCount:
type: number
description: The number of pages in the document.
externalDocumentId:
type: string
description: The external id of the document.
fileId:
type: number
description: The id of the file that the document belongs to.
envelopeId:
type: string
description: The id of the envelope that the document belongs to.
envelopeName:
type: string
# --- truncated at 32 KB (40 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/skyslope/refs/heads/main/openapi/skyslope-documents-api-openapi.yml