Skip to main content
API docs by Redocly

Jakamo Buyer API (v2)

Download OpenAPI specification:Download

Open API description for V2 of the Jakamo API. The API is used to integrate with Jakamo.

General guidelines

Authentication

All requests to the API must be authenticated. The authentication is done using OAuth2.0. Refer to the OAuth2.0 documentation for instructions on how to setup Oauth2 authentication.

HTTP codes and verbs

HTTP verbs

POST - Create a new resource
GET - Read one or more resources
PUT - Replace a resource
PATCH - Partially update a resource
DELETE - Delete a resource

HTTP codes

200 - OK. The request was successful.
201 - Created. The request was successful and a new resource was created.
400 - Bad request. The request was invalid. See the response body for details.
401 - Unauthorized. The request was not authenticated. See the response body for details.
404 - Not found. The requested resource was not found.
429 - Too many requests. The request was throttled. Investigate Retry-After header
500 - Internal server error. An error occurred in the server. See the response body for details.

Handling errors

If the API returns an error, the response body will contain an error object. The error object contains a message and a list of errors.
If a 4xx status code is returned, clients must take care not to retry the request without modification. The exception here is 429 too many requests that can be retried after a period given in Retry-After header.

If a 5xx status code is returned, clients may retry the request. It is preferable to use an exponential backoff strategy when retrying

Identifiers

Companies, business units and persons need to be mapped to their corresponding entities in Jakamo. To do this, Jakamo has a simple mapping table feature that can be used to map external identifiers to Jakamo entities. To setup a mapping table in Jakamo, see: Mapping Tables

To use a mapped identifier, send the identifier and set type of the identifier to MAPPING_TABLE_ENTRY:

"authorPerson": {
  "identifier": "msierra",
  "identifierType": "MAPPING_TABLE_ENTRY"
},

Getting started

Follow these instructions to get started with development.

  1. Setup Authentication Follow instructions at OAuth2.0 documentation and setup a new OAUTH2 application. Add credentials for any applications you intend to integrate. Make sure you have a Buyer API integration enabled in Jakamo and the OAUTH2 application connected to that integration

  2. Setup Person and Company Mapping Follow instructions at Mapping Tables and create a mapping table for your suppliers and if necessary, business units. Mapping strings for persons can be entered directly on the integrations page, there is no mapping table support for them yet. After setting up the mapping table, make sure to connect it to the Buyer API Integration on the integrations page

  3. Download this open api specification. You can open it for example using Postman or alternatively you can generate a client using some open api tooling. Setup Oauth2 authentication and you should be able to interact with the API. For development, use https://demo.thejakamo.com as the base url.

RFQs

Endpoints for sharing RFQs with suppliers and receiving quotations.

Create a new Request For Quotation

Create a new Request For Quotation. Key features:

  • Author person. This will be shown as the author of the RFQ for the suppliers
  • Author business unit. Must be set if your company is using business units in Jakamo
  • Suppliers. Add one or many suppliers that will receive the RFQ
  • Requested items. List of items to request quotations for.
  • Questions. Additional questions that the suppliers should answer. Can be either header level or item level
  • Publish. Set to true if you wish the RFQ to be shared to suppliers immediately. If set false, users can publish it in the Jakamo user interface
Request Body schema: application/json
required
rfqNumber
required
string [ 1 .. 100 ] characters

Unique required identifier of the RFQ.

title
required
string [ 1 .. 500 ] characters

Display name of the RFQ

description
string or null

General description of the RFQ

projectNumber
string or null

Project number of the RFQ.

currency
required
string = 3 characters ^[A-Z]{3}$

Desired currency for the RFQ. Use ISO 4217 currency codes

publish
boolean or null

Should the RFQ be published. It will not be shared to recipients until published. If not published, users may publish it later in Jakamo UI

offerDueDate
required
string <date> non-empty

Due date for the suppliers to submit their quotations.

required
object (Rfqs.Models.PersonModel)

A person in Jakamo

object (Rfqs.Models.BusinessUnitModel)

A business unit in Jakamo

Array of objects or null (Rfqs.Models.CompanyModel)

List of suppliers

Array of objects or null (Rfqs.Models.PersonModel)

List of responsible persons from the buyer side

Array of objects or null (Rfqs.Models.RfqItem)

Suppliers are requested to provide information for these fields for each requested item

Array of objects or null (Rfqs.Models.QuestionModel)

