Request for Quotation API

1. Overview

Jakamo Request for Quotation UBL API (RFQ UBL API) is an XML-based (UBL 2.3) API for sending offer requests from the customer system and sharing them with a supplier via Jakamo. The API is part of the Jakamo Buyer API v2 and it accepts standard UBL 2.3 RequestForQuotation documents.

The API can create a new RFQ, update an existing RFQ, and add attachments to an RFQ. For retrieving suppliers' offers see (see 6.4 Retrieving suppliers' offers).

The same functionality is available in JSON format through the Jakamo Buyer API (JSON), which supports a wider set of RFQ features. See 9. UBL API compared with the JSON API.

If you already have an integration against the earlier Jakamo UBL RFQ API, see 10. Migration from the earlier UBL RFQ API.

1.1 Requirements how to get started

Request demo accounts from Jakamo Support Team (support@thejakamo.com) to create an RFQ integration from your system.

There are two similar Jakamo environments available for you: the test environment and the production environment.

Test environment is for testing purposes. Start your integration testing and user training in a test environment.
Production environment is for the live use with other Jakamo companies.

In addition to the integration itself, the RFQ UBL API requires that

a Buyer API integration is enabled for your Jakamo company account,
an OAuth2.0 application is connected to that integration and granted the RFQ write credential,
a company mapping table is created and connected to the integration, and
user mappings are defined for every person who will act as the author of an RFQ.

Without a connected mapping table the API cannot identify suppliers or business units, and every request fails.

1.2 Steps to go to production

The transition from the Jakamo test environment to the Jakamo production environment requires the following actions:

1. Production account establishment in Jakamo

Create the Jakamo production account via the Jakamo registration page. Please ensure that there is only one production account existing for your company in Jakamo (avoid creating a double account).

2. RFQ integration activation

Ask Jakamo Support Team (support@thejakamo.com) to activate the Buyer API integration for you in the production environment. After the integration is available in the Jakamo production account, the Integrations page appears in the dropdown menu in the Jakamo user interface. The integration settings page is available for company admin users.

3. API authentication

Register an OAuth2.0 application in the Jakamo production account and connect it to the Buyer API integration. Make sure the application is granted the RFQ write credential. Please ensure using different credentials in each enabled integration in use.

4. User and company mappings configuration in Jakamo

Define user and company mappings on the Jakamo Integrations page.

5. Message endpoint configuration

Change messages' endpoint configurations from demo to production (see Jakamo RFQ UBL API endpoints).

6. Everything is ready!

You can now send requests for quotations to your suppliers through Jakamo.

2. Authorization

Jakamo RFQ UBL API uses OAuth2.0 as the authentication method. Every request must carry a valid access token:

Authorization: Bearer <access_token>

The OAuth2.0 application must

be connected to a Buyer API integration of your Jakamo company, and
be granted the RFQ write credential.

Jakamo resolves the integration and the buyer company from the access token. If the token is missing, expired or invalid, the API returns 401 Unauthorized. If the token is valid but the RFQ write credential is not granted, the API returns 403 Forbidden.

The RFQ is created in Jakamo on behalf of the author person identified in the XML message (see 7.2 Buyer party), not on behalf of the OAuth2.0 application.

3. RFQ UBL API endpoints

Jakamo environment	Operation	HTTP request	Jakamo API endpoint
Test environment	Create new RFQ	POST	https://demo.thejakamo.com/api/v2/buyer/ubl/rfqs
Test environment	Update existing RFQ	PUT	https://demo.thejakamo.com/api/v2/buyer/ubl/rfqs
Test environment	Add attachments to an RFQ	POST	https://demo.thejakamo.com/api/v2/buyer/ubl/rfqs/attachments
Production environment	Create new RFQ	POST	https://www.thejakamo.com/api/v2/buyer/ubl/rfqs
Production environment	Update existing RFQ	PUT	https://www.thejakamo.com/api/v2/buyer/ubl/rfqs
Production environment	Add attachments to an RFQ	POST	https://www.thejakamo.com/api/v2/buyer/ubl/rfqs/attachments

Request headers for the create and update operations:

Header	Required	Description
`Authorization`	yes	`Bearer <access_token>`
`Content-Type`	yes	`application/xml` or `text/xml`. The body is always read as UTF-8.
`X-Correlation-Id`	no	Your own tracking identifier. It is returned in the response body. If it is omitted, Jakamo generates one.

An OpenAPI description of these endpoints is available at https://demo.thejakamo.com/swagger/buyer-ubl/swagger.json ("Jakamo Buyer API (UBL XML)"). You can open it for example in Postman, or use it to generate a client with OpenAPI tooling.

4. Request response messages

Jakamo RFQ UBL API always returns an HTTP response status code and an XML response body. A successfully created RFQ returns 201 Created, a successfully updated RFQ returns 200 OK. Errors are returned as RFC 7807 problem documents with the content type application/problem+xml.

4.1 Successful response

<SuccessResponse>
  <message>RFQ successfully created</message>
  <resourceIdentifier>OFFER_REQUEST_ID</resourceIdentifier>
  <correlationId>7c9f1a2e-2f4b-4c1e-9c0f-2a1b3c4d5e6f</correlationId>
