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
null or string

General description of the RFQ

projectNumber
null or string

Project number of the RFQ.

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

Desired currency for the RFQ. Use ISO 4217 currency codes

publish
null or boolean

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)

Author person of the RFQ

object (Rfqs.Models.BusinessUnitModel)

Business unit that owns the rfq.

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
null or string

General description of the RFQ

projectNumber
null or string

Project number of the RFQ.

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

Desired currency for the RFQ. Use ISO 4217 currency codes

publish
null or boolean

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)

Author person of the RFQ

object (Rfqs.Models.BusinessUnitModel)

Business unit that owns the rfq.

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
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
null or string

Display name of the supplier.

supplierNumber
required
null or string

Unique supplier number within the buyer organization. Used as the stable key for GET and PATCH operations. Lookup is case-insensitive; a 409 Conflict is returned if a supplier with the same number (case-insensitively) already exists.

dunsNumber
null or string

DUNS number (9 digits) for the supplier. Leave null to omit.

Array of objects or null (Srm.Models.Api.Suppliers.FieldValueInput)

Supplier's field values to update. Only fields with an apiIdentifier set on the template can be addressed here. See Jakamo.IntegrationService.Features.Srm.Models.Api.Suppliers.FieldValueInput.

Responses

Request samples

Content type
application/json
Example
{
  • "name": "Acme Corp",
  • "supplierNumber": "SUP-001"
}

Response samples

Content type
application/json
{
  • "name": "Acme Corp",
  • "supplierNumber": "SUP-001",
  • "dunsNumber": "123456789",
  • "fieldValues": [
    ],
  • "updatedAt": "2024-06-01T12:00:00+00:00"
}

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

Responses

Response samples

Content type
application/json
{
  • "name": "Acme Corp",
  • "supplierNumber": "SUP-001",
  • "dunsNumber": "123456789",
  • "fieldValues": [
    ],
  • "updatedAt": "2024-06-01T12:00:00+00:00"
}

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
Request Body schema: application/json
required
name
null or string

New display name for the supplier. Leave null to keep the current value.

dunsNumber
null or string

DUNS number (9 digits). Leave null to keep the current value. Pass an empty string to clear it.

supplierNumber
null or string

Supplier number. Leave null to keep the current value. Pass an empty string to clear it. A 409 Conflict is returned if another supplier already has this number.

Array of objects or null (Srm.Models.Api.Suppliers.FieldValueInput)

Supplier's field values to update. Only fields with an apiIdentifier set on the template can be addressed here. See Jakamo.IntegrationService.Features.Srm.Models.Api.Suppliers.FieldValueInput.

Responses

Request samples

Content type
application/json
Example
{
  • "name": "New Supplier Name"
}

Response samples

Content type
application/json
{
  • "name": "Acme Corp",
  • "supplierNumber": "SUP-001",
  • "dunsNumber": "123456789",
  • "fieldValues": [
    ],
  • "updatedAt": "2024-06-01T12:00:00+00:00"
}

Fired when a supplier is created or updated via the integration API. Webhook

Request Body schema: application/json
required
version
null or string

Payload schema version. Currently 1.0. Will be incremented on breaking changes.

name
null or string

Display name of the supplier.

supplierNumber
null or string

Buyer-assigned supplier number, if any.

dunsNumber
null or string

DUNS number, if any.

Array of objects or null (Srm.Models.Api.Suppliers.FieldValue)

Current values of template fields that have an apiIdentifier configured.

updatedAt
string <date-time>

Responses

Request samples

Content type
application/json
{
  • "version": "1.0",
  • "name": "Acme Corp",
  • "supplierNumber": "SUP-001",
  • "dunsNumber": "123456789",
  • "fieldValues": [
    ],
  • "updatedAt": "0001-01-01T00:00:00+00:00"
}

Fired when a supplier profile is updated via the SRM UI. Webhook

Request Body schema: application/json
required
version
null or string

Payload schema version. Currently 1.0. Will be incremented on breaking changes.

name
null or string

Display name of the supplier.

supplierNumber
null or string

Buyer-assigned supplier number, if any.

dunsNumber
null or string

DUNS number, if any.

Array of objects or null (Srm.Models.Api.Suppliers.FieldValue)

Current values of template fields that have an apiIdentifier configured.

