{"activeVersionTag":"latest","latestAvailableVersionTag":"latest","collection":{"info":{"_postman_id":"e4ce71c2-762a-4230-b0f9-c189d03f5810","name":"ServiceMonster API V1","description":"<img src=\"https://i.imgur.com/n744BL9.png\">\n\n## About\n\nWelcome to the ServiceMonster Developer Page! Here you can find all API documentation for  \nour V1 environment. Code References and Snippets are in the right hand pane.\n\nIf you have any questions please feel free to contact us at [developer@servicemonster.net](https://mailto:developer@servicemonster.net).\n\n# Getting Started\n\n## Using the API\n\n### Part 1: Returning a collection\n\nTo begin using the ServiceMonster REST API you will first and foremost need an authentication token. If you do not have an authentication token, please see the page on Creating a Basic Token. The token not only gives you access to the REST API, but it is also what ties your requests to a ServiceMonster Company ID.\n\nOnce you have your token, it is highly recommended that you compose your first HTTP requests with a program such as Fiddler Web Debugger. This program will allow you to compose requests, and to view the data that is returned from a properly formatted request. It is not necessary to use this third-party application, but it does make it very clear as to what is required in the request, what is returned in the data-set and how it is formatted. The following examples in this getting started tutorial will use the Fiddler Web Debugger.\n\nIn Fiddler, select the “Composer” tab to begin creating your HTTP request. In the Request Header, add the following lines:\n\n`Content-Type: application/json`  \n`Authorization: Basic {Your Token Here}`\n\nPlease be careful to put a space between “Basic” and your token. This is what your Request Header should look like for all future HTTP Requests:\n\n<img src=\"https://gitlab.servicemonster.net/documentation/documentation-site/raw/master/images/headers.png\">\n\nNow to compose the request itself. We will begin by doing a simple query of “Accounts” records. Directly above the Request Header section there is a drop-down list containing the available HTTP actions: GET, POST, PUT, etc.... Of these options, the REST API uses 4 which each relate to a CRUD operation. POST = create, GET = read, PUT = update, and DELETE = delete. For this example we will leave the drop-down list with “GET” selected.\n\nNext to the drop-down list there is an address bar. This is where you will specify the resource you are trying to access. For our example, Accounts, the address will look like this:\n\n<img src=\"https://gitlab.servicemonster.net/documentation/documentation-site/raw/master/images/composer.png\">\n\nFirst, you must use the HTTPS secure protocol. Regular HTTP requests will not work, and will result in a 404 “Not Found” error. Second is the address “api.servicemonster.net”. This will always be the address you should use to access any resource through the REST API. Third, after the address is the version number. Currently we are on version 1. Requests made to /v1/ will still continue to work after /v2/ is made available, thereby ensuring that any updates we make will not break a piece of software utilizing our API. Finally, after the version comes the resource that we are trying to access, in this case “accounts.” The address is not case-sensitive.\n\nOnce your request is complete, hit the button in the top-right of the screen. In the left side of the screen is the list of HTTP requests that have been made by your system, with the most recent request at the bottom.\n\n<img src=\"https://gitlab.servicemonster.net/documentation/documentation-site/raw/master/images/responses.png\">\n\nThe “Host” for our request should be “api.servicemonster.net” and the URL should be “/v1/accounts.” With your request selected, change the tab on the right side of the screen from “Composer” to “Inspectors.”\n\n<img src=\"https://gitlab.servicemonster.net/documentation/documentation-site/raw/master/images/tabs.png\">\n\nBeneath the Request Headers section is another row of tabs that allow you to view the data after it has been de-serialized in a variety of formats. The data returned by the API is serialized in JSON, fiddler should recognize this and automatically select the JSON tab, but if it does not, then select that tab now. (Alternatively, you can double-click the request in the Request List). The data returned should look something like this:\n\n<img src=\"https://gitlab.servicemonster.net/documentation/documentation-site/raw/master/images/response_body.png\">\n\nAt the top of the JSON package is the count. This number tells you how many records there are in the database for the type of resource selected. By default, the API will only return the first 10 records, however you can increase the “Page Size” or return a different “Page Index.” (See “Part IV: Parameters)\n\n### Part 2: Returning a Single Record top\n\nReturning a single record is very similar to returning a collection, however we must include the record identifier. The record identifier will be of the type “GUID” (Globally Unique Identifier)\\* and will be added to the end of the request address like so:\n\n<img src=\"https://gitlab.servicemonster.net/documentation/documentation-site/raw/master/images/get_account.png\">\n\nThis request will return the information regarding a single account. If you have successfully received a collection of account records, you can use the “accountID” property from one of those records as your record identifier. The property that contains the record identifier will have the resource name (“account,” in this case) in lowercase plus the letters “ID” capitalized. Ie: accountID, orderID, siteID, etc...\n\n### Part 3: Returning Child Collections\n\nYou can also request collections of data that “belong” to a record. For example, you may want to return a collection of the Orders that have been created for a specific Account. To do this, construct your request like you were returning a single Account record, and then add the child-resource to the end of it like so:\n\n<img src=\"https://gitlab.servicemonster.net/documentation/documentation-site/raw/master/images/get_account_orders.png\">\n\nThis request would return to us the orders for the account with accountID equal to “990d83de-0d9a-444f-bfd7-09101c756151.”\n\n### Part 4: Parameters\n\nPlease view the Parameters page [Parameters](#GET-Parameters)\n\n### Part 5: Creating a New Record\n\nA few of the resources made accessible by the API are set as read-only. For those, you will be unable to create new records. However, the majority of the ServiceMonster resources allow you to insert a new record via the API. In this example, we will add a new Account.\n\nFirst, set the drop-down list in the Fiddler Request Composer to “POST.” Second, we will construct the address as if we were requesting a collection; like so:\n\n<img src=\"https://gitlab.servicemonster.net/documentation/documentation-site/raw/master/images/post_account.png\">\n\nThe content for the resource we are trying to add goes in to the Request Body. For each type of resource, at least one property is required. If you were to hit “Execute” without typing anything into the Request Body, you will get the following error that basically just says it was expecting some data:\n\n<img src=\"https://gitlab.servicemonster.net/documentation/documentation-site/raw/master/images/length_required.png\">\n\nThat is because a JSON data package must be encapsulated with the curly braces { and }. If we simply put the open and closed curly braces into the request body, and hit “Execute” with our empty data-set, we will get the following error message that contains more meaningful information:\n\n<img src=\"https://gitlab.servicemonster.net/documentation/documentation-site/raw/master/images/required_fields.png\">\n\nFor Accounts, the only property that is required is accountName. If more of the properties were required, they would be listed here as well. This can be a good way to determine what fields will need to be supplied in order to create a record. To create a new Account with the absolute minimum of information, compose your Request Body so that it looks like the following:\n\n`{ \"accountName\":\"New Account\" }`\n\nIf you have constructed your request properly, the record will be created, and the record identifier will be returned in a JSON package. Some properties are read-only, so if you try to insert a record and have supplied a property that is read-only, you will get an error message and the record will not be created.\n\n### Part 6: Updating a Record\n\nSimilar to requesting a single record, you must supply the record ID in order to do an Update. You must also change the action drop-down list to “PATCH.”\n\nThen, form the Request Body like you did for a POST including the fields you want to update. None of the fields are required to do an update, however some of them are read-only. Also, you cannot update a required property with a blank or null value.\n\nPart 7: Deleting a Record top  \nJust like fetching or updating a single record, we need to supply a record ID to delete a record through the API. This time we will set the HTTP Action drop-down list to “DELETE”\n\n# Creating a Basic Token\n\n### Create an API Key\n\n1. Login to ServiceMonster at six.servicemonster.net (You will need to use an administrator account)\n    \n2. Navigate to Settings from the bar on the Left, and select \"API Users\"\n    \n3. Click \"+API User\" at the top of the list of existing API Keys.\n    \n4. Select a role, usually Admin and supply a note (optional), click \"Submit\"\n    \n5. A set of API Credentials will appear. Make sure you save the password, as it will not be retrievable if you lose it.\n    \n\n### Api User Roles\n\n- Admin - Can Create, Read, Update, and Delete on any of the available resources. Use of this role is typically not necessary.\n    \n- Super User - Can Create, Read and Update. Can not Delete. Most records can be archived or de-activated without deleting, so this Role should be able to achieve everything necessary for implementations.\n    \n- Read Only - can only Read.\n    \n- WebForms - can not perform any actions EXCEPT Creating new Web Lead records.\n    \n\n### Create a Basic Token using base64encode\n\nOpen [https://www.base64encode.org/](https://www.base64encode.org/)  \nMake sure you are set to encode, then in the top box paste your username and password generated in step one. They should be seperated by a colon. Then press \"Encode\"  \nEx: \"username\":\"password\"\n\n<img src=\"https://gitlab.servicemonster.net/documentation/documentation-site/raw/master/images/base64.png\">\n\nThe encoded string generated is your Basic Token. You can use it by supplying it in your request Headers.\n\n### Ajax Example:\n\nSee `javascript` code snippet to the right.\n\n``` javascript\nvar settings = {\n  \"url\": \"https://api.servicemonster.net/v1/accounts\",\n  \"method\": \"GET\",\n  \"headers\": {\n    \"authorization\": \"Basic ***********\"\n  }\n}\n$.ajax(settings).done(function (response) {\n  console.log(response);\n});\n\n ```\n\n# GET Parameters\n\n**GET Parameters**\n\n| Parameter | Description | Example |\n| --- | --- | --- |\n| fields | limits the return to the specified columns | v1/accounts?fields=id,accountName |\n| limit | limits the number of records returned for paging | v1/accounts?limit=25 |\n| pageIndex | The page of results to be returned. (example returns records 101-125) | v1/accounts?limit=25&pageIndex=4 |\n\n**GET Where Parameters**\n\n| Field | Description |\n| --- | --- |\n| wField | The data field to check against |\n| wValue | The value to filter on. (Use \" \" for spaces) |\n| wOperator | (optional)The type of camparison to be made. Default is the equals operator; do not include this parameter if you are looking for an exact match to the supplied value. (\"gt\") greater than; (\"lt\") less than(\"like\") LIKE, '%'s are added before and after value. See examples below. |\n\n**GET Where Examples**\n\n| Example | Description |\n| --- | --- |\n| .../v1/account?wField=lastName&wValue=Smith | Returns all Accounts where the Last Name equals \"Smith\" |\n| .../v1/orders?wField=balanceDue&wValue=100&wOperator=gt | Returns all Orders where the balance due is greater than $100.00 |\n| .../v1/leadSources?wField=name&wValue=magazine&wOperator=like | Returns all Lead Sources that have the word \"magazine\" somewhere in the name. |\n\n# Vendor Information\n\n## Overview\n\nServiceMonster is proud to offer data-integration to third party vendors who would like to offer their services to our customers.\n\nOnce you are approved as a vendor we will create a test company for you within the ServiceMonster test site ([http://west-test.servicemonster.net/servicemonster](http://west-test.servicemonster.net/servicemonster)). You will then be able to log in to ServiceMonster and create your own API credentials. Once you have created a set of API credentials you can start creating, reading, and modifying data through the API test site ([http://west-test.servicemonster.net/smapi](http://west-test.servicemonster.net/smapi)) and start building out your integration with ServiceMonster company data.\n\nOne key component to completing integration with ServiceMonster customer data, is the process through which the end-user will grant access to your application. This process is outlined in detail in this document and in this diagram.\n\n## Vendor Access Request\n\n** Creating Company-Specific API Credentials through the ServiceMonster API **\n\nWhen you are first approved as a vendor, you will be given a set of credentials as well as an Application ID for each app that you have in the marketplace that integrates with ServiceMonster data. You will use this AppID both when validating the API access request, and when completing the request to retrieve credentials.\n\n** Check if API Request is valid: **\n\n``` reference\nGET https://api.servicemonster.net/v1/apiRequests/{AppID}/{RequestID}\nAuthorization:  Basic {your token here}\n\n ```\n\nThis validation check must occur within 30 minutes from when the API request was created. After that it expires and the user will need to generate a new link (by refreshing the marketplace page).\n\n```\n{\n  \"companyKey\": \"5001\",\n  \"companyName\": \"Principal Focus\",\n  \"address1\": \"4204 Meridian St\",\n  \"address2\": \"Suite 105\",\n  \"city\": \"Bellingham\",\n  \"state\": \"WA\",\n  \"zip\": \"98226\",\n  \"phone\": \"(888) 901-3300\"\n}\n\n ```\n\nIf the Request is still valid, the API will return information specific to the company that has generated the API Access request. e.g.\n\nYou can use this data to pre-fill your purchase form. Once the customer has completed the purchasing process, you can then use your AppID and the RequestID again to “complete” the request, and have the API return a set of credentials that will allow you to access that company’s data.\n\n** Completing the API Request: **\n\n``` reference\nPOST    https://api.servicemonster.net/v1/apiRequests   \nAuthorization:  Basic {your token here}\nContent-Type:   application/json\nRequest Body:\n{\n  \"requestID\": \"{RequestID}\",\n  \"appID\": \"{AppID}\"\n}\n\n ```\n\nThe API Request must be completed within 1 hour from when the API request was created. After that it expires and the user will need to generate a new link (by refreshing the marketplace page).\n\n``` reference\n{\n  \"password\": \"**\",\n  \"userName\": \"**\"\n}\n\n ```\n\nUpon a successful post of the API Request object, the new credentials will be returned:\n\nOnce you have the credentials, you can Base64 them into a token to use when authenticating your requests: [Creating a Basic Token](#Creating-a-Basic-Token)\n\n## Vendor Request Flow\n\n<img src=\"https://gitlab.servicemonster.net/Bwebb/documentation-site/raw/master/images/api_flow.png\">\n\n# Using Postman\n\n<img src=\"https://www.getpostman.com/img/v2/media-kit/Logo/PNG/pm-logo-horiz.png\">\n\n[Postman](https://www.getpostman.com/) is a powerful tool for developing and testing API. By clicking the 'Run in Postman' button at the top of this page you can access a collection of all the requests available in the ServiceMonster API. For more information on getting started with Postman, see the [official documentation](https://www.getpostman.com/docs/postman/launching_postman/installation_and_updates).","schema":"https://schema.getpostman.com/json/collection/v2.0.0/collection.json","isPublicCollection":true,"owner":"3295919","team":96147,"collectionId":"e4ce71c2-762a-4230-b0f9-c189d03f5810","publishedId":"RVg2A8sE","public":true,"publicUrl":"https://developer.servicemonster.net","privateUrl":"https://go.postman.co/documentation/3295919-e4ce71c2-762a-4230-b0f9-c189d03f5810","customColor":{"top-bar":"3E6DB5","right-sidebar":"18488A","highlight":"00A650"},"documentationLayout":"classic-double-column","version":"8.10.1","publishDate":"2018-02-27T18:23:00.000Z","activeVersionTag":"latest","documentationTheme":"light","metaTags":{},"logos":{}},"statusCode":200},"environments":[],"user":{"authenticated":false,"permissions":{"publish":false}},"run":{"button":{"js":"https://run.pstmn.io/button.js","css":"https://run.pstmn.io/button.css"}},"web":"https://www.getpostman.com/","team":{"logo":"https://res.cloudinary.com/postman/image/upload/t_team_logo_pubdoc/v1/team/4a3b11e7ed496ad0160e0cf29828d7acc51f9aacabb2dc026dc5e8d7108820c3","favicon":"https://res.cloudinary.com/postman/image/upload/v1647297731/team/ultlksht6wlbe6drjxlt.ico"},"isEnvFetchError":false,"languages":"[{\"key\":\"csharp\",\"label\":\"C#\",\"variant\":\"HttpClient\"},{\"key\":\"csharp\",\"label\":\"C#\",\"variant\":\"RestSharp\"},{\"key\":\"curl\",\"label\":\"cURL\",\"variant\":\"cURL\"},{\"key\":\"dart\",\"label\":\"Dart\",\"variant\":\"http\"},{\"key\":\"go\",\"label\":\"Go\",\"variant\":\"Native\"},{\"key\":\"http\",\"label\":\"HTTP\",\"variant\":\"HTTP\"},{\"key\":\"java\",\"label\":\"Java\",\"variant\":\"OkHttp\"},{\"key\":\"java\",\"label\":\"Java\",\"variant\":\"Unirest\"},{\"key\":\"javascript\",\"label\":\"JavaScript\",\"variant\":\"Fetch\"},{\"key\":\"javascript\",\"label\":\"JavaScript\",\"variant\":\"jQuery\"},{\"key\":\"javascript\",\"label\":\"JavaScript\",\"variant\":\"XHR\"},{\"key\":\"c\",\"label\":\"C\",\"variant\":\"libcurl\"},{\"key\":\"nodejs\",\"label\":\"NodeJs\",\"variant\":\"Axios\"},{\"key\":\"nodejs\",\"label\":\"NodeJs\",\"variant\":\"Native\"},{\"key\":\"nodejs\",\"label\":\"NodeJs\",\"variant\":\"Request\"},{\"key\":\"nodejs\",\"label\":\"NodeJs\",\"variant\":\"Unirest\"},{\"key\":\"objective-c\",\"label\":\"Objective-C\",\"variant\":\"NSURLSession\"},{\"key\":\"ocaml\",\"label\":\"OCaml\",\"variant\":\"Cohttp\"},{\"key\":\"php\",\"label\":\"PHP\",\"variant\":\"cURL\"},{\"key\":\"php\",\"label\":\"PHP\",\"variant\":\"Guzzle\"},{\"key\":\"php\",\"label\":\"PHP\",\"variant\":\"HTTP_Request2\"},{\"key\":\"php\",\"label\":\"PHP\",\"variant\":\"pecl_http\"},{\"key\":\"powershell\",\"label\":\"PowerShell\",\"variant\":\"RestMethod\"},{\"key\":\"python\",\"label\":\"Python\",\"variant\":\"http.client\"},{\"key\":\"python\",\"label\":\"Python\",\"variant\":\"Requests\"},{\"key\":\"r\",\"label\":\"R\",\"variant\":\"httr\"},{\"key\":\"r\",\"label\":\"R\",\"variant\":\"RCurl\"},{\"key\":\"ruby\",\"label\":\"Ruby\",\"variant\":\"Net::HTTP\"},{\"key\":\"shell\",\"label\":\"Shell\",\"variant\":\"Httpie\"},{\"key\":\"shell\",\"label\":\"Shell\",\"variant\":\"wget\"},{\"key\":\"swift\",\"label\":\"Swift\",\"variant\":\"URLSession\"}]","languageSettings":[{"key":"csharp","label":"C#","variant":"HttpClient"},{"key":"csharp","label":"C#","variant":"RestSharp"},{"key":"curl","label":"cURL","variant":"cURL"},{"key":"dart","label":"Dart","variant":"http"},{"key":"go","label":"Go","variant":"Native"},{"key":"http","label":"HTTP","variant":"HTTP"},{"key":"java","label":"Java","variant":"OkHttp"},{"key":"java","label":"Java","variant":"Unirest"},{"key":"javascript","label":"JavaScript","variant":"Fetch"},{"key":"javascript","label":"JavaScript","variant":"jQuery"},{"key":"javascript","label":"JavaScript","variant":"XHR"},{"key":"c","label":"C","variant":"libcurl"},{"key":"nodejs","label":"NodeJs","variant":"Axios"},{"key":"nodejs","label":"NodeJs","variant":"Native"},{"key":"nodejs","label":"NodeJs","variant":"Request"},{"key":"nodejs","label":"NodeJs","variant":"Unirest"},{"key":"objective-c","label":"Objective-C","variant":"NSURLSession"},{"key":"ocaml","label":"OCaml","variant":"Cohttp"},{"key":"php","label":"PHP","variant":"cURL"},{"key":"php","label":"PHP","variant":"Guzzle"},{"key":"php","label":"PHP","variant":"HTTP_Request2"},{"key":"php","label":"PHP","variant":"pecl_http"},{"key":"powershell","label":"PowerShell","variant":"RestMethod"},{"key":"python","label":"Python","variant":"http.client"},{"key":"python","label":"Python","variant":"Requests"},{"key":"r","label":"R","variant":"httr"},{"key":"r","label":"R","variant":"RCurl"},{"key":"ruby","label":"Ruby","variant":"Net::HTTP"},{"key":"shell","label":"Shell","variant":"Httpie"},{"key":"shell","label":"Shell","variant":"wget"},{"key":"swift","label":"Swift","variant":"URLSession"}],"languageOptions":[{"label":"C# - HttpClient","value":"csharp - HttpClient - C#"},{"label":"C# - RestSharp","value":"csharp - RestSharp - C#"},{"label":"cURL - cURL","value":"curl - cURL - cURL"},{"label":"Dart - http","value":"dart - http - Dart"},{"label":"Go - Native","value":"go - Native - Go"},{"label":"HTTP - HTTP","value":"http - HTTP - HTTP"},{"label":"Java - OkHttp","value":"java - OkHttp - Java"},{"label":"Java - Unirest","value":"java - Unirest - Java"},{"label":"JavaScript - Fetch","value":"javascript - Fetch - JavaScript"},{"label":"JavaScript - jQuery","value":"javascript - jQuery - JavaScript"},{"label":"JavaScript - XHR","value":"javascript - XHR - JavaScript"},{"label":"C - libcurl","value":"c - libcurl - C"},{"label":"NodeJs - Axios","value":"nodejs - Axios - NodeJs"},{"label":"NodeJs - Native","value":"nodejs - Native - NodeJs"},{"label":"NodeJs - Request","value":"nodejs - Request - NodeJs"},{"label":"NodeJs - Unirest","value":"nodejs - Unirest - NodeJs"},{"label":"Objective-C - NSURLSession","value":"objective-c - NSURLSession - Objective-C"},{"label":"OCaml - Cohttp","value":"ocaml - Cohttp - OCaml"},{"label":"PHP - cURL","value":"php - cURL - PHP"},{"label":"PHP - Guzzle","value":"php - Guzzle - PHP"},{"label":"PHP - HTTP_Request2","value":"php - HTTP_Request2 - PHP"},{"label":"PHP - pecl_http","value":"php - pecl_http - PHP"},{"label":"PowerShell - RestMethod","value":"powershell - RestMethod - PowerShell"},{"label":"Python - http.client","value":"python - http.client - Python"},{"label":"Python - Requests","value":"python - Requests - Python"},{"label":"R - httr","value":"r - httr - R"},{"label":"R - RCurl","value":"r - RCurl - R"},{"label":"Ruby - Net::HTTP","value":"ruby - Net::HTTP - Ruby"},{"label":"Shell - Httpie","value":"shell - Httpie - Shell"},{"label":"Shell - wget","value":"shell - wget - Shell"},{"label":"Swift - URLSession","value":"swift - URLSession - Swift"}],"layoutOptions":[{"value":"classic-single-column","label":"Single Column"},{"value":"classic-double-column","label":"Double Column"}],"versionOptions":[],"environmentOptions":[{"value":"0","label":"No Environment"}],"canonicalUrl":"https://developer.servicemonster.net/view/metadata/RVg2A8sE"}