{"activeVersionTag":"latest","latestAvailableVersionTag":"latest","collection":{"info":{"_postman_id":"be508df6-609a-471d-a539-5718d9f1125f","name":"Exivity API v2 (Beta)","description":"<img src=\"https://content.pstmn.io/9944564b-820d-4d7e-a101-d4371e646a52/RXhpdml0eUJldGFMb2dvLnBuZw==\">\n\n**This documentation pertains to the beta release of API v2.**\n\n**We aim to provide clear and comprehensive information, yet we invite your feedback to further refine the documentation. We welcome any suggestions for improvement, bug reports, or additional comments to enhance the overall utility and accuracy.**\n\n**Please note that as this is a beta version, some endpoints are subject to potential changes. We will promptly document all modifications in this section and include them in our release notes.**\n\n---\n\nThis is the Exivity API specification, and should be used as a reference guide for creating requests and parsing responses. For a more general introduction to Exivity, please refer to our [documentation](https://).\n\nDownload latest [Postman collection](https://) from our [GitHub repository](https://).\n\n# Overview\n\n1. This API uses principles and constraints of [REST APIs](https://).\n2. You need a valid API token for requests.\n3. The API has rate limiting.\n4. Most resource endpoints listen to and responds with data structures as defined by the [JSON:API standard](https://). You'll recognise these endpoints when the documentation lists the following headers:\n    \n\n```\nContent-Type: application/vnd.api+json\nAccept: application/vnd.api+json\n\n ```\n\n# Authentication\n\nThe default method of authentication against the API is done through a stateless [JWT token](https://).\n\nIt is also possible to authenticate the API via LDAP or SAML, if your administrator has set up access to either of these systems.\n\n#### **How to use the token**\n\nThe default method of authentication against the API is done through a stateless [JWT token](https://), sent along as an Authentication header. To obtain a token, a request to the API endpoint `/v1/auth/token` should be made with the user credentials.\n\nOnce a token has been generated, please include it in the headers of other requests to allow authorization.\n\n_Example:_\n\n```\nAuthorization: Bearer [token]\n\n ```\n\nThe JWT token will expire after _4 hours_ for security reasons. This value is configurable. Please see [/configuration](https://) or [https://docs.exivity.com/architecture%20concepts/glossary/#authentication-token](https://docs.exivity.com/architecture%20concepts/glossary/#authentication-token) for more information.\n\n# The Resource Object\n\nEach section of the API Reference contains an object, detailing the different attributes the endpoint accepts.\n\n_Example:_\n\n| **attribute** | **type** | **mutability** | **description** |\n| --- | --- | --- | --- |\n| name | _string_ | 📝 editable | Required, unique name for service category. Max 255 chars. |\n\n## Types\n\nThe follow types appear in this document:\n\n- `integer`\n- `float`\n- `double`\n- `string`\n- `array`\n- `enum`\\- this will be followed by an array of possible values. e.g _enum_(`charge`,`quantity`)\n- `date`\n- `datetime`\n- `time`\n    \n\nDate, datetime and time follow the ISO 8601 standard\n\n- `Y` - A full numeric representation of a year, 4 digits e.g, `1996`, `2021`\n- `m` - Numeric representation of a month, with leading zeros e.g. `01` through `12`\n- `d` - Day of the month, 2 digits with leading zeros e.g. `01` to `31`\n- `H` - 24-hour format of an hour with leading zeros e.g. `00` to `23`\n- `i` - Minutes with leading zeros e.g. `00` to `59`\n- `s` - Seconds with leading zeros e.g. `00` to `59`\n- `Y-m-d\\TH:i:s\\Z` - ISO 8601 datetime e.g. `2022-05-17T13:35:25Z`\n    \n\n_Examples:_\n\n- Y-m = `2017-01`\n    \n\n### Nullable values\n\nNullable values will have a question mark listed after the type. Examples: `integer?`, `string?`\n\n## Mutability\n\nThis column states whether a value is changable.\n\n- 📝 editable - These values can be changed\n- 🔏 immutable - Once set, these values cannot be changed\n- 👁 read-only - This values are set internal by the system and the user cannot change them\n    \n\n## Relationships\n\nIt is possible to include related relationships with a give resource request (see Working with the API -> Include Related Resources for how to do this). The possible relationships are listed under the resource object.\n\nExample:\n\n| **relationship** | **type** | **required** |\n| --- | --- | --- |\n| hasOne | adjustments | ✔️ |\n| hasMany | services | ❌ |\n| hasOne | usergroup | ❌ |\n\n### Required\n\nSome resources require a relationship to be created e.g. creating a new user required a usergroup. Any required relationships will be give in the **Add** example of the resource.\n\n# Working with the API\n\n## Placeholders\n\nDifferent variables have double curly brackets around them (`{{`, `}}`). These used for placeholders in this documentation. When working with the API, these placeholders should be replaced with real values. Examples include:\n\n`{{base_url}}` - replace this with your API's url\n\n`{{workflow_id}}`, `{{report_id}}`, `{{account_id}}`, etc - these are placeholders for a specific ID for an object.\n\n## Query String Parameters\n\nSome requests using the JSON:API format accept additional query string parameters.\n\n### Filtering\n\nTo filter results, use the `filter[attribute]` query string parameter.\n\nThe following formats are supported for filtering results:\n\n| Token | Description | Example |\n| --- | --- | --- |\n| `^` | Field starts with | `filter[name]=^John` |\n| `$` | Field ends with | `filter[name]=$Smith` |\n| `~` | Field contains | `filter[favorite_cheese]=~cheddar` |\n| `<` | Field is less than | `filter[lifetime_value]=<50` |\n| `>` | Field is greater than | `filter[lifetime_value]=>50` |\n| `>=` | Field is greater than or equals | `filter[lifetime_value]=>=50` |\n| `<=` | Field is less than or equals | `filter[lifetime_value]=<=50` |\n| `=` | Field is equal to | `filter[username]==Specific Username` |\n| `!=` | Field is not equal to | `filter[username]=!=common username` |\n| `[...]` | Field is one or more of | `filter[id]=[1,5,10]` |\n| `![...]` | Field is not one of | `filter[id]=![1,5,10]` |\n| `{...,...}` | Between exclusive (e.g. 2 up to 99) | `filter[id]={1,100}` |\n| `={...,...}` | Between inclusive (e.g. 1 up to 100) | `filter[id]=={1,100}` |\n| `NULL` | Field is null | `filter[address]=NULL` |\n| `NOT_NULL` | Field is not null | `filter[email]=NOT_NULL` |\n\n_Example - get accounts that start with W:_\n\n```\nGET /accounts?filter[name]=^W\n\n ```\n\n#### Multiple filters\n\nThe filter parameter can occur multiple times in a request to filter by multiple fields.\n\n_Example - get accounts that start with W and level is set to one:_\n\n```\nGET /accounts?filter[name]=^W&filter[level]==1\n\n ```\n\n#### Related entities filters\n\nA filter can also use related entities (which don't have to be included in the request with the `include` parameter).\n\n_Example - get users with MANAGE_USERS permission, and an email address ending with \"example.com\":_\n\n```\nGET /user?filter[usergroup.permissions]=~MANAGE_USERS&filter[email_address]=$example.com\n\n ```\n\n### Pagination\n\nWhen making requests to endpoints which can return more than one entity, results are paginated. The number of results per page and the requested page can be adjusted with the `page[limit]` and `page[offset]` query string parameters.\n\n_Example:_\n\n```\nGET /user?page[limit]=50&page[offset]=2\n\n ```\n\nWhen the page limit is set to `-1`, all results are returned.\n\nThe `links` element in the JSON response contains references to URLs which can be used to navigate the resultset.\n\nThe `meta` element in the JSON response contains a reference to the total number of items in the resultset.\n\n### Sorting\n\nIt is possible to sort results by using the `sort` query string parameter. A descending sort order can be requested by prefixing a hyphen (U+002D).\n\n_Example:_\n\n```\nGET /user?sort=-username\n\n ```\n\n### Include Related Resources\n\nInclusion of related resources in the response can be requested with the `include` query string parameter. Multiple entities can be specified by separating them with a comma (U+002C). Each endpoint definition specifies which includes can be requested.\n\n_Examples:_\n\n```\nGET /user?include=usergroup,accounts\nGET /user/[id]?include=usergroup,accounts\n\n ```\n\n### Fetching relationships\n\nIt is also possible to fetch relationship data to a single resource using a separate endpoint. Relationships data on resources can be [queried](https://) and [modified](https://) by using the `/[resource]/[id]/relationships/[relation]` endpoint structure.\n\n```\nGET /user/[id]/usergroup\n\n ```\n\n# Atomic Operations\n\nMany endpoint support Atomic Operations. This provides a means to perform multiple “operations” in a linear and atomic manner.\n\nAt the top of all endpoints, it states whether or not it supports atomic operations:\n\n- Atomic support: ✔️\n- Atomic support:❌\n    \n\nPlease read the [JSON:API Atomic Operations](https://jsonapi.org/ext/atomic/) documentation to understand how this works.\n\n**Example**\n\nAdd a workflow and a workflow step in a single request:\n\n``` json\n{\n    \"atomic:operations\": [\n        {\n            \"op\": \"add\",\n            \"data\": {\n                \"type\": \"workflow\",\n                \"lid\": \"foo\",\n                \"attributes\": {\n                    \"name\": \"Atomic workflow\",\n                    \"description\": \"My new atomic workflow\"\n                }\n            }\n        },\n        {\n            \"op\": \"add\",\n            \"data\": {\n                \"type\": \"workflowstep\",\n                \"lid\": \"bar\",\n                \"attributes\": {\n                    \"type\": \"execute\",\n                    \"timeout\": 600,\n                    \"options\": {\n                        \"command\": \"echo \\\"testing\\\"\"\n                    }\n                },\n                \"relationships\": {\n                    \"workflow\": {\n                        \"data\": {\n                            \"type\": \"workflow\",\n                            \"lid\": \"foo\"\n                        }\n                    }\n                }\n            }\n        }\n    ]\n}\n\n ```\n\nAll atomic request must be submitted throught the atomic endpoint:\n\n`POST {{base_url}}/v2/`\n\nSee [General/Json API atomic operation](#d00d58da-6562-45db-bcb1-917dd57e6fb5) for more examples.\n\n# Error responses\n\nErrors are returned as a JSON object, following the [JSON:API error standard](https://). We use HTTP error responses in the status field, to indicate whether the request was a success (`2xx`) or a failure(`4xx`, `5xx`).\n\n_Example:_\n\n``` json\n{\n  \"errors\": [\n    {\n      \"status\": \"422\",\n      \"title\":  \"Attribute validation error\",\n      \"detail\": \"Password must contain at least 8 characters.\"\n    }\n  ]\n}\n\n ```\n\nPossible response codes:\n\n| Code | Description |\n| --- | --- |\n| `400 Bad request` | Something in the request is missing or invalid |\n| `401 Unauthorized` | JWT token is missing or invalid |\n| `403 Forbidden` | Missing required permission for this operation |\n| `404 Not found` | Entity can't be found |\n| `409 Conflict` | Entity type or id doesn't match endpoint |\n| `422 Unprocessable Entity` | Parameters validation error |\n| `503 Service Unavailable` | Rate lime exceeded |\n\n## Authentication error response\n\nIf an authorization token is missing, expired or malformed, an error response will be returned. These errors will always have a `401 Unauthorised` status.\n\n_Example:_\n\n``` json\n{\n    \"errors\": [\n        {\n            \"status\": 401,\n            \"title\": \"AuthException\",\n            \"detail\": \"Invalid token provided, please login again.\"\n        }\n    ]\n}\n\n ```\n\n## Authorization error response\n\nSome endpoints require a different set of permissions than others. If insufficient permissions are granted to the authenticated user, a `403 Forbidden` response is returned.\n\n# Rate limits\n\nAll API requests are rate limited to avoid overloading the server.  \nThe rate at which you can make requests to the API is limited by client IP address, and is limited at 10 requests per second. The API allows for short request bursts (i.e. you can exceed this limit for a short period of time). If you've exceeded your API rate limit, you'll get back a `503 Service Unavailable` response.\n\nRequests containing a user password in the payload are even further rate limited to mitigate brute-force attacks in user credentials.\n\n# Terms of service\n\nYou can find the terms of service [on our website](https://).\n\n# API Reference","schema":"https://schema.getpostman.com/json/collection/v2.0.0/collection.json","isPublicCollection":false,"owner":"11445485","team":48706,"collectionId":"be508df6-609a-471d-a539-5718d9f1125f","publishedId":"TzCLA9BM","public":true,"publicUrl":"https://api-v2.exivity.com","privateUrl":"https://go.postman.co/documentation/11445485-be508df6-609a-471d-a539-5718d9f1125f","customColor":{"top-bar":"FFFFFF","right-sidebar":"303030","highlight":"EF5B25"},"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":"EF5B25"}}]}},"version":"8.11.6","publishDate":"2024-04-16T12:50:06.000Z","activeVersionTag":"latest","documentationTheme":"light","metaTags":{"title":"","description":""},"logos":{"logoLight":null,"logoDark":null}},"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/768118b36f06c94b0306958b980558e6915839447e859fe16906e29d683976f0","favicon":"https://exivity.com/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"}],"canonicalUrl":"https://api-v2.exivity.com/view/metadata/TzCLA9BM"}