Sympa 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.
\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.
Similar logic applies to holidays (.../api/Holidays -> .../api/HolidaysFI and .../api/HolidaysSE, etc).
Requests to the API interfaces are authenticated using Basic Authentication (API key as the username, API secret as the password).
\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.
\nContact partners@sympa.com to get assigned an API key and secret for testing purposes.
\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.
The 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.
The API implements parts of the Open Data Protocol, Version 4. The supported features are described below.
\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.
\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$top
$skip
$orderby
$filter
$count
$expand
The query $top=XX will return the first XX matches to the query.
Example:
\n.../api/SYSTEMNAMEPerson/?$top=200
The query $skip=XX will leave out the first XX matches to the query.
Example:
\n.../api/SYSTEMNAMEPerson?$skip=10.../api/SYSTEMNAMEPerson?$skip=10&$top=10
The query $orderby=alias, otheralias desc will sort the result set, primarily by the alias “alias”, ascending, and secondarily by the alias “otheralias”, descending.
Example:
\n.../api/SYSTEMNAMEPerson?$orderby=Employee_number
The following subset of OData filters are supported by the API.
\nand
or
not
eq (equal)
gt (greater than)
lt (less than)
ge (greater than or equal to)
le (less than or equal to)
contains
startswith
endswith
Using 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).
Available filters vary by field type as follows:
\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”.
Example:
\n.../api/SYSTEMNAMEPerson?$count=true
The @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.
$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.
Example:
\n.../api/SYSTEMNAMECompensation?$expand=Compensation($filter=Valid_from ge 2011-01-01)
Note: 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.
You can combine $expand with other filters and attributes:
.../api/SYSTEMNAMECompensation?$filter=Test_user eq false&$expand=Compensation($filter=Approval eq 5)
In this example the all test users are filtered out of the response and the Compensation array will only include objects that are approved.
\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:
\nIn addition to the standard parameters, there are the following non-standard, Sympa-specific, query parameters available:
\nerrordata
\nsince
\nuntil
\nat
\nDo not use $ with the Sympa-specific query parameters, as they are customized parameters for Sympa and not ODATA standard.
\nThe query errordata=true will add a summary of all errors encountered in the data while querying, as a return value named “odata.errors”.
Parameters 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.
These 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.
\nExamples:
\n.../api/SYSTEMNAMECompensation?at=2024-01-01
.../api/SYSTEMNAMEAbsences?since=2011-12-29&until=2012-02-21
.../api/SYSTEMNAMEBenefits?since=2011-12-29
.../api/SYSTEMNAMEEmployment?until=2022-02-21
OData 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.
\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).
\nSympa holds the right to create new APIs as well as deprecate them, modify them and limit their access.
\n","schema":"https://schema.getpostman.com/json/collection/v2.0.0/collection.json","toc":[{"content":"General","slug":"general"},{"content":"Important on Absences and Holiday API URLs","slug":"important-on-absences-and-holiday-api-urls"},{"content":"Authentication","slug":"authentication"},{"content":"Metadata","slug":"metadata"},{"content":"Service Document","slug":"service-document"},{"content":"Querying Data","slug":"querying-data"}],"owner":"33639379","collectionId":"cb6be297-df44-41de-96c1-6991a5d1f978","publishedId":"2sA3kXG1vX","public":true,"customColor":{"top-bar":"FFFFFF","right-sidebar":"303030","highlight":"FF6C37"},"publishDate":"2024-08-30T12:18:17.000Z"},"item":[{"name":"Person","id":"c4df2b98-3d24-4529-a7d0-780b33271a01","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"GET","header":[],"url":"https://api.sympahr.net/api/GenericPerson","description":"Use this endpoint to fetch employees' basic information, such as their name and contact information.
\n","auth":{"type":"basic","basic":{"basicConfig":[{"key":"username","value":"