</SuccessResponse>

message – RFQ successfully created (POST) or RFQ successfully updated (PUT).
resourceIdentifier – the RFQ number taken from RequestForQuotation/ID.
correlationId – the value of your X-Correlation-Id header, or a Jakamo generated identifier.

4.2 Error response

<problem xmlns="urn:ietf:rfc:7807">
  <type>https://tools.ietf.org/html/rfc7231#section-6.5.1</type>
  <title>Validation Error</title>
  <status>400</status>
  <detail>One or more validation errors occurred</detail>
  <instance>/api/v2/buyer/ubl/rfqs</instance>
  <correlationId>7c9f1a2e-2f4b-4c1e-9c0f-2a1b3c4d5e6f</correlationId>
  <errors>
    <error>
      <field>Currency</field>
      <message>Currency is required</message>
    </error>
    <error>
      <field>organizations</field>
      <message>Cannot find match for organization string: SELLER_ID</message>
    </error>
  </errors>
</problem>

The <errors> list is present for schema validation errors and for message validation errors. field is either the name of the failing field, the literal schema for XSD errors, or persons / organizations for failing mapping lookups.

4.3 Response status codes

The table below presents the most common API request responses from Jakamo RFQ UBL API.

HTTP response status code	Response body `title`	Additional information
201 Created	`RFQ successfully created`	New RFQ created and published to the supplier.
200 OK	`RFQ successfully updated`	Existing RFQ updated.
400 Bad request	`Invalid Request`	The request body was empty or could not be read.
400 Bad request	`XSD Schema Validation Error`	The XML is not valid UBL 2.3. Each `<error>` names the line number and the schema violation. Check the element names, namespaces and element order (see 5. UBL document requirements).
400 Bad request	`UBL Conversion Error`	The document could not be read as a UBL `RequestForQuotation` – for example a wrong root element, a wrong namespace or an unparseable date value.
400 Bad request	`Validation Error`, `field` = field name	A field is missing or its value is rejected by Jakamo. See 7.7 Content validation rules.
400 Bad request	`Validation Error`, `field` = `organizations`, message `Cannot find match for organization string: X`	No relationship was found between the buyer and the supplier party, or the buyer business unit is unknown. Check that you have the correct company mapping in `RequestForQuotation/SellerSupplierParty/Party/PartyIdentification/ID` and in `RequestForQuotation/OriginatorCustomerParty/Party/PartyIdentification/ID`.
400 Bad request	`Validation Error`, `field` = `persons`, message `Cannot find match for person string: X`	Mapping is missing for the author person or a contact person. Check the user mapping for `RequestForQuotation/OriginatorCustomerParty/Party/Contact`.
401 Unauthorized	`Unauthorized`	Authentication failed because of a missing, expired or invalid access token, or because the token does not identify a Buyer API integration. Make sure you use the OAuth2.0 application connected to the Buyer API integration.
403 Forbidden	`Forbidden`	The RFQ write credential is not granted to the OAuth2.0 application.
404 Not found	`Not Found`	PUT only: no RFQ, or more than one RFQ, was found with the given `RequestForQuotation/ID`.
409 Conflict	`Conflict`	The RFQ cannot be modified in its current state.
422 Unprocessable entity	`Unprocessable Entity`	The message was well-formed and the parties were identified, but Jakamo could not process it. See `detail` for the reason.
503 Service unavailable	`Service Unavailable`	Jakamo is temporarily unable to process the request. Retry later.
500 Internal server error	`Internal Server Error`	An error occurred in Jakamo. Report the `correlationId` to Jakamo support.

If a 4xx status code is returned, do not retry the request without modification. If a 5xx status code is returned the request may be retried, preferably with an exponential backoff strategy. If 429 Too many requests is returned, honour the Retry-After header.

5. UBL document requirements

The message must be a schema-valid UBL 2.3 RequestForQuotation document. Jakamo validates every incoming document against the official OASIS UBL 2.3 XSD schemas before reading any field, so a document that is not schema-valid is rejected with 400 XSD Schema Validation Error.

Namespaces. The root element must be RequestForQuotation in the UBL RequestForQuotation namespace:

<RequestForQuotation
    xmlns="urn:oasis:names:specification:ubl:schema:xsd:RequestForQuotation-2"
    xmlns:cac="urn:oasis:names:specification:ubl:schema:xsd:CommonAggregateComponents-2"
    xmlns:cbc="urn:oasis:names:specification:ubl:schema:xsd:CommonBasicComponents-2">

Element order. UBL schemas use ordered sequences, so elements must appear in the order defined by the schema. The order used in the examples in section 6 is correct. Reordering elements causes an XSD validation error.

Elements required by the UBL 2.3 schema. cbc:IssueDate, cbc:IssueTime, cac:SellerSupplierParty and at least one cac:RequestForQuotationLine. Jakamo additionally requires the fields listed in 7.7 Content validation rules.

Unknown and unused elements. Elements that are not part of the UBL 2.3 schema are rejected. Elements that are valid UBL but not listed in 7. RFQ message field reference are accepted and ignored — they are not stored and not shown to the supplier.

Encoding. The body is always read as UTF-8, regardless of the charset parameter of the Content-Type header or of the XML declaration.

