Fire API

Overview

Fire (FImnet REgistry) is the Fimnet database containing information about the users. Fire API is a REST/JSON API with OAuth 2 authentication. 

Any REST client will work with this API. If you're using PHP, we provide a class:  FireApiClient

Authentication

The API uses OAuth2. In order to use it, you need an Access Token ("Bearer Token" in OAuth2 terminology). The Access Token can be of 2 types:

  • "User": You receive a User Access Token when using Fimnet Login. The token only gives access to the user who signed in, and his valid for the duration of the Fimnet session only.
  • "App": An Application Access Token gives access to all users managed by the application and is valid for a much longer period of time. It can be used for example in batch scripts to update your users while they are offline. It is provided by us only for the applications that needs it.

 

Global options

Selecting the fields returned

The default behavior of the API is to return every available fields. Use the fields parameter to limit the fields returned. Multiple fields must be coma separated.

Example: This request will only return id and first name

    GET /users?fields=id,first_name

Unless noted otherwise, you can select any field that appears in the default resultset.

Sorting

Use sort parameter to sort the result set by field value.

Example: This request will sort by first name

    GET /users?sort=first_name

Default order is ascending To use descending order, prepend a minus before the name of the field.

Example:

    GET /users?sort=-first_name

To sort by multiple fields, separate them with coma.

Example:

    GET /users?sort=created_at,-first_name

Unless noted otherwise, you can sort by any field that appears in the resultset.

Pagination

By default, the API will limit to 100 results at the time. To navigate from page to page, use page parameter. To control the number of results per page, use per_page.

Example:

    GET /users?per_page=25&page=2

Unless noted otherwise, the maximum number of result per page is 200.

Pagination metadata is returned along with the data. For example:

    { "page":1, "per_page":100, "total":61658, "nb_pages":617, "data":[ ... ] }

If needed you can enable/disable metadata with pagination_meta=0 or pagination_meta=1.

API methods for which the number of results is expected to always be under 100 usually have pagination metadata turned off by default (e.g. list of subusers of a user). When the number of expected is expected to always be over 100 pagination metadata is turned on by default (e.g. list of users).

Embedding resources

It is possible to request the API to include sub-resources in the resultset with the embed parameter. For example, let’s say you want to query a list of users and their details. Instead of making multiple API calls, you could do the following:

    GET /users/?embed=details

The resultset would look like:

    [ { "id":"1", 
        "fimnet_id":"test-1", 
        "first_name":"Test", 
        "last_name":"Test", 
        "nickname":"", 
        "company":"", 
        "language":"fi",
        "fimnet_email":"test@fimnet.fi", 
        "updated_at":"2014-02-13 14:00:58", 
        "details":{ "job_title":"", "website":"" } }, 
    ... ]

HTTP Return Codes

Here are the HTTP Status codes used by the API, and the most common possible causes.

  • 200 (Success) - All is good
  • 400 (Bad Request) - Your request is malformed and cannot be understood by the server
  • 403 (Forbidden) -  The Access Token is invalid or doesn't give you access to this method
  • 404 (Not Found) - You're requesting a resource that does not exists or  your Access Token doesn't give you acess to this particular user
  • 422 (Unprocessable Entity) - The data you sent when trying to create or update a ressource are invalid (e.g. required parameter is missing, or as invalid format, etc.). See below "Api Validation Errors".
  • 500 (Internal Server Error) - Something went terribly wrong! Please contact us to report the bug.

Api Validation Errors

When creating or updating a resource, the API will validate your data. If the data are not valid, it will returns a HTTP 422 Unprocessable Entity code. The body on the response will be a JSON object like this:

    { "success":false, 
      "message":"Validation failed. See \"errors\" fields for details", 
      "errors":{   "first_name":{"max_length":100},
      "email":{"required":true}  } 
    }

The errors field contains the list of fields that are not valid. For each field, it returns the list of validators that fails

Default validators