updatedAt
string <date-time>

Responses

Request samples

Content type
application/json
{
  • "version": "1.0",
  • "name": "Acme Corp",
  • "supplierNumber": "SUP-001",
  • "dunsNumber": "123456789",
  • "fieldValues": [
    ],
  • "updatedAt": "0001-01-01T00:00:00+00:00"
}

Engineering

Create a new engineering notice

Creates a new engineering notice (change or informational notice) and publishes it immediately, sharing it with the supplier — set publish: false to leave it as a draft instead, which can be published later via a follow-up update's own publish flag.

  • Notice number. Optional — if your company has notice-numbering enabled, EcmService generates its own and ignores whatever you send.
  • Author person. Shown as the author of the notice and impersonated to authorize the request. Automatically added as a customer-side responsible person.
  • Supplier. Optional at creation; can be set later via update. Locked once the notice is published. Publishing requires a supplier and a title to be set — leave publish: false if either isn't set yet.
  • responsiblePersons are additive to the author, who is always made a customer-side responsible person automatically — no need to repeat the author here.
  • projectNumber, description, additionalInformation, dueDate, part, additionalPartNumbers and purchaseOrders can all be set here too — the same fields update can edit later, so a follow-up update call isn't needed just to fill them in.
  • tasks. Ad hoc only — there is no way to create a task from your company's task-definition catalogue via this API. Each needs a title and a party (Customer, Supplier or Both); isIncluded defaults to true.

The response's resourceIdentifier is always the notice's actual number — read back after creation, since it may differ from what you submitted if notice-numbering is enabled. Use that returned value, not what you sent, for any follow-up update call.

The notice is created either way, even if publishing fails (e.g. a missing supplier or title) — this always returns 201 with that notice's number, not an error, since the resource genuinely exists at that point. Check the response message to see whether it was actually published or left as a draft.

Request Body schema: application/json
required
noticeNumber
null or string

Unique identifier of the notice within your company. Optional — if your company has notice-numbering enabled in Jakamo, EcmService generates its own number and ignores whatever you send here. Either way, the response always reflects the number actually assigned, not necessarily what you submitted — use that returned value, not this field, to update or publish the notice afterward.

type
null or string

What kind of notice this is. One of: Change, Notice. Cannot be changed after creation.

title
null or string

Display title of the notice.

collaborationMode
null or string

How the supplier participates. One of: Shared = the notice is shared to the supplier in Jakamo; the supplier works their own tasks. CustomerManaged = the supplier has no Jakamo access; the customer records progress on their behalf.

required
object (Ecm.Models.PersonModel)

Person who authors/creates the notice. Will be shown as the author to the supplier, and is used to authorize the request on your company's behalf.

object (Ecm.Models.BusinessUnitModel)

Business unit that owns the notice. Defaults to your company if not set.

object (Ecm.Models.CompanyModel)

The supplier the notice concerns. Optional at creation; can be set later via update.

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

Additional responsible persons on the customer side. The author is always added automatically as a responsible person, so this is only for anyone else who should also be responsible from the start — no need to repeat the author here.

projectNumber
null or string

Your own project/reference number for the notice.

description
null or string

Longer description of the notice.

additionalInformation
null or string

Free-form additional information.

dueDate
null or string <date-time>

Due date for the notice.

object (Ecm.Models.PartDetailsModel)

The part the notice concerns.

additionalPartNumbers
Array of strings or null

Additional part numbers, beyond the one on Jakamo.IntegrationService.Features.Ecm.Models.EcmNoticeModel.Part.

purchaseOrders
Array of strings or null

Purchase order references related to the notice.

Array of objects or null (Ecm.Models.TaskModel)

Ad-hoc tasks to add to the notice.

publish
null or boolean

Whether to publish the notice immediately, making it visible to the supplier. Defaults to true — set to false to leave it as an unpublished draft, which can be published later via update's own publish flag.

Responses

Request samples

