logo
Powered by Redocly

Portal API Docs (2024.09.18)

Download OpenAPI specification:Download

E-mail: support@portal.io URL: https://portal.io/contact Terms of Service

Run in Postman

Getting Started

The Portal API is a RESTful service. It uses resource-oriented URLs, accepts JSON-encoded request bodies, returns JSON-encoded responses, and uses standard HTTP response codes, authentication, and verbs.


PRODUCTION ACCESS

You will use our sandbox until your integration is reviewed and approved. Once approved we'll provide keys to use our production API at https://api.portal.io


SANDBOX ACCESS

STEP 1
Sign up for a free Sandbox Account at https://sandbox.portal.io. This is a dealer test account you will use to exchange test data.

STEP 2
After you have a sandbox account, let your Portal rep know, and they will provide you an API Application Key, as well as a Secret Key (used to hach the signature in your requests)

STEP 3
You're now ready to get your User Key. Please refer to the User Authentication section, which is next in these docs. The User Key is the last thing you'll need to start making requests to the sandbox API at https://sandbox.api.portal.io

User Authentication

To start making API calls you’ll need a User Key. You’ll make a request at https://sandbox.api.portal.io/authenticate/apikeyexchange.

Send your Portal account Username and Password and pass the following headers:

  • X-MSS-API-APPID - API Application Key
  • X-MSS-CUSTOM-DATE - a date time stamp of the request
  • X-MSS-SIGNATURE - A signature for the request.


SANDBOX SAMPLE SIGNATURE - GET a User Key

GEThttps://sandbox.api.portal.io/authenticate/apikeyexchangeMon, 29 Aug 2022 13:30:55 GMT

**Important** The signature must be hashed with HMAC SHA256 using Secret Key and converted to Base64





Once you have your User Key you are ready to start making requests. The signature format for all requests is as follows. Notice the UserKey is added to the end of the concatenated string.

[Verb of the Request][its URL][Content Type][Date Timestamp][User API key]


SANDBOX SAMPLE SIGNATURE - GET Proposal List

GEThttps://api.portal.io/proposalsMon, 29 Aug 2022 13:30:55 GMTGhr/FRUWkligku/RQC49bWl0PohT46mQaX0ptShYMvk=

Note, there is no content type for Get request.

**Important** The signature must be hashed with HMAC SHA256 using Secret Key and converted to Base64

Authenticate User & Get User Token

Sign In

Request
query Parameters
UserName
required
string <= 256 characters

user email address

Password
required
string <password>

user password

header Parameters
Accept
required
string

Accept Header

Value: "application/json"
X-MSS-API-APPID
required
string

Application Id

X-MSS-CUSTOM-DATE
required
string

A date timestamp of the request

X-MSS-SIGNATURE
required
string

A signature for the request

Responses
200

Success

401

Invalid credentials or User Email is not verified

get/authenticate/apikeyexchange
Request samples 
Response samples 
application/json
{
  • "userId": "string",
  • "sessionId": "string",
  • "userName": "string",
  • "displayName": "string",
  • "referrerUrl": "string",
  • "bearerToken": "string",
  • "refreshToken": "string",
  • "refreshTokenExpiry": "2019-08-24T14:15:22Z",
  • "profileUrl": "string",
  • "roles": [
    ],
  • "permissions": [
    ],
  • "responseStatus": {
    },
  • "meta": {
    }
}
Proposals
The 'Proposals' service contains two main endpoints: Search & Get Proposal List, and Get Proposal Details. The search endpoint provides you basic summary information about proposals, including the Proposal Id, which you can then use to query the Proposal details endpoint, and get full detail, including line items.


Search & Get Proposal List
Returns a list of all proposals, with summary information such as Status, Total and Customer.


Request 
query Parameters
SearchText
string
Search proposal by this text


 
Statuses
Array of strings
 
ContactId
integer <int32> 
 
ModifiedAfter
string <date-time> 
Modified after timestamp in UTC


 
SortBy
string
 Enum: "CreatedDate" "ModifiedDate" "Number" "Name" "ClientName" "Status" "LastModifiedByMe"  
SortDirection
string
 
PageNumber
integer <int32> 
Page number. Starting from 1


 
PageSize
integer <int32> 
Page Size


 
header Parameters
Accept
required
string
Accept Header


 Value: "application/json"  