List of questions that suppliers must answer when replying to the RFQ. Questions can be either general questions (applicable to the entire RFQ) or line questions (applicable to specific RFQ items).

General questions (IsQuestionForLines = false):

  • Asked once for the entire RFQ
  • Examples: company certifications, delivery preferences, payment terms

Line questions (IsQuestionForLines = true):

  • Asked for each individual RFQ item
  • Examples: lead time per item, technical specifications, item-specific certifications

Supported input types:

  • Text: Free text input for open-ended questions
  • Number: Numeric input for quantities, prices, etc.
  • Date: Date picker for deadlines, delivery dates
  • Select: Single choice from predefined options (requires ValueOptions)
  • MultiSelect: Multiple choices from predefined options (requires ValueOptions)
  • File: File upload for documents, certificates, etc.
  • Checkbox: Boolean yes/no questions
requestedProperties
Array of strings or null

Suppliers are requested to provide information for these fields for each requested item. Leave empty to use default values Possible values: Description: item description SellersItemNumber: item number on supplier side PriceWithoutVat: price without VAT included PriceWithVat: price with VAT included EstimatedDeliveryDate: estimated date when the supplier can deliver the requested goods LeadTimeDays: lead time of the requested goods DiscountPercent: discount percent from supplier side MinimumBatchSize: minimum batch size the supplier can provide CountryOfOrigin: country of origin of the requested goods CustomsCode: customs code of the requested goods AdditionalInfo: any additional information

Responses

Request samples

Content type
application/json
{
  • "rfqNumber": "RFQ12345",
  • "title": "RFQ12345",
  • "description": "Request for quotation for new project",
  • "projectNumber": "P55512345",
  • "currency": "EUR",
  • "publish": true,
  • "offerDueDate": "2038-01-19",
  • "authorPerson": {
    },
  • "authorBusinessUnit": {
    },
  • "suppliers": [
    ],
  • "responsiblePersons": [
    ],
  • "requestedItems": [
    ],
  • "questions": [
    ],
  • "requestedProperties": [
    ]
}

Update an existing Request For Quotation

Updates an existing RFQ.

Request Body schema: application/json
required
rfqNumber
required
string [ 1 .. 100 ] characters

Unique required identifier of the RFQ.

title
required
string [ 1 .. 500 ] characters

Display name of the RFQ

description
string or null

General description of the RFQ

projectNumber
string or null

Project number of the RFQ.

currency
required
string = 3 characters ^[A-Z]{3}$

Desired currency for the RFQ. Use ISO 4217 currency codes

publish
boolean or null

Should the RFQ be published. It will not be shared to recipients until published. If not published, users may publish it later in Jakamo UI

offerDueDate
required
string <date> non-empty

Due date for the suppliers to submit their quotations.

required
object (Rfqs.Models.PersonModel)

A person in Jakamo

object (Rfqs.Models.BusinessUnitModel)

A business unit in Jakamo

Array of objects or null (Rfqs.Models.CompanyModel)

List of suppliers

Array of objects or null (Rfqs.Models.PersonModel)

List of responsible persons from the buyer side

Array of objects or null (Rfqs.Models.RfqItem)

Suppliers are requested to provide information for these fields for each requested item

Array of objects or null (Rfqs.Models.QuestionModel)

List of questions that suppliers must answer when replying to the RFQ. Questions can be either general questions (applicable to the entire RFQ) or line questions (applicable to specific RFQ items).

General questions (IsQuestionForLines = false):

  • Asked once for the entire RFQ
  • Examples: company certifications, delivery preferences, payment terms

Line questions (IsQuestionForLines = true):

  • Asked for each individual RFQ item
  • Examples: lead time per item, technical specifications, item-specific certifications

Supported input types:

  • Text: Free text input for open-ended questions
  • Number: Numeric input for quantities, prices, etc.
  • Date: Date picker for deadlines, delivery dates
  • Select: Single choice from predefined options (requires ValueOptions)
  • MultiSelect: Multiple choices from predefined options (requires ValueOptions)
  • File: File upload for documents, certificates, etc.
  • Checkbox: Boolean yes/no questions
requestedProperties
Array of strings or null

Suppliers are requested to provide information for these fields for each requested item. Leave empty to use default values Possible values: Description: item description SellersItemNumber: item number on supplier side PriceWithoutVat: price without VAT included PriceWithVat: price with VAT included EstimatedDeliveryDate: estimated date when the supplier can deliver the requested goods LeadTimeDays: lead time of the requested goods DiscountPercent: discount percent from supplier side MinimumBatchSize: minimum batch size the supplier can provide CountryOfOrigin: country of origin of the requested goods CustomsCode: customs code of the requested goods AdditionalInfo: any additional information