Content type
application/json
{
  • "noticeNumber": "ECM-12345",
  • "type": "Change",
  • "title": "Bracket material change",
  • "collaborationMode": "Shared",
  • "authorPerson": {
    },
  • "customerOrganization": {
    },
  • "supplier": {
    },
  • "responsiblePersons": [
    ],
  • "projectNumber": "PRJ-2044",
  • "description": "Switch the mounting bracket to aluminium to reduce weight.",
  • "additionalInformation": "Coordinate with logistics before the next production run.",
  • "dueDate": "2026-09-30T00:00:00+00:00",
  • "part": {
    },
  • "additionalPartNumbers": [
    ],
  • "purchaseOrders": [
    ],
  • "tasks": [
    ]
}

Response samples

Content type
application/json
null

Update an existing engineering notice

Updates the notice matching the given noticeNumber. If the notice has already been published, a new draft version is opened automatically before applying the changes — the changes only become visible to the supplier once published, either by this same call (set publish: true) or a later one.

Supplier assignment/change is only possible before the notice's first publish. The notice's type can never be changed after creation. Its owning organization and collaboration mode aren't supported by this API yet, though EcmService itself allows changing them.

All fields are a partial update: omit one to leave it unchanged. part and the list fields (responsiblePersons, additionalPartNumbers, purchaseOrders) fully replace the existing value when sent — including as an empty array for the lists. dueDate is the same, except clearing it needs the explicit clearDueDate: true flag, since a null dueDate alone already means "leave unchanged". publish defaults to false, and editing other fields never publishes the notice on its own — only an explicit publish: true does that, which also requires a supplier and a title to already be set.

path Parameters
noticeNumber
required
string
Request Body schema: application/json
required
required
object (Ecm.Models.PersonModel)

Person making this update. Used to authorize the request on your company's behalf.

title
null or string

Display title of the notice.

object (Ecm.Models.CompanyModel)

The supplier the notice concerns. Assignment/change is only possible before the notice's first publish.

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

List of responsible persons on the customer side. Omit this field entirely to leave the existing list unchanged; send it (even as an empty array) to fully replace it — an empty array clears it, so include the author again here if they should remain responsible.

projectNumber
null or string

Your own project/reference number for the notice. Omit to leave unchanged.

description
null or string

Longer description of the notice. Omit to leave unchanged.

additionalInformation
null or string

Free-form additional information. Omit to leave unchanged.

dueDate
null or string <date-time>

Due date for the notice. Omit to leave unchanged; see Jakamo.IntegrationService.Features.Ecm.Models.UpdateNoticeModel.ClearDueDate to remove it.

clearDueDate
null or boolean

Set to true to remove the due date. A null Jakamo.IntegrationService.Features.Ecm.Models.UpdateNoticeModel.DueDate alone means "leave unchanged", so clearing it needs this explicit flag.

object (Ecm.Models.PartDetailsModel)

The part the notice concerns. Omit to leave unchanged.

additionalPartNumbers
Array of strings or null

Additional part numbers, beyond the one on Jakamo.IntegrationService.Features.Ecm.Models.UpdateNoticeModel.Part. Omit to leave unchanged; send it (even as an empty array) to fully replace it.

purchaseOrders
Array of strings or null

Purchase order references related to the notice. Omit to leave unchanged; send it (even as an empty array) to fully replace it.

publish
null or boolean

Whether to publish the current draft after applying these changes, making it visible to the supplier. Defaults to false — the notice stays a draft unless this is set to true.

Responses

Request samples

Content type
application/json
{
  • "authorPerson": {
    },
  • "title": "Bracket material change",
  • "supplier": {
    },
  • "responsiblePersons": [
    ],
  • "projectNumber": "PRJ-2044",
  • "description": "Switch the mounting bracket to aluminium to reduce weight.",
  • "additionalInformation": "Coordinate with logistics before the next production run.",
  • "dueDate": "2026-09-30T00:00:00+00:00",
  • "part": {
    },
  • "additionalPartNumbers": [
    ],
  • "purchaseOrders": [
    ],
  • "publish": false
}

Response samples

Content type
application/json
null

Upload one or more files to a notice

Uploads one or more supporting files to the notice matching noticeNumber — notice-level attachments only. Send as multipart/form-data with authorPersonIdentifier and one or more files.

Each file is uploaded independently, so one failing (e.g. an unsupported type) doesn't stop the rest. If every file was saved this returns 201; if some failed but at least one was saved, this returns 200 — check the message for which ones failed and why. If none were saved at all, this returns 400 instead.

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

Responses

Response samples

Content type
application/json
null