SkySlope
API docs by Redocly

SkySlope Partnership API Reference (1.0.0)

Download OpenAPI specification:

Support: [email protected] URL: https://support.skyslope.com/hc/en-us Terms of Service

Introduction

The SkySlope Forms API is organized around REST. Our API has predictable resource-oriented URLs, accepts JSON-encoded request bodies, returns JSON-encoded responses, and uses standard HTTP response codes, authentication, and verbs.

NOTE: Endpoints marked with an asterisk (*) will be available to our partners in the near future.

Authentication

This API uses OAuth 2.0 authorization code flow to obtain an access token that can be used to authenticate subsequent API requests.

Access Tokens

Request

To obtain an access token, first redirect the user to the authorization endpoint:

https://accounts.skyslope.com/oauth2/authorize?
  response_type=code
  &client_id={YOUR_CLIENT_ID}
  &redirect_uri={YOUR_REDIRECT_URI}
  &scope=forms.files
  &state={RANDOM_STATE_VALUE}
  &code_challenge={CODE_CHALLENGE}
  &code_challenge_method=S256

After the user authorizes your application, they'll be redirected back to your redirect URI with an authorization code. Exchange this code for an access token by making a POST request to the token endpoint:

POST /oauth2/token HTTP/1.1
Host: accounts.skyslope.com
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code
&client_id={YOUR_CLIENT_ID}
&client_secret={YOUR_CLIENT_SECRET}
&code={AUTHORIZATION_CODE}
&redirect_uri={YOUR_REDIRECT_URI}
&code_verifier={CODE_VERIFIER}

Usage

Authentication to the API is performed by including your access token in the Authorization header of your API requests with the Bearer authentication scheme:

GET /partner/api/files HTTP/1.1
Host: forms.skyslope.com
Authorization: Bearer {YOUR_ACCESS_TOKEN}

All API requests must be made over HTTPS. Calls made over plain HTTP will fail. API requests without authentication will also fail.

Refresh Tokens

Refresh tokens allow you to obtain new access tokens without requiring the user to re-authenticate. When you first complete the OAuth flow, you'll receive both an access token and a refresh token.

Request

To receive a refresh token, include the offline_access scope in your initial authorization request:

https://accounts.skyslope.com/oauth2/authorize?
  response_type=code
  &client_id={YOUR_CLIENT_ID}
  &scope=forms.files offline_access
  &redirect_uri={YOUR_REDIRECT_URI}

Usage

When your access token expires, make a POST request to the token endpoint:

POST /oauth2/token HTTP/1.1
Host: accounts.skyslope.com
Content-Type: application/x-www-form-urlencoded

grant_type=refresh_token
&client_id={YOUR_CLIENT_ID}
&client_secret={YOUR_CLIENT_SECRET}
&refresh_token={YOUR_REFRESH_TOKEN}

This will return a new access token and refresh token pair.

Security Best Practices

  • Store refresh tokens securely on your backend server, never on client side
  • Encrypt refresh tokens at rest using strong encryption
  • Rotate refresh token on each use
  • Set up monitoring for unusual refresh token usage patterns
  • If a refresh token is compromised, revoke it immediately using the token revocation endpoint
  • Implement automatic cleanup of unused refresh tokens

Files

Update File Details

Update the file details of a listing or transaction file. Supply onBehalfOf when updating a file owned by a user who has granted delegate access to the authenticated caller.

REQUIRED SCOPES:
forms.files

path Parameters
fileId
required
integer

The id of the file to update.

Request Body schema: application/json
name
string

The name of the file.

object

File data that can be updated.

onBehalfOf
string

The id of the user whose file is being updated. Supply this when updating a file owned by a user who has granted delegate access to the authenticated caller, so that any records the update creates are owned by that user rather than the caller. Requires a valid delegate access grant; requests without one are rejected with a 404.

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "fileData": {
    },
  • "onBehalfOf": "string"
}

Response samples

Content type
application/json
{
  • "fileId": 477309,
  • "didAddendumsChange": false
}

Update File

Update the file of a listing or transaction file. Supply onBehalfOf when updating a file owned by a user who has granted delegate access to the authenticated caller; the contacts and commissions this request writes are then owned by that user.

REQUIRED SCOPES:
forms.files

path Parameters
fileId
required
integer

The id of the file to update.

Request Body schema: application/json
required
mlsNumber
string

The mls number of the file.

purchasePrice
number

The purchase price of the property.

closingDateTime
string or null

The closing date of the file. Send a calendar date, YYYY-MM-DD (preferred). Full datetimes remain accepted and are reduced to their calendar day (an explicit UTC offset keeps the date at that offset). A value that is not a date is rejected with HTTP 400. Null or an empty string clears the date — and note this endpoint is a full replace: OMITTING the field also clears the stored date.

acceptanceDateTime
string or null

The acceptance date of the file. Same calendar-date semantics as closingDateTime: YYYY-MM-DD preferred, datetimes reduced to their day, invalid values rejected with 400, and omission clears the stored date (full-replace endpoint).

required
object

The property that the file is associated with.

required
Array of objects

An array of the commissions for the file.

required
Array of objects

An array of contacts for the file.

onBehalfOf
string

The id of the user whose file is being updated. Supply this when updating a file owned by a user who has granted delegate access to the authenticated caller, so that the contacts and commissions this request writes are owned by that user rather than the caller. Requires a valid delegate access grant; requests without one are rejected with a 404.

Responses

Request samples

Content type
application/json
{
  • "mlsNumber": "string",
  • "purchasePrice": 0,
  • "closingDateTime": "string",
  • "acceptanceDateTime": "string",
  • "property": {
    },
  • "commissions": [
    ],
  • "contacts": [
    ],
  • "onBehalfOf": "string"
}

Response samples

Content type
application/json
{
  • "fileId": 0,
  • "commissions": [
    ],
  • "contacts": [
    ]
}