6. Request for quotation process in Jakamo

6.1 Create new RFQ

The customer creates a new offer request in Jakamo and shares it with a supplier by posting a RequestForQuotation message to the Jakamo RFQ UBL API. The RFQ is published to the supplier immediately when the message is accepted.

One UBL document is shared with one supplier. If the same offer request needs to be sent to several suppliers, post one document per supplier with a different RequestForQuotation/ID, or use the JSON API, which supports several suppliers on one RFQ.

Example: Creating a new RFQ (Offer request) to Jakamo (HTTP POST)

<?xml version="1.0" encoding="UTF-8"?>
<RequestForQuotation xmlns="urn:oasis:names:specification:ubl:schema:xsd:RequestForQuotation-2"
          xmlns:cac="urn:oasis:names:specification:ubl:schema:xsd:CommonAggregateComponents-2"
          xmlns:cbc="urn:oasis:names:specification:ubl:schema:xsd:CommonBasicComponents-2">
    <!-- UBLVersionID and CustomizationID are accepted but not used by Jakamo -->
    <cbc:UBLVersionID>2.3</cbc:UBLVersionID>
    <cbc:CustomizationID>Jakamo</cbc:CustomizationID>
    <!-- RFQ number. Identifies the RFQ in updates and in attachment uploads -->
    <cbc:ID>OFFER_REQUEST_ID</cbc:ID>
    <cbc:CopyIndicator>false</cbc:CopyIndicator>
    <!-- IssueDate and IssueTime are required by the UBL schema, but not used by Jakamo -->
    <cbc:IssueDate>2026-01-13</cbc:IssueDate>
    <cbc:IssueTime>09:00:00</cbc:IssueTime>
    <!-- Offer due date. Required, must be today or in the future -->
    <cbc:SubmissionDueDate>2026-02-13</cbc:SubmissionDueDate>
    <!-- Becomes both the title and the description of the RFQ -->
    <cbc:Note>Bolts and washers for assembly line 3</cbc:Note>
    <!-- Currency of the RFQ. Required, ISO 4217 -->
    <cbc:PricingCurrencyCode>EUR</cbc:PricingCurrencyCode>
    <!-- Project number. Only read when DocumentTypeCode is PROJECT -->
    <cac:AdditionalDocumentReference>
        <cbc:ID>PROJECT_REF_1</cbc:ID>
        <cbc:DocumentTypeCode>PROJECT</cbc:DocumentTypeCode>
    </cac:AdditionalDocumentReference>
    <!-- Buyer: owning business unit and the author of the RFQ -->
    <cac:OriginatorCustomerParty>
        <cac:Party>
            <cac:PartyIdentification>
                <cbc:ID>BUYER_PARTY_ID</cbc:ID>
            </cac:PartyIdentification>
            <cac:Contact>
                <cbc:ID>USER_ID</cbc:ID>
            </cac:Contact>
        </cac:Party>
    </cac:OriginatorCustomerParty>
    <!-- Supplier the RFQ is shared with. Exactly one supplier per document -->
    <cac:SellerSupplierParty>
        <cac:Party>
            <cac:PartyIdentification>
                <cbc:ID>SELLER_ID</cbc:ID>
            </cac:PartyIdentification>
            <!-- Optional supplier side contact person -->
            <cac:Contact>
                <cbc:ElectronicMail>sales@supplier.example</cbc:ElectronicMail>
            </cac:Contact>
        </cac:Party>
    </cac:SellerSupplierParty>
    <cac:RequestForQuotationLine>
        <!-- Line identifier. Must be unique inside the document -->
        <cbc:ID>1</cbc:ID>
        <!-- Additional information shown to the supplier for this line -->
        <cbc:Note>Zinc plated, grade 8.8</cbc:Note>
        <cac:LineItem>
            <!-- Buyer's item number -->
            <cbc:ID>BUYERS_ITEM_ID</cbc:ID>
            <!-- Requested quantity and unit of measure -->
            <cbc:Quantity unitCode="PCE">100</cbc:Quantity>
            <cac:Delivery>
                <!-- Requested delivery date -->
                <cac:RequestedDeliveryPeriod>
                    <cbc:StartDate>2026-03-28</cbc:StartDate>
                </cac:RequestedDeliveryPeriod>
            </cac:Delivery>
            <cac:Item>
                <cbc:Description>Hex bolt M12x40</cbc:Description>
                <cbc:Name>ITEM NAME</cbc:Name>
                <!-- Supplier's item number -->
                <cac:SellersItemIdentification>
                    <cbc:ID>SELLERS_ITEM_ID</cbc:ID>
                </cac:SellersItemIdentification>
            </cac:Item>
        </cac:LineItem>
    </cac:RequestForQuotationLine>
</RequestForQuotation>

6.2 Update RFQ

The customer can update an offer request already posted to Jakamo. Use the same body message and change the HTTP request to use the PUT method. The RFQ is identified by RequestForQuotation/ID; if no RFQ or more than one RFQ matches that number, the API returns 404 Not Found.

An update replaces the whole RFQ and re-publishes it

The update is a full replace: the RFQ is rebuilt from the message you send. Lines that are not present in the message are removed. Always send the complete RFQ content in the update message.

