Welcome to openprocurement.api’s documentation!

Contents:

Overview

The Open Procurement API is the only interface to Open Procurement database that is core unit of Open Procurement infrastructure.

The Open Procurement API is REST-ful interface, providing programmatic access to Tender database of Open Procurement system. It provides predictable URLs for accessing resources, and uses built-in HTTP features to receive commands and return responses. This makes it easy to communicate with.

The API accepts JSON or form-encoded content in requests. It returns JSON content in all of its responses, including errors. Only the UTF-8 character encoding is supported for both requests and responses.

Conventions

All API POST and PUT requests expect a top-level object with a single element in it named data. Successful responses will mirror this format. The data element should itself be an object, containing the parameters for the request. In the case of creating a new tender, these are the fields we want to set on the tender itself.

If the request was successful, we will get a response code of 201 indicating the object was created. That response will have a data field at its top level, which will contain complete information on the new tender, including its ID.

If something went wrong during the request, we’ll get a different status code and the JSON returned will contain an errors field at the top level containing a list of problems. We look at the first one and print out its message.

Main responsibilities

Business logic

Project status

The project has pre alpha status.

The source repository for this project is on GitHub:

https://github.com/openprocurement/openprocurement.api

You can leave feedback by raising a new issue on the issue tracker (GitHub registration necessary). For general discussion use Open Procurement General maillist.

API stability

API is highly unstable, and while API endpoint are expecetd to remain relatively stable the data exchange formats are expected to be changed a lot. The changes in the API are communicated via Open Procurement API maillist.

Change log

0.1

Released: Not yet.

  • Set up general build, testing, deployment, and ci framework.

Next steps

You might find it helpful to look at the Tutorial, or the API Reference.

Responses

After processing API is always providing response, reporting either success or failure.

Status Codes

In all cases, the API should return an HTTP Status Code that indicates the nature of the failure (below), with a response body in JSON format containing additional information.

200
Success. If data was requested, it will be available in the data field at the top level of the response body.
201
Success (for object creation). Its information is available in the data field at the top level of the response body. The API URL where the object can be retrieved is also returned in the Location header of the response.
400
Invalid request. This usually occurs because of a missing or malformed parameter. Check the documentation and the syntax of your request and try again.
401
No authorization. A valid API key was not provided with the request, so the API could not associate a user with the request.
403
Forbidden. The API key and request syntax was valid but the server is refusing to complete the request. This can happen if you try to read or write to objects or properties that the party does not have access to.
404
Not found. Either the request method and path supplied do not specify a known action in the API, or the object specified by the request does not exist.
429
Rate Limit Enforced.
500
Server error. There was a problem on OpenProcurement’s end.

Success Response

Every successful get, create, update, replace request results in response that contains data attribute. That data attribute contains full JSON object representation after the operation. If some data were generated in the results of processing (like new object IDs, of modified date) they are present in the respose.

The listing requests result in similar responses, but instead of single object in data attribute, the JSON response contains collection of objects.

Example Succes Response

Here is response describing tender

HTTP/1.1 200 OK

{
    "data":{
        "id": "64e93250be76435397e8c992ed4214d1",
        "tenderID": "UA-2014-DUS-156",
        "modified": "2014-10-27T08:06:58.158Z",
        "procuringEntity": {
            "id": {
                "name": "Державне управління справами",
                "scheme": "https://ns.openprocurement.org/ua/edrpou",
                "uid": "00037256",
                "uri": "http://www.dus.gov.ua/"
            },
            "address": {
                "countryName": "Україна",
                "postalCode": "01220",
                "region": "м. Київ",
                "locality": "м. Київ",
                "streetAddress": "вул. Банкова, 11, корпус 1"
            }
        },
        "totalValue": {
            "amount": 500,
            "currency": "UAH",
            "valueAddedTaxIncluded": true
        },
        "itemsToBeProcured": [
            {
                "description": "футляри до державних нагород",
                "primaryClassification": {
                    "scheme": "CPV",
                    "id": "44617100-9",
                    "description": "Cartons"
                },
                "additionalClassification": [
                    {
                        "scheme": "ДКПП",
                        "id": "17.21.1",
                        "description": "папір і картон гофровані, паперова й картонна тара"
                    }
                ],
                "unitOfMeasure": "item",
                "quantity": 5
            }
        ],
        "clarificationPeriod": {
            "endDate": "2014-10-31T00:00:00"
        },
        "tenderPeriod": {
            "endDate": "2014-11-06T10:00:00"
        },
        "awardPeriod": {
            "endDate": "2014-11-13T00:00:00"
        }
    }
}

