API documentation

Making an API request

To call one of the Hankintarekisteri API methods make an HTTP GET call to https://api.hankintarekisteri.fi. An API-key must be provided in the request x-api-key header. An unique API-key can be obtained by email from info@hankintarekisteri.fi.

An example request for searching organizations could be:

curl -X GET "https://api.hankintarekisteri.fi/organizations?limit=1&organization=hankintarekisteri" -H "x-api-key: k99W2xhfdtXhyCjdbJ5vJKKWLHdd4UhZvG22UHxG"

Which would result in the following response:

{
  "success": true,
  "message": "Found 1 organizations",
  "query": {
      "order": "name",
      "direction": "asc",
      "limit": 1,
      "include": [],
      "service": null,
      "area": null,
      "organization": "hankintarekisteri"
  },
  "organizations": [
    {
      "id": "123e4567-e89b-12d3-a456-426655440000",
      "name": "Hankintarekisteri",
      "businessType": "contractor",
      "businessIdCode": "2814195-6",
      "description": "Hankintarekisteri on Suomen Hankintarekisterin tuottama ja ylläpitämä verkkopalvelu, jonka tavoitteena on tarjota rakennusalan jokaiselle toimijalle kustannustehokas ja keskitetty palvelu eri sidosryhmien väliseen vuorovaikutukseen",
      "logoUrl": "https://cdn.hankintarekisteri.fi/images/logo-brand-warning-dark.png",
      "revenue": "123",
      "personnelAmount": 123,
      "revenueClass": 0,
      "personnelAmountClass": 0,
      "rating": 123,
      "canUseSubcontracting": true,
      "externalUrl": "https://hankintarekisteri.fi"
      "stvStatus": "Ok",
      "stvStatusDescription": "Tietolähteiden perusteella yritys on hoitanut tilaajavastuulain edellyttämät velvoitteet.",
      "stvStatusUpdatedAt: "2018-09-23T01:11:34.505Z"
    }
  ]
}

API method reference

Method: GET /organizations

The method will provide a list or organizations matching the provided search parameters

Parameters

limit (int): If provided the maximum amount of returned organizations will be equal to the provided limit. Limited to 1000
order (string): Orders the results in the requested order. Valid values are: name, createdAt, updatedAt, businessIdCode, revenueClass, personnelAmountClass, rating. Defaults to ‘name’.
direction (string): Order results in ascending or descending order. Valid values are: asc and desc. Defaults to ‘asc’
area: (string): Search organizations by area name (e.g. Helsinki).
service (uuid): Search organizations by service id.
organization (string): Search organizations by organization name.

Response properties

id (uuid): Unique id for the organization
name (string): Organization name
businessType (string): Type of the organization (contractor, materialSupplier, consultant)
businessIdCode (string): Business id
description (string): Description for the organization
logoUrl (string): Url for the organization logo
revenue (string): Latest revenue for the organization
personnelAmount (int): Amount of personnel in the organization
revenueClass (int): A class description of the revenue amount
personnelAmountClass (int): A class description of the personnel amount
rating (int): Numerical rating calculated for the organization
canUseSubcontracting (boolean): Depicts if the organization is able to use subcontracting
externalUrl (string): A related external url, e.g. a homepage
stvStatus (string): Status of the Suomen Tilaajavastuu Oy report
stvStatusDescription (string): A description for stvStatus
stvStatusUpdatedAt (date): Date when the stvStatus was last updated


Method: GET /contracts (requires a paid plan)

The method will provide a list or contracts matching the provided search parameters

Parameters

limit (int): If provided the maximum amount of returned organizations will be equal to the provided limit. Limited to 1000
order (string): Orders the results in the requested order. Valid values are: name, createdAt, updatedAt. Defaults to ‘createdAt’.
direction (string): Order results in ascending or descending order. Valid values are: asc and desc. Defaults to ‘desc’.
area: (string): Search contracts by area name (e.g. Helsinki).
service (uuid): Search contracts by service id.

Response properties

id (uuid): Unique id for the contract
type (string): Value is ‘hilma’ if the contract is synced from Hilma, otherwise ‘userCreated’
offersDueDate (string): Last date to submit offers for the contract
name (string): Name or title for the contract
description (string): Main description for the contract
additionalDescription (string): Additional info for the contract
value (string): Monetary value for the contract
startDate (date): Estimated date when the contract starts
endDate (date): Estimated date when the contract ends
contractorLiabilityCheckRequired (boolean): Contract requires the contractor to have a liability check done before the contract begins
revenueRequirementMin (string): Minimum revenue requirement for the contractor
revenueRequirementMax (string): Maximum revenue requirement for the contractor
personnelAmountRequirementMin (string): Minimum personnel amount requirement for the contractor
personnelAmountRequirementMax (string): Maximum personnel amount requirement for the contractor
ratingRequirement (int): Minimum rating requirement in Hankintarekisteri for the contractor
streetAddress (string): Steet address of the contract execution site
postalCode (string): Postal code of the contract execution site
postOffice (string): Post office of the contract execution site
contactPersonName (string): Name of the contract’s contact person
contactPersonPhone (string): Phone number of the contract’s contact person
contactPersonEmail (string): Email of the contract’s contact person
options (string): Additional options regarding the contract execution
externalUrl (string): An external url for additional info about the contract
participationUrl (string): An external url for submitting an offer to the contract
createdAt (date): Date when the contract was submitted
updatedAt (date): Date when the contract was last modified
project.id (uuid): Unique identifier for the contract’s project
project.name (string): Name of the contract’s project
project.projectCode (string): A reference code for the contract’s project
project.description (string): Description for the project
organization.id (uuid): Unique identifier for the submitting organization
organization.name (string): Name of the submitting organization
organization.businessIdCode (string): Business id of the submitting organization


Method: GET /services

The method will provide a list of all services in the system. A service is a category which depicts the services which an organization will provide or a contract can require. A service id can be used as a parameter when searching organizations and contracts.

Parameters

No available parameters

Response properties

id (uuid): Unique id for the service
name (string): Name of the service
description (string): Description for the meaning and content of the service
parentId (uuid): An unique identifier for the parent service. Null if a top level service