Example: Updating a RFQ (Offer request) already existing in Jakamo (HTTP PUT)

<?xml version="1.0" encoding="UTF-8"?>
<RequestForQuotation xmlns="urn:oasis:names:specification:ubl:schema:xsd:RequestForQuotation-2"
          xmlns:cac="urn:oasis:names:specification:ubl:schema:xsd:CommonAggregateComponents-2"
          xmlns:cbc="urn:oasis:names:specification:ubl:schema:xsd:CommonBasicComponents-2">
    <cbc:UBLVersionID>2.3</cbc:UBLVersionID>
    <cbc:CustomizationID>Jakamo</cbc:CustomizationID>
    <!-- Same RFQ number as in the original message. This identifies the RFQ to update -->
    <cbc:ID>OFFER_REQUEST_ID</cbc:ID>
    <cbc:CopyIndicator>false</cbc:CopyIndicator>
    <cbc:IssueDate>2026-01-20</cbc:IssueDate>
    <cbc:IssueTime>09:00:00</cbc:IssueTime>
    <!-- Due date moved forward -->
    <cbc:SubmissionDueDate>2026-02-28</cbc:SubmissionDueDate>
    <cbc:Note>Bolts and washers for assembly line 3 - revised quantities</cbc:Note>
    <cbc:PricingCurrencyCode>EUR</cbc:PricingCurrencyCode>
    <cac:AdditionalDocumentReference>
        <cbc:ID>PROJECT_REF_1</cbc:ID>
        <cbc:DocumentTypeCode>PROJECT</cbc:DocumentTypeCode>
    </cac:AdditionalDocumentReference>
    <cac:OriginatorCustomerParty>
        <cac:Party>
            <cac:PartyIdentification>
                <cbc:ID>BUYER_PARTY_ID</cbc:ID>
            </cac:PartyIdentification>
            <cac:Contact>
                <cbc:ID>USER_ID</cbc:ID>
            </cac:Contact>
        </cac:Party>
    </cac:OriginatorCustomerParty>
    <cac:SellerSupplierParty>
        <cac:Party>
            <cac:PartyIdentification>
                <cbc:ID>SELLER_ID</cbc:ID>
            </cac:PartyIdentification>
        </cac:Party>
    </cac:SellerSupplierParty>
    <!-- All lines must be included: the RFQ is fully replaced by this message -->
    <cac:RequestForQuotationLine>
        <cbc:ID>1</cbc:ID>
        <cbc:Note>Zinc plated, grade 8.8</cbc:Note>
        <cac:LineItem>
            <cbc:ID>BUYERS_ITEM_ID</cbc:ID>
            <cbc:Quantity unitCode="PCE">1000</cbc:Quantity>
            <cac:Delivery>
                <cac:RequestedDeliveryPeriod>
                    <cbc:StartDate>2026-04-01</cbc:StartDate>
                </cac:RequestedDeliveryPeriod>
            </cac:Delivery>
            <cac:Item>
                <cbc:Description>Hex bolt M12x40</cbc:Description>
                <cbc:Name>ITEM NAME</cbc:Name>
                <cac:SellersItemIdentification>
                    <cbc:ID>SELLERS_ITEM_ID</cbc:ID>
                </cac:SellersItemIdentification>
            </cac:Item>
        </cac:LineItem>
    </cac:RequestForQuotationLine>
</RequestForQuotation>

6.3 Add attachments to an RFQ

Files can be attached to an existing RFQ. The attachment endpoint is not an XML endpoint: it takes a multipart/form-data request and returns a JSON response.

POST /api/v2/buyer/ubl/rfqs/attachments

Form field	Type	Required	Description
`rfqNumber`	text	yes	The RFQ number, that is, the value sent in `RequestForQuotation/ID`.
`authorPersonIdentifier`	text	yes	The user mapping string of the person who adds the attachments. The same strings are used as in `OriginatorCustomerParty/Party/Contact/ID`.
files	file	yes, one or more	The files to attach.

Example: Adding attachments to an existing RFQ (HTTP POST)

POST /api/v2/buyer/ubl/rfqs/attachments HTTP/1.1
Host: demo.thejakamo.com
Authorization: Bearer <access_token>
Content-Type: multipart/form-data; boundary=----Boundary

------Boundary
Content-Disposition: form-data; name="rfqNumber"

OFFER_REQUEST_ID
------Boundary
Content-Disposition: form-data; name="authorPersonIdentifier"

USER_ID
------Boundary
Content-Disposition: form-data; name="files"; filename="drawing.pdf"
Content-Type: application/pdf

<binary content>
------Boundary--

Response:

{
  "message": "Attachments uploaded successfully",
  "rfqNumber": "OFFER_REQUEST_ID",
  "fileCount": 1
}

Responses of the attachment endpoint:

HTTP response status code	Additional information
200 OK	All files were attached to the RFQ.
400 Bad request	`rfqNumber`, `authorPersonIdentifier` or the files are missing, or the person identifier has no user mapping.
404 Not found	No RFQ, or more than one RFQ, was found with the given RFQ number.
500 Internal server error	One or more files could not be attached. The upload is not atomic: some files may have been attached even when this code is returned. Check the RFQ in Jakamo before retrying.
503 Service unavailable	Jakamo is temporarily unable to process the request.

