{"activeVersionTag":"latest","latestAvailableVersionTag":"latest","collection":{"info":{"_postman_id":"e111b3a3-68a2-aba8-0c4a-f8a0225d7019","name":"🚀 Pureservice API Guide - 1.0.0 (public preview)","description":"Welcome to the Pureservice API documentation. This guide provides a comprehensive overview of the API's capabilities, including authentication, entity management, filtering, paging, and static values. Use this guide to integrate Pureservice into your applications securely and efficiently.\n\nThe Pureservice API offers a robust and flexible interface for integrating with the Pureservice platform. It supports secure operations for reading, creating, updating, and managing entities such as tickets, statuses, users, and more.\n\n---\n\n# 📚 Table of Contents\n\n- [📚 Table of Contents](#table-of-contents)\n    \n- [✅ Return Codes](#return-codes)\n    \n- [🌐 Base URL](#base-url)\n    \n- [📝 Content Negotiation](#content-negotiation)\n    \n- [🔐 Authentication](#authentication)\n    \n    - 🔑 API Keys\n        \n    - 🔑 API Tokens\n        \n- [🚦 Limits and Throttling](#limits-and-throttling)\n    \n    - ⏱️ Rate Limits\n        \n    - 📏 Entity Limits\n        \n- [🗂️ Entity Operations](#entity-operations)\n    \n    - 🔎 Fetching Entities (GET)\n        \n        - 🔍 Get a Single Entity by ID\n            \n        - 📋 Get All Entities by Type\n            \n        - 📑 Get Multiple Entities by IDs\n            \n    - ➕ Creating Entities (POST)\n        \n        - 🛠️ Example: Creating a Ticket\n            \n    - ✏️ Updating Entities (PUT/PATCH)\n        \n        - 🛠️ Example: Partial Update (PATCH)\n            \n        - 🛠️ Example: Full Update (PUT)\n            \n- [🔎 Filtering, Sorting, and Paging](#filtering-sorting-and-paging)\n    \n    - 🔍 Filtering\n        \n    - ↕️ Sorting\n        \n    - 📄 Paging\n        \n    - 🔗 Including Related Entities\n        \n- [🔢 Static Values](#static-values)\n    \n    - UserRole\n        \n    - Visibility\n        \n    - PhonenumberType\n        \n    - 📢 AnnouncementType\n        \n- [🏷️ Zone Security (If Applicable)](#️zone-security-if-applicable)\n    \n- [❗ Validation Errors](#validation-errors)\n    \n\n---\n\n# ✅ Return Codes\n\n| Code Range | Description |\n| --- | --- |\n| 🟢 **2XX** | Success — The API call completed successfully. |\n| 🟠 **4XX** | Client Error — There was a validation or input error in the request. |\n| 🔴 **5XX** | Server Error — The API failed to process the request. Try again later. |\n\n---\n\n# 🌐 Base URL\n\nAll API endpoints are served from the **Agent** application. You must direct your API calls to the Agent URL, not the Selfservice (end-user) portal.\n\nFor **SaaS** customers, the base URL follows this pattern:\n\n```\nhttps://{customer}.pureservice.com/agent/api/\n\n ```\n\nFor example, if your Pureservice instance is `acme.pureservice.com`, your API base URL is:\n\n```\nhttps://acme.pureservice.com/agent/api/\n\n ```\n\n> ⚠️ **Important:** Do not send API requests to the Selfservice portal URL (e.g. `https://{customer}.pureservice.com/api/`). API calls must always target the Agent application path (`/agent/api/`). \n  \n\nAll examples in this documentation use the SaaS URL pattern (`customer.pureservice.com/agent/api`). If you are running an on-premises installation the base URL depends on your deployment configuration. Contact your system administrator for the correct Agent URL. Request examples show SaaS requests.\n\n---\n\n# 📝 Content Negotiation\n\nTo ensure JSON:API-compliant communication, set the following headers:\n\n- **Accept:**  \n    `application/vnd.api+json`\n    \n- **Content-Type:**  \n    `application/vnd.api+json` (for requests with a payload)\n    \n> ⚠️ **Important:** For `PATCH` requests, use content-type `application/json`, see examples.\n\n**Example:**\n\n```\nAccept: application/vnd.api+json\nContent-Type: application/vnd.api+json\n\n ```\n\n---\n\n# 🔐 Authentication\n\n## 🔑 API Keys\n\nAPI keys allow integration with third-party services and are managed via the Pureservice web interface.\n\nAuthenticate by passing your API key in the `X-Authorization-Key` HTTP header with every request.\n\n**Best Practices:**\n\n- 🔒 Keep keys confidential and rotate regularly.\n    \n- ⏳ Set expiration dates where possible.\n    \n- 🗑️ Deactivate or delete unused keys.\n    \n\n**Administering API Keys:**  \nNavigate to **Pureservice > Administration > Security > API keys** to manage your keys.\n\n**Usage Example:**\n\n``` http\nGET /agent/api/status HTTP/1.1\nHost: customer.pureservice.com\nAccept: application/vnd.api+json\nX-Authorization-Key: YOUR_API_KEY\n\n ```\n\n---\n\n## 🔑 API Tokens\n\nAPI tokens are used for user-based authentication via the `Authorization: Bearer` header. This method is scheduled for deprecation.\n\n``` http\nGET /agent/api/status HTTP/1.1\nHost: customer.pureservice.com\nAccept: application/vnd.api+json\nAuthorization: Bearer YOUR_USER_TOKEN\n\n ```\n\n---\n\n# 🚦 Limits and Throttling\n\n## ⏱️ Rate Limits\n\n- **100 requests per minute** per client (SaaS only).\n    \n- Exceeding this limit returns `429 Too Many Requests` with potentially a `Retry-After` header if applicable.\n    \n\n**Example:**\n\n``` http\nHTTP/1.1 429 Too Many Requests\nContent-Type: application/json\nRetry-After: 15\n\n ```\n\n## 📏 Entity Limits\n\n- **Maximum 500 entities per request**.\n    \n- Use paging (`start` and `limit` parameters) to retrieve more.\n    \n\n---\n\n# 🗂️ Entity Operations\n\n## 🔎 Fetching Entities (GET)\n\n### 🔍 Get a Single Entity by ID\n\n``` http\nGET /agent/api/status/1 HTTP/1.1\nHost: customer.pureservice.com\nAccept: application/vnd.api+json\nX-Authorization-Key: YOUR_API_KEY\n\n ```\n\nor\n\n``` http\nGET /agent/api/status?id=1 HTTP/1.1\nHost: customer.pureservice.com\nAccept: application/vnd.api+json\nX-Authorization-Key: YOUR_API_KEY\n\n ```\n\n### 📋 Get All Entities by Type\n\n``` http\nGET /agent/api/status/ HTTP/1.1\nHost: customer.pureservice.com\nAccept: application/vnd.api+json\nX-Authorization-Key: YOUR_API_KEY\n\n ```\n\n- **Note:** Maximum 500 items per request. Use paging for more.\n    \n\n### 📑 Get Multiple Entities by IDs\n\n``` http\nGET /agent/api/status/?ids=1,5 HTTP/1.1\nHost: customer.pureservice.com\nAccept: application/vnd.api+json\nX-Authorization-Key: YOUR_API_KEY\n\n ```\n\n---\n\n## ➕ Creating Entities (POST)\n\n### 📝 Example: Creating a Ticket\n\n``` http\nPOST /agent/api/ticket HTTP/1.1\nHost: customer.pureservice.com\nContent-Type: application/vnd.api+json\nAccept: application/vnd.api+json\nX-Authorization-Key: YOUR_API_KEY\n{\n  \"tickets\": [\n    {\n      \"subject\": \"Cannot access email\",\n      \"description\": \"User reports email access issues since this morning.\",\n      \"statusId\": 1,\n      \"priorityId\": 2,\n      \"requestTypeId\": 1,\n      \"userId\": 42\n    }\n  ]\n}\n\n ```\n\n---\n\n## ✏️ Updating Entities (PUT/PATCH)\n\n- **PUT:** Full update (missing properties are reset to default).\n    \n- **PATCH:** Partial update (only specified properties are updated).\n    \n\n**Recommended:** Use `PATCH` for updates.\n\n### 🛠️ Example: Partial Update (PATCH)\n\n``` http\nPATCH /agent/api/ticket/10 HTTP/1.1\nHost: customer.pureservice.com\nContent-Type: application/json\nAccept: application/vnd.api+json\nX-Authorization-Key: YOUR_API_KEY\n{ \"subject\": \"...\" }\n\n ```\n\n### 🛠️ Example: Full Update (PUT)\n\n``` http\nPUT /agent/api/ticket/10 HTTP/1.1\nHost: customer.pureservice.com\nContent-Type: application/vnd.api+json\nAccept: application/vnd.api+json\nX-Authorization-Key: YOUR_API_KEY\n{\n  \"tickets\": [\n    {\n      \"subject\": \"Updated summary\",\n      \"description\": \"Full description here.\"\n      ...\n    }\n  ]\n}\n\n ```\n\n---\n\n# 🔎 Filtering, Sorting, and Paging\n\n## 🔍 Filtering\n\nUse the `filter` query parameter to filter entities. Supports logical operators (`AND`, `OR`) and standard operators.\n\n**Examples:**\n\n- `name == \"Closed\"`\n    \n- `default == true AND name == \"Open\"`\n    \n- `name == \"Closed\" OR (default == true AND name == \"Open\")`\n    \n\n**Supported Operators:**\n\n| Operator Type | Syntax | Example |\n| --- | --- | --- |\n| 🟰 Equals | `==` | `status == \"Closed\"` |\n| 🔼 Greater than | `>` | `index > 1` |\n| 🔽 Less than | `<` | `index < 5` |\n| 🔎 Contains | `[Property].Contains([Value])` | `name.Contains(\"Open\")` |\n| ✔️ Boolean | `[Property] == true/false` | `default == true` |\n| ➕ AND | `AND / &&` | `name == \"Open\" AND default == true` |\n| ➖ OR | \\`OR / |  |\n\n---\n\n## ↕️ Sorting\n\nUse the `sort` query parameter to sort results.\n\n- Single field: `?sort=fieldName asc`\n    \n- Multiple fields: `?sort=field1 asc,field2 desc`\n    \n- Default direction is ascending.\n    \n\n---\n\n## 📄 Paging\n\nUse `start` and `limit` query parameters for paging.\n\n**Example:**\n\n``` http\nGET /agent/api/status/?start=0&limit=10 HTTP/1.1\nHost: customer.pureservice.com\nAccept: application/vnd.api+json\nX-Authorization-Key: YOUR_API_KEY\n\n ```\n\n---\n\n## 🔗 Including Related Entities\n\nUse the `include` parameter to include related entities.\n\n**Example:**\n\n``` http\nGET /agent/api/status/?include=requesttype,createdBy HTTP/1.1\nHost: customer.pureservice.com\nAccept: application/vnd.api+json\nX-Authorization-Key: YOUR_API_KEY\n\n ```\n\n---\n\n# 🔢 Static Values\n\nThe following enumerated constants are used throughout the Pureservice API:\n\n## UserRole\n\n| Name | Value |\n| --- | --- |\n| None | `0` |\n| PendingActivate | `1` |\n| LocationPendingActivate | `2` |\n| Enduser | `10` |\n| Agent | `20` |\n| ZoneAdmin | `25` |\n| Administrator | `30` |\n| System | `50` |\n\n## Visibility\n\n| Name | Value |\n| --- | --- |\n| Visible | `0` |\n| VisibleSilent | `1` |\n| NotVisible | `2` |\n\n## PhonenumberType\n\n| Name | Value |\n| --- | --- |\n| Home | `0` |\n| Cellphone | `1` |\n\n## AnnouncementType\n\n| Name | Value |\n| --- | --- |\n| Information | `0` |\n| Warning | `1` |\n| Critical | `2` |\n\n---\n\n# 🏷️ Zone Security (If Applicable)\n\nIf your Pureservice instance uses **zone-security features**, note:\n\n- 🏷️ Entities with a `department` or `assignedDepartment` property must have a non-null value.\n    \n- 🏷️ Entities restricted by a zone must be explicitly assigned to a zone.\n    \n- 🏷️ The property is called `department` in the API for backward compatibility, but is displayed as `zone` in the UI.\n    \n- ❗ Missing or invalid zone fields result in a `400 Bad Request`.\n    \n\n---\n\n# ❗ Validation Errors\n\nValidation errors are returned as an array of error objects under the `errors` property.\n\n**Example:**\n\n``` http\nHTTP/1.1 400 Bad Request\nContent-Type: application/json\n{\n  \"errors\": [{\n    \"message\": \"SomeFieldOne : SomeFieldOne is required.\"\n  }]\n}\n\n ```\n\n---\n\nFor further details or assistance, [contact our support](https://support.pureservice.com) or send us an email at [support@pureservice.com](mailto:support@pureservice.com).","schema":"https://schema.getpostman.com/json/collection/v2.0.0/collection.json","isPublicCollection":false,"owner":"398215","collectionId":"e111b3a3-68a2-aba8-0c4a-f8a0225d7019","publishedId":"2SJVwo","public":true,"publicUrl":"https://api-docs.pureservice.com","privateUrl":"https://go.postman.co/documentation/398215-e111b3a3-68a2-aba8-0c4a-f8a0225d7019","customColor":{"top-bar":"FFFFFF","right-sidebar":"303030","highlight":"EF5B25"},"documentationLayout":"classic-double-column","version":"8.11.4","publishDate":"2019-11-06T14:12:51.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/6d831c67cdf8175ffc364d0a0011372247bc3e4e65b94d96a65a0b1040da22ce","favicon":"https://res.cloudinary.com/postman/image/upload/v1632894173/team/r7cy7i02hwuoqztsjzx6.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://api-docs.pureservice.com/view/metadata/2SJVwo"}