Get File

Retrieve the details of a listing or transaction file.

REQUIRED SCOPES:
forms.files
forms.files.read

path Parameters
fileId
required
integer >= 1

The id of the file to retrieve.

Responses

Response samples

Content type
application/json
{
  • "id": 1,
  • "name": "File Name",
  • "type": "File",
  • "representationType": "Buyer",
  • "templateCategory": "Landlord",
  • "closingDateTime": "2023-12-31",
  • "acceptanceDateTime": "2023-12-31",
  • "meta": {
    },
  • "mlsNumber": "1589519",
  • "purchasePrice": 1598000,
  • "fileData": {
    },
  • "transactionMeta": {
    },
  • "property": {
    },
  • "contacts": [
    ],
  • "commissions": [
    ],
  • "documentData": [
    ],
  • "isDeleted": false,
  • "isArchived": false,
  • "createdOn": "2023-12-31T12:12:12.123Z",
  • "createdBy": "iajv98j498j98vasj4h",
  • "updatedOn": "2023-12-31T12:12:12.123Z",
  • "updatedBy": "iajv98j498j98vasj4h",
  • "ownedBy": "iajv98j498j98vasj4h"
}

Get Files

Retrieve the files that the user has access to.

REQUIRED SCOPES:
forms.files
forms.files.read

query Parameters
page
integer >= 1
Default: 1

The page number to retrieve.

pageSize
integer [ 1 .. 500 ]
Default: 10

The number of files returned per page.

filters
string

A comma separated sieve filter to that will be applied to the results. Ex: filters=representationtype==Buyer,(createddate)>=2024-01-01,(createddate)<=2024-01-31

sorts
string

A sieve list of sort fields to sort the results by.

Responses

Response samples

Content type
application/json
{
  • "totalRecords": 1,
  • "files": [
    ]
}

Create Listing or Transaction File

Create a listing or transaction file. Supply onBehalfOf to create it for a user who granted you delegate access; that user owns the file and you are recorded as its creator.

File creation requires forms.files. Set importMls=true to request an MLS import after creation. Import additionally requires forms.mls.import; without that scope the file is still created and mlsImport reports not_imported/missing_scope.

A supplied mlsNumber is saved as file data even when import is not requested. With the import scope, an omitted or blank number skips requested import with missing_mls_number. Without requested import the response contains only fileId.

Import searches using the file owner’s configured regions and imports only a single matching listing. The MLS number selects the listing; its address is not compared with the supplied property address.

Import runs with overwrite enabled. Available MLS values, including the address, take precedence over supplied values even when the addresses differ. Creation has no overwrite parameter. Verify the MLS number identifies the intended property before requesting import.

Creation and import are separate operations. Once creation succeeds, the response retains fileId even if import is skipped, fails, or times out. Inspect mlsImport.status rather than treating HTTP 200 as confirmation of import. importedCount measures fields or field groups, not an exact count of changed values; zero is valid and an unavailable count is omitted.

Retry import with POST /files/{fileId}/mls-import to avoid creating another file. That endpoint defaults to preserving populated values unless shouldOverride=true is supplied.

Import uses the service’s default MLS source; callers cannot select another source. Utah and Florida MLS coverage is not fully supported.

REQUIRED SCOPES:
forms.files

query Parameters
importMls
boolean
Default: false

Import MLS data after creating the file. Available MLS values replace supplied values, including the address, without comparing the two addresses. Requires forms.mls.import only for the import; missing that scope does not prevent file creation.

Request Body schema: application/json
mlsNumber
string

The MLS number saved on the file. Does not trigger import unless importMls=true is supplied in the query.

name
string

The name of the file.

representationType
string
Enum: "Buyer" "Seller" "Tenant" "Landlord"

The representation type of the file.

object

The property that the file is associated with.

onBehalfOf
string

The id of the user to create the file for. When provided, that user becomes the owner of the file (ownedBy) while the authenticated caller is recorded as its creator (createdBy). Requires that the user has granted delegate access to the authenticated caller; requests without a valid grant are rejected with a 404.

Responses

Request samples

Content type
application/json
{
  • "mlsNumber": "string",
  • "name": "string",
  • "representationType": "Buyer",
  • "property": {
    },
  • "onBehalfOf": "string"
}

Response samples

Content type
application/json
Example
{
  • "fileId": 477309
}

Add Contact to File

Add a contact to a file. Supply onBehalfOf to add the contact for a user who has granted delegate access to the authenticated caller.

REQUIRED SCOPES:
forms.files

path Parameters
fileId
required
integer >= 1

The id of the file to add the contact to.

Request Body schema: application/json
required

The body of the request to add a contact to a file.

actionAttribute
string
Enum: "Empty" "NeedsToSign" "CanView" "ReceivesCopy" "NoAction"

Actions for contact to participate in.

NeedsToSign: Contact will will receive an email containing a document needing to be signed

ReceivesCopy: Contact to receive a copy of Signed Documents once signing is complete

No Action: Contact needs not further action

type
required
string
Enum: "Broker" "Buyer" "BuyerAgent" "BuyersLawyer" "EscrowOfficer" "LoanOfficer" "Other" "Seller" "SellerAgent" "SellersLawyer" "TitleOfficer"

The role that a contact has been assigned.

isEntity
boolean

Evaluates to true if the contact is an entity.

isUser
boolean

Evaluates to true if the contact is the also the agent (self).

firstName
required
string

The first name of the contact.

middleName
string

The middle name of the contact.

lastName
required
string

The last name of the contact.

suffix
string

The suffix of the contact.

email
string

The email of the contact.

primaryPhoneNumber
string

The primary phone number of the contact.

brokeragePhoneNumber
string

The brokerage phone number of the contact.

faxPhoneNumber
string

The fax phone number of the contact.

object

The primary address of the contact.

companyName
string

The company name that the contact belongs to.

agentLicenseNumber
string