Responses

Request samples

Content type
application/json
{
  • "rfqNumber": "RFQ12345",
  • "title": "RFQ12345",
  • "description": "Request for quotation for new project",
  • "projectNumber": "P55512345",
  • "currency": "EUR",
  • "publish": true,
  • "offerDueDate": "2038-01-19",
  • "authorPerson": {
    },
  • "authorBusinessUnit": {
    },
  • "suppliers": [
    ],
  • "responsiblePersons": [
    ],
  • "requestedItems": [
    ],
  • "questions": [
    ],
  • "requestedProperties": [
    ]
}

Response samples

Content type
application/json
null

Upload one or more files to an RFQ

Upload files to attach to an RFQ document. RFQ is identified by RFQ number. You must also set the author person for the attachment, use mapped person strings for this.

Request Body schema: multipart/form-data
required
rfqNumber
required
string
authorPersonIdentifier
required
string
files
required
Array of strings <binary> [ items <binary > ]

Responses

Response samples

Content type
application/json
null

Suppliers

Endpoints for creating and managing suppliers in Jakamo SRM. The supplierNumber is the stable external key used in all operations. Lookups are case-insensitive.

Ping

Health check for the Suppliers API. Returns 200 OK if the service is reachable and the credentials are valid.

Responses

Create a new supplier

Creates a new supplier in the buyer organization's SRM.

The supplierNumber must be unique within the organization (case-insensitive) — a 409 Conflict is returned if a supplier with that number already exists.

To set custom field values, configure apiIdentifier values on template fields in the SRM settings (Settings → API integration), then pass them as entries with fieldId in fieldValues. A 400 Bad Request is returned if an unknown fieldId is provided. Fields configured as "updated by supplier" cannot be set via the integration API.

Request Body schema: application/json
required
name
required
string or null
supplierNumber
required
string or null
dunsNumber
string or null
Array of objects or null (Jakamo.Contracts.Srm.Suppliers.IntegrationFieldValueDto)
createdByIntegrationId
integer or null <int64>

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "supplierNumber": "string",
  • "dunsNumber": "string",
  • "fieldValues": [
    ],
  • "createdByIntegrationId": 0
}

Response samples

Content type
application/json
{
  • "name": "string",
  • "supplierNumber": "string",
  • "dunsNumber": "string",
  • "fieldValues": [
    ],
  • "updatedAt": "2019-08-24T14:15:22Z"
}

Get a supplier by supplier number

Returns the supplier matching the given supplierNumber within the buyer organization.

The fieldValues list in the response contains all template fields that have an apiIdentifier configured in SRM settings, including those with no value set (value will be null).

path Parameters
supplierNumber
required
string

The buyer-assigned supplier number. Lookup is case-insensitive.

Responses

Response samples

Content type
application/json
{
  • "name": "string",
  • "supplierNumber": "string",
  • "dunsNumber": "string",
  • "fieldValues": [
    ],
  • "updatedAt": "2019-08-24T14:15:22Z"
}

Update a supplier

Partially updates the supplier matching the given supplierNumber.

Null means keep: omit a field (or pass null) to leave its current value unchanged. Empty string means clear: pass "" for dunsNumber or supplierNumber to remove the value. Note: name cannot be set to empty — a 400 Bad Request is returned.

The fieldValues list is merged by fieldId — only the entries you include are updated; all other field values remain unchanged. A 409 Conflict is returned if the new supplierNumber is already taken by another supplier. Fields configured as "updated by supplier" cannot be edited via the integration API.

path Parameters
supplierNumber
required
string

The buyer-assigned supplier number of the supplier to update. Lookup is case-insensitive.

Request Body schema: application/json
required
name
string or null
dunsNumber
string or null
supplierNumber
string or null
Array of objects or null (Jakamo.Contracts.Srm.Suppliers.IntegrationFieldValueDto)

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "dunsNumber": "string",
  • "supplierNumber": "string",
  • "fieldValues": [
    ]
}

Response samples

Content type
application/json
{
  • "name": "string",
  • "supplierNumber": "string",
  • "dunsNumber": "string",
  • "fieldValues": [
    ],
  • "updatedAt": "2019-08-24T14:15:22Z"
}