{"activeVersionTag":"latest","latestAvailableVersionTag":"latest","collection":{"info":{"_postman_id":"cb6be297-df44-41de-96c1-6991a5d1f978","name":"Sympa Generic API","description":"# General\n\nSympa Generic Integration API (from here on “API” in this document) is a set of standardised API endpoints for exposing data from Sympa to a third-party software provider. This document describes the technical functionality of the API as well as the standard API endpoints.\n\n# Important on Absences and Holiday API URLs\n\nIn this documentation, the API URL for Absences is `https://api.sympahr.net/api/Absences`. It is important to note, that if the customer entity is multinational, the Absences API URLs will include a country suffix, such as AbsencesFI or AbsencesUK, and the absences for employees in each country will be fetched through different API endpoints. In single-country entities no suffixes are used.\n\nSimilar logic applies to holidays (`.../api/Holidays` -> `.../api/HolidaysFI` and `.../api/HolidaysSE`, etc).\n\n# Authentication\n\nRequests to the API interfaces are authenticated using Basic Authentication (API key as the username, API secret as the password).\n\nRequests where the authentication fails will get an HTTP Unauthorized (401) response code. Since unauthenticated requests are not necessarily associated with any specific ApiKey or interface, these failed requests will not be visible in the API Activity Log.\n\nContact [<b>partners@sympa.com</b>](https://mailto:partners@sympa.com) to get assigned an API key and secret for testing purposes.\n\n# Metadata\n\nInterface metadata can be accessed by appending `/$metadata` to the api service root URL (`https://api.sympahr.net/api`). The metadata is returned as XML, and it lists the available interfaces and their field properties.\n\n# Service Document\n\nThe service returns a service document from the root URL (`https://api.sympahr.net/api`). This document is returned as JSON, and it lists all the API interfaces available with the given authentication method.\n\n# Querying Data\n\nThe API implements parts of the Open Data Protocol, Version 4. The supported features are described below.\n\nEvery query returns all matches, which may decrease the performance especially with large data sets. It is recommended to implement as many appropriate query parameters to your requests as necessary to avoid unnecessary polling of data.\n\n## GET Query Standard Parameters\n\nThe results from all data queries are returned in JavaScript Object Notation (JSON) format. Only a subset of OData query parameters, listed below, are supported:\n\n- `$top`\n    \n- `$skip`\n    \n- `$orderby`\n    \n- `$filter`\n    \n- `$count`\n    \n- `$expand`\n    \n\n### Top\n\nThe query `$top=XX` will return the first XX matches to the query.\n\nExample:\n\n`.../api/SYSTEMNAMEPerson/?$top=200`\n\n### Skip\n\nThe query `$skip=XX` will leave out the first XX matches to the query.\n\nExample:\n\n`.../api/SYSTEMNAMEPerson?$skip=10`  \n`.../api/SYSTEMNAMEPerson?$skip=10&$top=10`\n\n### Orderby\n\nThe query `$orderby=alias, otheralias desc` will sort the result set, primarily by the alias “alias”, ascending, and secondarily by the alias “otheralias”, descending.\n\nExample:\n\n`.../api/SYSTEMNAMEPerson?$orderby=Employee_number`\n\n### Filter\n\nThe following subset of OData filters are supported by the API.\n\n- `and`\n    \n- `or`\n    \n- `not`\n    \n- `eq` (equal)\n    \n- `gt` (greater than)\n    \n- `lt` (less than)\n    \n- `ge` (greater than or equal to)\n    \n- `le` (less than or equal to)\n    \n- `contains`\n    \n- `startswith`\n    \n- `endswith`\n    \n\nUsing any other OData filter operator (e.g., `in`, `has`) or query function (e.g., `now`, `tolower`, `indexof`) will return an HTTP status code 501 (Not Implemented).\n\nAvailable filters vary by field type as follows:\n\n| **Field Type** | **Supported Filters** | **Examples** |\n| --- | --- | --- |\n| **All field types** | All field types can be filtered by null or by text. |  |\n| **Number** | `eq`, `gt`, `lt`, `ge`, `le` | `.../api/SYSTEMNAMEPerson?$filter=not (number eq null)`  <br>  <br>`.../api/SYSTEMNAMEPerson?$filter=number ge 0`  <br>  <br>`.../api/SYSTEMNAMEPerson?$filter=number ge 1.14d` |\n| **Date** | `eq`, `gt`, `lt`, `ge`, `le` | `.../api/SYSTEMNAMEPerson?$filter=not(Original_hire_date eq null)`  <br>  <br>`.../api/SYSTEMNAMEPerson?$filter=Date_of_birth gt 1980-12-17`  <br>  <br>`.../api/SYSTEMNAMEPerson?$filter=(Original_hire_date gt 2020-02-29) and (Original_hire_date lt 2020-03-02)` |\n| **Timestamp**  <br>_\"created\" and \"modified\"_ | `eq`, `gt`, `lt`, `ge`, `le` | `.../api/SYSTEMNAMEPerson?$filter=(modified gt 2015-12-31T23:59:59Z)`  <br>  <br>If you don't specify the time, the timestamp is interpreted as T00:00:00  <br>  <br>Note: if the `created` field is null in Sympa, the API displays a value \"0001-01-01T00:00:00\" but an empty `modified` field is shown as \"null\" |\n| **Unique** **identifier**  <br>_\"Employee_number\" and \"Candidate_ID_from_ATS\"_ | By null or by text. | `.../api/SYSTEMNAMEPerson?$filter=Employee_number eq '123'`  <br>  <br>If the employee numbers have a letter prefix, such as EMP123, leave the letter(s) out of the filter. Using values that are not numbers (e.g. Employee_number eq 'EMP123') will give an error (\"message\": \"Error with SQM query:  <br>MissingFilterField\"). |\n\n### Count\n\nThe query `$count=true` will add the total count of all matches, after filtering, but before skip and top, as a return value named “odata.count”.\n\nExample:\n\n`.../api/SYSTEMNAMEPerson?$count=true`\n\nThe @odata.count value always contains all the results matched by the filter, i.e. top and skip do not affect the count. Query `.../api/SYSTEMNAMEPerson?$skip=2&$top=1&$count=true` count value is same as `.../api/SYSTEMNAMEPerson?$count=true`.\n\n### Expand\n\n`$expand` query parameter allows filtering Sympa table rows (objects) inside a Sympa table (array). This query parameter is only in use with API endpoints that include arrays.\n\nExample:\n\n`.../api/SYSTEMNAMECompensation?$expand=Compensation($filter=Valid_from ge 2011-01-01)`\n\nNote: the `$expand` parameter filters only within the array in question, meaning the result set contains all the employees it would contain without the filtering; only the array objects are filtered.\n\nYou can combine `$expand` with other filters and attributes:\n\n`.../api/SYSTEMNAMECompensation?$filter=Test_user eq false&$expand=Compensation($filter=Approval eq 5)`\n\nIn this example the all test users are filtered out of the response and the Compensation array will only include objects that are approved.\n\n### Approval Status in GET Queries\n\nIf the API endpoint includes data that is associated with approval workflows, the approval information is returned as an integer value in the JSON message:\n\n| **Approval Status** | **Value** |\n| --- | --- |\n| Undefined | 0 |\n| Waiting for data to be saved | 1 |\n| Waiting for approval request to be sent | 2 |\n| Waiting for approval | 3 |\n| Declined | 4 |\n| Approved | 5 |\n\n## GET Query Sympa-Specific Parameters\n\nIn addition to the standard parameters, there are the following non-standard, Sympa-specific, query parameters available:\n\n- errordata\n    \n- since\n    \n- until\n    \n- at\n    \n\nDo not use $ with the Sympa-specific query parameters, as they are customized parameters for Sympa and not ODATA standard.\n\n### Errordata\n\nThe query `errordata=true` will add a summary of all errors encountered in the data while querying, as a return value named “odata.errors”.\n\n### Since, Until, At\n\nParameters `since`, `until`, and `at` can be used in API endpoints that include Sympa tables (arrays) to only return time-related objects that overlap with the given time frame.\n\nThese parameters are often used, for exampel, when wanting to fetch Employment, Compensation, or Absence data only for a given time period, instead of querying the entire history.\n\nExamples:\n\n`.../api/SYSTEMNAMECompensation?at=2024-01-01`\n\n`.../api/SYSTEMNAMEAbsences?since=2011-12-29&until=2012-02-21`\n\n`.../api/SYSTEMNAMEBenefits?since=2011-12-29`\n\n`.../api/SYSTEMNAMEEmployment?until=2022-02-21`\n\n## Notes\n\nOData queries (GET requests) to the interface are performed against Sympa’s pre-calculated Reporting database. There’s a small delay from creating or modifying data to it being persisted to the pre-calculated Reporting database. What this means is that there is a small delay from modifying data with a POST or PATCH request before it will be queryable with a GET request. Usually the delay is less than a minute, in exceptional cases it may take up to 30 minutes.\n\nThe default throttling level is up to 100 requests in 1h time per interface. This limit of 100 requests is a shared limit across all request types, so no more than 100 requests per hour can be executed regardless of type (GET, POST, PATCH).\n\nSympa holds the right to create new APIs as well as deprecate them, modify them and limit their access.","schema":"https://schema.getpostman.com/json/collection/v2.0.0/collection.json","isPublicCollection":false,"owner":"33639379","team":6102157,"collectionId":"cb6be297-df44-41de-96c1-6991a5d1f978","publishedId":"2sA3kXG1vX","public":true,"publicUrl":"https://documenter-api.postman.tech/view/33639379/2sA3kXG1vX","privateUrl":"https://go.postman.co/documentation/33639379-cb6be297-df44-41de-96c1-6991a5d1f978","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-08-30T12:18:17.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/50a510ed8836ea09261c5e0a789904fc92215218dfe383079e3a7029dcc7116d","favicon":"https://res.cloudinary.com/postman/image/upload/v1712747787/team/tpxi5l0un8xqty2upxsf.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://documenter.gw.postman.com/view/metadata/2sA3kXG1vX"}