API Technical Documentation
Introduction
The Business Intelligence API is designed to allow querying of notice, awards and spend data. This document will guide you on how to create your API key, how to authenticate with the API, and how to then use this authentication token to fetch data.
Sandbox
A sandbox environment has been created that allows you to test out your connections to the service, without using up any of your daily limit of calls to the service. This should be used just to verify that you can successfully generate authentication tokens, and to make calls to the API endpoints and receive successful responses.
Please note, the endpoints in the sandbox are built to return stubbed data. These values are mocked and always return the same regardless of the criteria provided in a request.
When testing against the sandbox, please use the following urls:
Authentication: https://sandbox.oidc.bipintelligence.com/.well-known/openid-configuration
API: https://sandbox.bipintelligence.com/open-api/v3/api-docs
The sandbox does not require you to configure an API client key and secret for your account via the BI Platform site. When using the sandbox, you can skip the “Access Token Setup” section in this guide, and instead use the below common client key and secret to generate authentication tokens:
Key: open-api-sandbox
Secret: open-api-sandbox-secret
API Technical Documentation – Live API
Access Token Setup
Access token setup must be performed by the Primary or Admin user for your organisation’s account in the BI Platform by navigating to the “Open API” page.
In this page, you will initially be presented with an empty table of access tokens, and can create one by selecting “Generate Token”. In this form, you can select which data your access token should be permitted to query, and must also provide a list of IP addresses that are allowed to make calls with this access token. There is no limit on the number of IP addresses that can be entered here.
Selecting “Submit” will then present your API Client ID and Secret. Please take note of these details immediately, as the Secret cannot be viewed again after this, and would require the regeneration of your Access Token.
Successfully generated tokens are then viewable within this page, allowing you edit the IP Addresses and endpoints you wish to allow access to, as well as regenerating tokens before they expire.
Authentication
The API uses the OAuth2 standard for authentication and authorization. Authentication tokens should be created using the ‘client_credentials’ grant type and one or more of the following scopes, which you should have permitted the token to use in the “Open API” management page in the Bi site:
- OPENAPI_NOTICES
- OPENAPI_AWARDS
- OPENAPI_SPEND
Token requests should be made to https://oidc.bipintelligence.com/oauth2/token, eg in unix:
curl --location 'https://oidc.bipintelligence.com/oauth2/token' \ --header 'Content-Type: application/x-www-form-urlencoded' \ --header 'Authorization: Basic <CLIENT_ID:CLIENT_SECRET>' \ --data-urlencode 'grant_type=client_credentials' \ --data-urlencode 'scope=OPENAPI_NOTICES OPENAPI_AWARDS'
Or in Windows:
curl.exe -L "https://oidc.bipintelligence.com/oauth2/token" ^ -H "Content-Type: application/x-www-form-urlencoded" ^ -u "CLIENT_ID:CLIENT_SECRET" ^ --data-urlencode "grant_type=client_credentials" ^ --data-urlencode "scope=OPENAPI_NOTICES OPENAPI_AWARDS"
You should ensure that <CLIENT_ID>:<CLIENT_SECRET> is encoded in Base 64. This will give a response similar to:
{
"access_token": "Your token here",
"scope": "OPENAPI_AWARDS OPENAPI_NOTICES",
"token_type": "Bearer",
"expires_in": 899
}
The ‘access_token’ value from the above response should then be passed as a Bearer token in any request to the API. Access Tokens are valid for 15 minutes before they need to be regenerated.
API Technical Documentation – API Requests
Open API Spec/Swagger
The full API specification can be found at https://app.bipintelligence.com/open-api/v3/api-docs as well as a Swagger UI at https://app.bipintelligence.com/open-api/swagger-ui/index.html. These can be used for a full reference of the fields that can be used for searching each dataset, and for details on the fields returned. Please note, when using the Swagger UI, the Bearer Authentication token must be set using the steps mentioned in the ‘Authentication’ section above.
Response Codes
There are 3 main types of response codes you should receive when making requests to the API:
- 401, you are unauthorized to call this endpoint (e.g. due to an Expired Access Token, calling from an IP Address not configured for this token)
- 429, you have used up your daily request limit (See ‘Daily Limits’ section below)
- 200, your request was successful, and data was returned.
Daily Limits
Open API Core users are limited to 10 successful API calls per day. In successful calls to the API endpoints, the response will contain the ‘X-Rate-Limit-Remaining’ header detailing how many remaining requests you have.
Endpoints
API URL: https://app.bipintelligence.com/open-api
Notices
- /notices (POST)
This endpoint allows you to search notice data using a given criteria
- /notices/{id} (GET)
This endpoint returns the detailed view of a notice
Awards
- /awards (POST)
This endpoint allows you to search award data using a given criteria
- /awards/{id} (GET)
This endpoint returns the detailed view of an award
Spend
- /spend/buyers (GET)
This endpoint returns a list of buyer names, for which we hold spend data
- /spend/suppliers (GET)
This endpoint returns a list of supplier names, for which we hold spend data
- /spend/transactions (POST)
This endpoint returns transactions for a given buyer/supplier name and a date range.
API Technical Documentation – API Schema
/notices
| Field | Type | Description |
|---|---|---|
| totalResults | Long | Total number of matched results for the performed search |
| results | Object[] | List of the notice summaries |
| results.id | Long | ID of the notice, used to view the full detail |
| results.title | String | Title of the contract |
| results.awardingAuthority | String | Name of the authority which published this notice |
| results.value | Double | Value of the tender notice |
| results.currency | String | Currency of the tender notice |
| results.country | String | Country in which the tender will take place |
| results.publishedDate | String | Date the notice was published (YYYY-MM-DD) |
| results.startDate | String | Date the tender will begin once awarded (YYYY-MM-DD) |
| results.endDate | String | Date the tender will end once awarded (YYYY-MM-DD) |
| results.deadlineDate | String | Deadline date for applications (YYYY-MM-DD) |
/awards
| Field | Type | Description |
|---|---|---|
| totalResults | Long | Total number of matched results for the performed search |
| results | Object[] | List of the award summaries |
| results.id | Long | ID of the award, used to view the full detail |
| results.title | String | Title of the awarded contract |
| results.awardingAuthority | String | Name of the authority which published this award |
| results.suppliers | String[] | List of the suppliers the tender was awarded to |
| results.value | Double | Value of the tender award |
| results.currency | String | Currency of the tender award |
| results.country | String | Country in which the award will take place |
| results.publishedDate | String | Date the award was published (YYYY-MM-DD) |
| results.startDate | String | Date the awarded tender will begin (YYYY-MM-DD) |
| results.endDate | String | Date the awarded tender will end (YYYY-MM-DD) |
/notices/{id}
| Field | Type | Description |
|---|---|---|
| apiContractNoticeDetail | Object | Object holding the notice details |
| apiContractNoticeDetail.id | Long | ID of the notice, used to view the full detail |
| apiContractNoticeDetail.title | String | Title of the contract |
| apiContractNoticeDetail.description | String | Description of the contract |
| apiContractNoticeDetail.location | String | Location of the contract to be performed |
| apiContractNoticeDetail.value | Double | Value of the tender notice |
| apiContractNoticeDetail.publishedDate | String | Date the notice was published (YYYY-MM-DD) |
| apiContractNoticeDetail.cpvCodes | String | CPV Code which apply to this tender notice |
| apiContractNoticeDetail.contact | Object | Primary contact we hold for this tender notice |
| apiContractNoticeDetail.contact.contactName | String | Name of the contact |
| apiContractNoticeDetail.contact.contactPhoneNumber | String | Telephone number of the contact |
| apiContractNoticeDetail.contact.email | String | Email of the contact |
| apiContractNoticeDetail.awardingAuthority | String | Name of the authority which published this notice |
| apiContractNoticeDetail.address | Object | Object holding address details for this authority |
| apiContractNoticeDetail.address.address | String | Address of the authority |
| apiContractNoticeDetail.address.town | String | Town of the authority |
| apiContractNoticeDetail.address.postCode | String | Post code of the authority |
| apiContractNoticeDetail.referenceNumber | String | Reference number for this tender notice |
| apiContractNoticeDetail.deadlineDate | String | Deadline date for applications (YYYY-MM-DD) |
/awards/{id}
| Field | Type | Description |
|---|---|---|
| apiAwardDetails | Object | Object holding the award details |
| apiAwardDetails.id | Long | ID of the award, used to view the full detail |
| apiAwardDetails.title | String | Title of the contract |
| apiAwardDetails.description | String | Description of the contract |
| apiAwardDetails.location | String | Location of the contract to be performed |
| apiAwardDetails.value | Double | Value of the tender award |
| apiAwardDetails.publishedDate | String | Date the award was published (YYYY-MM-DD) |
| apiAwardDetails.cpvCodes | String | CPV Code which apply to this tender award |
| apiAwardDetails.contact | Object | Primary contact we hold for this tender award |
| apiAwardDetails.contact.contactName | String | Name of the contact |
| apiAwardDetails.contact.contactPhoneNumber | String | Telephone number of the contact |
| apiAwardDetails.contact.email | String | Email of the contact |
| apiAwardDetails.awardingAuthority | String | Name of the authority which published this award |
| apiAwardDetails.address | Object | Object holding address details for this authority |
| apiAwardDetails.address.address | String | Address of the authority |
| apiAwardDetails | String | Town of the authority |
| apiAwardDetails.address.postCode | String | Post code of the authority |
| apiAwardDetails.referenceNumber | String | Reference number for this tender award |
| apiAwardDetails.endDate | String | Deadline date for applications (YYYY-MM-DD) |
| apiAwardDetails.suppliers | String[] | List of the suppliers the tender was awarded to |
/spend/buyers
| Field | Type | Description |
|---|---|---|
| totalResults | Long | Total Buyer count |
| totalPages | Long | Number of pages of Buyers that can be requested |
| results | Object[] | List holding Buyer objects |
| results.organisationName | String | Name of the Buyer |
/spend/suppliers
| Field | Type | Description |
|---|---|---|
| totalResults | Long | Total Supplier count |
| totalPages | Long | Number of pages of Supplier that can be requested |
| results | Object[] | List holding Supplier objects |
| results.organisationName | String | Name of the Supplier |
/spend/transactions
| Field | Type | Description |
|---|---|---|
| totalResults | Long | Total Transaction count |
| results | Object[] | List holding Transaction objects |
| results.buyerName | String | Name of the Buyer |
| results.supplierName | String | Name of the Supplier |
| results.transactionName | String | Name of the Transaction |
| results.amount | Double | Value of the Transaction |
| results.transactionDate | String | Date recorded for the Transaction (YYYY-MM-DD) |
| results.industry | String | Industry of the Transaction |
| results.region | String | Region of the Transaction |