6.4 Retrieving suppliers' offers

This is an upcoming feature and will be made available in Q3 2026.

7. RFQ message field reference

This section lists everything Jakamo reads from the RequestForQuotation message and what each field does. Elements that are not listed here are not used.

7.1 Document header

UBL element	Used as	Description
`RequestForQuotation/ID`	RFQ number	Identifies the RFQ. Used to find the RFQ when it is updated and when attachments are added. Required, maximum 100 characters. Should be unique inside your company.
`RequestForQuotation/Note`	RFQ title and description	Shown to the supplier as the name and the description of the RFQ. Only the first `Note` element is read. Maximum 500 characters for the title, 5000 for the description. If no `Note` is given, the RFQ number is used as the title and the description is left empty.
`RequestForQuotation/PricingCurrencyCode`	Currency	The currency the supplier quotes in. Required, three uppercase letters (ISO 4217), for example `EUR`.
`RequestForQuotation/SubmissionDueDate`	Offer due date	The deadline for the supplier to submit the quotation. Required, must be today or in the future.
`RequestForQuotation/AdditionalDocumentReference/ID`	Project number	Read only from the first `AdditionalDocumentReference` element, and only when its `DocumentTypeCode` is exactly `PROJECT`. Maximum 100 characters.
`RequestForQuotation/AdditionalDocumentReference/DocumentTypeCode`	Selector	Must be `PROJECT` for the project number to be read.

7.2 Buyer party – author and owning business unit

The buyer is identified in RequestForQuotation/OriginatorCustomerParty.

UBL element	Used as	Description
`OriginatorCustomerParty/Party/PartyIdentification/ID`	Owning business unit	The company or business unit that owns the RFQ in Jakamo. Must match a company mapping on the Integrations page. Only the first `PartyIdentification` is read. Required in practice.
`OriginatorCustomerParty/Party/Contact/ID`	Author person	The Jakamo user who is shown as the author of the RFQ and on whose behalf the RFQ is created. Must match a user mapping on the Integrations page. This is the recommended way to identify the author.
`OriginatorCustomerParty/Party/Contact/ElectronicMail`	Author person (fallback)	Used as the author identifier when `Contact/ID` is not given. Must be a valid email address and must match a user mapping.
`OriginatorCustomerParty/Party/Contact/Name`	Author person (fallback), and buyer responsible person	Used as the author identifier when neither `Contact/ID` nor `Contact/ElectronicMail` is given. In addition, whenever `Contact/Name` is present it is used as a buyer-side responsible person on the RFQ.
`OriginatorCustomerParty/Party/PartyName/Name`	–	Accepted, not used. Companies are always identified by `PartyIdentification/ID`.

The contact name must also be mapped

The buyer contact is read twice: once as the author of the RFQ and once as a responsible person. The author is taken from Contact/ID (or the email, or the name), while the responsible person prefers Contact/Name and falls back to Contact/ElectronicMail. If you send both Contact/ID and Contact/Name, both strings must exist as user mappings, otherwise the request fails with Cannot find match for person string. The simplest configuration is to send only Contact/ID.

7.3 Supplier party

The supplier is identified in RequestForQuotation/SellerSupplierParty. Exactly one supplier can be given per document.

UBL element	Used as	Description
`SellerSupplierParty/Party/PartyIdentification/ID`	Supplier	The supplier the RFQ is shared with. Must match a company mapping on the Integrations page. Only the first `PartyIdentification` is read. Required.
`SellerSupplierParty/Party/Contact/ID`	Supplier contact person	Optional. The supplier-side contact person for the RFQ. Must match a user mapping.
`SellerSupplierParty/Party/Contact/ElectronicMail`	Supplier contact person (fallback)	Used when `Contact/ID` is not given. Must be a valid email address and must match a user mapping.
`SellerSupplierParty/Party/Contact/Name`	Supplier contact person (fallback)	Used when neither `Contact/ID` nor `Contact/ElectronicMail` is given. Must match a user mapping.
`SellerSupplierParty/Party/PartyName/Name`	–	Accepted, not used.

7.4 RFQ lines

Each RequestForQuotation/RequestForQuotationLine becomes one requested item on the RFQ. A line that has no LineItem, or whose LineItem has no Item, is skipped without an error.

UBL element (inside `RequestForQuotationLine`)	Used as	Description
`ID`	Line identifier	Identifies the line inside the RFQ and binds the supplier's answers to it. Must be unique inside the document, maximum 100 characters. If it is omitted, Jakamo generates `ITEM_1`, `ITEM_2`, … which makes later updates unreliable, so always send it.
`Note`	Additional information	Free text shown to the supplier for this line. Only the first `Note` is read. Maximum 5000 characters.
`LineItem/ID`	Buyer's item number	Your item number for the requested item. Maximum 100 characters.
`LineItem/Quantity`	Requested quantity	The quantity the supplier quotes. Must be greater than zero. One quantity per line.
`LineItem/Quantity/@unitCode`	Unit of measure	For example `PCE`, `PCS`, `NIU`, `SET`. Passed to Jakamo as given, maximum 20 characters.
`LineItem/Delivery/RequestedDeliveryPeriod/StartDate`	Requested delivery date	The delivery date requested for the line. Must be today or in the future. Only the first `Delivery` element is read, and only `StartDate`.
`LineItem/Item/Description`	Item description	Description shown to the supplier. Only the first `Description` is read. Maximum 2000 characters.
`LineItem/Item/Name`	Item name	Maximum 500 characters.
`LineItem/Item/SellersItemIdentification/ID`	Supplier's item number	The supplier's own item number for the item. Maximum 100 characters. Alternatively `Item/CatalogueItemIdentification/ID` with `schemeID="VN"` can be used.

