Skip to content

Contacts API v1

Jump to bottom
Mårten Thavenius edited this page Mar 8, 2017 · 27 revisions

Introduction

The Contacts API v1 is a read-only REST API to get contact information to employees and to group contacts in the City of Malmö. It is an authenticated server-to-server API and is only accepting requests from registered applications. The information can only be used in applications governed by the City of Malmö.

Registration

Before you can use the API, you need to contact [email protected] to discuss the purpose of the usage of the data and the estimated traffic. Provide the IP-address for your test and production servers, the systems common name and the email address to the system manager.

Authentication

You will get an app_token and an app_secret when you register a consuming application for a specific server or developing machine. Those parameters must be passed with each request.

Caching

You are responsible for caching requests in the consuming application. The caching policy depends on the amount of traffic the application will create and the need for fresh data. Please contact [email protected] to discuss an appropriate policy.

Exception Handling

You must handle exceptions in the consuming application for responses. This includes both HTTP response codes and timeouts from the API server.

A request for a contact that has been removed will return:

HTTP/1.1 404 Not Found

{
  "message": "404 Not Found"
}

Authentication failures will return:

HTTP/1.1 401 Unauthorized

{
  "message": "401 Unauthorized. Your app_token, app_secret or ip address is not correct."
}

HTTP Redirects

The API might use HTTP redirection. Clients should assume that any request may result in a redirection. Receiving an HTTP redirection is not an error and clients should follow that redirect.

Resources

All API access is over HTTPS and accessed from the following base address:

GET https://minsida.malmo.se/

All data is received as JSON.

Search Employees

Case insensitive search where the value of the q parameter is matching the start of one of the following fields: first_name, last_name, first_name last_name (combined) or email.

Example request:

GET /api/v1/employees/search?q=jes

Response:

HTTP/1.1 200 OK

[
  {
    "catalog_id": "magiva",
    "id": 111,
    "first_name": "Jesper",
    "last_name": "Bylund",
    "title": "Enhetschef",
    "email": "[email protected]",
    "company": "102 Stadskontoret",
    "department": "Kommunikationsavdelningen"
  },
  {
    "catalog_id": "asajes",
    "id": 50,
    "first_name": "\u00c5sa",
    "last_name": "Jespersson",
    "title": "Processchef",
    "email": "[email protected]",
    "company": "040 Fritidsf\u00f6rvaltningen",
    "department": null
  },
  ...
]

Get a Single Employee

Get the record for a single employee by the unique :id or the :catalog_id that is an unique identifier within the organization's systems.

GET /api/v1/employees/:id
GET /api/v1/employees/:catalog_id

Example requests:

GET /api/v1/employees/111
GET /api/v1/employees/magiva

Response:

HTTP/1.1 200 OK

{
  "catalog_id": "magiva",
  "id": 111,
  "first_name": "Jesper",
  "last_name": "Bylund",
  "title": "Enhetschef",
  "email": "[email protected]",
  "phone": "040-342091",
  "cell_phone": null,
  "company": "102 Stadskontoret",
  "department": null,
  "room": "2413",
  "address": "Krangatan 4",
  "zip_code": "211 24",
  "postal_town": "Malmö",
  "geo_position_x": 119890,
  "geo_position_y": 6165766,
  "created_at": "2012-05-02T11:44:16.000+02:00",
  "updated_at": "2015-04-22T09:59:55.000+02:00",
  "roles": ["Stadskontoret", "IT", "Kommunikationsarbete", "Chef", "IT Malmö stad"],
  "skills": ["responsiv design", "webb", "webbutveckling", "malmo.se", "Intranät", "Komin", "CSS", "CSS3", "media queries", "HTML5", "applikationer", "externwebb", "medborgarservice", "Digitala staden", "Digitala arbetsplatsen", "Digitala infrastrukturen"],
  "languages": ["engelska"],
  "contact_card": "https://minsida.malmo.se/users/magiva",
  "avatars": {
    "xlarge": "//profilbilder.malmo.se/magiva/xlarge.jpg",
    "large": "//profilbilder.malmo.se/magiva/large.jpg",
    "large_quadrat": "//profilbilder.malmo.se/magiva/large_quadrat.jpg",
    "medium": "//profilbilder.malmo.se/magiva/medium.jpg",
    "medium_quadrat": "//profilbilder.malmo.se/magiva/medium_quadrat.jpg",
    "small": "//profilbilder.malmo.se/magiva/small.jpg",
    "small_quadrat": "//profilbilder.malmo.se/magiva/small_quadrat.jpg",
    "thumb_quadrat": "//profilbilder.malmo.se/magiva/thumb_quadrat.jpg",
    "tiny_quadrat": "//profilbilder.malmo.se/magiva/tiny_quadrat.jpg",
    "mini_quadrat": "//profilbilder.malmo.se/magiva/mini_quadrat.jpg"
  }
}

Profile Pictures for Employees

To get profile pictures for an employee, use the employee's :catalog_id as documented in the Avatar Service API.

Search Group Contacts

Case insensitive search where the value of the q parameter is matching the start of the name field.

Example request:

GET /api/v1/group_contacts/search?q=Individ-%20&%20familjeomsorgen

Response:

HTTP/1.1 200 OK

[
  {
    "id": 16,
    "name": "Individ- & familjeomsorgen Centrum"
  },
  {
    "id": 23,
    "name": "Individ- & familjeomsorgen Roseng\u00e5rd"
  },
  ...
]

Get a Single Group Contact

Get the record for a single contact by the unique :id you get from the group contact search.

GET /api/v1/group_contacts/:id

Example request:

GET /api/v1/group_contacts/23

Response:

HTTP/1.1 200 OK

{
  "id": 23,
  "name": "Individ- & familjeomsorgen Roseng\u00e5rd",
  "email": "[email protected]",
  "phone": "040-34 33 69",
  "phone_hours": "M\u00e5n\u2013Tor: 08.00\u201316.00, lunchst\u00e4ngt 11.45\u201313.00. Fre 08.00\u201315.00 Lunchst\u00e4ngt 11.45\u201313.00",
  "cell_phone": "",
  "fax": "",
  "address": "",
  "zip_code": "",
  "postal_town": "",
  "visiting": {
    "address": "von Troils v\u00e4g 8A",
    "zip_code": "213 73",
    "postal_town": "Malm\u00f6",
    "district": "\u00d6ster",
    "geo_position": {
      "x": "121638",
      "y": "6162531"
    },
    "hours": "M\u00e5n\u2013Tor 08.30\u201315.30, lunchst\u00e4ngt 11.45\u201313.00, Fre 08.30\u201315.00, lunchst\u00e4ngt 11.45\u201313.00",
  },
  "homepage": "",
  "created_at": "2013-11-01T15:41:52+01:00",
  "updated_at": "2013-11-05T13:59:56+01:00",
  "legacy_dn": "cn=Individ- & familjeomsorgen Roseng\u00e5rd, ou=Funktionskonton, ou=Organisation och funktion, ou=Sitevision, o=malmo"
}

The geo_position coordinates are using the SWEREF991330 standard.

Pagination

Search requests will return 25 items by default. You can control this with the per_page parameter. 100 items is the maximum. Use the 1-based page parameter to access more pages.

This request will return items 51–100 for the given query:

GET /api/v1/employees/search?q=sven&per_page=50&page=2
Clone this wiki locally