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). Both APIs create the same RFQ; questions and requested properties are the only features the UBL API takes from an RFQ template instead of from the message. 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.
Company identifiers are read from the connected mapping table only. Without a connected mapping table the API cannot identify suppliers or business units, and every request fails with 500 Internal Server Error. The older supplier mappings that older integrations keep on the integration itself are not read by this API, see 8. User and company mappings.
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: the user strings on the Jakamo Integrations page, and the company identifiers in a mapping table that you connect to the Buyer API integration.
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 |
| Test environment | Query supplier quotations from queue | GET | https://demo.thejakamo.com/api/v2/queues/quotations |
| 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 |
| Production environment | Query supplier quotations from queue | GET | https://www.thejakamo.com/api/v2/queues/quotations |
The create and update endpoints take a UBL XML body and answer with XML. The attachment endpoint is different: it takes a multipart/form-data request and answers with JSON, see 6.3 Add attachments to an RFQ.
Request headers for the create and update operations:
| Header | Required | Description |
|---|---|---|
Authorization | yes | Bearer <access_token> |
Content-Type | yes | application/xml or text/xml for the create and update endpoints, multipart/form-data for the attachment endpoint. The body is always read as UTF-8, whatever the charset parameter of the header or the XML declaration says. |
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) orRFQ successfully updated(PUT).resourceIdentifier– the RFQ number taken fromRequestForQuotation/ID.correlationId– the value of yourX-Correlation-Idheader, 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: message on success, title on an error | 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 | The identifier has no entry in the mapping table connected to the integration, so the supplier or the buyer business unit is unknown. Check the identifiers you send in RequestForQuotation/SellerSupplierParty/Party/PartyIdentification/ID, in the cac:SellerSupplierParty and jak:Supplier elements of the Jakamo extension, and in RequestForQuotation/OriginatorCustomerParty/Party/PartyIdentification/ID against the entries of that table. Mappings kept on the integration itself are not read, see 8.3. |
| 400 Bad request | Validation Error, message Company not found with email: X | A supplier was given as an email address, but your company has no supplier without a Jakamo account with that email. See 7.3 Supplier party. |
| 400 Bad request | Validation Error, message Company X is not connected to your company in Jakamo | The identifier is mapped, but the company or business unit it points at has no relationship with your company in Jakamo. Either the mapping points at the wrong company, or the relationship has not been established. A mapping that narrows to a business unit needs that business unit to be connected, not only its parent company. |
| 400 Bad request | Validation Error, message Company not found: X | The company mapping points at a company that does not exist in Jakamo. Check the entry in the mapping table. |
| 400 Bad request | Validation Error, message Source rfq not found | The jak:TemplateId of the message does not name a template or an RFQ of your own company. See 6.5 Create an RFQ from a template. |
| 400 Bad request | Validation Error, field = persons, message Cannot find match for person string: X | Mapping is missing for the author person, who is the only person a UBL message names. 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. |
| 429 Too many requests | Too Many Requests | Too many requests in too short a time. Honour the Retry-After header of the response and retry after it. |
| 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. Every request also fails this way when no mapping table is connected to the integration, so check that first (see 8. User and company mappings). |
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. Every line needs a cac:LineItem, and that needs a cbc:ID and a cac:Item. 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.
5.1 Jakamo UBL extension
A few RFQ features have no representation in standard UBL 2.3: several suppliers on one RFQ, suppliers that are not Jakamo companies, leaving the RFQ in draft state instead of publishing it, creating the RFQ from an RFQ template, and three line fields, annual volume, price list group and further requested quantities. These are given in UBL extensions in the Jakamo namespace urn:jakamo:rfq:2, which is the mechanism UBL defines for private extensions. Everything else Jakamo reads is a standard UBL element.
Both extensions are optional. A document without them behaves exactly as a document sent before they existed: one supplier, taken from SellerSupplierParty, and the RFQ is published.
The schema of the extensions is published as jakamo-rfq-2.xsd, so you can validate your messages locally against it together with the OASIS UBL 2.3 schemas. Jakamo does not validate the Jakamo elements of an extension against that schema — it checks them while it reads the message, which gives an error that names the element and the value that is wrong. The UBL elements inside an extension are a different matter, see Validation of the extensions below.
Document extension
<ext:UBLExtensions>
<ext:UBLExtension>
<ext:ExtensionURI>urn:jakamo:rfq:2</ext:ExtensionURI>
<ext:ExtensionContent>
<jak:Rfq xmlns:jak="urn:jakamo:rfq:2">
<!-- Leave the RFQ in draft state instead of publishing it -->
<jak:Publish>false</jak:Publish>
<!-- Create the RFQ from an RFQ template -->
<jak:TemplateId>3fa85f64-5717-4562-b3fc-2c963f66afa6</jak:TemplateId>
<!-- Suppliers in addition to the one in SellerSupplierParty. The UBL party is read
exactly as the SellerSupplierParty of the document itself -->
<cac:SellerSupplierParty>
<cac:Party>
<cac:PartyIdentification>
<cbc:ID>SELLER_2</cbc:ID>
</cac:PartyIdentification>
</cac:Party>
</cac:SellerSupplierParty>
<!-- A supplier that is not a Jakamo company, in the shorter Jakamo form -->
<jak:Supplier>
<cbc:ID schemeID="EMAIL">sales@external.example</cbc:ID>
</jak:Supplier>
</jak:Rfq>
</ext:ExtensionContent>
</ext:UBLExtension>
</ext:UBLExtensions>
ext:UBLExtensions is the first element of the document, before every other element, and the ext prefix is bound to urn:oasis:names:specification:ubl:schema:xsd:CommonExtensionComponents-2.
Give ext:ExtensionURI as urn:jakamo:rfq:2 in every extension you send. That is the element UBL provides for naming an extension, and it is how Jakamo recognises its own: a document can carry extensions of several systems, and each of them is read by the system that owns it. An extension without the URI is still read when its content is jak:Rfq in the Jakamo namespace, so older messages keep working, and extensions of other systems are accepted and ignored.
| Element | Used as | Description |
|---|---|---|
jak:Rfq | – | Container for the Jakamo specific data. Must be the apex element of the extension content. |
jak:Publish | Publishing | true or false (1 and 0 are also accepted). false leaves the RFQ unpublished, so it is not shared with the suppliers and can be reviewed and published in the Jakamo user interface. If the element is omitted, the RFQ is published. |
jak:TemplateId | RFQ template | The identifier (UUID) of the RFQ template the new RFQ is created from, see 6.5 Create an RFQ from a template. Only read when a new RFQ is created. |
cac:SellerSupplierParty | Supplier | One additional supplier, on top of the supplier of the document. The preferred way to give one: it is the UBL element the document itself uses, and it is read by the same code, so Party/PartyIdentification/ID with its schemeID and Party/Contact/ElectronicMail all behave exactly as they do there. Repeat it for every additional supplier. |
jak:Supplier | Supplier | The older and shorter form of the same thing, still read. Repeat it for every additional supplier. |
jak:Supplier/cbc:ID | Supplier identifier | Required, exactly one per supplier. The identifier of the supplier, read the same way as SellerSupplierParty/Party/PartyIdentification/ID. Note that this is the UBL cbc:ID element, not a Jakamo one, so bind the cbc prefix as usual. |
jak:Supplier/cbc:ID/@schemeID | Identifier scheme | Optional, and read exactly as on a party of the document itself: leave it out for a company mapping, or use EMAIL for a supplier that is not a Jakamo company. Any other scheme is rejected. See 7.8 Identifier schemes. |
jak:Supplier/jak:Contact | – | Not supported. Contact persons of a supplier cannot be set through the API, see 7.3 Supplier party. A message that contains this element is rejected. |
Every company and person of a message is identified with a cbc:ID element and its schemeID attribute – PartyIdentification/ID on a party of the document or of the extension, Contact/ID for a person, jak:Supplier/cbc:ID in the short form – so that Jakamo can start accepting a new kind of identifier, a GLN, an OVT identifier or a national business identifier, without a change to the message structure. Only the schemes listed in 7.8 Identifier schemes are accepted today; anything else is rejected with 400 UBL Conversion Error and a message naming the schemes that are supported, rather than being read as a company mapping and failing later with Cannot find match for organization string.
<!-- Rejected today, and the shape a future identifier scheme would take -->
<cac:PartyIdentification>
<cbc:ID schemeID="0216">003712345678</cbc:ID>
</cac:PartyIdentification>
Line extension
The line fields that UBL cannot carry are given per line, in a UBL extension of the RequestForQuotationLine. ext:UBLExtensions is the first element of the line, before cbc:ID.
<cac:RequestForQuotationLine>
<ext:UBLExtensions>
<ext:UBLExtension>
<ext:ExtensionURI>urn:jakamo:rfq:2</ext:ExtensionURI>
<ext:ExtensionContent>
<jak:Line xmlns:jak="urn:jakamo:rfq:2">
<jak:AnnualVolume>10000</jak:AnnualVolume>
<jak:PriceListGroup>FASTENERS-A</jak:PriceListGroup>
<!-- Quote for 100 (the UBL quantity), 500 and 1000 pieces -->
<jak:AdditionalQuantity>500</jak:AdditionalQuantity>
<jak:AdditionalQuantity>1000</jak:AdditionalQuantity>
</jak:Line>
</ext:ExtensionContent>
</ext:UBLExtension>
</ext:UBLExtensions>
<cbc:ID>1</cbc:ID>
<!-- ... -->
<cac:LineItem>
<cbc:Quantity unitCode="H87">100</cbc:Quantity>
<!-- ... -->
</cac:LineItem>
</cac:RequestForQuotationLine>
| Element | Used as | Description |
|---|---|---|
jak:Line | – | Container for the Jakamo specific data of the line. Must be the apex element of the extension content. |
jak:AnnualVolume | Annual volume | Estimated yearly volume of the item, a number with a dot as the decimal separator. Must be greater than zero. The unit is the unit of the line, LineItem/Quantity/@unitCode. |
jak:PriceListGroup | Price list group | Price list group of the item. Maximum 100 characters. |
jak:AdditionalQuantity | Requested quantity | One more quantity the supplier is asked to quote for, on top of LineItem/Quantity, which UBL allows only once per line. Repeat the element for every further quantity. A number with a dot as the decimal separator, greater than zero. The unit is the unit of the line; the element takes no attributes. |
The requested quantities of a line are LineItem/Quantity first, then the jak:AdditionalQuantity elements in document order. The supplier is asked to quote a price for each of them, which is how a quantity discount is asked for.
Validation of the extensions
UBL declares the content of an extension as <xsd:any namespace="##other" processContents="lax">: any element outside the UBL extension namespace is allowed there, and it is validated only if the validator knows a schema for it. That splits the extension in two:
- The Jakamo elements —
jak:Rfq,jak:Line,jak:Publish,jak:TemplateId,jak:Supplierand the line fields — are inurn:jakamo:rfq:2, which the OASIS UBL 2.3 schemas know nothing about, so the XSD validation skips them. Jakamo checks them while it reads the message and rejects a bad one with400 UBL Conversion Error. - A
cac:SellerSupplierPartyinside the extension is a UBL element, and the validator does have its declaration, so it is schema checked, exactly as the party of the document is. A party that is not valid UBL — a misspelled child element, children in the wrong order — is rejected with400 XSD Schema Validation Errorbefore Jakamo reads anything.
Validate your messages against the OASIS UBL 2.3 schemas and jakamo-rfq-2.xsd together, and a malformed Jakamo element and a malformed UBL party are both caught before you send. The content rules below are checked by Jakamo, not by a schema. Jakamo rejects the following with 400 UBL Conversion Error:
- an unknown element inside
jak:Rfq,jak:Supplierorjak:Line, - a
jak:Publishvalue that is not a boolean, - a
jak:TemplateIdvalue that is not a UUID, - a
jak:AnnualVolumeorjak:AdditionalQuantityvalue that is not a number, - a
jak:Supplierwithout acbc:IDelement, with an empty one, or with several of them, - a
cbc:IDwhoseschemeIDis a scheme the extension does not support, - a
jak:Contactinside ajak:Supplier, because supplier contact persons cannot be set through the API, - a
cac:SellerSupplierPartyof the extension without acac:Partyin it, - a supplier of the extension that names no supplier at all, that is, an empty element, or a party with neither an identifier nor an email address,
- a supplier of the extension that carries only a party name, since a name does not identify a company.
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 the suppliers by posting a RequestForQuotation message to the Jakamo RFQ UBL API. The RFQ is published to the suppliers immediately when the message is accepted, unless the message asks for a draft (see 5.1 Jakamo UBL extension).
The first supplier is given in SellerSupplierParty, which UBL 2.3 allows only once per document. Further suppliers are given in the Jakamo UBL extension, each in a cac:SellerSupplierParty of its own — the same UBL element, read by the same rules — or in the shorter jak:Supplier form. A supplier that is not a Jakamo company is identified by an email address instead of a company mapping, see 7.3 Supplier party.
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"
xmlns:ext="urn:oasis:names:specification:ubl:schema:xsd:CommonExtensionComponents-2">
<!-- Optional Jakamo extension: additional suppliers and the publishing state -->
<ext:UBLExtensions>
<ext:UBLExtension>
<ext:ExtensionURI>urn:jakamo:rfq:2</ext:ExtensionURI>
<ext:ExtensionContent>
<jak:Rfq xmlns:jak="urn:jakamo:rfq:2">
<!-- Publish the RFQ to the suppliers. Use false to leave it in draft state -->
<jak:Publish>true</jak:Publish>
<!-- Second supplier, in the preferred form: the same UBL element the document -->
<!-- uses for the first supplier, read by exactly the same rules -->
<cac:SellerSupplierParty>
<cac:Party>
<cac:PartyIdentification>
<cbc:ID>SELLER_ID_2</cbc:ID>
</cac:PartyIdentification>
</cac:Party>
</cac:SellerSupplierParty>
<!-- Third supplier is not a Jakamo company, so it is identified by its email. -->
<!-- jak:Supplier is the shorter Jakamo form of the same thing -->
<jak:Supplier>
<cbc:ID schemeID="EMAIL">sales@external.example</cbc:ID>
</jak:Supplier>
</jak:Rfq>
</ext:ExtensionContent>
</ext:UBLExtension>
</ext:UBLExtensions>
<!-- RFQ number. Identifies the RFQ in updates and in attachment uploads -->
<cbc:ID>OFFER_REQUEST_ID</cbc:ID>
<!-- 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>
<!-- Description of the RFQ. Repeat Note for every line of it -->
<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. DocumentTypeCode PROJECT is accepted as well -->
<cac:AdditionalDocumentReference>
<cbc:ID>PROJECT_REF_1</cbc:ID>
<cbc:DocumentType>Project</cbc:DocumentType>
</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>
<!-- Names are informational: accepted, never read, never mapped -->
<cac:PartyName>
<cbc:Name>Bridgtow District Council, Purchasing</cbc:Name>
</cac:PartyName>
<cac:Contact>
<cbc:ID>USER_ID</cbc:ID>
<cbc:Name>Sam Massiah</cbc:Name>
</cac:Contact>
</cac:Party>
</cac:OriginatorCustomerParty>
<!-- First supplier the RFQ is shared with. Further suppliers go to the Jakamo extension above -->
<cac:SellerSupplierParty>
<cac:Party>
<cac:PartyIdentification>
<cbc:ID>SELLER_ID</cbc:ID>
</cac:PartyIdentification>
<cac:PartyName>
<cbc:Name>Consortial Oy</cbc:Name>
</cac:PartyName>
<!-- Contact persons of the supplier are set in Jakamo, not in the message -->
<!-- Any cac:Contact given here is accepted and ignored -->
</cac:Party>
</cac:SellerSupplierParty>
<cac:RequestForQuotationLine>
<!-- Optional Jakamo line extension: the line fields UBL has no element for -->
<ext:UBLExtensions>
<ext:UBLExtension>
<ext:ExtensionURI>urn:jakamo:rfq:2</ext:ExtensionURI>
<ext:ExtensionContent>
<jak:Line xmlns:jak="urn:jakamo:rfq:2">
<jak:AnnualVolume>10000</jak:AnnualVolume>
<jak:PriceListGroup>FASTENERS-A</jak:PriceListGroup>
<!-- Ask for a price for 100 (below), 500 and 1000 pieces -->
<jak:AdditionalQuantity>500</jak:AdditionalQuantity>
<jak:AdditionalQuantity>1000</jak:AdditionalQuantity>
</jak:Line>
</ext:ExtensionContent>
</ext:UBLExtension>
</ext:UBLExtensions>
<!-- Line number. Optional: Jakamo numbers the lines when it is left out -->
<cbc:ID>10</cbc:ID>
<!-- Additional information shown to the supplier for this line -->
<cbc:Note>Zinc plated, grade 8.8</cbc:Note>
<!-- Contract number. DocumentTypeCode 315 is accepted as well -->
<cac:DocumentReference>
<cbc:ID>CNT-2024-00123</cbc:ID>
<cbc:DocumentType>Contract</cbc:DocumentType>
</cac:DocumentReference>
<cac:LineItem>
<!-- Identifier of the line in your own system. Identifies the line, so an update -->
<!-- that sends the same identifier targets this line -->
<!-- Most commonly this is just the rfq line number in sender system-->
<cbc:ID>10</cbc:ID>
<!-- Requested quantity and unit of measure -->
<cbc:Quantity unitCode="H87">100</cbc:Quantity>
<!-- Minimum order quantity -->
<cbc:MinimumQuantity unitCode="H87">25</cbc:MinimumQuantity>
<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>
<!-- Buyer's item number and the revision of the item -->
<cac:BuyersItemIdentification>
<cbc:ID>BUYERS_ITEM_ID</cbc:ID>
<cbc:ExtendedID>Rev C</cbc:ExtendedID>
</cac:BuyersItemIdentification>
<!-- Drawing number -->
<cac:ItemSpecificationDocumentReference>
<cbc:ID>DWG-12345-03</cbc:ID>
</cac:ItemSpecificationDocumentReference>
<!-- Technical specifications, one element per specification -->
<cac:AdditionalItemProperty>
<cbc:Name>Material</cbc:Name>
<cbc:Value>Stainless steel</cbc:Value>
</cac:AdditionalItemProperty>
</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.
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, and so are suppliers that are not present in the message. Always send the complete RFQ content in the update message.
A line of the message and a line of the RFQ are the same line when they have the same LineItem/ID, so it is that identifier, not the position of the line in the message, that decides which line is updated. A line whose identifier the RFQ does not have is added, and a line of the RFQ whose identifier the message does not carry is removed — send the identifiers you sent when the RFQ was created, or the lines are replaced with new ones, together with their attachments, and the answers the suppliers have already given no longer belong to a line of the RFQ.
Questions are the exception in the other direction: because a UBL message cannot express them, an update never removes the questions the RFQ already has, whether they came from an RFQ template or from the Jakamo user interface.
A message that names no supplier at all is the one exception on the supplier side: the suppliers of the RFQ are then left as they are instead of being removed. The UBL schema requires the cac:SellerSupplierParty element, so "no supplier" means the element with nothing in it:
<cac:SellerSupplierParty />
Use it when you update the lines of an RFQ whose suppliers were chosen in Jakamo, and when you create a draft that a purchaser completes there. Suppliers cannot be removed from an RFQ through the UBL API, only replaced with the ones you send. Note that this only applies to a message that leaves the RFQ in draft state, because a message that publishes the RFQ must name at least one supplier and is otherwise rejected with 400 At least one supplier is required.
The updated RFQ is published to the suppliers again, unless the message sets jak:Publish to false in the Jakamo UBL extension. In that case the changes are stored but left unpublished, and the RFQ waits for a user to publish it in the Jakamo user interface.
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"
xmlns:ext="urn:oasis:names:specification:ubl:schema:xsd:CommonExtensionComponents-2">
<!-- The same message as the create example, with the changed values. Everything the RFQ should -->
<!-- keep is sent again, because the update replaces the whole RFQ -->
<ext:UBLExtensions>
<ext:UBLExtension>
<ext:ExtensionURI>urn:jakamo:rfq:2</ext:ExtensionURI>
<ext:ExtensionContent>
<jak:Rfq xmlns:jak="urn:jakamo:rfq:2">
<jak:Publish>true</jak:Publish>
<!-- All three suppliers again: a supplier left out of the message is removed -->
<cac:SellerSupplierParty>
<cac:Party>
<cac:PartyIdentification>
<cbc:ID>SELLER_ID_2</cbc:ID>
</cac:PartyIdentification>
</cac:Party>
</cac:SellerSupplierParty>
<jak:Supplier>
<cbc:ID schemeID="EMAIL">sales@external.example</cbc:ID>
</jak:Supplier>
</jak:Rfq>
</ext:ExtensionContent>
</ext:UBLExtension>
</ext:UBLExtensions>
<!-- Same RFQ number as in the original message. This identifies the RFQ to update -->
<cbc:ID>OFFER_REQUEST_ID</cbc:ID>
<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:DocumentType>Project</cbc:DocumentType>
</cac:AdditionalDocumentReference>
<cac:OriginatorCustomerParty>
<cac:Party>
<cac:PartyIdentification>
<cbc:ID>BUYER_PARTY_ID</cbc:ID>
</cac:PartyIdentification>
<!-- Names are informational: accepted, never read, never mapped -->
<cac:PartyName>
<cbc:Name>Bridgtow District Council, Purchasing</cbc:Name>
</cac:PartyName>
<cac:Contact>
<cbc:ID>USER_ID</cbc:ID>
<cbc:Name>Sam Massiah</cbc:Name>
</cac:Contact>
</cac:Party>
</cac:OriginatorCustomerParty>
<cac:SellerSupplierParty>
<cac:Party>
<cac:PartyIdentification>
<cbc:ID>SELLER_ID</cbc:ID>
</cac:PartyIdentification>
<cac:PartyName>
<cbc:Name>Consortial Oy</cbc:Name>
</cac:PartyName>
</cac:Party>
</cac:SellerSupplierParty>
<!-- All lines must be included: the RFQ is fully replaced by this message -->
<cac:RequestForQuotationLine>
<!-- The line extension is sent again too: the line fields it carries are replaced as well -->
<ext:UBLExtensions>
<ext:UBLExtension>
<ext:ExtensionURI>urn:jakamo:rfq:2</ext:ExtensionURI>
<ext:ExtensionContent>
<jak:Line xmlns:jak="urn:jakamo:rfq:2">
<jak:AnnualVolume>10000</jak:AnnualVolume>
<jak:PriceListGroup>FASTENERS-A</jak:PriceListGroup>
<jak:AdditionalQuantity>500</jak:AdditionalQuantity>
<jak:AdditionalQuantity>1000</jak:AdditionalQuantity>
</jak:Line>
</ext:ExtensionContent>
</ext:UBLExtension>
</ext:UBLExtensions>
<cbc:ID>10</cbc:ID>
<cbc:Note>Zinc plated, grade 8.8</cbc:Note>
<cac:DocumentReference>
<cbc:ID>CNT-2024-00123</cbc:ID>
<cbc:DocumentType>Contract</cbc:DocumentType>
</cac:DocumentReference>
<cac:LineItem>
<!-- Same identifier as in the original message, so this updates that line -->
<cbc:ID>10</cbc:ID>
<!-- Quantity raised from 100 to 1000 -->
<cbc:Quantity unitCode="H87">1000</cbc:Quantity>
<cbc:MinimumQuantity unitCode="H87">25</cbc:MinimumQuantity>
<cac:Delivery>
<!-- Delivery date moved forward -->
<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:BuyersItemIdentification>
<cbc:ID>BUYERS_ITEM_ID</cbc:ID>
<cbc:ExtendedID>Rev C</cbc:ExtendedID>
</cac:BuyersItemIdentification>
<cac:ItemSpecificationDocumentReference>
<cbc:ID>DWG-12345-03</cbc:ID>
</cac:ItemSpecificationDocumentReference>
<cac:AdditionalItemProperty>
<cbc:Name>Material</cbc:Name>
<cbc:Value>Stainless steel</cbc:Value>
</cac:AdditionalItemProperty>
</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' quotations
Please note that retrieving supplier's orders is an upcoming feature in Q3 2026. Minor modifications to data content are possible before release
Supplier responses can be queried by calling endpoint GET /api/v2/queues/quotations . The endpoint will return first unacknowledged message as an UBL 2.3 quotation message.
The response also contains an x-acknowledge-url header that holds an url that can be used to acknowledge the message after processing.
Example: Retrieving a supplier quotation
<?xml version="1.0" encoding="UTF-8"?>
<!--
Supplier's offer to OFFER_REQUEST_ID, as returned by the Jakamo RFQ UBL API.
Identifiers are the buyer's own: the same mapping table entries, user strings and
line identifiers the buyer sent in the RequestForQuotation message.
-->
<Quotation xmlns="urn:oasis:names:specification:ubl:schema:xsd:Quotation-2"
xmlns:cac="urn:oasis:names:specification:ubl:schema:xsd:CommonAggregateComponents-2"
xmlns:cbc="urn:oasis:names:specification:ubl:schema:xsd:CommonBasicComponents-2"
xmlns:ext="urn:oasis:names:specification:ubl:schema:xsd:CommonExtensionComponents-2"
xmlns:jak="urn:jakamo:rfq:2">
<ext:UBLExtensions>
<ext:UBLExtension>
<ext:ExtensionURI>urn:jakamo:rfq:2</ext:ExtensionURI>
<ext:ExtensionContent>
<jak:Quotation>
<jak:OfferId>9b2e6a10-4c1f-4d2b-8e7a-1f3c5d7e9a21</jak:OfferId>
<!-- Submitted | Awarded | PartiallyAwarded | NotAwarded -->
<jak:Status>PartiallyAwarded</jak:Status>
<jak:SubmittedAt>2026-02-10T14:32:05Z</jak:SubmittedAt>
<jak:AwardedAt>2026-02-17T09:05:41Z</jak:AwardedAt>
<jak:Answer>
<jak:Question>Is your quality system certified to ISO 9001?</jak:Question>
<jak:Value>Yes, certificate FI-12345 valid to 2028-05</jak:Value>
</jak:Answer>
</jak:Quotation>
</ext:ExtensionContent>
</ext:UBLExtension>
</ext:UBLExtensions>
<cbc:UBLVersionID>2.3</cbc:UBLVersionID>
<cbc:CustomizationID>Jakamo</cbc:CustomizationID>
<!-- Supplier's offer number -->
<cbc:ID>Q-2026-0417</cbc:ID>
<cbc:IssueDate>2026-02-10</cbc:IssueDate>
<cbc:IssueTime>14:32:05</cbc:IssueTime>
<!-- Supplier's general remarks. One Note per line of text -->
<cbc:Note>Prices ex works Tampere, packaging included.</cbc:Note>
<cbc:Note>Lead times assume order confirmation within offer validity.</cbc:Note>
<!-- Currency of the RFQ; every amount below is in it -->
<cbc:PricingCurrencyCode>EUR</cbc:PricingCurrencyCode>
<cbc:LineCountNumeric>3</cbc:LineCountNumeric>
<!-- Offer valid until -->
<cac:ValidityPeriod>
<cbc:StartDate>2026-02-10</cbc:StartDate>
<cbc:EndDate>2026-04-30</cbc:EndDate>
</cac:ValidityPeriod>
<!-- The RFQ this offer answers: the buyer's RFQ number, as sent in RequestForQuotation/ID -->
<cac:RequestForQuotationDocumentReference>
<cbc:ID>OFFER_REQUEST_ID</cbc:ID>
<cbc:IssueDate>2026-01-13</cbc:IssueDate>
</cac:RequestForQuotationDocumentReference>
<!-- Supplier. PartyIdentification/ID is the buyer's mapping table entry for this supplier,
the same value the buyer sent. Contact is the supplier user who submitted the offer -->
<cac:SellerSupplierParty>
<cac:Party>
<cac:PartyIdentification>
<cbc:ID>SELLER_ID</cbc:ID>
</cac:PartyIdentification>
<cac:PartyName>
<cbc:Name>Consortial Oy</cbc:Name>
</cac:PartyName>
<cac:Contact>
<cbc:Name>Maija Myyjä</cbc:Name>
<cbc:Telephone>+358 40 123 4567</cbc:Telephone>
<cbc:ElectronicMail>maija.myyja@consortial.example</cbc:ElectronicMail>
</cac:Contact>
</cac:Party>
</cac:SellerSupplierParty>
<!-- Buyer, mirrored from the RFQ: owning business unit and the author's user string -->
<cac:OriginatorCustomerParty>
<cac:Party>
<cac:PartyIdentification>
<cbc:ID>BUYER_PARTY_ID</cbc:ID>
</cac:PartyIdentification>
<cac:PartyName>
<cbc:Name>Bridgtow District Council, Purchasing</cbc:Name>
</cac:PartyName>
<cac:Contact>
<cbc:ID>USER_ID</cbc:ID>
<cbc:Name>Sam Massiah</cbc:Name>
</cac:Contact>
</cac:Party>
</cac:OriginatorCustomerParty>
<!-- Totals of the quoted lines at their first quantity, excluding VAT.
Lines the supplier did not quote contribute nothing -->
<cac:QuotedMonetaryTotal>
<cbc:LineExtensionAmount currencyID="EUR">1235.00</cbc:LineExtensionAmount>
<cbc:TaxExclusiveAmount currencyID="EUR">1235.00</cbc:TaxExclusiveAmount>
<cbc:AllowanceTotalAmount currencyID="EUR">65.00</cbc:AllowanceTotalAmount>
<cbc:PayableAmount currencyID="EUR">1235.00</cbc:PayableAmount>
</cac:QuotedMonetaryTotal>
<!-- ============================================================================
Line 10: quoted for three quantities, awarded at 500 pieces
============================================================================ -->
<cac:QuotationLine>
<ext:UBLExtensions>
<ext:UBLExtension>
<ext:ExtensionURI>urn:jakamo:rfq:2</ext:ExtensionURI>
<ext:ExtensionContent>
<jak:QuotationLine>
<!-- Quoted | NotQuoted -->
<jak:Quoted>true</jak:Quoted>
<!-- Awarded | NotAwarded | Pending -->
<jak:Award>Awarded</jak:Award>
<!-- Which of the quoted quantities was awarded -->
<jak:AwardedQuantity>500</jak:AwardedQuantity>
<jak:Answer>
<jak:Question>Country of manufacture?</jak:Question>
<jak:Value>Finland</jak:Value>
</jak:Answer>
</jak:QuotationLine>
</ext:ExtensionContent>
</ext:UBLExtension>
</ext:UBLExtensions>
<!-- Line number of the RFQ line (RequestForQuotationLine/ID) -->
<cbc:ID>10</cbc:ID>
<cbc:Note>Zinc plating per ISO 4042, batch certificate 3.1 included.</cbc:Note>
<!-- Contract the supplier quotes under -->
<cac:DocumentReference>
<cbc:ID>CNT-2024-00123</cbc:ID>
<cbc:DocumentType>Contract</cbc:DocumentType>
</cac:DocumentReference>
<!-- Price for the first requested quantity, 100 pieces -->
<cac:LineItem>
<!-- Identifier of the RFQ line (RequestForQuotation .../LineItem/ID) -->
<cbc:ID>10</cbc:ID>
<cbc:Quantity unitCode="H87">100</cbc:Quantity>
<!-- 100 x 3.05 less 5 % = 289.75 -->
<cbc:LineExtensionAmount currencyID="EUR">289.75</cbc:LineExtensionAmount>
<cbc:MinimumQuantity unitCode="H87">50</cbc:MinimumQuantity>
<cac:Delivery>
<!-- Lead time from order; a date is given as EndDate instead when the supplier
promises a date rather than a duration -->
<cac:EstimatedDeliveryPeriod>
<cbc:DurationMeasure unitCode="WEE">4</cbc:DurationMeasure>
</cac:EstimatedDeliveryPeriod>
</cac:Delivery>
<!-- Discount on this quantity. Code 95 is UN/EDIFACT 5189 "Discount" -->
<cac:AllowanceCharge>
<cbc:ChargeIndicator>false</cbc:ChargeIndicator>
<cbc:AllowanceChargeReasonCode>95</cbc:AllowanceChargeReasonCode>
<cbc:MultiplierFactorNumeric>0.05</cbc:MultiplierFactorNumeric>
<cbc:Amount currencyID="EUR">15.25</cbc:Amount>
<cbc:BaseAmount currencyID="EUR">305.00</cbc:BaseAmount>
</cac:AllowanceCharge>
<!-- Unit price before discount, per BaseQuantity -->
<cac:Price>
<cbc:PriceAmount currencyID="EUR">3.05</cbc:PriceAmount>
<cbc:BaseQuantity unitCode="H87">1</cbc:BaseQuantity>
</cac:Price>
<cac:Item>
<cbc:Description>Hex bolt M12x40, zinc plated, grade 8.8</cbc:Description>
<cbc:Name>ITEM NAME</cbc:Name>
<cac:BuyersItemIdentification>
<cbc:ID>BUYERS_ITEM_ID</cbc:ID>
<cbc:ExtendedID>Rev C</cbc:ExtendedID>
</cac:BuyersItemIdentification>
<cac:SellersItemIdentification>
<cbc:ID>SELLERS_ITEM_ID</cbc:ID>
</cac:SellersItemIdentification>
<cac:ItemSpecificationDocumentReference>
<cbc:ID>DWG-12345-03</cbc:ID>
</cac:ItemSpecificationDocumentReference>
<cac:OriginCountry>
<cbc:IdentificationCode>FI</cbc:IdentificationCode>
</cac:OriginCountry>
<cac:AdditionalItemProperty>
<cbc:Name>Material</cbc:Name>
<cbc:Value>Stainless steel A2-70</cbc:Value>
</cac:AdditionalItemProperty>
</cac:Item>
</cac:LineItem>
<!-- Prices for the further requested quantities (jak:AdditionalQuantity of the RFQ):
one AlternativeLineItem per quantity, in the order they were requested -->
<cac:AlternativeLineItem>
<cbc:ID>10</cbc:ID>
<cbc:Quantity unitCode="H87">500</cbc:Quantity>
<cbc:LineExtensionAmount currencyID="EUR">1400.00</cbc:LineExtensionAmount>
<cac:Delivery>
<cac:EstimatedDeliveryPeriod>
<cbc:DurationMeasure unitCode="WEE">5</cbc:DurationMeasure>
</cac:EstimatedDeliveryPeriod>
</cac:Delivery>
<cac:Price>
<cbc:PriceAmount currencyID="EUR">2.80</cbc:PriceAmount>
<cbc:BaseQuantity unitCode="H87">1</cbc:BaseQuantity>
</cac:Price>
<cac:Item>
<cbc:Name>ITEM NAME</cbc:Name>
<cac:BuyersItemIdentification>
<cbc:ID>BUYERS_ITEM_ID</cbc:ID>
</cac:BuyersItemIdentification>
</cac:Item>
</cac:AlternativeLineItem>
<cac:AlternativeLineItem>
<cbc:ID>10</cbc:ID>
<cbc:Quantity unitCode="H87">1000</cbc:Quantity>
<cbc:LineExtensionAmount currencyID="EUR">2550.00</cbc:LineExtensionAmount>
<cac:Delivery>
<cac:EstimatedDeliveryPeriod>
<cbc:DurationMeasure unitCode="WEE">6</cbc:DurationMeasure>
</cac:EstimatedDeliveryPeriod>
</cac:Delivery>
<cac:Price>
<cbc:PriceAmount currencyID="EUR">2.55</cbc:PriceAmount>
<cbc:BaseQuantity unitCode="H87">1</cbc:BaseQuantity>
</cac:Price>
<cac:Item>
<cbc:Name>ITEM NAME</cbc:Name>
<cac:BuyersItemIdentification>
<cbc:ID>BUYERS_ITEM_ID</cbc:ID>
</cac:BuyersItemIdentification>
</cac:Item>
</cac:AlternativeLineItem>
<!-- Reference back to the RFQ line: the buyer's line identifier -->
<cac:RequestLineReference>
<cbc:LineID>10</cbc:LineID>
<cac:DocumentReference>
<cbc:ID>OFFER_REQUEST_ID</cbc:ID>
</cac:DocumentReference>
</cac:RequestLineReference>
</cac:QuotationLine>
<!-- ============================================================================
Line 20: quoted with a promised delivery date, not awarded
============================================================================ -->
<cac:QuotationLine>
<ext:UBLExtensions>
<ext:UBLExtension>
<ext:ExtensionURI>urn:jakamo:rfq:2</ext:ExtensionURI>
<ext:ExtensionContent>
<jak:QuotationLine>
<jak:Quoted>true</jak:Quoted>
<jak:Award>NotAwarded</jak:Award>
</jak:QuotationLine>
</ext:ExtensionContent>
</ext:UBLExtension>
</ext:UBLExtensions>
<cbc:ID>20</cbc:ID>
<cac:LineItem>
<cbc:ID>20</cbc:ID>
<cbc:Quantity unitCode="H87">250</cbc:Quantity>
<cbc:LineExtensionAmount currencyID="EUR">945.25</cbc:LineExtensionAmount>
<cac:Delivery>
<!-- A promised date instead of a lead time -->
<cac:EstimatedDeliveryPeriod>
<cbc:EndDate>2026-03-28</cbc:EndDate>
</cac:EstimatedDeliveryPeriod>
</cac:Delivery>
<cac:Price>
<!-- Price per 100 pieces -->
<cbc:PriceAmount currencyID="EUR">378.10</cbc:PriceAmount>
<cbc:BaseQuantity unitCode="H87">100</cbc:BaseQuantity>
</cac:Price>
<cac:Item>
<cbc:Name>Washer M12 DIN 125 A2</cbc:Name>
<cac:BuyersItemIdentification>
<cbc:ID>BUYERS_ITEM_ID_2</cbc:ID>
</cac:BuyersItemIdentification>
<cac:SellersItemIdentification>
<cbc:ID>WSH-12-A2</cbc:ID>
</cac:SellersItemIdentification>
</cac:Item>
</cac:LineItem>
<cac:RequestLineReference>
<cbc:LineID>20</cbc:LineID>
</cac:RequestLineReference>
</cac:QuotationLine>
<!-- ============================================================================
Line 30: the supplier did not quote this line. No Price, no amounts
============================================================================ -->
<cac:QuotationLine>
<ext:UBLExtensions>
<ext:UBLExtension>
<ext:ExtensionURI>urn:jakamo:rfq:2</ext:ExtensionURI>
<ext:ExtensionContent>
<jak:QuotationLine>
<jak:Quoted>false</jak:Quoted>
<jak:Award>NotAwarded</jak:Award>
</jak:QuotationLine>
</ext:ExtensionContent>
</ext:UBLExtension>
</ext:UBLExtensions>
<cbc:ID>30</cbc:ID>
<cbc:Note>Not in our programme - please contact our distributor Fasteners Nordic.</cbc:Note>
<cac:LineItem>
<!-- The buyer's line identifier need not be the line number -->
<cbc:ID>PR-4711-30</cbc:ID>
<cbc:Quantity unitCode="H87">40</cbc:Quantity>
<cac:Item>
<cbc:Name>Nyloc nut M12 A2</cbc:Name>
<cac:BuyersItemIdentification>
<cbc:ID>BUYERS_ITEM_ID_3</cbc:ID>
</cac:BuyersItemIdentification>
</cac:Item>
</cac:LineItem>
<cac:RequestLineReference>
<cbc:LineID>PR-4711-30</cbc:LineID>
</cac:RequestLineReference>
</cac:QuotationLine>
</Quotation>
6.5 Create an RFQ from a template
An RFQ can be created from an RFQ template by giving the identifier of the template in jak:TemplateId of the Jakamo UBL extension. The new RFQ starts as a copy of the template, and the content of your message is then applied on top of it.
This is how questions and requested properties are set through the UBL API, and the two features UBL 2.3 has no representation for are therefore available in it. Everything the template carries and the message does not set is kept, in particular:
- the questions for the suppliers, general and per line, including their input types and options,
- the requested properties, that is, the fields the supplier is asked to fill in,
- the general attachments of the template.
Build one template per kind of RFQ you send – with its questions and its requested properties – and name the template in every message. The questions and the properties are then maintained by purchasing in Jakamo, without a change to your integration.
The parts your message does define replace the ones from the template: the lines of the message are the lines of the RFQ, and a template line that is not in the message is removed. The same applies to the suppliers, unless your message names no supplier at all, in which case the suppliers of the template are kept.
Find the identifier on the Jakamo RFQ settings page, under Templates: every template shows its identifier next to its name, and the copy button next to it puts the identifier on the clipboard. The identifier does not change, so it can be stored in your own system as the template to use.
Notes:
jak:TemplateIdis only read when a new RFQ is created withPOST. On an update it is ignored, because an existing RFQ cannot be re-created from a template.- The template must be a template or an RFQ of your own company. If it is not found, the request fails with
400 Validation Errorand the messageSource rfq not found. - A company template is created in the Jakamo user interface. Templates cannot be created through this API.
Example: Creating an RFQ from a template (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"
xmlns:ext="urn:oasis:names:specification:ubl:schema:xsd:CommonExtensionComponents-2">
<ext:UBLExtensions>
<ext:UBLExtension>
<ext:ExtensionURI>urn:jakamo:rfq:2</ext:ExtensionURI>
<ext:ExtensionContent>
<jak:Rfq xmlns:jak="urn:jakamo:rfq:2">
<!-- The questions and the requested properties of this template are kept -->
<jak:TemplateId>3fa85f64-5717-4562-b3fc-2c963f66afa6</jak:TemplateId>
</jak:Rfq>
</ext:ExtensionContent>
</ext:UBLExtension>
</ext:UBLExtensions>
<cbc:ID>OFFER_REQUEST_ID</cbc:ID>
<cbc:IssueDate>2026-01-13</cbc:IssueDate>
<cbc:IssueTime>09:00:00</cbc:IssueTime>
<cbc:SubmissionDueDate>2026-02-13</cbc:SubmissionDueDate>
<cbc:Note>Bolts and washers for assembly line 3</cbc:Note>
<cbc:PricingCurrencyCode>EUR</cbc:PricingCurrencyCode>
<cac:OriginatorCustomerParty>
<cac:Party>
<cac:PartyIdentification>
<cbc:ID>BUYER_PARTY_ID</cbc:ID>
</cac:PartyIdentification>
<!-- Names are informational: accepted, never read, never mapped -->
<cac:PartyName>
<cbc:Name>Bridgtow District Council, Purchasing</cbc:Name>
</cac:PartyName>
<cac:Contact>
<cbc:ID>USER_ID</cbc:ID>
<cbc:Name>Sam Massiah</cbc:Name>
</cac:Contact>
</cac:Party>
</cac:OriginatorCustomerParty>
<cac:SellerSupplierParty>
<cac:Party>
<cac:PartyIdentification>
<cbc:ID>SELLER_ID</cbc:ID>
</cac:PartyIdentification>
<cac:PartyName>
<cbc:Name>Consortial Oy</cbc:Name>
</cac:PartyName>
</cac:Party>
</cac:SellerSupplierParty>
<cac:RequestForQuotationLine>
<cbc:ID>1</cbc:ID>
<cac:LineItem>
<cbc:ID>1</cbc:ID>
<cbc:Quantity unitCode="H87">100</cbc:Quantity>
<cac:Item>
<cbc:Name>Hex bolt M12x40</cbc:Name>
<!-- Buyer's item number, item name, quantity and unit are required for publishing -->
<cac:BuyersItemIdentification>
<cbc:ID>BUYERS_ITEM_ID</cbc:ID>
</cac:BuyersItemIdentification>
</cac:Item>
</cac:LineItem>
</cac:RequestForQuotationLine>
</RequestForQuotation>
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, and the name of the RFQ | Identifies the RFQ. Used to find the RFQ when it is updated and when attachments are added, and shown to the supplier as the name of the RFQ. Required, maximum 100 characters. Should be unique inside your company. |
RequestForQuotation/Note | Description | The description of the RFQ, shown to the supplier. Note is repeatable, so write the description one line per Note element: every note is read and they become the lines of the description, in the order they are given. Notes with no content in them are left out. Maximum 5000 characters in total. A document with no Note leaves the description 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 from the first AdditionalDocumentReference that is marked as a project reference by one of the two selectors below. Maximum 100 characters. |
RequestForQuotation/AdditionalDocumentReference/DocumentType | Selector | The free text name of the reference. Project, in any casing, marks the reference as the project number. This is the preferred form: DocumentTypeCode is a code element, and PROJECT is not a code from any list. |
RequestForQuotation/AdditionalDocumentReference/DocumentTypeCode | Selector | PROJECT marks the reference as the project number as well, and stays supported. |
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. Required: a message without it is rejected with 400 Validation Error. Must match a company mapping in the mapping table connected to the integration. Only the first PartyIdentification is read. See 7.8 Identifier schemes for the schemeID attribute. |
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. Required, unless the author is given as an email address. Must match a user mapping of the integration. This is the recommended way to name the author. |
OriginatorCustomerParty/Party/Contact/ElectronicMail | Author person, when there is no Contact/ID | The email address of the Jakamo user who authors the RFQ. Must be a valid email address, and the address itself has to be a user string of your integration: persons are always found through the user strings, never by looking an address up among the Jakamo users. Contact/ID with schemeID="EMAIL" means the same thing. Mapping the user string to the person once is the simpler setup. |
OriginatorCustomerParty/Party/Contact/Name | – | Informational only. Accepted and not read: a name is not an identifier of a Jakamo user. Send it to keep your message readable. |
OriginatorCustomerParty/Party/PartyName/Name | – | Informational only. Accepted and not read. Companies are always identified by PartyIdentification/ID. |
Names are never identifiers. Contact/Name and PartyName/Name are accepted and ignored, so a name needs no mapping and cannot fail a message: only the identifiers of the two rows above have to exist in your Jakamo mappings. A UBL message names no buyer side responsible persons; they are set in Jakamo.
7.3 Supplier party
The first supplier is identified in RequestForQuotation/SellerSupplierParty, which UBL 2.3 allows only once per document. Additional suppliers go in the Jakamo UBL extension, where a cac:SellerSupplierParty of its own carries each of them; the rows of this section apply to those exactly as they do to the supplier of the document. The suppliers of the RFQ are the supplier of SellerSupplierParty followed by the suppliers of the extension, in document order.
| UBL element | Used as | Description |
|---|---|---|
SellerSupplierParty/Party/PartyIdentification/ID | Supplier | The supplier the RFQ is shared with. Must match a company mapping in the mapping table, or be an email address with schemeID="EMAIL". Only the first PartyIdentification is read. Required, unless the supplier is given as an email address (see below). See 7.8 Identifier schemes. |
SellerSupplierParty/Party/Contact/ElectronicMail | The supplier itself, when no company mapping is given | When no PartyIdentification/ID is given, this email identifies a supplier company that is not a Jakamo company. Must be a valid email address. |
SellerSupplierParty/Party/Contact | – | Accepted, not used, whenever the supplier is identified by a company mapping. Contact persons of a supplier cannot be set through the API, see below. |
SellerSupplierParty/Party/PartyName/Name | – | Accepted, not used. |
Contact persons of a supplier
Contact persons of a supplier cannot be set through this API, in the UBL API or in the JSON API. A contact person is a user of the supplier's company, and the user mappings of your integration can only name users of your own company, so there is no identifier a message could carry for them.
This does not keep the RFQ from reaching the supplier. When the RFQ is published, Jakamo notifies the users of the supplier company according to their own notification settings. A contact person only adds one guarantee on top of that: a contact person is notified whether or not their notification settings would otherwise send them a message.
Contact persons are chosen in the Jakamo user interface, and a message never changes them: the contact persons of an RFQ that are set in Jakamo stay as they are when the RFQ is updated through the API.
The one exception is a supplier that is not a Jakamo company. Such a supplier is reached through the email address it is identified with, and Jakamo sets its contact person automatically, because publishing to it requires one.
Suppliers that are not Jakamo companies
A supplier that has no Jakamo account – a master data company or a supplier created in the Jakamo user interface – has no company mapping. Such a supplier is identified by the email address the RFQ is shared to:
- in
SellerSupplierParty, by givingParty/Contact/ElectronicMailand noParty/PartyIdentification/ID, - or, equivalently, by giving
PartyIdentification/IDwithschemeID="EMAIL", - or, for additional suppliers, the same two ways inside the
cac:SellerSupplierPartyof the Jakamo extension, or withjak:Supplier/cbc:IDandschemeID="EMAIL"in it.
Only suppliers that have no Jakamo account can be identified this way. A supplier that is a Jakamo company is always identified by its company mapping, even if you know the email address of one of its users. The email of such a supplier is the address the RFQ is shared to, not a contact person of a Jakamo company.
The supplier must already exist in Jakamo as a supplier of your company with that email address; Jakamo does not create suppliers from an RFQ message. The comparison is case-insensitive. If no supplier is found, the request fails with 400 Validation Error and the message Company not found with email: X. Contact persons cannot be given for these suppliers, because the RFQ is shared to the email address itself.
<cac:SellerSupplierParty>
<cac:Party>
<!-- No PartyIdentification: the email identifies the supplier -->
<cac:Contact>
<cbc:ElectronicMail>sales@external.example</cbc:ElectronicMail>
</cac:Contact>
</cac:Party>
</cac:SellerSupplierParty>
7.4 RFQ lines
Each RequestForQuotation/RequestForQuotationLine becomes one requested item on the RFQ.
A line carries two identifiers, and they are different things. LineItem/ID is the identifier of the line in your own system and it identifies the line: an update targets the line that was sent with the same identifier, whatever position it is sent in. Any identifier you have can be used — a requisition line number, a row key, a UUID — as long as it is the same identifier for the same line in every message and no two lines of one RFQ share it. RequestForQuotationLine/ID is the line number, which gives the line its number and place in the RFQ and is kept as you send it, so you can number the lines the way your own system numbers them. It is optional: leave it out and Jakamo numbers the lines for you. Your item number is neither of them; it belongs in Item/BuyersItemIdentification/ID, and the same item can be requested on several lines.
UBL element (inside RequestForQuotationLine) | Used as | Description |
|---|---|---|
LineItem/ID | Line identifier | The identifier of the line in your own system. Most often that is simply your own line number, 10, and it can be anything else you have, such as PR-4711-10 or a UUID. Required, because the UBL schema requires the element. Maximum 100 characters, read exactly as it is sent: 010 and 10 are two different lines. An update targets the line with the same identifier, so send the same identifier for the same line every time. |
ID | Line number | Optional. The number of the line in the RFQ: a whole number greater than zero. Stored and shown exactly as you send it, gaps included, so an RFQ numbered 10, 20, 30 the way your ERP numbers its lines keeps those numbers, and a line removed in a later message does not renumber the lines that stay. A line sent without a number keeps the number it already has, and a new line is given the next free number, so a message that gives no line numbers at all creates the lines in the order it sends them. Note that leaving the numbers out of an update does not reorder the lines that exist already: send the numbers to move a line. Two lines cannot ask for the same number, and the number is read as a number, so 010 and 10 are the same number and a document that sends both is rejected. |
Note | Additional information | Free text shown to the supplier for this line. Only the first Note is read. Maximum 5000 characters. |
LineItem/Item/BuyersItemIdentification/ID | Buyer's item number | Your item number for the requested item. Maximum 100 characters. Required for publishing the RFQ. |
LineItem/Quantity | Requested quantity | The first quantity the supplier quotes for. Must be greater than zero. Required for publishing the RFQ, as is the unit below. UBL allows one per line; further quantities are given with jak:AdditionalQuantity in the line extension. |
jak:Line/jak:AdditionalQuantity | Requested quantity | A further quantity the supplier is asked to quote for, repeatable. See 5.1 Jakamo UBL extension. |
LineItem/Quantity/@unitCode | Unit of measure | Passed to Jakamo as it is given, with no code list validation, and shown to the supplier as it is. Maximum 20 characters. Use UN/ECE Recommendation 20 codes, which is what UBL expects: H87 (piece), C62 (one), KGM (kilogram), MTR (metre), LTR (litre), SET (set). |
LineItem/Delivery/RequestedDeliveryPeriod/StartDate | Requested delivery date | The delivery date requested for the line. Must be later than today for the RFQ to be published, see 7.7. Only the first Delivery element is read. When the period carries both a StartDate and an EndDate, the start is used; when it carries only an EndDate, that date is used instead. |
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. Required for publishing the RFQ. |
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. |
LineItem/Item/BuyersItemIdentification/ExtendedID | Item revision | The revision of the requested item, for example Rev C. UBL has no revision element of its own, so the extended buyer's item number is used. Maximum 50 characters. |
LineItem/MinimumQuantity | Minimum order quantity | The smallest quantity the supplier may quote for. Must be greater than zero. The unitCode attribute is not read; the unit of the line comes from Quantity/@unitCode. |
RequestForQuotationLine/DocumentReference/ID | Contract number | Read from the first line level DocumentReference that is marked as a contract by one of the two selectors below. Maximum 100 characters. |
RequestForQuotationLine/DocumentReference/DocumentType | Selector | The free text name of the reference. Contract, in any casing, marks the reference as the contract number. This is the preferred form, the same as with the project number in 7.1. |
RequestForQuotationLine/DocumentReference/DocumentTypeCode | Selector | 315, the UN/EDIFACT code for a contract, or CONTRACT marks the reference as the contract number as well, and stays supported. |
LineItem/Item/ItemSpecificationDocumentReference/ID | Drawing number | The drawing, or other document, that specifies the item. Read from the first ItemSpecificationDocumentReference that has an ID, whatever its DocumentTypeCode is. Maximum 100 characters. |
LineItem/Item/AdditionalItemProperty/Name and /Value | Technical specifications | Free key/value specifications of the item, shown to the supplier. Repeat AdditionalItemProperty for every specification. Only the first property with a given name is read, and a property with no Value becomes an empty value. Maximum 1000 properties per line, 200 characters per name and 2000 per value. |
jak:Line/jak:AnnualVolume | Annual volume | See 5.1 Jakamo UBL extension. UBL 2.3 has no element for it. |
jak:Line/jak:PriceListGroup | Price list group | See 5.1 Jakamo UBL extension. UBL 2.3 has no element for it. |
7.5 Values Jakamo sets automatically
| Value | Behaviour |
|---|---|
| Publishing | The RFQ is published to the suppliers when the message is accepted, both on create and on update, unless jak:Publish in the Jakamo UBL extension is false. |
| Questions to suppliers | Set with an RFQ template, not in the message: UBL 2.3 has no representation for questions, so put them on a template in Jakamo and create the RFQ from it, and the RFQ carries them. A message never adds or removes questions, so the ones the RFQ already has always stay. |
| Requested properties, that is, the fields the supplier is asked to fill in | Set with an RFQ template, not in the message: choose them on the template in Jakamo, and an RFQ created from it uses them. Without a template the Jakamo default is used, which asks for price and lead time among others. |
| 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, revision, supplier's item number, contract number, drawing number, annual volume, minimum order quantity, price list group and technical specifications 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. |
SellerSupplierParty/Party/Contact, when the supplier has a company mapping | Contact persons of a supplier cannot be set through the API, see 7.3 Supplier party. The element is only read when it carries the email address that identifies a supplier that is not a Jakamo company. |
SellerSupplierParty/DespatchContact, /AccountingContact, /SellerContact | Not used. |
AdditionalDocumentReference with any DocumentType other than Project and any DocumentTypeCode other than PROJECT | Only the project number is read from additional document references. |
RequestForQuotationLine/DocumentReference with any DocumentType other than Contract and any DocumentTypeCode other than 315 or CONTRACT | Only the contract number is read from line level document references. |
LineItem/LineExtensionAmount, LineItem/Price, LineItem/AllowanceCharge, LineItem/PricingReference | No price, base quantity or discount information is read from an RFQ. |
RequestedDeliveryPeriod/DurationMeasure, second and further Delivery elements | Only the first Delivery is read. Of its period, StartDate is read, and EndDate only when there is no StartDate. |
Item/BuyersItemIdentification/BarcodeSymbologyID, /IssuerScopeID, /PhysicalAttribute, /MeasurementDimension, /IssuerParty | Only ID and ExtendedID are read, as the buyer's item number and the item revision. |
ItemSpecificationDocumentReference elements after the first one, and their other child elements | Only the ID of the first one is read, as the drawing number. |
AdditionalItemProperty/NameCode, /ValueQuantity, /ValueQualifier, /ListValue and the other child elements | Only Name and Value are read, as one technical specification. |
Item/CommodityClassification, Item/OriginCountry, Item/ClassifiedTaxCategory, Item/AdditionalInformation, Item/Keyword | Not used. |
Document level Delivery, DeliveryTerms, DestinationCountry, Contract, RequestedValidityPeriod, Signature | Not used. A contract number is read from the line level DocumentReference instead. |
UBLExtensions in any namespace other than urn:jakamo:rfq:2 | Not used. See 5.1 Jakamo UBL extension for the extensions Jakamo reads. |
LineItem/MaximumQuantity, LineItem/MinimumBackorderQuantity, LineItem/MaximumBackorderQuantity and the other line quantities | Only Quantity and MinimumQuantity are read. |
7.7 Identifier schemes
This section is the one place that decides how an identifier of the message is read. It applies to every identifier: the buyer party, the supplier party, the suppliers of the Jakamo extension and the buyer contact.
An identifier says what kind of identifier it is with the schemeID attribute of the element it is in. Jakamo supports two, and rejects the rest:
schemeID | Read as | Where it can be used |
|---|---|---|
| omitted | An entry of your mapping table for a company, or a user string of your integration for a person. This is the normal case. | Everywhere |
EMAIL | An email address. For a company it names a supplier that is not a Jakamo company and Jakamo finds the supplier by that address, see 7.3 Supplier party. For a person it only says that the identifier is an email address: the person is still found through the user strings of your integration, so the address has to be one of them. | SellerSupplierParty/Party/PartyIdentification/ID, both in the document and in a cac:SellerSupplierParty of the Jakamo extension, jak:Supplier/cbc:ID, and OriginatorCustomerParty/Party/Contact/ID |
| anything else | Nothing. The message is rejected with 400 UBL Conversion Error, and the message names the schemes that are supported. | – |
The value of schemeID is compared case-insensitively.
An identifier scheme Jakamo does not support is never read as a mapping table entry. schemeID="GLN", schemeID="DK:CVR" and schemeID="0216" are all rejected, because Jakamo has no way to resolve a Global Location Number, a national business identifier or an OVT identifier to a company of your Jakamo network. Leave schemeID out and give the identifier you have mapped in Jakamo.
Two rules follow from the table:
EMAILis for suppliers and for the buyer contact. OnOriginatorCustomerParty/Party/PartyIdentification/IDit is rejected: your own business unit is a Jakamo organisation and is named by a company mapping.- A person is never named by a business identifier.
schemeID="GLN"onContact/IDis rejected.
Support for real business identifiers can be added later, and it will use ISO 6523 ICD codes as the scheme, for example 0088 for a GLN, 0037 for a Finnish business identifier or 0216 for an OVT identifier. Until then those schemes are rejected, so that a message cannot look accepted while the identifier is read as something else than you meant.
8. User and company mappings in the Jakamo integration settings
The mappings that let Jakamo identify the buyer, the author and the suppliers of a message are configured in the Jakamo user interface, on the Integrations page and on the Mapping tables page. Both pages 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, and they are configured in two different places:
| Identifier | Where it is configured | Read from |
|---|---|---|
| Companies: suppliers and your own business units | A mapping table of your company, connected to the Buyer API integration | The connected mapping table only |
| Users: the author of the RFQ, a user of your own company. A UBL message names no other person: responsible persons and supplier contact persons are set in Jakamo | The User Strings of the Buyer API integration | The user strings of that integration |
Company identifiers are read from the mapping table connected to the Buyer API integration, and from nowhere else. If no mapping table is connected to the integration, no supplier and no business unit can be identified and every request fails with 500 Internal Server Error.
The older Jakamo supplier mappings that are configured directly on an integration – the vendor numbers of the classic order and order response integrations – are not supported by this API, even when they exist on the same Buyer API integration. See 8.3 Older per-integration supplier mappings for how to move them into a mapping table.
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 authorPersonIdentifier field of the attachment endpoint.
Only users of your own company can be mapped. Users of a supplier cannot, which is why the contact persons of a supplier are set in Jakamo instead of in a message, see 7.3 Supplier party.
Unlike company identifiers, user identifiers stay on the integration as its User Strings. If a user mapping table is connected to the integration, this API does not read it, so every person the message names still needs a user string on the Buyer API integration itself.
8.2 Company 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.
Company mappings are made on the Mapping tables page, not under the integration itself:
- On the Mapping tables page, select your mapping table, or create one with
Add Mapping Table. One mapping table per company is enough for most scenarios, and the same table can serve several integrations. - Add an entry for every supplier and for every business unit of your own that owns RFQs. An entry is a pair of an Identifier – the string you send in the message – and a Partner Company, optionally narrowed to a Business Unit. To be able to add an entry, the relationship with that company has to exist in Jakamo.
- On the Integrations page, connect the mapping table to your Buyer API integration. Until this is done, the API cannot identify any company.
- Identifier refers to the identifier string incoming in
RequestForQuotation/SellerSupplierParty/Party/PartyIdentification/ID. The same table is used for your own business units, which are identified inRequestForQuotation/OriginatorCustomerParty/Party/PartyIdentification/ID. - Partner Company refers to the Jakamo account the identifier maps to. The dropdown includes the companies your account has a relation established with in Jakamo, and your own company for business unit entries.
Any company you have a relationship with can be mapped and used as the supplier of an RFQ, including a company that is a customer of yours in Jakamo. Jakamo records which side was the buyer when the relationship was formed, but that does not limit who you may send an RFQ to. What matters is that the relationship exists; if it does not, the request fails with Company X is not connected to your company in Jakamo. When the mapping narrows to a business unit, that business unit has to be connected to you itself: the relationship of its parent company does not cover it, so a business unit whose connection has been removed cannot be used as a supplier.
8.3 Older per-integration supplier mappings
Integrations created before 2026 kept their supplier mappings on the integration itself, as vendor numbers of that one integration. Those mappings still serve the classic order and order response integrations, but this API does not read them. A supplier that is only mapped that way fails with Cannot find match for organization string: X, even when the mapping sits on the very Buyer API integration the request came in on.
Use the Initialize from Integration function on the Mapping tables page to copy the existing vendor number mappings of an integration into a mapping table instead of retyping them. The function only targets an empty mapping table, and it skips mappings to external identifiers and duplicate vendor numbers, listing everything it skipped. Review the entries of the table afterwards, then connect the table to the Buyer API integration.
9. UBL API compared with the JSON API
The RFQ UBL API and the Jakamo Buyer API (JSON) create the same RFQ in Jakamo, and the same RFQ features are available in both. Two of them are set differently:
| Feature | UBL API | JSON API |
|---|---|---|
| Questions to suppliers, general and per line | Supported through an RFQ template: the questions of the template are kept on the RFQ, and a message never removes them | Supported, written in the message |
| Choosing the fields the supplier is asked to fill in, that is, the requested properties | Supported through an RFQ template: the requested properties of the template are used | Supported, written in the message |
UBL 2.3 has no representation for questions, and none for choosing the requested properties, which is why the UBL API takes them from a template instead of from the message. Everything else is written in the message: the features UBL has no element for – several suppliers, suppliers that are not Jakamo companies, draft RFQs, the template itself, annual volume, price list group and further requested quantities – are given in the Jakamo UBL extensions.
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. |
| Company mappings | Vendor numbers of the integration | A mapping table connected to the integration. The vendor numbers of the integration are no longer read, see 8.3. |
| User mappings | User strings of the integration | User strings of the integration (unchanged) |
| Reading suppliers' offers | GET /api/rfq/response with an incoming message queue and the x-acknowledge-uri header | /api/v2/queues/quotations |
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 | A cac:SellerSupplierParty per additional supplier in the Jakamo UBL extension, which is the preferred form, or the shorter jak:Supplier. ASSP references are ignored. |
| Supplier contact person | SellerSupplierParty/Party/Contact | Not supported, and not needed: Jakamo notifies the users of the supplier company, and contact persons are set in Jakamo. The element is accepted and ignored, see 7.3 Supplier party. |
| Project number | ProjectReference/ID | AdditionalDocumentReference with DocumentType = Project, or DocumentTypeCode = PROJECT. Note that cac:ProjectReference is not part of the UBL 2.3 RequestForQuotation schema at all, so a message that still carries it is rejected by the XSD validation. |
| 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/Item/BuyersItemIdentification/ID (unchanged) |
| Line identifier | RequestForQuotationLine/ID | LineItem/ID. Any identifier of yours, and it is what an update targets, see 7.4 RFQ lines. |
| Line number | Not supported | RequestForQuotationLine/ID, optional. The number and the place of the line in the RFQ, kept as it is sent. |
| Supplier's item number | LineItem/Item/SellersItemIdentification/ID | LineItem/Item/SellersItemIdentification/ID (unchanged) |
| Requested delivery date | LineItem/Delivery/RequestedDeliveryPeriod/EndDate | LineItem/Delivery/RequestedDeliveryPeriod/StartDate. A period that carries only an EndDate is still read, so an existing message keeps working, see 7.4 RFQ lines. |
| Item revision | Item/BuyersItemIdentification/ExtendedID | Item/BuyersItemIdentification/ExtendedID (unchanged) |
| Drawing number | Item/ItemSpecificationDocumentReference/ID with DocumentTypeCode = 174 | Item/ItemSpecificationDocumentReference/ID (unchanged). The DocumentTypeCode is no longer needed, but it is accepted. |
| Contract number | RequestForQuotationLine/DocumentReference/ID with DocumentTypeCode = 315 | RequestForQuotationLine/DocumentReference/ID with DocumentType = Contract, or DocumentTypeCode = 315 or CONTRACT. An existing 315 message needs no change. |
| Annual volume, price list group | Not supported | jak:AnnualVolume and jak:PriceListGroup in the line extension. |
| Minimum order quantity | Not supported | LineItem/MinimumQuantity |
| Technical specifications | Not supported | Item/AdditionalItemProperty with Name and Value, one element per specification. |
| 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 name and description | Taken from Note | The RFQ number names the RFQ, and every Note of the document becomes a line of the description. |
| Line additional information | RequestForQuotationLine/Note | RequestForQuotationLine/Note (unchanged) |
10.3 Behaviour that has changed
- The RFQ is published unless you ask for a draft. A message accepted by this API is shared with the suppliers immediately, both on create and on update, unless
jak:Publishisfalsein the Jakamo UBL extension. - An update replaces the whole RFQ. Send the complete content in every
PUT; lines and suppliers missing from the message are removed from the RFQ, and the RFQ is published to the suppliers 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.
UBLVersionIDandCustomizationIDare 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 strings — they are the same strings, on the same integration. The company mappings have to move: this API reads them from a mapping table connected to the integration, not from the vendor numbers of the integration, so copy them over with
Initialize from Integration(see 8.3). Verify that the buyer business unit identifier is mapped too, since it is now sent inOriginatorCustomerParty. - Rewrite the message template according to 10.2 and validate the result against the UBL 2.3 schemas.
- Remove price and discount elements, or accept that they are ignored. Contract, drawing and revision elements can stay as they are.
- Move additional suppliers from
ASSPdocument references to the Jakamo UBL extension, each in acac:SellerSupplierPartyof its own (or in the shorterjak:Supplierform). - Update the response handling: expect
201 Createdon create and parse the problem document on errors. Store thecorrelationIdfrom the response for support requests. - Test the whole flow in the test environment, then repeat the configuration in production.
Didn't you find what you were looking for? Send an email to Jakamo support (support@thejakamo.com) and we will help you.