X-MSS-API-APPID
required
string
Application Id


 
X-MSS-CUSTOM-DATE
required
string
A date timestamp of the request


 
X-MSS-SIGNATURE
required
string
A signature for the request


 
X-MSS-API-USERKEY
required
string
User API Key


 
Responses 
200
Proposal List.


401
Not Authorized to access this endpoint or your HMAC hash was incorrect.


402
This action requires an active subscription.


403
You do not have permission for this API call.


get/public/proposals
Request samples 
Response samples 
application/json
{
  • "proposals": [
    ],
  • "proposalCount": 0
}
Get Proposal Details
Using the Proposal ID you can get all the details for a proposal. It's important to understand the data structure of our proposals so you know where to find the item details.  


Proposal
  Areas
    Options
      Items  


Items are contained within Options, and Options are contained with Areas. Options allow the client to choose between different variations of an area. Only a single option can be accepted. We show you the declined options as well so you'll need to ignore those if you only care about items on accepted proposals.


Request 
path Parameters
ProposalId
required
integer <int32> 
Proposal Id.


 
header Parameters
Accept
required
string
Accept Header


 Value: "application/json"  
X-MSS-API-APPID
required
string
Application Id


 
X-MSS-CUSTOM-DATE
required
string
A date timestamp of the request


 
X-MSS-SIGNATURE
required
string
A signature for the request


 
X-MSS-API-USERKEY
required
string
User API Key


 
Responses 
200
Proposal Details


401
Not Authorized to access this endpoint or your HMAC hash was incorrect.


403
You do not have permission for this API call.


get/public/proposals/{ProposalId}
Request samples 
Response samples 
application/json
{
  • "id": 0,
  • "createdDate": "2019-08-24T14:15:22Z",
  • "clientLastDecisionDate": "2019-08-24T14:15:22Z",
  • "lastCompletedDate": "2019-08-24T14:15:22Z",
  • "lastModifiedDate": "2019-08-24T14:15:22Z",
  • "lastModifiedByUserDate": "2019-08-24T14:15:22Z",
  • "financialSummary": {
    },
  • "changeOrders": [
    ],
  • "number": 0,
  • "name": "string",
  • "status": "Undefined",
  • "lastSubmittedDate": "2019-08-24T14:15:22Z",
  • "clientLastOpenedDate": "2019-08-24T14:15:22Z",
  • "customer": {
    },
  • "dealer": {
    },
  • "coverpageImageUrl": "string",
  • "aboutUs": "string",
  • "projectDescription": "string",
  • "areas": [
    ],
  • "profit": {
    },
  • "recurringServices": {
    },
  • "paymentSchedule": {
    },
  • "paymentRequests": [
    ],
  • "projectTerms": "string",
  • "lastModifiedUser": {
    }
}
Get Change Order Details
Get Change Order Details


Request 
path Parameters
ProposalId
required
integer <int32> 
Proposal Id.


 
ChangeOrderId
required
integer <int32> 
Change Order Id.


 
header Parameters
Accept
required
string
Accept Header


 Value: "application/json"  
X-MSS-API-APPID
required
string
Application Id


 
X-MSS-CUSTOM-DATE
required
string
A date timestamp of the request


 
X-MSS-SIGNATURE
required
string
A signature for the request


 
X-MSS-API-USERKEY
required
string
User API Key


 
Responses 
200
Change Order Details


401
Not Authorized to access this endpoint or your HMAC hash was incorrect.


403
You do not have permission for this API call.


get/public/proposals/{ProposalId}/changeorders/{ChangeOrderId}
Request samples 
Response samples 
application/json
{
  • "id": 0,
  • "createdDate": "2019-08-24T14:15:22Z",
  • "clientLastDecisionDate": "2019-08-24T14:15:22Z",
  • "lastCompletedDate": "2019-08-24T14:15:22Z",
  • "lastModifiedDate": "2019-08-24T14:15:22Z",
  • "lastModifiedByUserDate": "2019-08-24T14:15:22Z",
  • "financialSummary": {
    },
  • "number": 0,
  • "name": "string",
  • "status": "Undefined",
  • "lastSubmittedDate": "2019-08-24T14:15:22Z",
  • "clientLastOpenedDate": "2019-08-24T14:15:22Z",
  • "customer": {
    },
  • "dealer": {
    },
  • "coverpageImageUrl": "string",
  • "aboutUs": "string",
  • "projectDescription": "string",
  • "areas": [
    ],
  • "profit": {
    },
  • "recurringServices": {
    },
  • "paymentSchedule": {
    },
  • "paymentRequests": [
    ],
  • "projectTerms": "string",
  • "lastModifiedUser": {
    }
}
Search & Get Change Order List
Returns a list of all change orders for a particular proposal, with summary information such as Status, Total and Customer.