The agent license number of the contact.

agentMLSCode
string

The agent mls code of the contact.

brokerLicenseNumber
string

The broker license number of the contact.

brokerMLSCode
string

The broker mls code of the contact.

brokerageLicenseNumber
string

The brokerage license number of the contact.

brokerageMLSCode
string

The brokerage mls code of the contact.

lenderLicenseNumber
string

The lender license number of the contact.

onBehalfOf
string

The id of the user to add the contact for. When provided, the contact is owned by that user while the authenticated caller is recorded as its creator. Requires that the user has granted delegate access to the authenticated caller; requests without a valid grant are rejected with a 404.

Responses

Request samples

Content type
application/json
{
  • "actionAttribute": "Empty",
  • "type": "Broker",
  • "isEntity": true,
  • "isUser": true,
  • "firstName": "string",
  • "middleName": "string",
  • "lastName": "string",
  • "suffix": "string",
  • "email": "string",
  • "primaryPhoneNumber": "string",
  • "brokeragePhoneNumber": "string",
  • "faxPhoneNumber": "string",
  • "primaryAddress": {
    },
  • "companyName": "string",
  • "agentLicenseNumber": "string",
  • "agentMLSCode": "string",
  • "brokerLicenseNumber": "string",
  • "brokerMLSCode": "string",
  • "brokerageLicenseNumber": "string",
  • "brokerageMLSCode": "string",
  • "lenderLicenseNumber": "string",
  • "onBehalfOf": "string"
}

Response samples

Content type
application/json
{
  • "contactId": 123456
}

Update Contact in File.

Update a contact in a file. Supply onBehalfOf to update the contact for a user who has granted delegate access to the authenticated caller.

REQUIRED SCOPES:
forms.files

path Parameters
contactId
required
integer >= 1

The id of the contact to update.

Request Body schema: application/json
required

The body of the request to add a contact to a file.

actionAttribute
string
Enum: "Empty" "NeedsToSign" "CanView" "ReceivesCopy" "NoAction"

Actions for contact to participate in.

NeedsToSign: Contact will will receive an email containing a document needing to be signed

ReceivesCopy: Contact to receive a copy of Signed Documents once signing is complete

No Action: Contact needs not further action

type
required
string
Enum: "Broker" "Buyer" "BuyerAgent" "BuyersLawyer" "EscrowOfficer" "LoanOfficer" "Other" "Seller" "SellerAgent" "SellersLawyer" "TitleOfficer"

The role that a contact has been assigned.

isEntity
boolean

Evaluates to true if the contact is an entity.

isUser
boolean

Evaluates to true if the contact is the also the agent (self).

firstName
required
string

The first name of the contact.

middleName
string

The middle name of the contact.

lastName
required
string

The last name of the contact.

suffix
string

The suffix of the contact.

email
string

The email of the contact.

primaryPhoneNumber
string

The primary phone number of the contact.

brokeragePhoneNumber
string

The brokerage phone number of the contact.

faxPhoneNumber
string

The fax phone number of the contact.

object

The primary address of the contact.

companyName
string

The company name that the contact belongs to.

agentLicenseNumber
string

The agent license number of the contact.

agentMLSCode
string

The agent mls code of the contact.

brokerLicenseNumber
string

The broker license number of the contact.

brokerMLSCode
string

The broker mls code of the contact.

brokerageLicenseNumber
string

The brokerage license number of the contact.

brokerageMLSCode
string

The brokerage mls code of the contact.

lenderLicenseNumber
string

The lender license number of the contact.

onBehalfOf
string

The id of the user to add the contact for. When provided, the contact is owned by that user while the authenticated caller is recorded as its creator. Requires that the user has granted delegate access to the authenticated caller; requests without a valid grant are rejected with a 404.

Responses

Request samples

Content type
application/json
{
  • "actionAttribute": "Empty",
  • "type": "Broker",
  • "isEntity": true,
  • "isUser": true,
  • "firstName": "string",
  • "middleName": "string",
  • "lastName": "string",
  • "suffix": "string",
  • "email": "string",
  • "primaryPhoneNumber": "string",
  • "brokeragePhoneNumber": "string",
  • "faxPhoneNumber": "string",
  • "primaryAddress": {
    },
  • "companyName": "string",
  • "agentLicenseNumber": "string",
  • "agentMLSCode": "string",
  • "brokerLicenseNumber": "string",
  • "brokerMLSCode": "string",
  • "brokerageLicenseNumber": "string",
  • "brokerageMLSCode": "string",
  • "lenderLicenseNumber": "string",
  • "onBehalfOf": "string"
}

Response samples

Content type
application/json
{
  • "contactId": 123456
}

Add Contacts to File

Add one or more contacts to a file. Supply onBehalfOf to add the contacts for a user who has granted delegate access to the authenticated caller.

REQUIRED SCOPES:
forms.files

path Parameters
fileId
required
integer >= 1

The id of the file to add the contacts to.

Request Body schema: application/json

The body of the request to add multiple contacts to a file.

Array of objects

The contacts to add to the file.

onBehalfOf
string

The id of the user to add the contacts for. When provided, the contacts are owned by that user while the authenticated caller is recorded as their creator. Requires that the user has granted delegate access to the authenticated caller; requests without a valid grant are rejected with a 404.

Responses

Request samples

Content type
application/json
{
  • "contacts": [
    ],
  • "onBehalfOf": "string"
}

Response samples

Content type
application/json
{
  • "totalRecordsAdded": 3,
  • "contacts": [
    ]
}

Delete Contact from File.

Delete a contact from a file.

REQUIRED SCOPES:
forms.files

path Parameters
contactId
required
integer >= 1

The id of the contact to delete.

fileId
required
integer >= 1

The id of the file to delete the contact from.

Responses

Response samples

Content type
application/json
{
  • "contactId": 123456
}

Get File Documents

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.

