{"activeVersionTag":"latest","latestAvailableVersionTag":"latest","collection":{"info":{"_postman_id":"c158d929-94ae-4cf6-9d90-c85f96fc00d4","name":"SalesMessage Public API v2.2","description":"## Introduction\nThis API documentation will start with an overview of the Salesmsg authorization methods and flows, followed by reference information about each specific endpoint.\n\n## Mock Server\nAdditionally, if you want to try the API requests out on our mock server, then you can import the endpoints and set baseUrl variable in your collection as `https://e33e4a6a-ff9d-419f-a378-ec53560c0bb7.mock.pstmn.io`\n\n## Authentication\n\nSupported authorization methods include: **Personal Access Token (PAT)** and **OAuth2**.\nWhether to use PAT or regular OAuth2 tokens highly depends on your use case.\n\n- **OAuth2** authorization type is to go for in case you want to allow other users to authenticate against SalesMessage in order for your app to use the issued token as well as utilize the SalesMessage’s functionality.\n\n- **PAT** authorization type is to go for in case you want to integrate your personal existing account with Salesmsg in order to extend your app’s functionality. PAT are managed by the user, which means that they are tied to a user account. This makes Personal Access Tokens a good choice for development, as well as automation purposes, when an application does only require a single SalesMessage account to manage organizations.\n\n### OAuth2\n\nThe first step in implementing OAuth2 is [registering an oauth application](/settings/developer/applications) and retrieving your client ID and client secret. Most people who will be implementing OAuth2 will want to find and utilize a library in the language of their choice. For those implementing OAuth2 from scratch, please see [RFC 6749](https://datatracker.ietf.org/doc/html/rfc6749) for details. After you create your application with SalesMessage, make sure that you have your `client_id` and `client_secret` handy. The next step is to figure out which OAuth2 flow is right for your purposes. Here are your options:\n\n- Authorization code grant flow\n\n- Implicit grant flow\n\n##### OAuth2 URLs\n\n| URL | Description |\n|-----------------------|------|\n| `https://app.salesmessage.com/auth/oauth` |    Base authorization URL |\n| `https://api.salesmessage.com/pub/v2.2/oauth/token` | Token URL |\n\n#### 1. Authorization code grant flow\n\nThe authorization code grant flow is most suitable for **web and mobile applications**. It differs from the other grant types by requiring the application to launch a browser first to begin the integration.\n\nThe integration consists of the following steps:\n\n1. The application opens a browser to send the user to the OAuth server.\n2. The user receives the authorization prompt and approves the application request.\n3. The user is redirected back to the app with the authorization code in the query string.\n4. The application exchanges the authorization code for an access token.\n\nBelow, you can find the description of the authorization code grant flow in detail.\n\n##### Get user permission\n\nThe application sends the user to a browser to get their permission. To begin the authorization flow, the application constructs an URL like the following and opens a browser to that URL:\n\n`https://app.salesmessage.com/auth/oauth?response_type=code&client_id=269&redirect_uri=https://example.app/callback&scope=public-api&state=xcoiv98y2kd22vusuye3kch`\n\nHere’s each query parameter explained:\n\n| Parameter | Description |\n|-----------------------|------|\n| `Response_type`  |    Set to code indicating that you want an authorization code as the response. |\n| `Client_id`  | The identifier for apps. You will find it on the OAuth Applications page. |\n| `Redirect_uri`  | Used to redirect to after the user is granted permission or denied permission. The URI needs to have been entered in the Redirect URI field that the user specified at creating the application. |\n| `Scope`  | Stands for the scopes the application is requesting, separated by URL-encoded spaces. |\n| `State`  | A value included in the request, which is also returned in the token response. It can be a string of any content that you wish. A randomly generated unique value is typically used for preventing cross-site request forgery attacks. |\n\n##### Successful response\n\nIf the user approves the request, the authorization server will redirect the browser back to the redirect_uri specified by the OAuth application, adding a  code and state to the query string.\n\nThe user will be redirected back to an URL such as:\n\n`https://example.app/callback?code=g0ZGZmNjVmOWIjNTk2NTk4ZTYyZGI3&state=xcoiv98y2kd22vusuye3kch`\n\nWhere:\n\n| Parameter | Description |\n|-----------------------|------|\n| `Code` |    An authorization code that you can exchange for an access token within 10 minutes. After that, the code expires. |\n| `State`   | A value included in the request, which is also returned in the token response. It can be a string of any content that you wish. A randomly generated unique value is typically used for preventing cross-site request forgery attacks. |\n\n##### Exchange the authorization code for an access token\n\nIn case the user approves the request, the OAuth app is ready to exchange the authorization code for an access token. It goes by making a POST request to the 'https://app.salesmessage.com/app/auth/token' endpoint.\n\nThe body of this POST request must contain the following parameters encoded in `application/x-www-form-urlencoded`:\n\n```\nPOST `https://api.salesmessage.com/pub/v2.2/oauth/token`\n\nContent-Type: application/x-www-form-urlencoded\n\n`grant_type`=authorization_code\n\n&`code`=<my-authorization-code>\n\n&`client_id`=<client_id>\n\n&`client_secret`=<client_secret>\n\n&`redirect_uri`=<https://example.app/callback>\n```\n\nWhere:\n\n| Parameter | Description |\n|-----------------------|------|\n| `Grant_type`  |    Must be set to authorization_code. |\n| `Code`   | The authorization code returned from the previous request. |\n| `Client_id`  | The identifier for the app. Find it on the OAuth Applications page. |\n| `Client_secret` | The secret of the app. Find it on the OAuth Applications page. |\n| `Redirect_uri` |  Used for validation only (there is no actual redirection). The value of the parameter must exactly match the value of `redirect_uri` supplied when requesting the authorization code. |\n\nThe token endpoint will verify all the parameters in the request, **ensuring the code hasn’t expired** and that **the client ID matches the client secret**. If everything checks out, it will generate an access token and return it in the response.\n\n```\nHTTP/1.1 200 OK\nContent-Type: application/json\n{\n\"token_type\": \"Bearer\",\n\"expires_in\": 31536000,\n\"access_token\":\"MTQ0NjJkZmQ5OTM2NDE1ZTZjNGZmZjI3\",\n\"refresh_token\":\"IwOGYzYTlmM2YxOTQ5MGE3YmNmMDFkNTVk\"\n}\n```\n\nWhen the access token expires, use the refresh token to get a new access token. For information about using refresh tokens, see the section below.\n\n##### Request a refreshed access token\n\nAccess tokens are deliberately set to expire after a short time, after which new tokens may be granted by supplying the refresh token originally obtained during the authorization code exchange.\n\nTo refresh the token, a POST request must be sent with the following body parameters encoded in `application/x-www-form-urlencoded`:\n\n```\nPOST https://api.salesmessage.com/pub/v2.2/oauth/token/refresh\nContent-Type: application/x-www-form-urlencoded\ngrant_type=refresh_token\n&client_id=<client_id>\n&client_secret=<client_secret>\n&refresh_token=<refresh_token>\n&scope=public-api\n```\n\nWhere:\n\n| Parameter | Description |\n|-----------------------|------|\n| `Grant_type`  |    Must be set to `refresh_token` |\n| `Refresh_token`  | The refresh token returned from the authorization code exchange. |\n\n### 2. Implicit grant flow\n\nThis flow is meant for apps that don’t use a server, such as **client-side JavaScript apps or mobile apps**.\n\nTo get a user access token using the implicit grant flow, navigate a user to `https://api.salesmessage.com/pub/v2.2/auth/oauth` with the following query parameters that are appropriate for your application:\n\n| Parameter | Description |\n|-----------------------|------|\n| `client_id`  |    Your app’s registered client ID. |\n| `force_verify`   | Set to true to force the user to re-authorize your app’s access to their resources. The default is `false`. |\n| `redirect_uri`  | Your app’s registered redirect URI. The access token is sent to this URI. |\n| `response_type` | Must be set to token. |\n| `scope` |  Stands for the scopes the application is requesting, separated by URL-encoded spaces. |\n| `state` |  A value included in the request, which is also returned in the token response. It can be a string of any content that you wish. A randomly generated unique value is typically used for preventing cross-site request forgery attacks. |\n\nBelow find an example of the URI that you’ll navigate to in your web browser control:\n\n```\nhttps://api.salesmessage.com/pub/v2.2/auth/oauth\n?response_type=token\n&client_id=hof5gwx0su6owfnys0yan9c87zr6t\n&redirect_uri=http://localhost:3000\n&scope=channel%3Amanage%3Apolls+channel%3Aread%3Apolls\n&state=c3ab8aa609ea11e793ae92361f002671\n```\n\nIf the user is logged into Salemsg, Salemsg asks them to authorize your application. In case they’re not logged in, Salemsg asks them to log in first. Then, the user is prompted to authorize your application.\n\nAs soon as the user authorizes your application, the server sends the access token to your redirect URI in the fragment portion of the URI (see the `access_token parameter`):\n\n```\nhttp://localhost:3000/\n#access_token=73d0f8mkabpbmjp921asv2jaidwxn\n&scope=channel%3Amanage%3Apolls+channel%3Aread%3Apolls\n&state=c3ab8aa609ea11e793ae92361f002671\n&token_type=bearer\n```\n\nIn case the user didn’t authorize your application, the server sends the error code and description to your redirect URI (see the `error` and `error_description` parameters).\n\n```\nhttp://localhost:3000/\n?error=access_denied\n&error_description=The+user+denied+you+access\n&state=c3ab8aa609ea11e793ae92361f002671\n```\n\n### PAT: Personal Access Tokens\n\nPersonal Access Tokens (PAT) are an alternative to regular OAuth tokens. Technically, it allows access to our API just like an OAuth token. However, it is tied to the user who creates the request, meaning that they are allowed to directly call the SalesMessage APIs.\nTo create a new Personal Access Token or revoke an existing one, go to the [Personal Access Tokens tab](/settings/developer/access-tokens) in the Settings page. You can request as many as you like, and revoke them at any time.\nYour PAT functions like a password, so it should not be hard coded into any scripts. Store your PAT in a safe space.\n\n## HTTP status codes\n\nUse the following set of HTTP response status codes:\n\n| STATUS | DESCRIPTION |\n|----|------------------------|\n| 200 | The request was a success. |\n| 400 | There was something wrong with incoming data from Salesmsg.  Provide an error response body to clarify what went wrong. |\n| 401 |\tSalesmsg sent an OAuth2 access token that isn’t valid. |\n| 403 | Access to this method is forbidden. |\n| 404 | \tSalesmsg is trying to reach a URL that doesn’t exist.|\n| 500 | \tThere was an error in your application logic. |\n| 503 | Your service is not available at the moment, but Salesmsg should try again later. |\n\nEach endpoint of our API returns responses in a JSON format.\n\n## Rate Limits\nThe global rate limit for our API is **60 requests per minute**. If you exceed this, all API calls for the next 60 seconds will be blocked, receiving a HTTP 429 response.","schema":"https://schema.getpostman.com/json/collection/v2.0.0/collection.json","isPublicCollection":false,"owner":"13783878","team":1436923,"collectionId":"c158d929-94ae-4cf6-9d90-c85f96fc00d4","publishedId":"2sAY4rEQ4J","public":true,"publicUrl":"https://documenter-api.postman.tech/view/13783878/2sAY4rEQ4J","privateUrl":"https://go.postman.co/documentation/13783878-c158d929-94ae-4cf6-9d90-c85f96fc00d4","customColor":{"top-bar":"FFFFFF","right-sidebar":"303030","highlight":"FF6C37"},"documentationLayout":"classic-double-column","customisation":{"metaTags":[{"name":"description","value":""},{"name":"title","value":""}],"appearance":{"default":"light","themes":[{"name":"dark","logo":null,"colors":{"top-bar":"212121","right-sidebar":"303030","highlight":"FF6C37"}},{"name":"light","logo":null,"colors":{"top-bar":"FFFFFF","right-sidebar":"303030","highlight":"FF6C37"}}]}},"version":"8.10.1","publishDate":"2024-10-23T09:43:13.000Z","activeVersionTag":"latest","documentationTheme":"light","metaTags":{"title":"","description":""},"logos":{"logoLight":null,"logoDark":null}},"statusCode":200},"environments":[{"name":"SalesMessage Production 2.2","id":"baa788ca-04dc-47eb-b34e-21da9a122929","owner":"13783878","values":[{"key":"baseUrl","value":"https://api.salesmessage.com/pub/v2.2","enabled":true}],"published":true}],"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/5f82b7d232ffcfc360f3d95d6e235edbec5057eb013df92685f882c3e10906b7","favicon":""},"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"},{"label":"SalesMessage Production 2.2","value":"13783878-baa788ca-04dc-47eb-b34e-21da9a122929"}],"canonicalUrl":"https://documenter.gw.postman.com/view/metadata/2sAY4rEQ4J"}