Error Response

In the event of an error, the response body will contain an errors field at the top level. This contains an array of at least one error object, described below:

message
totalValue.amount: Missing input - Message providing more detail about the error that occurred, if available.
messageUID
Unique message id. Will stay the same even if content of the message can change, depending on other parameters.
id
Unique correlation identifier of the error response for audit and issue reporting purposes.

Example Error Response

Sample below indicate incomplete request.

HTTP/1.1 400 Missing input

{
  "message":"totalValue.amount: Missing input",
  "messageUID":"e6cfac20-4497-4b36-bae8-7048133d9d07",
  "id":"4468eee5-9820-4d51-adee-a245a2fb6ee5"
}

Date Format

The date format is ISO 8601.

http://imgs.xkcd.com/comics/iso_8601.png

Tutorial

Let’s try exploring the /tenders endpoint:

curl -v http://api-sandbox.openprocurement.org/api/0/tenders
> GET /api/0/tenders HTTP/1.1
> Host: api-sandbox.openprocurement.org
>
< HTTP/1.1 200 OK
< Content-Type: application/json; charset=UTF-8
<
{
  "data": []
}

Just invoking it reveals empty set.

Now let’s attempt creating some tender:

curl -v -X POST http://api-sandbox.openprocurement.org/api/0/tenders
> POST /api/0/tenders HTTP/1.1
> Host: api-sandbox.openprocurement.org
>
< HTTP/1.1 415 Unsupported Media Type
< Content-Type: application/json; charset=UTF-8
<
{
  "status": "error",
  "errors": [
    {
      "location": "header",
      "name": "Content-Type",
      "description": "Content-Type header should be one of ['application\/json']"
    }
  ]
}

Error states that only accepted Content-Type is application/json.

Let’s satisfy the Content-type requirement:

curl -v -H "Content-Type: application/json" -X POST http://api-sandbox.openprocurement.org/api/0/tenders
> POST /api/0/tenders HTTP/1.1
> Host: api-sandbox.openprocurement.org
> Content-Type: application/json
>
< HTTP/1.1 422 Unprocessable Entity
< Content-Type: application/json; charset=UTF-8
<
{
  "status": "error",
  "errors": [
    {
      "location": "body",
      "name": "data",
      "description": "No JSON object could be decoded"
    }
  ]
}

Error states that no data found in JSON body.

Let’s provide the data attribute in the body submitted:

curl -v -H "Content-Type: application/json" -X POST --data @data.json http://api-sandbox.openprocurement.org/api/0/tenders
> POST /api/0/tenders HTTP/1.1
> Host: api-sandbox.openprocurement.org
> Content-Type: application/json
>
> {
>    "data":{}
> }

< HTTP/1.1 201 Created
< Content-Type: application/json; charset=UTF-8
< Location: http://api-sandbox.openprocurement.org/api/0/tenders/be40e257812044f3913534cc537d1f99
<
{
  "data": {
    "id": "be40e257812044f3913534cc537d1f99",
    "tenderID": "UA-be40e257812044f3913534cc537d1f99",
    "modified": "2014-10-25T00:24:12.772078"
  }
}

Success! Now we can see that new object was created. Response code is 201 and Location response header reports the location of object created. The body of response reveals the information about tender created, its internal id (that matches the Location segment), its official tenderID and modified datestamp stating the moment in time when tender was last modified.

Let’s access the URL of object created (the Location header of the response):

curl -v http://api-sandbox.openprocurement.org/api/0/tenders/be40e257812044f3913534cc537d1f99
> GET /api/0/tenders/be40e257812044f3913534cc537d1f99 HTTP/1.1
> Host: api-sandbox.openprocurement.org
>
< HTTP/1.1 200 OK
< Content-Type: application/json; charset=UTF-8
<
{
  "data": {
    "id": "be40e257812044f3913534cc537d1f99",
    "tenderID": "UA-be40e257812044f3913534cc537d1f99",
    "modified": "2014-10-25T00:24:12.772078"
  }
}

We can see the same response we got after creating tender.

Let’s see what listing of tenders reveals us:

curl -v http://api-sandbox.openprocurement.org/api/0/tenders/
> GET /api/0/tenders/ HTTP/1.1
> Host: api-sandbox.openprocurement.org
>
< HTTP/1.1 200 OK
< Content-Type: application/json; charset=UTF-8
<
{
  "data": [
    {
      "id": "be40e257812044f3913534cc537d1f99",
      "modified": "2014-10-25T00:24:12.772078"
    }
  ]
}

