SkySlope Contacts API
The Contacts API from SkySlope — 4 operation(s) for contacts.
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 Contacts 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: Contacts
paths:
/files/{fileId}/contacts:
post:
summary: Add Contact to File
tags:
- Contacts
description: 'Add a contact 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>'
requestBody:
content:
application/json:
schema:
type: object
description: The body of the request to add a contact to a file.
required:
- firstName
- lastName
- type
additionalProperties: false
properties:
actionAttribute:
type: string
enum:
- Empty
- NeedsToSign
- CanView
- ReceivesCopy
- NoAction
description: "Actions for contact to participate in.\n <br><p><strong>NeedsToSign:</strong> Contact will will receive an email containing a document needing to be signed\n</p><p><strong>ReceivesCopy:</strong> Contact to receive a copy of Signed Documents once signing is complete</p><p><strong>No Action:</strong> Contact needs not further action</p>"
type:
type: string
enum:
- Broker
- Buyer
- BuyerAgent
- BuyersLawyer
- EscrowOfficer
- LoanOfficer
- Other
- Seller
- SellerAgent
- SellersLawyer
- TitleOfficer
description: The role that a contact has been assigned.
isEntity:
type: boolean
description: Evaluates to true if the contact is an entity.
isUser:
type: boolean
description: Evaluates to true if the contact is the also the agent (self).
firstName:
type: string
description: The first name of the contact.
middleName:
type: string
description: The middle name of the contact.
lastName:
type: string
description: The last name of the contact.
suffix:
type: string
description: The suffix of the contact.
email:
type: string
description: The email of the contact.
primaryPhoneNumber:
type: string
description: The primary phone number of the contact.
brokeragePhoneNumber:
type: string
description: The brokerage phone number of the contact.
faxPhoneNumber:
type: string
description: The fax phone number of the contact.
primaryAddress:
type: object
description: The primary address of the contact.
additionalProperties: false
properties:
streetNumber:
type: string
description: The street number of the property.
streetName:
type: string
description: The street name of the property.
unitNumber:
type: string
description: The unit number of the property.
city:
type: string
description: The city of the property.
state:
type: string
description: The abbreviation for the state/province of the property.
minLength: 2
maxLength: 2
postalCode:
type: string
description: The postal code of the property.
county:
type: string
description: The county of the property.
required:
- streetNumber
- streetName
- city
- state
- postalCode
companyName:
type: string
description: The company name that the contact belongs to.
agentLicenseNumber:
type: string
description: The agent license number of the contact.
agentMLSCode:
type: string
description: The agent mls code of the contact.
brokerLicenseNumber:
type: string
description: The broker license number of the contact.
brokerMLSCode:
type: string
description: The broker mls code of the contact.
brokerageLicenseNumber:
type: string
description: The brokerage license number of the contact.
brokerageMLSCode:
type: string
description: The brokerage mls code of the contact.
lenderLicenseNumber:
type: string
description: The lender license number of the contact.
required: true
description: The body of the request to add a contact to a file.
parameters:
- schema:
type: integer
minimum: 1
in: path
name: fileId
required: true
description: The id of the file to add the contact to.
responses:
'200':
description: Default Response
content:
application/json:
schema:
type: object
properties:
contactId:
type: number
description: The id of the contact that was added to the file.
example:
contactId: 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/contacts/{contactId}:
put:
summary: Update Contact in File.
tags:
- Contacts
description: 'Update a contact in 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>'
requestBody:
content:
application/json:
schema:
type: object
description: The body of the request to add a contact to a file.
required:
- firstName
- lastName
- type
additionalProperties: false
properties:
actionAttribute:
type: string
enum:
- Empty
- NeedsToSign
- CanView
- ReceivesCopy
- NoAction
description: "Actions for contact to participate in.\n <br><p><strong>NeedsToSign:</strong> Contact will will receive an email containing a document needing to be signed\n</p><p><strong>ReceivesCopy:</strong> Contact to receive a copy of Signed Documents once signing is complete</p><p><strong>No Action:</strong> Contact needs not further action</p>"
type:
type: string
enum:
- Broker
- Buyer
- BuyerAgent
- BuyersLawyer
- EscrowOfficer
- LoanOfficer
- Other
- Seller
- SellerAgent
- SellersLawyer
- TitleOfficer
description: The role that a contact has been assigned.
isEntity:
type: boolean
description: Evaluates to true if the contact is an entity.
isUser:
type: boolean
description: Evaluates to true if the contact is the also the agent (self).
firstName:
type: string
description: The first name of the contact.
middleName:
type: string
description: The middle name of the contact.
lastName:
type: string
description: The last name of the contact.
suffix:
type: string
description: The suffix of the contact.
email:
type: string
description: The email of the contact.
primaryPhoneNumber:
type: string
description: The primary phone number of the contact.
brokeragePhoneNumber:
type: string
description: The brokerage phone number of the contact.
faxPhoneNumber:
type: string
description: The fax phone number of the contact.
primaryAddress:
type: object
description: The primary address of the contact.
additionalProperties: false
properties:
streetNumber:
type: string
description: The street number of the property.
streetName:
type: string
description: The street name of the property.
unitNumber:
type: string
description: The unit number of the property.
city:
type: string
description: The city of the property.
state:
type: string
description: The abbreviation for the state/province of the property.
minLength: 2
maxLength: 2
postalCode:
type: string
description: The postal code of the property.
county:
type: string
description: The county of the property.
required:
- streetNumber
- streetName
- city
- state
- postalCode
companyName:
type: string
description: The company name that the contact belongs to.
agentLicenseNumber:
type: string
description: The agent license number of the contact.
agentMLSCode:
type: string
description: The agent mls code of the contact.
brokerLicenseNumber:
type: string
description: The broker license number of the contact.
brokerMLSCode:
type: string
description: The broker mls code of the contact.
brokerageLicenseNumber:
type: string
description: The brokerage license number of the contact.
brokerageMLSCode:
type: string
description: The brokerage mls code of the contact.
lenderLicenseNumber:
type: string
description: The lender license number of the contact.
required: true
description: The body of the request to add a contact to a file.
parameters:
- schema:
type: integer
minimum: 1
in: path
name: contactId
required: true
description: The id of the contact to update.
responses:
'200':
description: Default Response
content:
application/json:
schema:
type: object
properties:
contactId:
type: number
description: The id of the contact that was added to the file.
example:
contactId: 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}/contacts/bulk:
post:
summary: Add Contacts to File
tags:
- Contacts
description: 'Add one or more contacts 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>'
requestBody:
content:
application/json:
schema:
type: object
description: The body of the request to add multiple contacts to a file.
properties:
contacts:
type: array
description: The contacts to add to the file.
items:
type: object
description: The body of the request to add a contact to a file.
required:
- firstName
- lastName
- type
additionalProperties: false
properties:
actionAttribute:
type: string
enum:
- Empty
- NeedsToSign
- CanView
- ReceivesCopy
- NoAction
description: "Actions for contact to participate in.\n <br><p><strong>NeedsToSign:</strong> Contact will will receive an email containing a document needing to be signed\n</p><p><strong>ReceivesCopy:</strong> Contact to receive a copy of Signed Documents once signing is complete</p><p><strong>No Action:</strong> Contact needs not further action</p>"
type:
type: string
enum:
- Broker
- Buyer
- BuyerAgent
- BuyersLawyer
- EscrowOfficer
- LoanOfficer
- Other
- Seller
- SellerAgent
- SellersLawyer
- TitleOfficer
description: The role that a contact has been assigned.
isEntity:
type: boolean
description: Evaluates to true if the contact is an entity.
isUser:
type: boolean
description: Evaluates to true if the contact is the also the agent (self).
firstName:
type: string
description: The first name of the contact.
middleName:
type: string
description: The middle name of the contact.
lastName:
type: string
description: The last name of the contact.
suffix:
type: string
description: The suffix of the contact.
email:
type: string
description: The email of the contact.
primaryPhoneNumber:
type: string
description: The primary phone number of the contact.
brokeragePhoneNumber:
type: string
description: The brokerage phone number of the contact.
faxPhoneNumber:
type: string
description: The fax phone number of the contact.
primaryAddress:
type: object
description: The primary address of the contact.
additionalProperties: false
properties:
streetNumber:
type: string
description: The street number of the property.
streetName:
type: string
description: The street name of the property.
unitNumber:
type: string
description: The unit number of the property.
city:
type: string
description: The city of the property.
state:
type: string
description: The abbreviation for the state/province of the property.
minLength: 2
maxLength: 2
postalCode:
type: string
description: The postal code of the property.
county:
type: string
description: The county of the property.
required:
- streetNumber
- streetName
- city
- state
- postalCode
companyName:
type: string
description: The company name that the contact belongs to.
agentLicenseNumber:
type: string
description: The agent license number of the contact.
agentMLSCode:
type: string
description: The agent mls code of the contact.
brokerLicenseNumber:
type: string
description: The broker license number of the contact.
brokerMLSCode:
type: string
description: The broker mls code of the contact.
brokerageLicenseNumber:
type: string
description: The brokerage license number of the contact.
brokerageMLSCode:
type: string
description: The brokerage mls code of the contact.
lenderLicenseNumber:
type: string
description: The lender license number of the contact.
description: The body of the request to add multiple contacts to a file.
parameters:
- schema:
type: integer
minimum: 1
in: path
name: fileId
required: true
description: The id of the file to add the contacts to.
responses:
'200':
description: Default Response
content:
application/json:
schema:
type: object
properties:
totalRecordsAdded:
type: number
description: The total number of contacts that were added to the file.
example:
totalRecordsAdded: 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.
/files/{fileId}/contacts/{contactId}:
delete:
summary: Delete Contact from File.
tags:
- Contacts
description: 'Delete a contact from 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>'
parameters:
- schema:
type: integer
minimum: 1
in: path
name: contactId
required: true
description: The id of the contact to delete.
- schema:
type: integer
minimum: 1
in: path
name: fileId
required: true
description: The id of the file to delete the contact from.
responses:
'200':
description: Default Response
content:
application/json:
schema:
type: object
required:
- contactId
properties:
contactId:
type: number
description: The id of the contact that was deleted from the file.
example:
contactId: 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.