Key (name of the validator) Value (value of the validator) Description
required N/A A required field is missing.
max_length integer The field exceed the maximum length given in value.
min_length integer  
email N/A The field must be an email
bool N/A  
date    
time    
numeric    
max_value    
min_value    
enum array The value must be part of the array of possible values
enum_keys assoc array The value must be a key of the array of possible values

Debug endpoints

Get API Version

    GET /version

Returns the current version of the API.

Get client information

    GET /whoami

Returns information about the token being used.

  • Type can base “user” or “app”

Example

    { "type":"user", 
      "client":{"client_id":"sll","name":"Suomen Lääkäriliitto"}, 
      "user":{"id":"60346","fimnet_id":"abc-1"} 
    }

Users

Fields (for reference only, might be incomplete)

Name Type Description
id Int Fire ID
fimnet_id string Fimnet ID
slug string URL Slug
first_name string First name with other first names (if any)
nickname string Shorter version of the first name. Should be displayed instead of first name if present.
last_name string Last name
company string Company name. Might or might not be empty when account_type is “individual”.
full_name string

Use for filtering and sorting only.
Contains “last_name, first_name” when account_type is “individual” and “company” when account_type is “company”.
account_type enum If account_type is “company”, then company name should be displayed instead of the name
fimnet_email   Fimnet-email address (not to be used)
secondary_email   Users email address (Use this address instead of fimnet_email)
language   ‘fi’ or ‘sv’
phone_number   Phone number

Searching users

    GET /users

Filtering options

The following fields can be used for filtering/search.

id  
fimnet_id  
fimnet_email  
main_user_id  
main_group_code  
external_id = “ulkop_tunniste” - Should be used in combination with main_group_code.
doctor_id Doctor identification number
full_name You can use the “%” wildcard character
city You can use the “%” wildcard character
q

Special parameter to make a search in full_name and city fields at once. For example:

GET /users?q=Markku%20Helsinki

will search for people whose name or city match “Markku” and name or city match “Helsinki”.

Note: “%” are automatically added, you don’t need to do it.

 

You can add “search_mode=extended” parameter to extend the search to fimnet_id, fimnet_email and full address (including street and postcode)
visibility “public” or “private”
include_deleted Use include_deleted=1 to include deleted users in the search. Caution: deleted users cannot be used in other endpoints.

Embedding

details
address
groups
privacy_settings
email_settings
ftp_settings

 

Creating a new user

POST /users

Parameters

Name Type Description
account_type enum Optional. “individual” or “company”. Default is “individual”.
first_name string Required if account type is “individual”.
nickname string Optional. If not provided, first_name will be used (if account type is “individual”)
last_name string Required if account type is “individual”.
company string Required if account type is “company”.
main_group_code string Required. The membership code.
external_id int Optional. The ID number from the union.
doctor_id int Optional. The doctor identification number.
password string Optional. The clear text password. If not provided, a random password will be generated and returned.
language enum Optional. ‘fi’ or ‘sv’. Default is “fi”.
secondary_email string Optional.
phone_number string Optional.
address array Accept the same fields at the /users/<id>/address endpoint (see below).
details array Accept the same fields at the /users/<id>/details endpoint (see below).
accept_tos bool Post 0/false to refuse Terms of Service, or 1/true to accept. The date will be recorded.
visibility enum Optional. “public” or “private”. Default is “public”.

Updating sub-ressources

It’s possible to update user details and user address at the same time, by including them in the array. For example, using the PHP API:

    $client->put(
         "/users/$id", 
         array( 'language' => 'en', 
                'address' => array( 'street' => 'Test street' ), 
                'details' => array( 'facebook_url' => 'Test FB Url' ) 
                )
                );

Returns

This methods will return a user object with the following fields populated:

  • fimnet_id

  • slug

  • full_name

  • password (only if none has been provided)

 

Updating a user

PUT /users/<id>

You don’t have to provide the “required” field if they already exists.

