Help Page Home

Contracts Finder API - Version 2 Release Notes

Introduction

The Contracts Finder API service is updating. We are releasing new versions of some of the API methods.

The Version 2 of these API methods support new policy and features. These include:

  • Supply chain notices
  • Early engagement closing date
  • Supplier references
  • Supplier awarded value
  • SME/VSCE flags
  • Procedure Types

They also attempt to improve the structure of the data and standardise approaches to aid the user in posting and retrieving notices.

Whilst we are still supporting Version 1 methods for the foreseeable future to provide backwards compatibility, they should be considered deprecated and we encourage the uptake of the Version 2 methods and features.

1. Version 2

1.1 Methods

Please note, the Contracts Finder API still supports JSON. JSON requests are achieved by altering the URL from /xml to /json. Examples are given in both formats.

We have made it clear in the documentation where there the Version 2 methods are available. They are:

1.2 Other improvements

The improvements in these methods are as follows:

  • In order to standardise and improve notice structure across methods, the NoticeImport object is replaced with the standard Notice object.
  • The IsPreAwarded URI parameter has been removed for Version 2 of the Create draft notice method api/rest/2/create_draft_notice/{MimeType} as now the adding of awards with api/rest/2/add_draft_award/{MimeType} will determine whether the notice has been awarded.
  • Stricter validation moved to the point of adding/editing draft notices in Version 2 instead of publishing notices.

2. New features in Version 2

A number of features have been added for Version 2 of the API.

2.1 Supply chain notices

Version 2 now has the ability to POST supply chain notices via:

To use this feature, the API user is to POST along with current parameters a SupplyChain boolean flag parameter in the Notice object.

This parameter is not mandatory, and if not passed will default to false.

If the SupplyChain parameter is set to true, and the API user has the permissions to post a supply chain notice, the notice posted will be a supply chain notice as opposed to a public notice. If the user does not have permissions to post supply chain notices then an error will be returned when the value is set to true.

2.2 Early engagement closing date

In Version 1 methods a closing date for Early Engagement notices is ignored.

Version 2 methods now support a mandatory requirement to set a closing date for early engagement notices in the following methods:

In order to reduce the number of Version 1 open early engagement opportunities that are out of date, Contracts Finder automatically sets a closing date that is 3 months after the publication date.

2.3 Supplier references

Version 2 now affords the user the ability to add a reference type and reference number to a supplier when awarding a notice. A ReferenceType object, a reference id (Reference) can now be passed in Version 2 of the AwardDetail object in following methods:

An example of this reference type and number could be a Companies House number 04854362. For this example, a parameter of ReferenceType must be added with the value of COMPANIES_HOUSE and a Reference parameter of 04854362.

The ReferenceType and Reference parameters are not mandatory and will default to NONE if not provided.

This functionality is to provide a richer data set for suppliers within Contracts Finder.

2.4 Supplier awarded value

Version 2 now has the ability to set the value of a contract in GBP for the individual supplier when awarding the notice. The supplier awarded value, SupplierAwardedValue can be passed in Version 2 of the AwardDetail object provided in the following services:

For example, providing the supplier awarded value as 100.2 will put the contract value to £100.20 for that individual supplier.

The supplier awarded value is not mandatory and will default to NULL if not provided.

This functionality is to provide greater transparency around awarded contracts.

2.5 SME/VSCE flags

In order to help Buyers identify contracts that are suitable for SME and VSCE suppliers in Early Engagement notices, we now make use of the IsSuitableFor... flag for EE notices; for SME (IsSuitableForSme) or a VCSE (IsSuitableForVco) within the following methods:

In Version 2, these flags are now mandatory for all notice types. In Version 1 this flag is ignored for Early Engagement notices, and they default to No for Future Opportunity and Opportunity notices where they were Null.

In order to show which notices ended up being awarded to SME or VSCE suppliers we are adding another, non-mandatory flag: for SME (AwardedToSme) or a VCSE (AwardedToVcse) which can be passed in both Version 1 and 2 of the AwardDetail object:

For some time we have supported these in Version 1 including the ability to search against notices suitable for SME (SuitableForSme) and VCSE (SuitableForVco) within the following methods:

Version 2 now has the added ability to filter search results based on the awarded to flag with the SME (AwardedToSME) and VCSE (AwardedToVCSE) parameters within the following method:

For example, providing a value of true to the parameter AwardedToSME will return search results of notices that have been awarded to at least one SME supplier. If you provide a value of true to both parameters, the search results will contain notices awarded to either at least one SME or at least one VCSE.

Note: VCO, VCSO and VCSE are all variants of the name for Voluntary, Community and Social Enterprise which have changed over time.

2.6 Procedure Types

There are new procedure types to use that are supported in both Version 1 and 2. All procedure types are still supported but we would encourage you to adopt the new ones. You can see the list of procedure types here.

When the procedure type is accelerated, you also should supply a justification for why it is being accelerated with the ProcedureAcceleratedJustification parameter although it is not mandatory.