Request 
path Parameters
ProposalId
required
integer <int32> 
Proposal Id.


 
header Parameters
Accept
required
string
Accept Header


 Value: "application/json"  
X-MSS-API-APPID
required
string
Application Id


 
X-MSS-CUSTOM-DATE
required
string
A date timestamp of the request


 
X-MSS-SIGNATURE
required
string
A signature for the request


 
X-MSS-API-USERKEY
required
string
User API Key


 
Responses 
200
Change Order List by Proposal.


401
Not Authorized to access this endpoint or your HMAC hash was incorrect.


402
This action requires an active subscription.


403
You do not have permission for this API call.


get/public/proposals/{ProposalId}/changeorders
Request samples 
Response samples 
application/json
[
  • {
    }
]
People
The People service allows you to manage a dealer’s contacts, which are used in proposals.


Search & Get Contact List
Search & Get Contact List


Request 
query Parameters
SearchText
string
Search text


 
PersonTypes
Array of strings
Person Types.


 
SortBy
string
 Enum: "ModifiedDate" "CreatedDate" "FirstName" "LastName"  
SortDirection
string
 
PageNumber
integer <int32> 
Page number. Starting from 1


 
PageSize
integer <int32> 
Page Size


 
header Parameters
Accept
required
string
Accept Header


 Value: "application/json"  
X-MSS-API-APPID
required
string
Application Id


 
X-MSS-CUSTOM-DATE
required
string
A date timestamp of the request


 
X-MSS-SIGNATURE
required
string
A signature for the request


 
X-MSS-API-USERKEY
required
string
User API Key


 
Responses 
200
Contact List.


401
Not Authorized to access this endpoint or your HMAC hash was incorrect.


402
This action requires an active subscription.


403
You do not have permission for this API call.


get/public/people
Request samples 
Response samples 
application/json
{
  • "people": [
    ],
  • "peopleCount": 0
}
Create a New Contact
Create a New Contact


Request 
header Parameters
Accept
required
string
Accept Header


 Value: "application/json"  
X-MSS-API-APPID
required
string
Application Id


 
X-MSS-CUSTOM-DATE
required
string
A date timestamp of the request


 
X-MSS-SIGNATURE
required
string
A signature for the request


 
X-MSS-API-USERKEY
required
string
User API Key


 
Request Body schema: application/x-www-form-urlencoded
required
ContactType
required
string
 
ContactCategory
required
string
 
FirstName
required
string
First Name (Maximum character length is 100)


 
LastName
string
Last Name (Maximum character length is 50)


 
CompanyName
string
Company Name (Maximum character length is 100)


 
ContactEmail
string
Email (Maximum character length is 256)


 
ContactEmailCC
string
Additioanl email(s) copied when a proposal is submitted


 
ContactPhone
string
Contact Phone (Maximum character length is 30)


 
Notes
string
 
Responses 
200
Success


401
Not Authorized to access this endpoint or your HMAC hash was incorrect.


402
This action requires an active subscription.


403
You do not have permission for this API call.


post/public/people
Request samples 
application/x-www-form-urlencoded
ContactType=string&ContactCategory=string&FirstName=string&LastName=string&CompanyName=string&ContactEmail=string&ContactEmailCC=string&ContactPhone=string&Notes=string
Response samples 
application/json
{
  • "notes": "string",
  • "lastModifiedDate": "2019-08-24T14:15:22Z",
  • "primaryLocation": {
    },
  • "billingLocation": {
    },
  • "proposalCount": 0,
  • "paymentCount": 0,
  • "id": 0,
  • "contactType": "Undefined",
  • "contactCategory": "Undefined",
  • "firstName": "string",
  • "lastName": "string",
  • "companyName": "string",
  • "contactEmail": "string",
  • "contactEmailCC": "string",
  • "contactPhone": "string"
}
Get Contact Details
Get Contact Details


Request 
path Parameters
PersonId
required
integer <int32> 
Person Id.


 
query Parameters
IncludeCounts
boolean
 