7.5 Values Jakamo sets automatically

Value	Behaviour
Publishing	The RFQ is always published to the supplier when the message is accepted, both on create and on update. There is no way to create a draft RFQ through the UBL API.
Questions to suppliers	Never set. UBL 2.3 has no standard representation for RFQ questions. Use the JSON API if you need questions.
Requested properties	Left to the Jakamo default, which defines the fields the supplier is asked to fill in, such as price and lead time.
Provided properties	Derived from the message: the supplier always sees the buyer's item number, item name, quantity and unit, plus the description, additional information, requested delivery date and supplier's item number for those fields that are present in the message.

7.6 Elements that are not read

The following elements are valid UBL 2.3 and are accepted by the API, but Jakamo does not read them. They are listed so that you can be sure they will have no effect on the RFQ.

UBL element	Note
`UBLVersionID`, `CustomizationID`, `ProfileID`, `UUID`, `CopyIndicator`, `LineCountNumeric`	Document metadata.
`IssueDate`, `IssueTime`	Required by the UBL schema, not used by Jakamo.
`BuyerCustomerParty`	Use `OriginatorCustomerParty` for the buyer party.
`AdditionalDocumentReference` with any `DocumentTypeCode` other than `PROJECT`	Only the project number is read from additional document references.
`ProjectReference`	Use `AdditionalDocumentReference` with `DocumentTypeCode` = `PROJECT`.
`RequestForQuotationLine/DocumentReference`, for example a contract reference	Contract numbers cannot be set through the UBL API.
`LineItem/LineExtensionAmount`, `LineItem/Price`, `LineItem/AllowanceCharge`, `LineItem/PricingReference`	No price, base quantity or discount information is read from an RFQ.
`RequestedDeliveryPeriod/EndDate` and `DurationMeasure`, second and further `Delivery` elements	Only the first `Delivery` and its `StartDate` are read.
`Item/BuyersItemIdentification`, including `ExtendedID`	The buyer's item number comes from `LineItem/ID`. Item revision cannot be set through the UBL API.
`Item/ItemSpecificationDocumentReference`, for example a drawing number	Drawing numbers cannot be set through the UBL API.
`Item/CommodityClassification`, `Item/OriginCountry`, `Item/ClassifiedTaxCategory`, `Item/AdditionalInformation`, `Item/Keyword`	Not used.
Document level `Delivery`, `DeliveryTerms`, `DestinationCountry`, `Contract`, `RequestedValidityPeriod`, `Signature`, `UBLExtensions`	Not used.
`LineItem/MinimumQuantity`, `LineItem/MaximumQuantity` and other line quantities	Only `Quantity` is read. Annual volume, minimum order quantity and price list group are available in the JSON API only.

7.7 Content validation rules

After the message has passed XSD validation, Jakamo validates the content. A failure returns 400 Validation Error with the field name in the <field> element.

Field	Rule
RFQ number (`ID`)	Required, maximum 100 characters.
Title (first `Note`, or `ID`)	Required, maximum 500 characters.
Description (first `Note`)	Maximum 5000 characters.
Project number	Maximum 100 characters.
Currency (`PricingCurrencyCode`)	Required, exactly three uppercase letters.
Offer due date (`SubmissionDueDate`)	Required, today or later.
Author person	Required, and must match a user mapping.
Supplier	Required, and must match a company mapping.
Line identifiers	Unique inside the document, maximum 100 characters each.
Requested quantity	Greater than zero.
Requested delivery date	Today or later.
Unit of measure	Maximum 20 characters.
Item description / name / supplier's item number / buyer's item number	Maximum 2000 / 500 / 100 / 100 characters.
Line additional information	Maximum 5000 characters.
Every identifier	Maximum 500 characters. Email identifiers must be valid email addresses.

7.8 Identifier schemes

By default the identifiers you send in PartyIdentification/ID and Contact/ID are treated as mapping table entries, that is, as the strings you have configured on the Jakamo Integrations page. The optional schemeID attribute can be used to state that the identifier is a standard business identifier instead:

`schemeID` on `PartyIdentification/ID`	Interpreted as
`GLN`	Global Location Number
`DK:CVR`	Danish CVR number
`DK:SE`	Danish SE number
omitted or any other value	Mapping table entry

`schemeID` on `Contact/ID`	Interpreted as
`EMAIL`	Email address of the Jakamo user
omitted or any other value	Mapping table entry

The value of schemeID is compared case-insensitively.

note