REQUIRED SCOPES:
forms.documents
forms.documents.read

path Parameters
fileId
required
integer >= 1

The id of the file to retrieve documents for.

Responses

Response samples

Content type
application/json
{
  • "totalRecords": 1,
  • "documents": [
    ]
}

Add Documents to File

Add one or more documents to a file. Supply onBehalfOf to add the documents for a user who has granted delegate access to the authenticated caller; the forms are then resolved against that user's libraries rather than the caller's.

REQUIRED SCOPES:
forms.files
forms.documents

path Parameters
fileId
required
integer >= 1

The id of the file to add the documents to.

Request Body schema: application/json
required
formIds
required
Array of integers non-empty

An array of the Form Ids of the Forms to add to the file.

onBehalfOf
string

The id of the user to add the documents for. When provided, the documents are owned by that user while the authenticated caller is recorded as their creator, and the forms are resolved against that user's libraries rather than the caller's. Requires that the user has granted delegate access to the authenticated caller; requests without a valid grant are rejected with a 404.

Responses

Request samples

Content type
application/json
{
  • "formIds": [
    ],
  • "onBehalfOf": "string"
}

Response samples

Content type
application/json
{
  • "documentIds": [
    ]
}

Get Signed Documents

Retrieve the signed documents for a file.

REQUIRED SCOPES:
forms.documents
forms.documents.read

path Parameters
fileId
required
integer >= 1

The id of the file to retrieve signed documents for.

Responses

Response samples

Content type
application/json
{
  • "totalRecords": 2,
  • "documents": [
    ]
}

Get Signed Documents in Envelope

Retrieve the signed documents for a single envelope in a file.

REQUIRED SCOPES:
forms.documents
forms.documents.read

path Parameters
fileId
required
integer >= 1

The id of the file to retrieve signed documents for.

formsEnvelopeId
required
integer >= 1

The Forms id of the envelope to retrieve signed documents for. This is the numeric id returned by Get Envelopes in File, not the DigiSign envelope guid.

Responses

Response samples

Content type
application/json
{
  • "totalRecords": 2,
  • "documents": [
    ]
}

Subscribe To Signed Documents Webhook

Subscribe a file to the signed documents webhook.

REQUIRED SCOPES:
forms.webhooks

path Parameters
fileId
required
integer >= 1

The id of the file to subscribe to the signed documents webhook.

Request Body schema: application/json
required
webhookUrl
required
string

The url to send the webhook response to when documents are signed documents.

Responses

Request samples

Content type
application/json
{
  • "webhookUrl": "string"
}

Response samples

Content type
application/json
{
  • "subscribed": true
}

Get Envelopes in File

Get the envelopes associated with a file.

REQUIRED SCOPES:
forms.files
forms.files.read

path Parameters
fileId
required
integer >= 1

The id of the file to retrieve envelopes for.

query Parameters
page
integer >= 1
Default: 1

The page number to retrieve.

pageSize
integer [ 1 .. 500 ]
Default: 10

The number of files returned per page.

filters
string

A sieve filter to that will be applied to the results.

sorts
string

A sieve list of sort fields to sort the results by.

Responses

Response samples

Content type
application/json
{
  • "totalRecords": 0,
  • "envelopes": [
    ]
}

Create Envelope in File

Create an envelope for a file. Supply onBehalfOf to create the envelope for a user who has granted delegate access to the authenticated caller; the envelope is then owned by that user and is sent from them when it goes out for signature.

REQUIRED SCOPES:
forms.files

path Parameters
fileId
required
integer >= 1

The id of the file to add the envelope to.

Request Body schema: application/json
required
envelopeName
required
string

The name of the envelope to add to the file.

documentIds
required
Array of numbers

An array of the ids of the documents to add to the envelope.

onBehalfOf
string

The id of the user to create the envelope for. When provided, the envelope is owned by that user while the authenticated caller is recorded as its creator, and the envelope is sent from that user when it goes out for signature. Requires that the user has granted delegate access to the authenticated caller; requests without a valid grant are rejected with a 404.

Responses

Request samples

Content type
application/json
{
  • "envelopeName": "string",
  • "documentIds": [
    ],
  • "onBehalfOf": "string"
}

Response samples

Content type
application/json
{
  • "fileId": 539181,
  • "envelope": {
    }
}

Apply Template to File

Apply a template to a file.

REQUIRED SCOPES:
forms.files

path Parameters
fileId
required
integer >= 1

The id of the file to apply the template to.

Request Body schema: application/json
required
templateId
required
integer

The id of the template to apply to the file.

Responses

Request samples

Content type
application/json
{
  • "templateId": 0
}

Response samples

Content type
application/json
{
  • "fileId": 667309
}

Download File Documents as PDF

Download one or more documents from a file as a combined PDF with file details stamped on the documents. If the call is successful, the response will be a PDF file containing the requested documents. If it is not successful, the response will be json containing the error.

REQUIRED SCOPES:
forms.files
forms.documents

path Parameters
fileId
required
integer >= 1

The id of the file to download documents from.

query Parameters
documentIds
required
string

Comma-separated list of document IDs to include in the PDF. Example: "123,456,789"

Responses

Response samples

Content type
application/json
{
  • "code": "string",
  • "message": "string",
  • "errors": [
    ],
  • "traceId": "string"
}

Download File Documents

Download one or more documents from a file with file details stamped on the documents. Returns a single PDF if one document ID is provided, or a ZIP file containing multiple documents if more than one document ID is provided. The Content-Type header will reflect the appropriate file type.

REQUIRED SCOPES:
forms.documents.read

path Parameters
fileId
required
integer >= 1

The id of the file to download documents from.

query Parameters
documentIds
required
string

Comma-separated list of document IDs to download. Single ID returns PDF, multiple IDs return ZIP. Example: "123,456,789"

Responses

Response samples

Content type
application/json
{
  • "code": "string",
  • "message": "string",
  • "errors": [
    ],
  • "traceId": "string"
}

