# Contract Requests

# Creating contract requests

With the creation of a ContractRequest, you will let any given Supplier know that you would like to get access to their products and order goods from them. Any supplier can choose whether or not they would like to do business with you. They can do that by either accepting or declining your request. Once this ContractRequest has been accepted, we will automatically create a Contract between you and the Supplier.

In order to create a ContractRequest for any given supplier, you can again use either the API or the Procurement application itself. No matter which way you choose, you need to provide the following information:

Information	Required	Description
Customer Number	❌	If you already have an existing customer number with the supplier, you can provide it here
Contact Details	✅	The respective contact person in your organization. This is required in case the supplier needs any further information from your side. Requires: `first_name`, `last_name`,`email`, `phone`
Currency	✅	Currency to be used for monetary transfers between you and the respective supplier. Supported currencies: `EUR`, `USD`, `GBP`

# Create a contract request via API

In order to create a ContractRequest, you have to use the POST /suppliers/{supplier_id}/contract_requests (opens new window) endpoint.

# Example Request

POST /suppliers/a362331b-e105-5ead-a691-e767ce70dd11/contract_requests

body:
{
  "contract_request": {
    "contact_email": "john.doe@example.com",
    "contact_first_name": "John",
    "contact_last_name": "Doe",
    "currency": "EUR",
    "customer_number": "Customer-0001",
    "contact_phone": "123456"
  }
}

# Example Response

{
  "id": "66c53be0-bffc-4702-bfe7-f32dfaae7721",
  "accepted_at": null,
  "connectivity_checked_at": null,
  "contact_email": "john.doe@example.com",
  "contact_first_name": "John",
  "contact_last_name": "Doe",
  "contact_phone": "123456",
  "currency": "EUR",
  "customer_number": "Customer-0001",
  "declined_at": null,
  "mapped_at": null,
  "references": [
    "CR/XQPAKS"
  ],
  "state": "pending",
  "vetted_at": null,
  "consumer_id": "84bb7fea-d7c2-5383-aef4-e3ae1c1c6784",
  "consumer": {
    "id": "84bb7fea-d7c2-5383-aef4-e3ae1c1c6784",
    "display_name": "Doe Print Services",
    "links": [
      {
        "rel": "self",
        "href": null
      }
    ]
  },
  "supplier_id": "a362331b-e105-5ead-a691-e767ce70dd11",
  "supplier": {
    "id": "a362331b-e105-5ead-a691-e767ce70dd11",
    "display_name": "Paper Mill Ltd.",
    "links": [
      {
        "rel": "self",
        "href": "/consumers/api/v1/suppliers/paper_mill"
      }
    ]
  },
  "created_at": "2020-12-18T08:28:30.061Z",
  "updated_at": "2020-12-18T08:28:30.061Z"
}

# Create a contract request via the UI

You can also create contract requests by visiting the Procurement Website using the URLs below. Just click the Connect button on the Supplier you want to be connected to.

Environment	URL
`sandbox`	https://procurement.sandbox.zaikio.com/consumers/suppliers
`production`	https://procurement.zaikio.com/consumers/suppliers

# Checking the status of existing contract requests

Once a ContractRequest has been created, a supplier might take multiple days to process your request. In order for you to stay informed about the current status of any given request, you can use two the following two methods.

# Listening to contract request events

The easiest and preferred solution would be to use the Zaikio Event System (Loom) (opens new window). The following events will keep you informed about status changes regarding your open ContractRequests.

event	Description
`procurement_consumer.contract_request_accepted`	This event will be posted once a contract request has been accepted
`procurement_consumer.contract_request_declined`	This event will be posted once a contract request has been declined

Read more about these events here (opens new window)

# Requesting current data via API

Alternatively you can ask for the current status in regular intervals using the Procurement API and one of the following endpoints:

# Example request

Returns all currently pending ContractRequests

GET /contract_requests?state=pending

# Example response

[
  {
    "id": "0ced2b32-e172-5ca1-b010-5ac590ebde2f",
    "accepted_at": null,
    "connectivity_checked_at": null,
    "contact_email": "johndoe@example.com",
    "contact_first_name": "John",
    "contact_last_name": "Doe",
    "contact_phone": "+49 1234567890",
    "currency": "EUR",
    "customer_number": "JDS-123456",
    "declined_at": null,
    "mapped_at": null,
    "references": [],
    "state": "pending",
    "vetted_at": null,
    "consumer_id": "84bb7fea-d7c2-5383-aef4-e3ae1c1c6784",
    "consumer": {
      "id": "84bb7fea-d7c2-5383-aef4-e3ae1c1c6784",
      "display_name": "Doe Print Services",
      "links": [
        {
          "rel": "self",
          "href": null
        }
      ]
    },
    "supplier_id": "a362331b-e105-5ead-a691-e767ce70dd11",
    "supplier": {
      "id": "a362331b-e105-5ead-a691-e767ce70dd11",
      "display_name": "Smith Papers",
      "links": [
        {
          "rel": "self",
          "href": "/consumers/api/v1/suppliers/smith_papers"
        }
      ]
    },
    "created_at": "2020-11-02T13:51:32.963Z",
    "updated_at": "2020-11-02T13:51:32.963Z"
  }
]

Procurement (Consumers)

Reference