Interface specification

OcdsApi

Methods for retrieving notices in OCDS compliant data formats.

APIDescription
GET Published/Notices/OCDS/Search?publishedFrom={publishedFrom}&publishedTo={publishedTo}&stages={stages}&limit={limit}&cursor={cursor}

Search for published notice OCDS releases package with optional search criteria.

GET Published/OCDS/Record/{ocid}

Retrieves the OCDS record package from a provided ocid.

GET Published/OCDS/Release/{id}

Retrieves the OCDS release package from a provided id.

GET Harvester/Notices/Data/CSV/Daily

Retrieves the OCDS releases in CSV format for the current date.

GET Harvester/Notices/Data/CSV/{year}/{month}/{day}

Retrieves the OCDS releases in CSV format from a specific date.

PostcodeApi

Methods related to postal codes.

APIDescription
GET Postcode/Postcodes/{postCode}

Retrieves a list of valid UK postcodes that start with the provided prefix.

UserProfileApi

Methods for creating, updating and deleting user profile information.

APIDescription
GET User/MyProfile

Get the profile details for the signed in user, contained in a User object.

POST User/MyProfile/Save

Update the profile details for the signed in user.

GET User/MyProfile/SavedSearch/GetAll

Gets details of the saved searches associated with the signed in user. Returns a collection of SavedSearch objects, each representing a saved search.

GET User/MyProfile/SavedSearch/Get?id={id}

Gets details of a saved search by its unique identifier. The requested information must be associated with the signed in user. Returns the requested SavedSearch object.

POST User/MyProfile/SavedSearch/Update

Updates an existing saved search associated with the signed in user.

POST User/MyProfile/SavedSearch/Delete

Deletes a number of saved searches associated with the signed in users. The saved searches to be deleted are identified by a collection of integers, each being the id of a saved search associated with the user.

POST User/MyProfile/SavedSearch/Create

Creates a new saved search for the signed in user.

GET User/MyProfile/WatchedNotice/GetAll

Gets details of all the watched notices for the signed in user, contained in a collection of WatchedNotice objects.

GET User/MyProfile/WatchedNotice/Get?id={id}

Gets details of the watched notices with the given identifier. The requested watched notice must be associated with the signed in user.

POST User/MyProfile/WatchedNotice/Create

Creates a new watched notice for the signed in user.

POST User/MyProfile/WatchedNotice/Update

Updates an existing watched notice associated with the signed in user.

POST User/MyProfile/WatchedNotice/Delete

Deletes a number of watched notices associated with the signed in user. The watched notices to be deleted are identified by a collection of integers, each being the id of a watched notice associated with the user.

PublishNoticeApi

Methods for managing published notices.

APIDescription
GET Published/AdditionalDetails/{id}

Gets a single additional detail object by its unique identifier. The identifier is a GUID. The returned additional detail is contained in a AdditionalDetail object.

Version 2 = GET api/rest/2/get_published_notice/{MimeType}/{id}

Version 1 = GET Published/Notice/{id}

Gets a published notice by its unique identifier, which is a GUID. The returned notice is described by a FullNotice xml object.

GET Published/Notice/OCDS/{id}

Gets the OCDS for the provided notice identity.

POST Published/Notices

Gets a collection of published for the provided list of identities.

POST Published/Notice/Withdraw

Withdraws the published notice identified by the provided identifier. A reason needs to be provided and is recorded against the withdrawal action.

POST Published/Notice/Withdraw/2

Withdraws the published notice identified by the provided identifier. A reason needs to be provided and is recorded against the withdrawal action (version:2).

GET Published/CpvCodes/{id}

Gets a collection of CPV codes associated with the identified notice. The provided id should be a GUID that uniquely identifies a published notice.

GET Published/LogNoticeView/{id}

Log a view event for the published notice with the given identity.

GET Published/NoticeVersions/{id}

Gets historical version details for the published notice identified by the provided id.

NoticeApi

Methods for managing draft notices.

APIDescription
GET Draft/FindNoticesForUser?noticeType={noticeType}&noticeStatus={noticeStatus}&filter={filter}&page={page}&numberPerPage={numberPerPage}&showMyNoticesOnly={showMyNoticesOnly}

Returns details of the notices that match the specified search criteria. Only notices associated with the organization of the current user are included. The current user must be a buyer in order to use this service.

Version 2 = GET api/rest/2/get_draft_notice/{MimeType}/{id}

Version 1 = GET Draft/Notice/{id}

Gets the draft notice identified by the provided GUID.

POST Draft/Notices

Gets a collection of draft for the provided list of identities.

Version 2 = POST api/rest/2/create_draft_notice/{MimeType}

Version 1 = POST Draft/Notice/Add?isPreAwarded={isPreAwarded}

This operation is used to upload an individual notice. The payload consists of a single notice definition, configured to be an Early Engagement, a Future Opportunity, or a Live Opportunity.

POST Draft/Notice/Copy

This operation will create a copy of an identified notice using the provided new notice identifier. The notice being copied is identified by the internally assigned GUID. The provided identifier should be the user-defined notice id, which cannot be the same as an existing notice - a new GUID will be assigned and returned to the caller.

POST Draft/Notice/CopyAwarded

This operation will create a copy of an identified awarded notice using the provided new notice identifier and the new type. The notice being copied is identified by the internally assigned GUID. The provided identifier should be the user-defined notice id, which cannot be the same as an existing notice - a new GUID will be assigned and returned to the caller.

POST Draft/Notice/Convert

Converts an existing future opportunity into a current opportunity.

POST Draft/Notice/Update

This operation allows an existing notice to be updated. A Notice object is provided including the notice id and its new state. The provided details will replace those currently stored.