Upload Document to File

Upload a PDF document to a file. Max size 25MB. Accepts multipart/form-data with fields: DocumentName (string), DocumentBody (binary PDF file), IsSignedDocument (true/false, optional), onBehalfOf (string, optional). Supply onBehalfOf to upload the document for a user who has granted delegate access to the authenticated caller; the document is then owned by that user while the caller is recorded as its creator.

REQUIRED SCOPES:
forms.files
forms.documents

path Parameters
fileId
required
integer >= 1

The id of the file to upload the document to.

Responses

Response samples

Content type
application/json
{
  • "documentId": 0
}

Import MLS Data into File

Import MLS data into an existing Forms file using an MLS number and the file owner's configured regions. Templates are not supported and return a 400 error.

An omitted or blank MLS number skips the import without changing the saved number. A nonblank number is saved before lookup, even when it differs from the current number. It remains saved if lookup finds no match, multiple matches, or no configured regions.

Only a single listing match is imported. No match or multiple matches skip the import, and listing candidates are not returned. The listing address is not compared with the file address.

With shouldOverride=false, populated data is preserved; address and agent contact values may be handled together as groups. With shouldOverride=true, listing data can replace populated values. The supplied MLS number is saved regardless of this setting.

An imported outcome includes successful imports with a count of zero. The count measures processed fields or field groups rather than exactly how many individual values changed and is omitted when unavailable.

Inspect mlsImport.status even when the HTTP response is 200. A not_imported outcome means no listing data was imported; a supplied MLS number may still have been saved. A failed outcome reports an error during lookup or import. An unknown outcome means a write request timed out and its completion could not be confirmed. Failed or unknown outcomes do not guarantee that file data remained unchanged. Before retrying, check the file and choose shouldOverride accordingly.

For not_imported, missing_mls_number means no nonblank number was supplied; missing_regions means the file owner has no configured search regions; no_match and multiple_matches mean the search returned zero or more than one listing. For failed, provider_error means the owner profile or MLS search could not be retrieved; import_error means saving the MLS number or importing listing data failed.

Saving the MLS number and importing listing data are separate operations, not one atomic update. Send imports for the same file sequentially and avoid editing the file while an import is pending. Even with sequential requests, changing the MLS number with shouldOverride=false can retain data from a previous listing.

This endpoint searches the MLS source selected by the service; callers cannot select a source. Utah and Florida MLS coverage is not fully supported.

REQUIRED SCOPES:
forms.files
forms.mls.import

path Parameters
fileId
required
integer >= 1

The id of the existing Forms file to import MLS data into. Templates are not supported.

Request Body schema: application/json
mlsNumber
string

The MLS number to look up and set on the file, even when it differs from the current number. An omitted or blank value skips the import; the existing file MLS number is not used as a fallback.

shouldOverride
boolean
Default: false

Whether to replace populated file data with listing data. Must be a JSON boolean (true or false), not a string or number. Defaults to false. Address and agent contact values may be preserved or replaced together as groups.

onBehalfOf
string

The Forms user ID to act on behalf of. When specifying another user, that user must have granted delegate access to the authenticated user. The authenticated user must also have permission to update the target file. The delegated user does not have to own the file. Omit this field to act as the authenticated user. MLS lookup always uses the file owner's configured regions, regardless of this field.

Responses

Request samples

Content type
application/json
{
  • "mlsNumber": "string",
  • "shouldOverride": false,
  • "onBehalfOf": "string"
}

Response samples

Content type
application/json
{
  • "fileId": 1,
  • "mlsImport": {
    }
}

Templates

Get Templates

Retrieve templates. Defaults to personal templates (type=Template). Use type=BrokerTemplate for broker templates.

REQUIRED SCOPES:
forms.templates.read
forms.files.read
forms.files

query Parameters
type
string
Default: "Template"

The type of templates to retrieve. Defaults to Template (personal templates).

Responses

Response samples

Content type
application/json
{
  • "totalRecords": 1,
  • "files": [
    ]
}

Contacts

Add Contact to File

Add a contact to a file. Supply onBehalfOf to add the contact for a user who has granted delegate access to the authenticated caller.

REQUIRED SCOPES:
forms.files

path Parameters
fileId
required
integer >= 1

The id of the file to add the contact to.

Request Body schema: application/json
required

The body of the request to add a contact to a file.

actionAttribute
string
Enum: "Empty" "NeedsToSign" "CanView" "ReceivesCopy" "NoAction"

Actions for contact to participate in.

NeedsToSign: Contact will will receive an email containing a document needing to be signed

ReceivesCopy: Contact to receive a copy of Signed Documents once signing is complete

No Action: Contact needs not further action

type
required
string
Enum: "Broker" "Buyer" "BuyerAgent" "BuyersLawyer" "EscrowOfficer" "LoanOfficer" "Other" "Seller" "SellerAgent" "SellersLawyer" "TitleOfficer"

The role that a contact has been assigned.

isEntity
boolean

Evaluates to true if the contact is an entity.

isUser
boolean

Evaluates to true if the contact is the also the agent (self).

firstName
required
string

The first name of the contact.

middleName
string

The middle name of the contact.

lastName
required
string

The last name of the contact.

suffix
string

The suffix of the contact.

email
string

The email of the contact.

primaryPhoneNumber
string

The primary phone number of the contact.

brokeragePhoneNumber
string

The brokerage phone number of the contact.

faxPhoneNumber
string

The fax phone number of the contact.

object

The primary address of the contact.

companyName
string

The company name that the contact belongs to.

agentLicenseNumber
string

The agent license number of the contact.

agentMLSCode
string

The agent mls code of the contact.

brokerLicenseNumber
string

The broker license number of the contact.

brokerMLSCode
string

The broker mls code of the contact.

brokerageLicenseNumber
string

The brokerage license number of the contact.

