> For the complete documentation index, see [llms.txt](https://docs.eu-pactum.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.eu-pactum.com/procurement-api/integration-guide.md).

# Integration Guide

The key entity for conducting autonomous negotiations via Pactum is the Negotiation Event. It serves as the root for all input and results data points in the negotiation process. The API allows you to create a negotiation event based on data from a requisition or sourcing event.

## Negotiation event creation

The negotiation event can be created in the source system either through user interaction, such as clicking a button, or by utilizing automated workflows. A common scenario is when Pactum acts as an approver in the approval chain, automatically added based on predefined criteria.

<figure><img src="https://documents.lucid.app/documents/2bfad46c-c38a-4d76-bcd9-9f3ab25b33c0/pages/0_0?a=1589&#x26;x=23&#x26;y=343&#x26;w=2114&#x26;h=794&#x26;store=1&#x26;accept=image%2F*&#x26;auth=LCA%2058a91a5f8ced953342762bbf7e29c8f0191d26b18231e8433ba9f56a55f264b0-ts%3D1750944378" alt=""><figcaption><p>Negotiation event creation</p></figcaption></figure>

Negotiation Events are created under Workspaces, which are represented by IDs. It is important to define the mapping on your side, taking into account the workspace division (e.g., business unit, country). Sandbox and Production workspaces have different IDs. You can retrieve the workspace IDs from the the workspaces endpoint.

You can use Pactum’s API alongside the Negotiation Suite to view and manage all negotiation events.

| Endpoints                                                                                           |
| --------------------------------------------------------------------------------------------------- |
| `GET /procurement/v1/workspaces`                                                                    |
| `POST /procurement/v1/workspaces/{workspaceId}/negotiation-events`                                  |
| `POST /procurement/v1/workspaces/{workspaceId}/negotiation-events/{negotiationEventId}/attachments` |

Not all negotiations require the full set of terms to be provided by the integrator. Depending on the product configuration, the needs may differ. For example, the negotiation of requisitions can be achieved with just price and payment terms, while contract negotiations can include warranties, MOQs, and other

If the source system uses advanced unit pricing data structures, for example when a price is defined for a certain quantity of items, then this information must be passed to Pactum upon event creation.

#### Providing existing payment terms

During deployment, Pactum will request an export of payment terms from your source systems. This helps map the terms into Pactum's internal structure, allowing you to reference each payment term by its ID.

For example:

| Description             | ID in your system | Pactum mapping |
| ----------------------- | ----------------- | -------------- |
| within 45 days Due net  | Z45T              | Net 45         |
| 10 Days 3%, 30 days net | 7                 | 3/10, Net 30   |
| ...                     | ...               | ...            |

To reference existing payment terms during a negotiation event, use `suppliers.paymentTerms.externalId` with the relevant ID (e.g., "Z45T" or "7").

#### Attachments and intelligent processing

Many of Pactum's capabilities and performance will depend on additional data provided when creating a negotation event. For this purpose,

To make use of these capabilities it is important to upload attachments. To do so, use the following endpoint to add attachments to a negotiation event:

`POST /procurement/v1/workspaces/{workspaceId}/negotiation-events/{negotiationEventId}/attachments`

## Starting negotiations

To achieve a fully automated workflow, the integrator will need to call the start endpoint through the API.

| Endpoint                                                                                      |
| --------------------------------------------------------------------------------------------- |
| `POST /procurement/v1/workspaces/{workspaceId}/negotiation-events/{negotiationEventId}/start` |

In a semi-automated workflow, the API can serve as a data import solution and can further be managed through Pactum’s Negotiation Suite. In the interface, click the "Start Negotiation" button to initiate negotiations. The started negotiation event will then transition from status `DRAFT` to `IN_PROGRESS`.

## Withdrawing negotiations

In situations where negotiations should not continue, it is important to call the Withdraw endpoint. This need can arise, for example, when source data has been entered incorrectly or when, due to the urgent need for goods or services, the negotiation process must be bypassed. Once withdrawn, the negotiation event transitions from `IN_PROGRESS` to `DRAFT` status, which can be tracked using the results endpoint.

| Endpoint                                                                                         |
| ------------------------------------------------------------------------------------------------ |
| `POST /procurement/v1/workspaces/{workspaceId}/negotiation-events/{negotiationEventId}/withdraw` |

## Receiving negotiation results

When negotiation events conclude (either with a successful agreement or not), the results can be retrieved through the results endpoint. A webhook can be configured to notify the integrating system of the event's conclusion, allowing it to query the results endpoint and achieve near real-time information

It is advised that regardless of webhook implementation, a polling solution should be added to serve as a backup mechanism in case of webhook failure. When used as a backup, the polling can be relatively infrequent. Alternatively, more frequent polling can suffice as the primary results retrieval mechanism.

An interval of 1 hour, for example, would be a reasonable minimum when a webhook is also added.

<figure><img src="https://documents.lucid.app/documents/2bfad46c-c38a-4d76-bcd9-9f3ab25b33c0/pages/0_0?a=1589&#x26;x=83&#x26;y=1403&#x26;w=2114&#x26;h=794&#x26;store=1&#x26;accept=image%2F*&#x26;auth=LCA%2028daf4a02315f4a8a7c4fd702e2a438ad764321064e5756f9445c7f732bdb448-ts%3D1750944378" alt=""><figcaption><p>Negotiation event conclusion</p></figcaption></figure>

| Endpoints                                                                                                         |
| ----------------------------------------------------------------------------------------------------------------- |
| `GET /procurement/v1/workspaces/{workspaceId}/negotiation-events/{negotiationEventId}/results`                    |
| `GET /procurement/v1/workspaces/{workspaceId}/negotiation-events/{negotiationEventId}/attachments/{attachmentId}` |

When negotiation results have been obtained, the source system needs to be updated with the improved terms (e.g. price and payment terms).

#### Retrieving updated payment terms

Find the updated payment terms in the `/results` response at `data.suppliers.paymentTerms.externalId`. This will be the ID of your source system, which will allow you to update the system directly.

#### Retrieving uploaded attachments

During negotiations, we may request the customer to upload necessary files, such as an updated quote. Retrieve these files by accessing the references in the `/results` endpoint response at `data.suppliers.attachments.id`. Then, download them from the attachment download endpoint.

`GET /procurement/v1/workspaces/{workspaceId}/negotiation-events/{negotiationEventId}/attachments/{attachmentId}`

## Deleting negotiations

Sometimes a negotiation event is created by accident or deleted in the source system. In such cases, the created negotiation event can be deleted by calling the Delete endpoint. The integrator must be aware that if a negotiation event is deleted from Suite by a user, Pactum's API will respond with HTTP 404 to attempts to get results or details for this negotiation event. Only negotiation events with status `DRAFT` can be deleted.

| Endpoint                                                                                  |
| ----------------------------------------------------------------------------------------- |
| `DELETE /procurement/v1/workspaces/{workspaceId}/negotiation-events/{negotiationEventId}` |

## Multi-supplier negotiatons

In situations where different suppliers are competing for the same line-items (e.g. a sourcing event), Pactum will conduct multiple negotiations in parallel. After the event has concluded, Pactum will automatically determine the winner based on the best offer. If the buyer would like to choose a different supplier, then the integration should call the endpoint "Select winning supplier".

To be able to compare offers, Pactum uses the concept of a baseline, which is by default the lowest bid from the suppliers. The buyer has the possibility to change the baseline, for example to the last supplier these goods were purchased from. To do this, the integration should call "Select baseline supplier" endpoint.

These two aspects are important for correctly and accurately reflect the savings achieved.

| Endpoints                                                                                               |
| ------------------------------------------------------------------------------------------------------- |
| `POST /procurement/v1/workspaces/{workspaceId}/negotiation-events/{negotiationEventId}/select-baseline` |
| `POST /procurement/v1/workspaces/{workspaceId}/negotiation-events/{negotiationEventId}/select-winner`   |