Whichever scheme you use, the identifier string itself must exist in your Jakamo integration mappings — the scheme only describes what kind of identifier it is. Do not use schemeID="GLN" on Contact/ID: a person cannot be identified by a GLN and the message is rejected.

8. User and company mappings in the Jakamo integration settings

Mapping configurations to identify the buyer, the author and the supplier in Jakamo are made in the Jakamo user interface on the Integrations page. Integration settings are available for you after the integration is activated for you in the Jakamo test environment and Jakamo production environment by Jakamo. See Jakamo's general integration mappings instructions from the User Guide.

Both a user mapping and a company mapping are required. The company mappings are kept in a mapping table that must be connected to the Buyer API integration on the Integrations page; if no mapping table is connected, every request fails.

8.1 User mapping – Map your ERP users to your Jakamo users

ERP users (buyers, purchasers, supplier responsibles) who will create offer requests via Jakamo must have their personal user accounts in Jakamo. A user has to have some identifier (string, email address, username, buyer number…) in the ERP, and that identifier will be transferred in the RFQ XML data (RequestForQuotation/OriginatorCustomerParty/Party/Contact/ID). This ERP identifier must be linked to the Jakamo user so that Jakamo can identify the author of the message. The RFQ integration requires passing this user information in the RFQ message when creating a new RFQ or updating an existing RFQ.

Create the required user mappings on the Integrations page. From that page can be found all the integrations in use. Under the User Strings, click ADD USER and create user mappings between Jakamo users and users in the ERP system. To be able to add a mapping, the user has to have a personal user account in Jakamo.

User identifier refers to the identifier string that you send in RequestForQuotation/OriginatorCustomerParty/Party/Contact/ID.
Jakamo account refers to the user's account in Jakamo. The Jakamo account dropdown includes the users who have their user accounts established in Jakamo.

The same user strings are used for the supplier-side contact person and for the authorPersonIdentifier field of the attachment endpoint.

8.2 Vendor mapping – Map your ERP suppliers to Jakamo companies

A relationship with the supplier company in Jakamo has to be established before any messages can be sent via Jakamo. A supplier has to have some identifier (string, for example a vendor number) in the ERP, and it will be transferred in the XML data (RequestForQuotation/SellerSupplierParty/Party/PartyIdentification/ID). This ERP identifier must be linked to the Jakamo company so that Jakamo can identify the receiving party.

Create company mappings on the Integrations page. From that page can be found all the integrations in use. Under the Company Strings, click ADD COMPANY and create a mapping between your ERP company (a supplier) and the Jakamo relationship. To be able to add a mapping, the relationship with that company has to exist in Jakamo.

Company identifier refers to the identifier string incoming in RequestForQuotation/SellerSupplierParty/Party/PartyIdentification/ID.
Jakamo company refers to the supplier account that needs to be mapped to this supplier identifier. The Jakamo company dropdown menu includes a list of supplier companies your account has a relation established with in Jakamo.

The same company mappings are used for your own business units, which are identified in RequestForQuotation/OriginatorCustomerParty/Party/PartyIdentification/ID.

9. UBL API compared with the JSON API

The RFQ UBL API and the Jakamo Buyer API (JSON) create the same RFQ in Jakamo, but the JSON API supports a wider set of RFQ features.

Feature	UBL API	JSON API
Questions to suppliers, general and per line	Not supported	Supported
Several requested quantities (quantity tiers) per line	Not supported, one quantity per line	Supported
Annual volume, minimum order quantity, price list group, contract number, item revision, drawing number, technical specifications	Not supported	Supported
Choosing the fields the supplier is asked to fill in	Not supported, Jakamo default is used	Supported
Creating an unpublished draft RFQ	Not supported, always published	Supported
Attachments	Supported	Supported

10. Migration from the earlier UBL RFQ API

This section is for integrations that already send UBL request for quotation messages to the earlier Jakamo RFQ API at /api/rfq. If you are building a new integration, you can skip this section.

The message is still a UBL RequestForQuotation document, but this is a new API rather than a new version of the old one: the endpoint, the authentication, the validation and several element paths have changed. Plan the migration as a rewrite of the message template rather than as a change of the endpoint address.

10.1 Endpoint, authentication and responses

Topic	Earlier UBL RFQ API	This API
Endpoint	`/api/rfq`	`/api/v2/buyer/ubl/rfqs`
Create / update	POST / PUT to the same address	POST / PUT to the same address (unchanged)
Authentication	Basic authentication or OAuth2.0	OAuth2.0 only
Success response	`200 OK`, mostly without a body	`201 Created` on create and `200 OK` on update, always with an XML body naming the RFQ number and the correlation id
Error response	Plain text or a short XML message	RFC 7807 problem document, `application/problem+xml`, with one `<error>` element per problem
Schema validation	Lenient	Strict validation against the official UBL 2.3 XSD schemas. Element order and element names must match the schema.
Reading suppliers' offers	`GET /api/rfq/response` with an incoming message queue and the `x-acknowledge-uri` header	Not available in this API. Offers are visible in the Jakamo user interface.

10.2 Message content that has to change