brokerageMLSCode
string

The brokerage mls code of the contact.

lenderLicenseNumber
string

The lender license number of the contact.

onBehalfOf
string

The id of the user to add the contact for. When provided, the contact is owned by that user while the authenticated caller is recorded as its creator. Requires that the user has granted delegate access to the authenticated caller; requests without a valid grant are rejected with a 404.

Responses

Request samples

Content type
application/json
{
  • "actionAttribute": "Empty",
  • "type": "Broker",
  • "isEntity": true,
  • "isUser": true,
  • "firstName": "string",
  • "middleName": "string",
  • "lastName": "string",
  • "suffix": "string",
  • "email": "string",
  • "primaryPhoneNumber": "string",
  • "brokeragePhoneNumber": "string",
  • "faxPhoneNumber": "string",
  • "primaryAddress": {
    },
  • "companyName": "string",
  • "agentLicenseNumber": "string",
  • "agentMLSCode": "string",
  • "brokerLicenseNumber": "string",
  • "brokerMLSCode": "string",
  • "brokerageLicenseNumber": "string",
  • "brokerageMLSCode": "string",
  • "lenderLicenseNumber": "string",
  • "onBehalfOf": "string"
}

Response samples

Content type
application/json
{
  • "contactId": 123456
}

Update Contact in File.

Update a contact in a file. Supply onBehalfOf to update the contact for a user who has granted delegate access to the authenticated caller.

REQUIRED SCOPES:
forms.files

path Parameters
contactId
required
integer >= 1

The id of the contact to update.

Request Body schema: application/json
required

The body of the request to add a contact to a file.

actionAttribute
string
Enum: "Empty" "NeedsToSign" "CanView" "ReceivesCopy" "NoAction"

Actions for contact to participate in.

NeedsToSign: Contact will will receive an email containing a document needing to be signed

ReceivesCopy: Contact to receive a copy of Signed Documents once signing is complete

No Action: Contact needs not further action

type
required
string
Enum: "Broker" "Buyer" "BuyerAgent" "BuyersLawyer" "EscrowOfficer" "LoanOfficer" "Other" "Seller" "SellerAgent" "SellersLawyer" "TitleOfficer"

The role that a contact has been assigned.

isEntity
boolean

Evaluates to true if the contact is an entity.

isUser
boolean

Evaluates to true if the contact is the also the agent (self).

firstName
required
string

The first name of the contact.

middleName
string

The middle name of the contact.

lastName
required
string

The last name of the contact.

suffix
string

The suffix of the contact.

email
string

The email of the contact.

primaryPhoneNumber
string

The primary phone number of the contact.

brokeragePhoneNumber
string

The brokerage phone number of the contact.

faxPhoneNumber
string

The fax phone number of the contact.

object

The primary address of the contact.

companyName
string

The company name that the contact belongs to.

agentLicenseNumber
string

The agent license number of the contact.

agentMLSCode
string

The agent mls code of the contact.

brokerLicenseNumber
string

The broker license number of the contact.

brokerMLSCode
string

The broker mls code of the contact.

brokerageLicenseNumber
string

The brokerage license number of the contact.

brokerageMLSCode
string

The brokerage mls code of the contact.

lenderLicenseNumber
string

The lender license number of the contact.

onBehalfOf
string

The id of the user to add the contact for. When provided, the contact is owned by that user while the authenticated caller is recorded as its creator. Requires that the user has granted delegate access to the authenticated caller; requests without a valid grant are rejected with a 404.

Responses

Request samples

Content type
application/json
{
  • "actionAttribute": "Empty",
  • "type": "Broker",
  • "isEntity": true,
  • "isUser": true,
  • "firstName": "string",
  • "middleName": "string",
  • "lastName": "string",
  • "suffix": "string",
  • "email": "string",
  • "primaryPhoneNumber": "string",
  • "brokeragePhoneNumber": "string",
  • "faxPhoneNumber": "string",
  • "primaryAddress": {
    },
  • "companyName": "string",
  • "agentLicenseNumber": "string",
  • "agentMLSCode": "string",
  • "brokerLicenseNumber": "string",
  • "brokerMLSCode": "string",
  • "brokerageLicenseNumber": "string",
  • "brokerageMLSCode": "string",
  • "lenderLicenseNumber": "string",
  • "onBehalfOf": "string"
}

Response samples

Content type
application/json
{
  • "contactId": 123456
}

Add Contacts to File

Add one or more contacts to a file. Supply onBehalfOf to add the contacts for a user who has granted delegate access to the authenticated caller.

REQUIRED SCOPES:
forms.files

path Parameters
fileId
required
integer >= 1

The id of the file to add the contacts to.

Request Body schema: application/json

The body of the request to add multiple contacts to a file.

Array of objects

The contacts to add to the file.

onBehalfOf
string

The id of the user to add the contacts for. When provided, the contacts are owned by that user while the authenticated caller is recorded as their creator. Requires that the user has granted delegate access to the authenticated caller; requests without a valid grant are rejected with a 404.

Responses

Request samples

Content type
application/json
{
  • "contacts": [
    ],
  • "onBehalfOf": "string"
}

Response samples

Content type
application/json
{
  • "totalRecordsAdded": 3,
  • "contacts": [
    ]
}

Delete Contact from File.

Delete a contact from a file.

REQUIRED SCOPES:
forms.files

path Parameters
contactId
required
integer >= 1

The id of the contact to delete.

fileId
required
integer >= 1

The id of the file to delete the contact from.

Responses

Response samples

Content type
application/json
{
  • "contactId": 123456
}

Documents

Get Document

Retrieve the details and field definitions for a document by its id.

REQUIRED SCOPES:
forms.documents
forms.documents.read

path Parameters
documentId
required
integer >= 1

The id of the document to retrieve.

query Parameters
page
integer >= 1
Default: 1

The page number of fields to retrieve.