header Parameters
Accept
required
string
Accept Header


 Value: "application/json"  
X-MSS-API-APPID
required
string
Application Id


 
X-MSS-CUSTOM-DATE
required
string
A date timestamp of the request


 
X-MSS-SIGNATURE
required
string
A signature for the request


 
X-MSS-API-USERKEY
required
string
User API Key


 
Responses 
200
Success


400
Person not found.


401
Not Authorized to access this endpoint or your HMAC hash was incorrect.


403
You do not have permission for this API call.


get/public/people/{PersonId}
Request samples 
Response samples 
application/json
{
  • "notes": "string",
  • "lastModifiedDate": "2019-08-24T14:15:22Z",
  • "primaryLocation": {
    },
  • "billingLocation": {
    },
  • "proposalCount": 0,
  • "paymentCount": 0,
  • "id": 0,
  • "contactType": "Undefined",
  • "contactCategory": "Undefined",
  • "firstName": "string",
  • "lastName": "string",
  • "companyName": "string",
  • "contactEmail": "string",
  • "contactEmailCC": "string",
  • "contactPhone": "string"
}
Get Contact Location List
Get Contact Location List


Request 
path Parameters
ContactId
required
integer <int32> 
 
query Parameters
PageNumber
integer <int32> 
 
PageSize
integer <int32> 
 
header Parameters
Accept
required
string
Accept Header


 Value: "application/json"  
X-MSS-API-APPID
required
string
Application Id


 
X-MSS-CUSTOM-DATE
required
string
A date timestamp of the request


 
X-MSS-SIGNATURE
required
string
A signature for the request


 
X-MSS-API-USERKEY
required
string
User API Key


 
Responses 
200
Contact Location list


401
Not Authorized to access this endpoint or your HMAC hash was incorrect.


403
You do not have permission for this API call.


get/public/people/{ContactId}/location
Request samples 
Response samples 
application/json
{
  • "contactLocations": [
    ],
  • "locationCount": 0
}
Create New Contact Location
Create New Contact Location


Request 
path Parameters
ContactId
required
integer <int32> 
 
header Parameters
Accept
required
string
Accept Header


 Value: "application/json"  
X-MSS-API-APPID
required
string
Application Id


 
X-MSS-CUSTOM-DATE
required
string
A date timestamp of the request


 
X-MSS-SIGNATURE
required
string
A signature for the request


 
X-MSS-API-USERKEY
required
string
User API Key


 
Request Body schema: application/x-www-form-urlencoded
required
ContactFirstName
string
Contact First Name (Maximum character length is 50)


 
ContactLastName
string
Contact Last Name (Maximum character length is 50)


 
ContactPhoneNumber
string
Contact Phone Number (Maximum character length is 50)


 
ContactEmail
string
Contact Email (Maximum character length is 100)


 
Street
required
string
Street (Maximum character length is 100)


 
Suite
string
Suite (Maximum character length is 100)


 
City
string
City (Maximum character length is 50)


 
PostalCode
string
Postal Code (Maximum character length is 20)


 
State
string
State (Maximum character length is 256)


 
Country
string
Country (Maximum character length is 256)


 
IsPrimary
boolean
 
IsBilling
boolean
 
Responses 
200
Contact Location


401
Not Authorized to access this endpoint or your HMAC hash was incorrect.


402
This action requires an active subscription.


403
You do not have permission for this API call.


404
This person does not exists.


post/public/people/{ContactId}/location
Request samples 
application/x-www-form-urlencoded
ContactFirstName=string&ContactLastName=string&ContactPhoneNumber=string&ContactEmail=string&Street=string&Suite=string&City=string&PostalCode=string&State=string&Country=string&IsPrimary=true&IsBilling=true
Response samples 
application/json
{
  • "contactFirstName": "string",
  • "contactLastName": "string",
  • "contactPhoneNumber": "string",
  • "contactEmail": "string",
  • "isPrimary": true,
  • "isBilling": true,
  • "id": 0,
  • "street": "string",
  • "suite": "string",
  • "city": "string",
  • "postalCode": "string",
  • "state": "string",
  • "stateAbbrev": "string",
  • "country": "string",
  • "phone": "string"
}
Catalog
**These endpoints require separate authorization**


