{"activeVersionTag":"latest","latestAvailableVersionTag":"latest","collection":{"info":{"_postman_id":"3b902962-097b-4ae4-9c95-f9cb63c78c29","name":"Swift Digital Suite REST API v3","description":"## Introduction\n\n---\n\nThe Swift Digital Suite REST API v3 is designed following REST principles. It utilises predictable, resource-oriented URLs, accepts form-encoded request bodies, and returns responses encoded in JSON format. The API also adheres to standard HTTP response codes, authentication mechanisms, and HTTP verbs.\n\nAuthentication is handled using OAuth 2.0. To access the API, you need to obtain an access token. This token can be generated by your administrator on the Swift Digital Suite platform. Once generated, this token can be used to authenticate API requests.\n\n---\n\n## Getting Started\n\nTo get started with the Swift Digital Suite REST API v3, just click the \"Run in Postman\" button above. Postman is a free tool that helps developers test and debug API requests, and it's where you'll find all the details in this documentation. You can easily access every endpoint mentioned here by importing our collection into the Postman app. Then, simply choose from the examples in the dropdown menu at the top right of the builder interface.\n\nThe simplest method to begin utilising the documentation is by clicking the \"Run in Postman\" button provided above.\n\n<a href=\"https://www.getpostman.com/\">Postman</a>\n\nIt is a free tool that assists developers in executing and debugging API requests and serves as the definitive source for this documentation. Each endpoint documented here is immediately accessible by running our Postman collection. Import the collection directly into the Postman app and access all saved examples from the \"Examples\" dropdown located in the upper right corner of the builder.\n\n<p><img src=\"https://assets.postman.com/postman-docs/accessing-saved-examples.jpg\"></p>\n\n---\n\n## Best Practices\n\n- Utilise the Recommended Endpoint Naming Conventions\n    \n- Use the Appropriate HTTP Method\n    \n- Consider rate limits when calling the REST API v3. The default is 600 requests/minute.\n    \n- Review the appropriate HTTP response code returned from the API.\n    \n\n---\n\n## Base URL\n\n``` php\nhttps://v3.api.swiftdigital.com.au/\n\n ```\n\n## Token URL\n\n``` php\nhttps://v3.api.swiftdigital.com.au/auth/token\n\n ```\n\n---\n\n# Authentication\n\nTo facilitate OAuth2 authentication and token generation for the Swift Digital Suite REST API v3, users can follow the steps outlined below. Here's a detailed guide on how users can work with our API to generate access tokens and refresh tokens:\n\n##### Step 1: Account Settings Permission\n\n- The administrator from your Swift Digital Suite account needs to go to Administration > Integrations and see if the REST API v3 can be accessed.\n    \n- If the REST API v3 is not visible, please reach out to your account manager and to [api@swiftdigital.com.au](https://mailto:api@swiftdigital.com.au).\n    \n\n<img src=\"https://content.pstmn.io/df25db08-7f10-4706-a354-f655f93d90c5/QVBJIHYzIEZpZ3VyZSAxLjEucG5n\" alt=\"Figure%201:%20Administration%20>%20Integration%20>%20REST%20API%20v3\">\n\n##### Step 2: Obtain Client ID, Client Secret, and T3 Account ID\n\n- The administrator from your Swift Digital Suite account needs to add an OAuth 2.0 API Client.\n    \n- OAuth 2.0 API client scopes must be selected by the administrator to grant permissions to your application.\n    \n- _The client secret is only given once, and it will be hidden after adding an OAuth2 API Client. Make sure to copy and save the client secret, as it will be used to get access tokens._\n    \n- The t3 account ID is given after adding an OAuth 2.0 API Client.\n    \n\n<img src=\"https://content.pstmn.io/00149455-04fc-49a5-8179-638f27547b95/QVBJIHYzIEZpZ3VyZSAyLnBuZw==\" alt=\"Figure%202:%20Add%20OAuth%202.0%20API%20Client\">\n\n##### Step 3: Get Access or Refresh Token\n\n- Using the Client ID, Client Secret, and T3 Account ID, an access token and a refresh token will be generated by making a POST request to the API's token endpoint.\n    \n- The POST request will include parameters such as client ID, client secret, and t3 account ID.\n    \n- The Swift Digital Suite API token endpoint will validate the details and issue an access token and a refresh token in the response.\n    \n\n##### Step 4: Use Access Token for API Requests\n\n- Your application can now use the obtained access token to authenticate API requests to the Swift Digital Suite REST API v3. The access token should be included in the Authorisation header of each request using the Bearer authentication scheme.\n    \n\n##### Step 5: Handle Token Expiration\n\n- Access tokens issued by the Swift Digital Suite REST API v3 typically have a limited lifespan. The users of the application should handle token expiration gracefully by monitoring the expiration time (provided in the token response) and refreshing the token when it expires.\n    \n\n##### Step 6: Refresh Access Token\n\n- When the access token expires, users' applications can use the refresh token to obtain a new access token without requiring the user to re-authenticate.\n    \n- The users of the application will make a POST request to the Swift Digital Suite REST API v3 token endpoint with parameters including client ID, client secret, refresh token, and grant type (refresh_token).\n    \n- The Swift Digital Suite REST API v3 token endpoint will validate the refresh token and issue a new access token in the response.\n    \n\nBy following these steps, users of our API will be able to authenticate with the Swift Digital Suite API REST v3, obtain access tokens, refresh tokens, and make authorised requests to our API.\n\n### Examples:\n\n#### Endpoint to get access and refresh token\n\n> [https://v3.api.swiftdigital.com.au/auth/token](https://v3.api.swiftdigital.com.au/server/includes/restapi/v3/auth/token.php) \n  \n\n##### Request:\n\n``` json\n{\n    \"grant_type\": \"password\",\n    \"client_id\": \"Client ID\",\n    \"client_secret\": \"Client Secret\",\n    \"t3acctid\": \"T3 Account ID\"\n}\n\n ```\n\n##### Response:\n\n``` json\n{\n    \"access_token\": \"dfg098ikdgf098ikdfg089ikdfg-90odfg-09oldgf\",\n    \"expires_in\": 2419200,\n    \"token_type\": \"Bearer\",\n    \"scope\": \"scope_contact_read:on,scope_contact_write:on\",\n    \"refresh_token\": \"b94Idfp8i054-09fd-0kdf88898fdnnid0995\"\n}\n\n ```\n\n#### How to get an access token using a refresh token\n\n> [https://v3.api.swiftdigital.com.au/auth/token](https://v3.api.swiftdigital.com.au/server/includes/restapi/v3/auth/token.php) \n  \n\n##### Request:\n\n``` json\n{\n    \"grant_type\": \"refresh_token\",\n    \"client_id\": \"Client ID\",\n    \"client_secret\": \"Client Secret\",\n    \"refresh_token\": \"Refresh Token\"\n}\n\n ```\n\n##### Response:\n\n``` json\n{\n    \"access_token\": \"dfgkhndg987yuhnd0-dfo87yuhndf9o8yuhn-898erkjh\",\n    \"expires_in\": 2419200,\n    \"token_type\": \"Bearer\",\n    \"scope\": \"scope_contact_read:on,scope_contact_write:on\",\n    \"refresh_token\": \"b9987dfugjn9d08-09dfiuyh-0kdfg098349dfg9g5\"\n}\n\n ```\n\n# Error Code\n\nSwift Digital Suite REST API v3 uses conventional HTTP response codes to indicate the success or failure of an API request. In general, Codes in the `2xx` range indicate success. Codes in the `4xx` range indicate an error that failed given the information provided (e.g., a required parameter was missing, etc.). Codes in the `5xx` range indicate an error with the Swift Digital Suite API servers.\n\nSome `4xx` errors that could be handled programmatically include an error code that briefly explains the error reported.\n\nHTTP Status Code Summary:\n\n| **Status Code** | **Message** | **Description** |\n| --- | --- | --- |\n| 200 | OK | Everything worked as expected. |\n| 204 | No Content | The resource was deleted successfully. |\n| 400 | Bad Request | The request was unacceptable, often due to a missing required parameter. |\n| 401 | Unauthorized | No valid API key provided. |\n| 403 | Forbidden | The API key doesn’t have permissions to perform the request. |\n| 404 | Not Found | The requested resource doesn’t exist. |\n| 409 | Conflict | The request conflicts with another request (perhaps due to using the same idempotent key). |\n| 415 | Unsupported Media Type | The parameter syntax was valid, but unable to process the requested content. |\n| 422 | Unprocessable Content | The parameter syntax was valid, but unable to process the requested content. |\n| 429 | Too Many Requests | Too many requests hit the API too quickly. We recommend an exponential backoff of your requests. |\n| 500, 502, 503, 504 | Server Errors | Something went wrong on the Server end. |\n\n---\n\n# Pagination\n\nAll top-level API resources have support for bulk fetches through “list” API methods.\n\nFor example, you can list contacts, mail groups, folders, events, etc.\n\nIt offers an easy-to-use interface for accessing paginated data.\n\nThese list API methods share a common structure and accept the following parameters:\n\n`from_date` is the start date to select items within a date range.\n\n- It is optional and in epoch unix timestamp (Example: `1735700971`)\n    \n\n`to_date` is the end date to select items within a date range.\n\n- It is optional and in epoch unix timestamp (Example: `1764558571`)\n    \n\nAfter 1st request, if `has_more` is `true` then you must use the `next_data` to send subsequent requests for data.\n\n##### Sample API Response from Contact/List\n\n``` json\n{\n  \"has_more\": true,\n  \"next_data\": \"fgdkiujh4509ujndfg098i45nmsd098imw098iumewr90_890734u5nsduhbn_34897yuhn_23897sdnujlfg90m4_rd-34-df8n_-897nsdf_ewoup8ikwmer\",\n  \"total\": 45,\n  \"contact_ids\": [\n    \"zzzzxx7593efr7110010\",\n    \"zzzzxx7593efr7110011\"\n  ]\n}\n\n ```\n\n---\n\n# Rate Limiting\n\nWe have applied rate limits to ensure a smooth and reliable experience with the Swift Digital Suite REST API v3. The default is 600 requests/minute.\n\nViolation of the above-mentioned rate limits may impose a temporary ban on the IP/Domain. After the ban is lifted, the client can resume calling the API again.\n\nThe ban on the IP/Domain will return the following information:\n\n> **HTTP Code: 429**  \nMessage: Too Many Requests  \nDescription: Too many requests hit the API too quickly. We recommend an exponential backoff of your requests.","schema":"https://schema.getpostman.com/json/collection/v2.0.0/collection.json","isPublicCollection":false,"owner":"848661","collectionId":"3b902962-097b-4ae4-9c95-f9cb63c78c29","publishedId":"2sA35G42ms","public":true,"publicUrl":"https://docs.v3.api.swiftdigital.com.au","privateUrl":"https://go.postman.co/documentation/848661-3b902962-097b-4ae4-9c95-f9cb63c78c29","customColor":{"top-bar":"FFFFFF","right-sidebar":"808080","highlight":"6CB8E0"},"documentationLayout":"classic-double-column","customisation":{"metaTags":[{"name":"description","value":""},{"name":"title","value":""}],"appearance":{"default":"light","themes":[{"name":"dark","logo":"https://content.pstmn.io/7f534956-3edb-4699-bc10-ac4149567294/U3dpZnQgRGlnaXRhbCAtIFN1aXRlIC0gTG9nby5wbmc=","colors":{"top-bar":"212121","right-sidebar":"303030","highlight":"6CB8E0"}},{"name":"light","logo":"https://content.pstmn.io/4ef1b057-bba9-44ef-ad9d-75b467f4c7a0/U3dpZnQgRGlnaXRhbCAtIFN1aXRlIC0gTG9nby5wbmc=","colors":{"top-bar":"FFFFFF","right-sidebar":"808080","highlight":"6CB8E0"}}]}},"version":"8.10.0","publishDate":"2025-09-08T00:46:03.000Z","activeVersionTag":"latest","documentationTheme":"light","metaTags":{"title":"","description":""},"logos":{"logoLight":"https://content.pstmn.io/4ef1b057-bba9-44ef-ad9d-75b467f4c7a0/U3dpZnQgRGlnaXRhbCAtIFN1aXRlIC0gTG9nby5wbmc=","logoDark":"https://content.pstmn.io/7f534956-3edb-4699-bc10-ac4149567294/U3dpZnQgRGlnaXRhbCAtIFN1aXRlIC0gTG9nby5wbmc="}},"statusCode":200},"environments":[{"name":"Sandbox","id":"e086901e-a188-4143-8c1f-5500508f4b64","owner":"848661","values":[{"key":"ClientID","value":"","enabled":true,"type":"default"},{"key":"ClientSecret","value":"","enabled":true,"type":"default"},{"key":"t3acctid","value":"","enabled":true,"type":"default"}],"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/c078fcdef59bf64a0b2ebd47ac33d982bda55a7b23a6de483db77f879a25cbd6","favicon":"https://swiftdigital.com.au/favicon.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"},{"label":"Sandbox","value":"848661-e086901e-a188-4143-8c1f-5500508f4b64"}],"canonicalUrl":"https://docs.v3.api.swiftdigital.com.au/view/metadata/2sA35G42ms"}