Name Type Description
account_type enum Optional. “individual” or “company”. Default is “individual”.
first_name string Required if account type is “individual”.
nickname string Optional, but if you update the first_name you should provide it!
last_name string Required if account type is “individual”.
company string Required if account type is “company”.
main_group_code string Required. The membership code.
external_id int Optional. The ID number from the union.
doctor_id int Optional. The doctor identification number.
language enum  
secondary_email string  
phone_number string  
accept_tos bool Post 0/false to refuse Terms of Service, or 1/true to accept. The date will be recorded.
visibility enum Optional. “public” or “private”. Default is “public”.
address array Accept the same fields at the /users/<id>/address endpoint (see below).
details array Accept the same fields at the /users/<id>/details endpoint (see below).

Updating sub-ressources

It’s possible to update user details and user address at the same time, by including them in the array, same as the POST endpoint.

Disabling an existing user

    DELETE /users/<id>

This method flag the user for future deletion. The user account is not deleted right away. The user will still be able to signin, change his settings and read his emails. However, he will be locked out from certain applications.

After a certain time, disabled user will be deleted.

When a user is disabled, API calls that returns groups will return empty arrays.

Re-enabling a user

    POST /users/<id>

This method reenables a user.

 

User groups

Getting user groups

    GET /users/<id>/groups

Returns an array

Return

    Array( ‘union’ => Array(...) ‘subservice’ => Array(...) ‘specialty’ => Array(...) )

Note: if the user is disabled, this method will return empty arrays.

Setting user groups

    POST /users/<id>/groups

This method will return 400 Bad Request if called for a disabled user. It’s not possible to update groups of a disabled user.

Parameters

For admin API clients:

Name Type Comment
union Array

A list of groups of type “union”. If empty, all groups of type “union” will be deleted. If not set, groups of type “union” will be left unchanged.
subservice Array Same for type “subservice”.
specialty Array Same for type “specialty”.

For normal (unions) API clients:

Name Type Comment
groups Array

A list of groups of type “union”. If empty, all groups of type “union” will be deleted. If not set, groups of type “union” will be left unchanged.
     
     

Example with curl:

    curl -X POST "http://..." -d "groups[]=X&groups[]=Y"

Returns

This method returns the updated list of groups on success.

Synchronisation trigger

This is a special endpoint that will cause the API to synchronize a particular user with it’s union database.

    POST /users/<id>/sync

Returns

    {“success”:true, “data”: {USER}}

Workflow 1: when union database has a read API, but not support for trigger

  Browser                  Frontend           API            Union
     |                         |               |               |
     |-- Update user info ---->|               |               |
     |<--- redirect to union --|               |               |
     |                         |               |               |
     |------------- Update user info ------------------------->|
     |<---------------------------- redirect after post--------|
     |                         |               |               |
     |-- get user info ------->|               |               |
     |                         |- POST /sync ->|               |
     |                         |               |--GET data---->|
     |                         |               |<--------------|
     |                         |<-return info--|               |
     |<------------------------|               |               |

 

Workflow 2: when union database supports trigger

  Browser                  Frontend           API           Union
     |                         |               |               |
     |-- Update user info ---->|               |               |
     |<--- redirect to union --|               |               |
     |                         |               |               |
     |------------- Update user info ------------------------->|
     |                         |               |<- POST /sync -|
     |                         |               |--GET data---->|
     |                         |               |<--------------|
     |<---------------------------- redirect after post--------|
     |                         |               |               |
     |-- get user info ------->|               |               |
     |<------------------------|               |               |

Other endpoints

 

Groups

    GET /groups

Languages translation

    GET /languages

The values won’t change very often, so you should cache the result for a very long time. You should not call this method all the time.

Query parameters

in_language

Valid values: ‘fi’, ‘en’, ‘sv’

Default: ‘fi’

Select in which language the languages names must be returned.

Country names translation & country codes

    GET /countries

The values won’t change very often, so you should cache the result for a very long time. You should not call this method all the time.

Query parameters

in_language

Valid values: ‘fi’, ‘en’, ‘sv’

Default: ‘fi’

Select in which language the country names must be returned.

Fimnet tunnistusasiakkaan ohjesivusto

Satunnainen terveystarkastaja