The Catalog service provides access to all items in the Portal catalog, including information about their MSRP, cost, sell prices and suppliers.


Search & Get Catalog Items
Search & Get Catalog Items


Request 
query Parameters
SearchText
string
 
ParentCategoryId
integer <int32> 
 
CategoryId
integer <int32> 
 
Brands
Array of strings
 
Suppliers
Array of strings
 
Industries
Array of integers <int32> 
 
IsInStock
boolean
 
IsFavorite
boolean
 
IsAuthorized
boolean
 
IsDiscontinued
boolean
 
IsIndustrialFavorite
boolean
 
MinMsrp
number <double> 
Filter for products with an MSRP (of the users current country currency. If it doesn't exist then USD MSRP is used.) greater than this amount.


 
MaxMsrp
number <double> 
Filter for products with an MSRP (of the users current country currency. If it doesn't exist then USD MSRP is used.) less than this amount.


 
PageNumber
integer <int32> 
 
PageSize
integer <int32> 
Limit the number of results


 
IncludeImageUrl
boolean
 
ItemType
string
 
header Parameters
Accept
required
string
Accept Header


 Value: "application/json"  
X-MSS-API-APPID
required
string
Application Id


 
X-MSS-CUSTOM-DATE
required
string
A date timestamp of the request


 
X-MSS-SIGNATURE
required
string
A signature for the request


 
X-MSS-API-USERKEY
required
string
User API Key


 
Responses 
200
A catalog response


401
Not Authorized to access this endpoint or your HMAC hash was incorrect.


402
This action requires an active subscription.


403
You do not have permission for this API call.


500
Internal error.


get/public/catalog
Request samples 
Response samples 
application/json
{
  • "items": [
    ],
  • "favoriteItems": [
    ],
  • "categoryFacets": [
    ],
  • "brandFacets": [
    ],
  • "supplierFacets": [
    ],
  • "totalItemCount": 0,
  • "processingTimeMS": 0,
  • "favoriteItemCount": 0,
  • "labors": [
    ],
  • "customItems": [
    ]
}
Category List
Return the current category structure.


Request 
header Parameters
Accept
required
string
Accept Header


 Value: "application/json"  
X-MSS-API-APPID
required
string
Application Id


 
X-MSS-CUSTOM-DATE
required
string
A date timestamp of the request


 
X-MSS-SIGNATURE
required
string
A signature for the request


 
X-MSS-API-USERKEY
required
string
User API Key


 
Responses 
200
A catalog response


401
Not Authorized to access this endpoint or your HMAC hash was incorrect.


402
This action requires an active subscription.


403
You do not have permission for this API call.


500
Internal error.


get/public/catalog/categories
Request samples 
Response samples 
application/json
[
  • {
    }
]
Get Catalog Item Details
Get Catalog Item Details


Request 
path Parameters
ItemId
required
integer <int32> 
Item Id


 
query Parameters
ExtendedDetails
boolean
Provides additional details like full description, specs, linked resources


 
ItemType
string
 Enum: "Part" "Labor" "CustomItem"  
header Parameters
Accept
required
string
Accept Header


 Value: "application/json"  
X-MSS-API-APPID
required
string
Application Id


 
X-MSS-CUSTOM-DATE
required
string
A date timestamp of the request


 
X-MSS-SIGNATURE
required
string
A signature for the request


 
X-MSS-API-USERKEY
required
string
User API Key


 
Responses 
200
Product Details


204
The requested item doesn't exist


401
Not Authorized to access this endpoint or your HMAC hash was incorrect.


402
This action requires an active subscription.


403
You do not have permission for this API call.


get/public/catalog/{ItemId}
Request samples 
Response samples 
application/json
{
  • "description": "string",
  • "productUrl": "string",
  • "manufacturerProductUrl": "string",
  • "additionalImageUrls": [
    ],
  • "pdfResourceLinks": [
    ],
  • "videoResourceLinks": [
    ],
  • "specs": [
    ],
  • "suppliers": [
    ],
  • "id": 0,
  • "brand": "string",
  • "model": "string",
  • "shortDescription": "string",
  • "primaryImageUrl": "string",
  • "parentCategoryId": 0,
  • "categoryId": 0,
  • "categories": [
    ],
  • "isFavorite": true,
  • "isDiscontinued": true,
  • "msrp": {
    },
  • "defaultCost": {
    },
  • "sellPrice": {
    }
}