Version 2 = POST api/rest/2/publish_draft_notice/{MimeType}

Version 1 = POST Draft/Notice/Publish

This operation allows an existing notice to be published. This will make the current state of the notice visible to the public through the Contracts Finder online service. The publish request may include comments that are recorded against the publish action. If the VisibleToPublic flag is false, notifications will be suppressed to anybody watching this notice - this is only appropriate for minor modifications to existing notices.

POST Draft/Notice/Validate

This operation is used to simply validate the notice. This is used when validation has already failed after a user has attempted to publish the notice. Needed because we refresh the page if validation fails - losing the error messages.

POST Draft/AdditionalDetail/Add

This operation is to be used to upload additional information relating to a single notice. The payload consists of a single additional detail definition. The operation requires the identity of a previously created notice, with which the additional detail data will be associated. This requires the caller to have access to the GUID identifying the notice, which could be obtained using Draft/Notices/Lookup.

GET Draft/AdditionalDetails/{id}

Gets a collection of AdditionalDetail objects associated with the specified notice. The notice is identified by its GUID.

POST Draft/AdditionalDetail/Update

This operation allows an individual additional detail to be updated. The provided AdditionalDetail object identifies the additional detail and describes its updated state.

POST Draft/AdditionalDetail/Set

This operation allows multiple additional details to be added or updated. The provided AdditionalDetails object contains all the new and updated AdditionalDetail objects.

POST Draft/Notice/Delete

This operation allows a draft notice to be deleted, as identified by the provided GUID. A draft notice cannot be deleted once it has been published. To remove a published notice from the Contracts Finder online service, use the Published/Notice/Withdraw operation.

POST Draft/AdditionalDetail/Delete

This operation allows an additional detail to be deleted, as identified by the provided GUID.

GET Draft/AdditionalDetail/Attachment/{id}

Get an attachment given its id. The return is an AdditionalDetail object containing all of the information necessary to create the file attachment.

Version 2 = GET api/rest/2/get_draft_awards/{MimeType}/{id}

Version 1 = GET Draft/Awards/{id}

Gets all award details for the specified notice. This method will return multiple items if present. Multiple award details identify multiple suppliers associated with a single award.

Version 2 = POST api/rest/2/add_draft_award/{MimeType}

Version 1 = POST Draft/Award/Add

This operation is used to award a single notice. The payload consists of a single award definition. The operation requires the identity of a previously created notice with which the award data will be associated. The caller needs to have access to the GUID identifying the notice - which could be obtained using Draft/Notices/Lookup.

Version 2 = POST api/rest/2/update_draft_award/{MimeType}

Version 1 = POST Draft/Award/Update

This method allows the award details for a notice to be updated. The provided AwardDetail should identify the notice associated with the award and contain its updated state.

POST Draft/Award/SetNoticeAwards

This method allows multiple award details for a notice to be updated. The provided AwardDetails should identify the notice associated with the awards and contain the updated state.

Version 2 = POST api/rest/2/import_draft_notices/{MimeType}

Version 1 = POST Draft/Notices/Import

This operation is to be used to upload multiple notices, including award information and additional data where relevant. Note that the operation may be used to upload notices with award information, but cannot be used to add award details to already existing notices. Similarly, uploaded notices may include additional data, but additional cannot be added to already existing notices. This is because the awarded and additional detail information supplied in the import is implicitly associated with an imported notice and there is no means to select a previously imported notice. Where a notice is awarded to multiple suppliers, this is indicated by providing multiple AwardDetail items. Note that only supplier-specific information should vary between AwardDetail items - award-level information will be set by the first item only: i.e. Value, Start Date, End Date, Awarded Date, Procedure Type.

POST Draft/Notices/ImportFlat

This operation provides the same functionality as Draft/Notices/Import. However, the input format for this variant is simpler in structure, but is more restrictive.

GET Draft/Notices/Lookup/{identifier}

This operation is used to return the internal system ID for the specified notice(s). The notice of interest is indicated by passing in the user-defined unique identifier. (The user-defined identifier is specified by a user at creation, for example through the Contracts Finder online service). All notices that have an identifier beginning with the supplied text are returned. A collection of details are returned for the notices matching the seach criterion.

GET Draft/Notices/Statistics

Get basic statistics for signed in user's organisation notices.

CountryApi

Methods for retrieving country data.

APIDescription
GET Country/Countries

Gets country data relevant to the Contracts Finder system.

CpvCodeApi

Methods for retrieving CPV Codes information.

APIDescription
GET CpvCodes/Children/{requestCode}

Gets a collection of CPVCode objects where the parent code matches the supplied CPV code.

GET CpvCodes/Parents/{requestCode}

Returns any CPVCode object that is a parent of the supplied request code.

GET CpvCodes/Sectors

Gets a collection of the root CPVCode objects. These are the "sector" codes, beneath which all other CPV codes are arranged.

GET CpvCodes/Codes/{codes}

Gets a collection of CPVCode objects according to the provided, comma-separated list of CPV codes.

GET CpvCodes/Search/{identifier}

Gets a collection of CPVCode objects based on the supplied identifier. If the identifier is numeric then the lookup will match against the CPV code, otherwise it will match against the CPV description.

SearchApi

Methods to support searching the Contracts Finder notices.

APIDescription
Version 2 = POST api/rest/2/search_notices/{MimeType}

Version 1 = POST Searches/Search

Searches for notices based on the provided search criteria.

RegionApi

Methods related to region data.

APIDescription
GET Region/Regions

Gets all Region data relevant to the Contracts Finder system.

Authorisation

Authorisation is based on the OAuth 2.0 client credentials grant .

APIDescription
POST token

OAuth token end point