We do see the internal id of a tender (that can be used to construct full URL by prepending http://api-sandbox.openprocurement.org/api/0/tenders/) and its modified datestamp.

Let’s try creating tender with more data, passing the procuringEntity of a tender:

curl -v -H "Content-Type: application/json" --data @tender.json -X POST http://api-sandbox.openprocurement.org/api/0/tenders
> POST /api/0/tenders HTTP/1.1
> Host: api-sandbox.openprocurement.org
> Content-Type: application/json
>
> {
>     "data":{
>         "procuringEntity": {
>             "id": {
>                 "name": "Заклад \"Загальноосвітня школа І-ІІІ ступенів № 10 Вінницької міської ради\"",
>                 "scheme": "https://ns.openprocurement.org/ua/edrpou",
>                 "uid": "21725150",
>                 "uri": "http://sch10.edu.vn.ua/"
>             },
>             "address": {
>                 "countryName": "Україна",
>                 "postalCode": "21027",
>                 "region": "м. Вінниця",
>                 "locality": "м. Вінниця",
>                 "streetAddress": "вул. Стахурського. 22"
>             }
>         }
>     }
> }

< HTTP/1.1 201 Created
< Content-Type: application/json; charset=UTF-8
< Location: http://api-sandbox.openprocurement.org/api/0/tenders/8c2ba371505348ed8f5f0e5119a80451
<
{
  "data": {
    "id": "8c2ba371505348ed8f5f0e5119a80451",
    "tenderID": "UA-8c2ba371505348ed8f5f0e5119a80451",
    "modified": "2014-10-25T00:37:13.847358",
    "procuringEntity": {
      "id": {
        "scheme": "https:\/\/ns.openprocurement.org\/ua\/edrpou",
        "name": "\u0417\u0430\u043a\u043b\u0430\u0434 \"\u0417\u0430\u0433\u0430\u043b\u044c\u043d\u043e\u043e\u0441\u0432\u0456\u0442\u043d\u044f \u0448\u043a\u043e\u043b\u0430 \u0406-\u0406\u0406\u0406 \u0441\u0442\u0443\u043f\u0435\u043d\u0456\u0432 \u2116 10 \u0412\u0456\u043d\u043d\u0438\u0446\u044c\u043a\u043e\u0457 \u043c\u0456\u0441\u044c\u043a\u043e\u0457 \u0440\u0430\u0434\u0438\"",
        "uri": "http:\/\/sch10.edu.vn.ua\/",
        "uid": "21725150"
      },
      "address": {
        "postalCode": "21027",
        "countryName": "\u0423\u043a\u0440\u0430\u0457\u043d\u0430",
        "streetAddress": "\u0432\u0443\u043b. \u0421\u0442\u0430\u0445\u0443\u0440\u0441\u044c\u043a\u043e\u0433\u043e. 22",
        "region": "\u043c. \u0412\u0456\u043d\u043d\u0438\u0446\u044f",
        "locality": "\u043c. \u0412\u0456\u043d\u043d\u0438\u0446\u044f"
      }
    }
  }
}

And again we have 201 Created response code, Location header and body wth extra id, tenderID, and modified properties.

Let’s check what tender registry contains:

curl -v http://api-sandbox.openprocurement.org/api/0/tenders/
> GET /api/0/tenders/ HTTP/1.1
> Host: api-sandbox.openprocurement.org
>
< HTTP/1.1 200 OK
< Content-Type: application/json; charset=UTF-8
<
{
  "data": [
    {
      "id": "be40e257812044f3913534cc537d1f99",
      "modified": "2014-10-25T00:24:12.772078"
    },
    {
      "id": "8c2ba371505348ed8f5f0e5119a80451",
      "modified": "2014-10-25T00:37:13.847358"
    }
  ]
}

And indeed we have 2 tenders now.

Let’s update tender by providing it with all other essential properties:

curl -v -H "Content-Type: application/json" -X PATCH --data @tender-update.json http://api-sandbox.openprocurement.org/api/0/tenders/8c2ba371505348ed8f5f0e5119a80451
> PATCH /api/0/tenders/8c2ba371505348ed8f5f0e5119a80451 HTTP/1.1
> Host: api-sandbox.openprocurement.org
> Content-Type: application/json
>
> {
>     "data":{
>         "totalValue": {
>             "amount": 50000,
>             "currency": "UAH",
>             "valueAddedTaxIncluded": true
>         },
>         "itemsToBeProcured": [
>             {
>                 "description": "Послуги шкільних їдалень",
>                 "primaryClassification": {
>                     "scheme": "CPV",
>                     "id": "55523100-3",
>                     "description": "Послуги з харчування у школах"
>                 },
>                 "additionalClassification": [
>                     {
>                         "scheme": "ДКПП",
>                         "id": "55.51.10.300",
>                         "description": "Послуги шкільних їдалень"
>                     }
>                 ],
>                 "unitOfMeasure": "item",
>                 "quantity": 5
>             }
>         ],
>         "clarificationPeriod": {
>             "endDate": "2015-05-29T00:00:00"
>         },
>         "tenderPeriod": {
>             "endDate": "2015-06-07T10:00:00"
>         },
>         "awardPeriod": {
>             "endDate": "2015-06-18T00:00:00"
>         }
>     }
> }

< HTTP/1.1 200 OK
< Content-Type: application/json; charset=UTF-8
<
{
  "data": {
    "clarificationPeriod": {
      "startDate": null,
      "endDate": "2015-05-29T00:00:00.000000"
    },
    "awardPeriod": {
      "startDate": null,
      "endDate": "2015-06-18T00:00:00.000000"
    },
    "tenderPeriod": {
      "startDate": null,
      "endDate": "2015-06-07T10:00:00.000000"
    },
    "modified": "2014-10-25T00:42:44.968106",
    "itemsToBeProcured": [
      {
        "unitOfMeasure": "item",
        "description": "\u041f\u043e\u0441\u043b\u0443\u0433\u0438 \u0448\u043a\u0456\u043b\u044c\u043d\u0438\u0445 \u0457\u0434\u0430\u043b\u0435\u043d\u044c",
        "valuePerUnit": null,
        "additionalClassification": [
          {
            "scheme": "\u0414\u041a\u041f\u041f",
            "id": "55.51.10.300",
            "uri": null,
            "description": "\u041f\u043e\u0441\u043b\u0443\u0433\u0438 \u0448\u043a\u0456\u043b\u044c\u043d\u0438\u0445 \u0457\u0434\u0430\u043b\u0435\u043d\u044c"
          }
        ],
        "primaryClassification": {
          "scheme": "CPV",
          "id": "55523100-3",
          "uri": null,
          "description": "\u041f\u043e\u0441\u043b\u0443\u0433\u0438 \u0437 \u0445\u0430\u0440\u0447\u0443\u0432\u0430\u043d\u043d\u044f \u0443 \u0448\u043a\u043e\u043b\u0430\u0445"
        },
        "quantity": 5
      }
    ],
    "tenderID": "UA-8c2ba371505348ed8f5f0e5119a80451",
    "totalValue": {
      "currency": "UAH",
      "amount": 50000,
      "valueAddedTaxIncluded": true
    },
    "id": "8c2ba371505348ed8f5f0e5119a80451",
    "procuringEntity": {
      "id": {
        "scheme": "https:\/\/ns.openprocurement.org\/ua\/edrpou",
        "name": "\u0417\u0430\u043a\u043b\u0430\u0434 \"\u0417\u0430\u0433\u0430\u043b\u044c\u043d\u043e\u043e\u0441\u0432\u0456\u0442\u043d\u044f \u0448\u043a\u043e\u043b\u0430 \u0406-\u0406\u0406\u0406 \u0441\u0442\u0443\u043f\u0435\u043d\u0456\u0432 \u2116 10 \u0412\u0456\u043d\u043d\u0438\u0446\u044c\u043a\u043e\u0457 \u043c\u0456\u0441\u044c\u043a\u043e\u0457 \u0440\u0430\u0434\u0438\"",
        "uri": "http:\/\/sch10.edu.vn.ua\/",
        "uid": "21725150"
      },
      "address": {
        "postalCode": "21027",
        "countryName": "\u0423\u043a\u0440\u0430\u0457\u043d\u0430",
        "streetAddress": "\u0432\u0443\u043b. \u0421\u0442\u0430\u0445\u0443\u0440\u0441\u044c\u043a\u043e\u0433\u043e. 22",
        "region": "\u043c. \u0412\u0456\u043d\u043d\u0438\u0446\u044f",
        "locality": "\u043c. \u0412\u0456\u043d\u043d\u0438\u0446\u044f"
      }
    }
  }
}

We see the added properies merged with existing data of tender. Additionally the modified property updated to reflect the last modification datestamp.

Checking the listing again reflets the new modification date:

curl -v http://api-sandbox.openprocurement.org/api/0/tenders/
> GET /api/0/tenders/ HTTP/1.1
> Host: api-sandbox.openprocurement.org
>
< HTTP/1.1 200 OK
< Content-Type: application/json; charset=UTF-8
<
{
  "data": [
    {
      "modified": "2014-10-25T00:42:44.968106",
      "id": "8c2ba371505348ed8f5f0e5119a80451"
    },
    {
      "id": "be40e257812044f3913534cc537d1f99",
      "modified": "2014-10-25T00:24:12.772078"
    }
  ]
}

Retrieving Tender Information

Getting list of all tenders

GET /tenders HTTP/1.1

HTTP/1.1 200 OK

Reading the individual tender information

GET /tenders/64e93250be76435397e8c992ed4214d1 HTTP/1.1

HTTP/1.1 200 OK

Procuring Entity Operations

Registration of the Tender

Tender registration consist of primary record creation and documentation uploading.

Creating primary Tender record

When registering tender in the database, one has provide all primary tender details (except binary documents) in payload of request.

POST /tenders HTTP/1.1

The response produced will have URL of the tender created in Location header of resoponse, and in data.id of body.

HTTP/1.1 201 Created
Location: /tenders/64e93250be76435397e8c992ed4214d1

Uploading documentation

All tender documentation should be uploaded following requests one request per document.

POST /tenders/64e93250be76435397e8c992ed4214d1/documents HTTP/1.1

The response produced will have URL of the tender document uploaded in Location header of resoponse, and in data.id of body.

HTTP/1.1 201 Created
Location: /tenders/64e93250be76435397e8c992ed4214d1/documents/6a7d13bd8ec449e08882aeb92180d938

Changing the Tender

Procuring Entity can change both the primary record and associated documentation.

Changing primary Tender Record

Procuring Entity can change the Tender properties with following request. Data to change should be in payload of the message.

PATCH /tenders/64e93250be76435397e8c992ed4214d1 HTTP/1.1

HTTP/1.1 200 OK

Changing existing documents

Procuring Entity can upload new versions of the tender documentation.

PUT /tenders/64e93250be76435397e8c992ed4214d1/documents/6a7d13bd8ec449e08882aeb92180d938 HTTP/1.1

HTTP/1.1 200 OK

Uploading additional documents

The same as Uploading documentation

Bidder Operations

Registration of Bid proposal

POST /tenders/64e93250be76435397e8c992ed4214d1/bidders/ HTTP/1.1

HTTP/1.1 201 Created
Location: /tenders/64e93250be76435397e8c992ed4214d1/bidders/4879d3f8ee2443169b5fbbc9f89fa607

Uploading Bid documents

POST /tenders/64e93250be76435397e8c992ed4214d1/bidders/4879d3f8ee2443169b5fbbc9f89fa607/documents HTTP/1.1

HTTP/1.1 201 Created
Location: /tenders/64e93250be76435397e8c992ed4214d1/bidders/4879d3f8ee2443169b5fbbc9f89fa607/documents/bd2e4c64179445cab93987fff3d58d23

Update of proposal

PUT /tenders/64e93250be76435397e8c992ed4214d1/bidders/4879d3f8ee2443169b5fbbc9f89fa607 HTTP/1.1

HTTP/1.1 200 OK

Updating Bid documents

POST /tenders/64e93250be76435397e8c992ed4214d1/bidders/4879d3f8ee2443169b5fbbc9f89fa607/documents HTTP/1.1

HTTP/1.1 201 Created
Location: /tenders/64e93250be76435397e8c992ed4214d1/bidders/4879d3f8ee2443169b5fbbc9f89fa607/documents/bd2e4c64179445cab93987fff3d58d23

Cancelling the proposal

DELETE /tenders/64e93250be76435397e8c992ed4214d1/bidders/4879d3f8ee2443169b5fbbc9f89fa607 HTTP/1.1

HTTP/1.1 200 OK

Bids Listing

GET /tenders/64e93250be76435397e8c992ed4214d1/bidders/ HTTP/1.1

HTTP/1.1 200 OK

Retrieving the proposal

GET /tenders/64e93250be76435397e8c992ed4214d1/bidders/4879d3f8ee2443169b5fbbc9f89fa60 HTTP/1.1

HTTP/1.1 200 OK

Qualification Operations

Contract Awarding

POST /tenders/64e93250be76435397e8c992ed4214d1/awards HTTP/1.1

{
    "data":{
        "awardStatus": "pending"
    }
}

HTTP/1.1 201 Created
Location: /tenders/64e93250be76435397e8c992ed4214d1/awards/ea36a10ad89649ccac253f23d8e0e80d HTTP/1.1

Disqualification

POST /tenders/64e93250be76435397e8c992ed4214d1/awards HTTP/1.1

{
    "data":{
        "awardStatus": "unsuccessful"
    }
}

HTTP/1.1 201 Created
Location: /tenders/64e93250be76435397e8c992ed4214d1/awards/ea36a10ad89649ccac253f23d8e0e80d HTTP/1.1

API Reference

Spore service at /spore

GET

Response: json

Tender Auction service at /tenders/{tender_id}/auction

GET

Get auction info.

Get tender auction info

Example request to get tender auction information:

GET /tenders/4879d3f8ee2443169b5fbbc9f89fa607/auction HTTP/1.1
Host: example.com
Accept: application/json

This is what one should expect in response:

HTTP/1.1 200 OK
Content-Type: application/json

{
    "data": {
        "modified": "2014-10-27T08:06:58.158Z",
        "bids": [
            {
                "amount": 500,
                "currency": "UAH"
            },
            {
                "amount": 485,
                "currency": "UAH"
            }
        ],
        "minimalStep":{
            "amount": 35,
            "currency": "UAH"
        },
        "period":{
            "startDate": "2014-11-06T12:00:00"
        }
    }
}

Response: json

PATCH

Report auction results.

Report auction results

Example request to report auction results:

PATCH /tenders/4879d3f8ee2443169b5fbbc9f89fa607/auction HTTP/1.1
Host: example.com
Accept: application/json

{
    "data": {
        "modified": "2014-10-27T08:06:58.158Z",
        "bids": [
            {
                "amount": 400,
                "currency": "UAH"
            },
            {
                "amount": 385,
                "currency": "UAH"
            }
        ]
    }
}

This is what one should expect in response:

HTTP/1.1 200 OK
Content-Type: application/json

{
    "data": {
        "modified": "2014-10-27T08:06:58.158Z",
        "bids": [
            {
                "amount": 400,
                "currency": "UAH"
            },
            {
                "amount": 385,
                "currency": "UAH"
            }
        ],
        "minimalStep":{
            "amount": 35,
            "currency": "UAH"
        },
        "period":{
            "startDate": "2014-11-06T12:00:00"
        }
    }
}

Response: json

Collection_Tender service at /tenders

Open Contracting compatible data exchange format. See http://ocds.open-contracting.org/standard/r/master/#tender for more info

GET

Tenders List

Get Tenders List

Example request to get tenders list:

GET /tenders HTTP/1.1
Host: example.com
Accept: application/json

This is what one should expect in response:

HTTP/1.1 200 OK
Content-Type: application/json

{
    "data": [
        {
            "id": "64e93250be76435397e8c992ed4214d1",
            "modified": "2014-10-27T08:06:58.158Z"
        }
    ]
}

Response: json

POST

This API request is targeted to creating new Tenders by procuring organizations.

Creating new Tender

Example request to create tender:

POST /tenders HTTP/1.1
Host: example.com
Accept: application/json

{
    "data": {
        "procuringEntity": {
            "id": {
                "name": "Державне управління справами",
                "scheme": "https://ns.openprocurement.org/ua/edrpou",
                "uid": "00037256",
                "uri": "http://www.dus.gov.ua/"
            },
            "address": {
                "countryName": "Україна",
                "postalCode": "01220",
                "region": "м. Київ",
                "locality": "м. Київ",
                "streetAddress": "вул. Банкова, 11, корпус 1"
            }
        },
        "totalValue": {
            "amount": 500,
            "currency": "UAH",
            "valueAddedTaxIncluded": true
        },
        "itemsToBeProcured": [
            {
                "description": "футляри до державних нагород",
                "primaryClassification": {
                    "scheme": "CPV",
                    "id": "44617100-9",
                    "description": "Cartons"
                },
                "additionalClassification": [
                    {
                        "scheme": "ДКПП",
                        "id": "17.21.1",
                        "description": "папір і картон гофровані, паперова й картонна тара"
                    }
                ],
                "unitOfMeasure": "item",
                "quantity": 5
            }
        ],
        "clarificationPeriod": {
            "endDate": "2014-10-31T00:00:00"
        },
        "tenderPeriod": {
            "endDate": "2014-11-06T10:00:00"
        },
        "awardPeriod": {
            "endDate": "2014-11-13T00:00:00"
        }
    }
}

This is what one should expect in response:

HTTP/1.1 201 Created
Location: http://localhost/api/0.1/tenders/64e93250be76435397e8c992ed4214d1
Content-Type: application/json

{
    "data": {
        "id": "64e93250be76435397e8c992ed4214d1",
        "tenderID": "UA-2014-DUS-156",
        "modified": "2014-10-27T08:06:58.158Z",
        "procuringEntity": {
            "id": {
                "name": "Державне управління справами",
                "scheme": "https://ns.openprocurement.org/ua/edrpou",
                "uid": "00037256",
                "uri": "http://www.dus.gov.ua/"
            },
            "address": {
                "countryName": "Україна",
                "postalCode": "01220",
                "region": "м. Київ",
                "locality": "м. Київ",
                "streetAddress": "вул. Банкова, 11, корпус 1"
            }
        },
        "totalValue": {
            "amount": 500,
            "currency": "UAH",
            "valueAddedTaxIncluded": true
        },
        "itemsToBeProcured": [
            {
                "description": "футляри до державних нагород",
                "primaryClassification": {
                    "scheme": "CPV",
                    "id": "44617100-9",
                    "description": "Cartons"
                },
                "additionalClassification": [
                    {
                        "scheme": "ДКПП",
                        "id": "17.21.1",
                        "description": "папір і картон гофровані, паперова й картонна тара"
                    }
                ],
                "unitOfMeasure": "item",
                "quantity": 5
            }
        ],
        "clarificationPeriod": {
            "endDate": "2014-10-31T00:00:00"
        },
        "tenderPeriod": {
            "endDate": "2014-11-06T10:00:00"
        },
        "awardPeriod": {
            "endDate": "2014-11-13T00:00:00"
        }
    }
}

Response: json

Tender service at /tenders/{id}

Open Contracting compatible data exchange format. See http://ocds.open-contracting.org/standard/r/master/#tender for more info

GET

Tender Read

Get Tender

Example request to get tender:

GET /tenders/64e93250be76435397e8c992ed4214d1 HTTP/1.1
Host: example.com
Accept: application/json

This is what one should expect in response:

HTTP/1.1 200 OK
Content-Type: application/json

{
    "data": {
        "id": "64e93250be76435397e8c992ed4214d1",
        "tenderID": "UA-2014-DUS-156",
        "modified": "2014-10-27T08:06:58.158Z",
        "procuringEntity": {
            "id": {
                "name": "Державне управління справами",
                "scheme": "https://ns.openprocurement.org/ua/edrpou",
                "uid": "00037256",
                "uri": "http://www.dus.gov.ua/"
            },
            "address": {
                "countryName": "Україна",
                "postalCode": "01220",
                "region": "м. Київ",
                "locality": "м. Київ",
                "streetAddress": "вул. Банкова, 11, корпус 1"
            }
        },
        "totalValue": {
            "amount": 500,
            "currency": "UAH",
            "valueAddedTaxIncluded": true
        },
        "itemsToBeProcured": [
            {
                "description": "футляри до державних нагород",
                "primaryClassification": {
                    "scheme": "CPV",
                    "id": "44617100-9",
                    "description": "Cartons"
                },
                "additionalClassification": [
                    {
                        "scheme": "ДКПП",
                        "id": "17.21.1",
                        "description": "папір і картон гофровані, паперова й картонна тара"
                    }
                ],
                "unitOfMeasure": "item",
                "quantity": 5
            }
        ],
        "clarificationPeriod": {
            "endDate": "2014-10-31T00:00:00"
        },
        "tenderPeriod": {
            "endDate": "2014-11-06T10:00:00"
        },
        "awardPeriod": {
            "endDate": "2014-11-13T00:00:00"
        }
    }
}

Response: json

PUT

Tender Edit (full)

Response: json

PATCH

Tender Edit (partial)

For example here is how procuring entity can change number of items to be procured and total Value of a tender:

PATCH /tenders/4879d3f8ee2443169b5fbbc9f89fa607 HTTP/1.1
Host: example.com
Accept: application/json

{
    "data": {
        "totalValue": {
            "amount": 600
        },
        "itemsToBeProcured": [
            {
                "quantity": 6
            }
        ]
    }
}

And here is the response to be expected:

HTTP/1.0 200 OK
Content-Type: application/json

{
    "data": {
        "id": "4879d3f8ee2443169b5fbbc9f89fa607",
        "tenderID": "UA-2014-DUS-156",
        "modified": "2014-10-27T08:12:34.956Z",
        "totalValue": {
            "amount": 600
        },
        "itemsToBeProcured": [
            {
                "quantity": 6
            }
        ]
    }
}

Response: json

Collection_Tender Documents service at /tenders/{tender_id}/documents

Tender related binary files (PDFs, etc.)

GET

Tender Documents List

Response: json

POST

Tender Document Upload

Response: json

Tender Documents service at /tenders/{tender_id}/documents/{id}

Tender related binary files (PDFs, etc.)

GET

Tender Document Read

Response: json

PUT

Tender Document Update

Response: json

Collection_Tender Bids service at /tenders/{tender_id}/bidders

Tender bidders

POST

Registration of new bid proposal

Creating new Bid proposal

Example request to create bid proposal:

POST /tenders/4879d3f8ee2443169b5fbbc9f89fa607/bidders HTTP/1.1
Host: example.com
Accept: application/json

{
    "data": {
        "bidders": [
            {
                "id": {
                    "name": "Державне управління справами",
                    "scheme": "https://ns.openprocurement.org/ua/edrpou",
                    "uid": "00037256",
                    "uri": "http://www.dus.gov.ua/"
                },
                "address": {
                    "countryName": "Україна",
                    "postalCode": "01220",
                    "region": "м. Київ",
                    "locality": "м. Київ",
                    "streetAddress": "вул. Банкова, 11, корпус 1"
                }
            }
        ],
        "totalValue": {
            "amount": 489,
            "currency": "UAH",
            "valueAddedTaxIncluded": true
        }
    }
}

This is what one should expect in response:

HTTP/1.1 201 Created
Content-Type: application/json

{
    "data": {
        "id": "4879d3f8ee2443169b5fbbc9f89fa607",
        "status": "registration",
        "date": "2014-10-28T11:44:17.947Z",
        "bidders": [
            {
                "id": {
                    "name": "Державне управління справами",
                    "scheme": "https://ns.openprocurement.org/ua/edrpou",
                    "uid": "00037256",
                    "uri": "http://www.dus.gov.ua/"
                },
                "address": {
                    "countryName": "Україна",
                    "postalCode": "01220",
                    "region": "м. Київ",
                    "locality": "м. Київ",
                    "streetAddress": "вул. Банкова, 11, корпус 1"
                }
            }
        ],
        "totalValue": {
            "amount": 489,
            "currency": "UAH",
            "valueAddedTaxIncluded": true
        }
    }
}

Response: json

Tender Bids service at /tenders/{tender_id}/bidders/{id}

Tender bidders

Collection_Tender Bid Documents service at /tenders/{tender_id}/bidders/{bid_id}/documents

Tender bidder documents

POST

Tender Bid Document Upload

Response: json

Tender Bid Documents service at /tenders/{tender_id}/bidders/{bid_id}/documents/{id}

Tender bidder documents

Collection_Tender Awards service at /tenders/{tender_id}/awards

Tender awards

POST

Accept or reject bidder application

Creating new Award

Example request to create award:

POST /tenders/4879d3f8ee2443169b5fbbc9f89fa607/bidders HTTP/1.1
Host: example.com
Accept: application/json

{
    "data": {
        "awardStatus": "active",
        "suppliers": [
            {
                "id": {
                    "name": "Державне управління справами",
                    "scheme": "https://ns.openprocurement.org/ua/edrpou",
                    "uid": "00037256",
                    "uri": "http://www.dus.gov.ua/"
                },
                "address": {
                    "countryName": "Україна",
                    "postalCode": "01220",
                    "region": "м. Київ",
                    "locality": "м. Київ",
                    "streetAddress": "вул. Банкова, 11, корпус 1"
                }
            }
        ],
        "awardValue": {
            "amount": 489,
            "currency": "UAH",
            "valueAddedTaxIncluded": true
        }
    }
}

This is what one should expect in response:

HTTP/1.1 201 Created
Content-Type: application/json

{
    "data": {
        "awardID": "4879d3f8ee2443169b5fbbc9f89fa607",
        "awardDate": "2014-10-28T11:44:17.947Z",
        "awardStatus": "active",
        "suppliers": [
            {
                "id": {
                    "name": "Державне управління справами",
                    "scheme": "https://ns.openprocurement.org/ua/edrpou",
                    "uid": "00037256",
                    "uri": "http://www.dus.gov.ua/"
                },
                "address": {
                    "countryName": "Україна",
                    "postalCode": "01220",
                    "region": "м. Київ",
                    "locality": "м. Київ",
                    "streetAddress": "вул. Банкова, 11, корпус 1"
                }
            }
        ],
        "awardValue": {
            "amount": 489,
            "currency": "UAH",
            "valueAddedTaxIncluded": true
        }
    }
}

Response: json

Tender Awards service at /tenders/{tender_id}/awards/{id}

Tender awards

Please report any problems or suggestions for improvement either via the mailing list or the issue tracker.

Indices and tables