Purpose	Earlier UBL RFQ API	This API
Author of the RFQ	`BuyerCustomerParty/BuyerContact/ID`	`OriginatorCustomerParty/Party/Contact/ID`
Buyer company or business unit	`BuyerCustomerParty/Party/PartyIdentification/ID`	`OriginatorCustomerParty/Party/PartyIdentification/ID`
Supplier	`SellerSupplierParty/Party/PartyIdentification/ID`	`SellerSupplierParty/Party/PartyIdentification/ID` (unchanged)
Several suppliers on one RFQ	`AdditionalDocumentReference/ID` with `DocumentTypeCode` = `ASSP`, one element per additional supplier	Not supported. Send one document per supplier, each with its own `RequestForQuotation/ID`, or use the JSON API. `ASSP` references are ignored.
Project number	`ProjectReference/ID`	`AdditionalDocumentReference/ID` with `DocumentTypeCode` = `PROJECT`
Currency	Taken from the `currencyID` attributes of the price elements	`PricingCurrencyCode` in the document header. Required.
Offer due date	`SubmissionDueDate`, optional	`SubmissionDueDate`, required and must be today or in the future
Buyer's item number	`LineItem/Item/BuyersItemIdentification/ID`	`LineItem/ID`
Supplier's item number	`LineItem/Item/SellersItemIdentification/ID`	`LineItem/Item/SellersItemIdentification/ID` (unchanged)
Requested delivery date	`LineItem/Delivery/RequestedDeliveryPeriod/EndDate`	`LineItem/Delivery/RequestedDeliveryPeriod/StartDate`
Item revision	`Item/BuyersItemIdentification/ExtendedID`	Not supported in UBL. Available in the JSON API.
Drawing number	`Item/ItemSpecificationDocumentReference/ID` with `DocumentTypeCode` = `174`	Not supported in UBL. Available in the JSON API.
Contract number	`RequestForQuotationLine/DocumentReference/ID` with `DocumentTypeCode` = `315`	Not supported in UBL. Available in the JSON API.
Prices, discounts and line totals	`LineItem/Price`, `LineItem/AllowanceCharge`, `LineItem/LineExtensionAmount`	Not read. An RFQ asks the supplier for prices, so no price information is imported.
RFQ title and description	Taken from `Note`	Taken from `Note` (unchanged). The first `Note` becomes both the title and the description.
Line additional information	`RequestForQuotationLine/Note`	`RequestForQuotationLine/Note` (unchanged)

10.3 Behaviour that has changed

The RFQ is always published. A message accepted by this API is shared with the supplier immediately, both on create and on update.
An update replaces the whole RFQ. Send the complete content in every PUT; lines missing from the message are removed from the RFQ, and the RFQ is published to the supplier again.
Attachments have their own endpoint. Files are no longer part of the RFQ message; use POST /api/v2/buyer/ubl/rfqs/attachments (see 6.3).
UBL version. The namespace URIs are unchanged, but documents are validated against the UBL 2.3 schemas. A document built for UBL 2.1 usually validates, but verify it against the 2.3 schemas before going live. UBLVersionID and CustomizationID are accepted and ignored, so they can be left as they are or removed.

10.4 Migration checklist

Register an OAuth2.0 application and connect it to the Buyer API integration; grant it the RFQ write credential.
Keep your existing user and company mappings — the mapping strings are the same. Verify that the buyer business unit identifier is mapped, since it is now sent in OriginatorCustomerParty.
Rewrite the message template according to 10.2 and validate the result against the UBL 2.3 schemas.
Remove price, discount, contract, drawing and revision elements, or accept that they are ignored.
Split multi-supplier messages into one message per supplier, or move that use case to the JSON API.
Update the response handling: expect 201 Created on create and parse the problem document on errors. Store the correlationId from the response for support requests.
Test the whole flow in the test environment, then repeat the configuration in production.

Help & Support

Didn't you find what you were looking for? Send an email to Jakamo support (support@thejakamo.com) and we will help you.

1. Overview​

1.1 Requirements how to get started​

1.2 Steps to go to production​

1. Production account establishment in Jakamo​

2. RFQ integration activation​

3. API authentication​

4. User and company mappings configuration in Jakamo​

5. Message endpoint configuration​

6. Everything is ready!​

2. Authorization​

3. RFQ UBL API endpoints​

4. Request response messages​

4.1 Successful response​

4.2 Error response​

4.3 Response status codes​

5. UBL document requirements​

6. Request for quotation process in Jakamo​

6.1 Create new RFQ​

6.2 Update RFQ​

6.3 Add attachments to an RFQ​

6.4 Retrieving suppliers' offers​

7. RFQ message field reference​

7.1 Document header​

7.2 Buyer party – author and owning business unit​

7.3 Supplier party​

7.4 RFQ lines​

7.5 Values Jakamo sets automatically​

7.6 Elements that are not read​

7.7 Content validation rules​

7.8 Identifier schemes​

8. User and company mappings in the Jakamo integration settings​

8.1 User mapping – Map your ERP users to your Jakamo users​

8.2 Vendor mapping – Map your ERP suppliers to Jakamo companies​

9. UBL API compared with the JSON API​

10. Migration from the earlier UBL RFQ API​

10.1 Endpoint, authentication and responses​

10.2 Message content that has to change​

10.3 Behaviour that has changed​

10.4 Migration checklist​