pageSize
integer [ 1 .. 500 ]
Default: 10

The number of fields returned per page.

Responses

Response samples

Content type
application/json
{
  • "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": [
    ]
}

Update Document

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.

REQUIRED SCOPES:
forms.documents

path Parameters
documentId
required
integer >= 1

The id of the document to update.

Request Body schema: application/json

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.

property name*
additional property
any

Responses

Request samples

Content type
application/json
{ }

Response samples

Content type
application/json
{
  • "documentId": 123456,
  • "didAddendumsChange": false
}

Delete Document.

Delete a document.

REQUIRED SCOPES:
forms.documents

path Parameters
documentId
required
integer >= 1

The id of the document to delete.

Responses

Response samples

Content type
application/json
{
  • "documentId": 123456
}

Get File Documents

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.

REQUIRED SCOPES:
forms.documents
forms.documents.read

path Parameters
fileId
required
integer >= 1

The id of the file to retrieve documents for.

Responses

Response samples

Content type
application/json
{
  • "totalRecords": 1,
  • "documents": [
    ]
}

Add Documents to File

Add one or more documents to a file. Supply onBehalfOf to add the documents for a user who has granted delegate access to the authenticated caller; the forms are then resolved against that user's libraries rather than the caller's.

REQUIRED SCOPES:
forms.files
forms.documents

path Parameters
fileId
required
integer >= 1

The id of the file to add the documents to.

Request Body schema: application/json
required
formIds
required
Array of integers non-empty

An array of the Form Ids of the Forms to add to the file.

onBehalfOf
string

The id of the user to add the documents for. When provided, the documents are owned by that user while the authenticated caller is recorded as their creator, and the forms are resolved against that user's libraries rather than the caller's. Requires that the user has granted delegate access to the authenticated caller; requests without a valid grant are rejected with a 404.

Responses

Request samples

Content type
application/json
{
  • "formIds": [
    ],
  • "onBehalfOf": "string"
}

Response samples

Content type
application/json
{
  • "documentIds": [
    ]
}

Get Signed Documents

Retrieve the signed documents for a file.

REQUIRED SCOPES:
forms.documents
forms.documents.read

path Parameters
fileId
required
integer >= 1

The id of the file to retrieve signed documents for.

Responses

Response samples

Content type
application/json
{
  • "totalRecords": 2,
  • "documents": [
    ]
}

Get Signed Documents in Envelope

Retrieve the signed documents for a single envelope in a file.

REQUIRED SCOPES:
forms.documents
forms.documents.read

path Parameters
fileId
required
integer >= 1

The id of the file to retrieve signed documents for.

formsEnvelopeId
required
integer >= 1

The Forms id of the envelope to retrieve signed documents for. This is the numeric id returned by Get Envelopes in File, not the DigiSign envelope guid.

Responses

Response samples

Content type
application/json
{
  • "totalRecords": 2,
  • "documents": [
    ]
}

Subscribe To Signed Documents Webhook

Subscribe a file to the signed documents webhook.

REQUIRED SCOPES:
forms.webhooks

path Parameters
fileId
required
integer >= 1

The id of the file to subscribe to the signed documents webhook.

Request Body schema: application/json
required
webhookUrl
required
string

The url to send the webhook response to when documents are signed documents.

Responses

Request samples

Content type
application/json
{
  • "webhookUrl": "string"
}

Response samples

Content type
application/json
{
  • "subscribed": true
}

Upload Document to File

Upload a PDF document to a file. Max size 25MB. Accepts multipart/form-data with fields: DocumentName (string), DocumentBody (binary PDF file), IsSignedDocument (true/false, optional), onBehalfOf (string, optional). Supply onBehalfOf to upload the document for a user who has granted delegate access to the authenticated caller; the document is then owned by that user while the caller is recorded as its creator.

REQUIRED SCOPES:
forms.files
forms.documents

path Parameters
fileId
required
integer >= 1

The id of the file to upload the document to.

Responses

Response samples

Content type
application/json
{
  • "documentId": 0
}

Envelopes

Get Signed Documents in Envelope

Retrieve the signed documents for a single envelope in a file.

REQUIRED SCOPES:
forms.documents
forms.documents.read

path Parameters
fileId
required
integer >= 1

The id of the file to retrieve signed documents for.

formsEnvelopeId
required
integer >= 1

The Forms id of the envelope to retrieve signed documents for. This is the numeric id returned by Get Envelopes in File, not the DigiSign envelope guid.

Responses

Response samples

Content type
application/json
{
  • "totalRecords": 2,
  • "documents": [
    ]
}

Get Envelopes in File

Get the envelopes associated with a file.

REQUIRED SCOPES:
forms.files
forms.files.read

path Parameters
fileId
required
integer >= 1

The id of the file to retrieve envelopes for.

query Parameters
page
integer >= 1
Default: 1

The page number to retrieve.

pageSize
integer [ 1 .. 500 ]
Default: 10

The number of files returned per page.

filters
string

A sieve filter to that will be applied to the results.

sorts
string

A sieve list of sort fields to sort the results by.

Responses

Response samples

Content type
application/json
{
  • "totalRecords": 0,
  • "envelopes": [
    ]
}

Create Envelope in File

Create an envelope for a file. Supply onBehalfOf to create the envelope for a user who has granted delegate access to the authenticated caller; the envelope is then owned by that user and is sent from them when it goes out for signature.

REQUIRED SCOPES:
forms.files

path Parameters
fileId
required
integer >= 1

The id of the file to add the envelope to.

Request Body schema: application/json
required
envelopeName
required
string

The name of the envelope to add to the file.

documentIds
required
Array of numbers

An array of the ids of the documents to add to the envelope.

onBehalfOf
string

The id of the user to create the envelope for. When provided, the envelope is owned by that user while the authenticated caller is recorded as its creator, and the envelope is sent from that user when it goes out for signature. Requires that the user has granted delegate access to the authenticated caller; requests without a valid grant are rejected with a 404.

Responses

Request samples

Content type
application/json
{
  • "envelopeName": "string",
  • "documentIds": [
    ],
  • "onBehalfOf": "string"
}

Response samples

Content type
application/json
{
  • "fileId": 539181,
  • "envelope": {
    }
}

Webhooks

Subscribe To Signed Documents Webhook

Subscribe a file to the signed documents webhook.

REQUIRED SCOPES:
forms.webhooks

path Parameters
fileId
required
integer >= 1

The id of the file to subscribe to the signed documents webhook.

Request Body schema: application/json
required
webhookUrl
required
string

The url to send the webhook response to when documents are signed documents.

Responses

Request samples

Content type
application/json
{
  • "webhookUrl": "string"
}

Response samples

Content type
application/json
{
  • "subscribed": true
}

Forms

Get Forms

Get all of the Forms that the currently authenticated user has access to.

REQUIRED SCOPES:
forms.forms.read

query Parameters
libraryIds
Array of integers

Supply an array of library ids to filter the forms by. NOTE: If a libraryId is provided that the current user does not have access to, it will be ignored.

page
integer >= 1
Default: 1

The page number to retrieve.

pageSize
integer >= 1
Default: 10

The number of forms returned per page.

Responses

Response samples

Content type
application/json
{}

Users

Get Collaborators

Retrieve the collaborators of the currently authenticated user - everyone they share Forms access with, in either direction. Collaborators with isReceivingAccess have shared their access with the caller, and their ids are the values accepted as onBehalfOf on the file write endpoints. Collaborators with only isSharingAccess cannot be used that way.

REQUIRED SCOPES:
forms.collaborators.read

Responses

Response samples

Content type
application/json
{
  • "totalRecords": 2,
  • "collaborators": [
    ]
}

Get User Profile

Retrieve the user profile of the currently authenticated user

Responses

Response samples

Content type
application/json
{
  • "id": "string",
  • "subscriberId": "string",
  • "firstName": "string",
  • "middleName": "string",
  • "lastName": "string",
  • "suffix": "string",
  • "email": "string",
  • "primaryPhoneNumber": "string",
  • "brokerageName": "string",
  • "brokerageAddress": {
    },
  • "brokeragePhone": "string",
  • "brokerageFax": "string",
  • "regions": [
    ],
  • "libraries": [
    ],
  • "authProfiles": [
    ],
  • "isInitialized": true,
  • "termAcceptanceDate": "string",
  • "mlsCode": "string",
  • "licenseNumber": "string",
  • "brokerageLicenseNumber": "string",
  • "brokerageMLSCode": "string",
  • "isAutoDeletePreDraftEnvelopeAllowed": true,
  • "isAutoDeleteFormAllowed": true,
  • "consentedAssociations": [
    ],
  • "userPreferences": {
    },
  • "location": "string",
  • "createdOn": "string",
  • "createdBy": "string",
  • "updatedOn": "string",
  • "updatedBy": "string"
}

Add Group

Create a new group via accounts-api.

REQUIRED SCOPES:
admin.groups

Request Body schema: application/json
brokerageId
string

The brokerage id for the new group. If not provided, will be auto-generated with prefix "partnerApi_".

brokerageName
string

The name of the brokerage.

Responses

Request samples

Content type
application/json
{
  • "brokerageId": "string",
  • "brokerageName": "string"
}

Response samples

Content type
application/json
{
  • "groupId": "string"
}

Add Child Group

Create a new child group for a parent group via accounts-api.

REQUIRED SCOPES:
admin.groups

path Parameters
groupId
required
string non-empty

The id of the parent group.

Request Body schema: application/json
required
name
required
string non-empty

The name of the child group.

Responses

Request samples

Content type
application/json
{
  • "name": "string"
}

Response samples

Content type
application/json
{
  • "childGroupId": "string"
}

Add Group to User

Add group to a user.

REQUIRED SCOPES:
admin.groups

path Parameters
userId
required
string non-empty

The id of the user to add to the group.

groupId
required
string non-empty

The id of the group to add the user to.

Responses

Response samples

Content type
application/json
{
  • "code": "string",
  • "message": "string",
  • "errors": [
    ],
  • "traceId": "string"
}

Remove User from Group

Remove a user from a group.

REQUIRED SCOPES:
admin.groups

path Parameters
userId
required
string non-empty

The id of the user to remove from the group.

groupId
required
string non-empty

The id of the group to remove the user from.

Responses

Response samples

Content type
application/json
{
  • "code": "string",
  • "message": "string",
  • "errors": [
    ],
  • "traceId": "string"
}

Libraries

Get Form Tags

Retrieve the tags that are associated with the forms.

REQUIRED SCOPES:
forms.forms.read

query Parameters
ids
string

The form version ids to retrieve tags for.

Responses

Response samples

Content type
application/json
{
  • "totalRecords": 2,
  • "records": [
    ]
}

Get Libraries

Retrieve the libraries that the user is authorized to access.

REQUIRED SCOPES:
forms.libraries.read

Responses

Response samples

Content type
application/json
{
  • "totalRecords": 1,
  • "libraries": [
    ]
}

Get Library Form Versions

Retrieve the form versions for a specific library.

REQUIRED SCOPES:
forms.libraries.read

path Parameters
libraryId
required
integer >= 1

The id of the library to retrieve form versions for.

Responses

Response samples

Content type
application/json
{
  • "totalRecords": 5,
  • "formVersions": [
    ]
}

Buyer Agreements

Get Buyer Agreements By Market

Retrieve the buyer agreements for a specific market.

REQUIRED SCOPES:
forms.buyerAgreements.restrictedRead

query Parameters
filters
string

A sieve list of filters that will be applied to the results.

Responses

Response samples

Content type
application/json
{
  • "totalRecords": 1,
  • "files": [
    ]
}