Fairmarkit Supplier Public API
Supplier-side Public API for retrieving buyer requests, reviewing request responses, submitting responses/bids, and rejecting requests. OpenAPI 3.1, API-key authenticated via the X-FM-API-KEY header.
OpenAPI Specification
{
"openapi": "3.1.0",
"info": {
"title": "Supplier Public Api",
"version": "1.20250902.1-release"
},
"servers": [
{
"url": "https://uat.fairmarkit.com",
"description": "UAT"
}
],
"paths": {
"/services/supplier-public-api/api/v1/requests/{request_id}/reject/": {
"post": {
"tags": [
"Requests",
"Requests",
"Requests"
],
"summary": "Reject Request",
"description": "Creates a Response with rejection information for the Request with provided request_id",
"operationId": "reject_request-Requests_Requests_Requests",
"security": [
{
"SupplierPublicAPIHeader": []
}
],
"parameters": [
{
"name": "request_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"format": "uuid",
"description": "Unique request ID.",
"examples": [
"b61da388-b09b-4334-ae8c-d7d89722a6d8"
],
"title": "Request Id"
},
"description": "Unique request ID."
},
{
"name": "x-fm-api-key",
"in": "header",
"required": true,
"schema": {
"type": "string",
"description": "Your unique personal api key generated on https://app.fairmarkit.com/vendor/administration/api-settings",
"title": "X-Fm-Api-Key"
},
"description": "Your unique personal api key generated on https://app.fairmarkit.com/vendor/administration/api-settings"
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/RequestRejectRequest"
}
}
}
},
"responses": {
"204": {
"description": "Successful Response"
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
}
}
}
}
},
"/services/supplier-public-api/api/v1/requests/{request_id}/response/": {
"get": {
"tags": [
"Requests",
"Requests",
"Requests"
],
"summary": "Get Request Response",
"description": "Returns information about Response that you submit for Request by provided request id.",
"operationId": "get_request_response-Requests_Requests_Requests",
"security": [
{
"SupplierPublicAPIHeader": []
}
],
"parameters": [
{
"name": "request_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"format": "uuid",
"description": "Unique request ID.",
"examples": [
"b61da388-b09b-4334-ae8c-d7d89722a6d8"
],
"title": "Request Id"
},
"description": "Unique request ID."
},
{
"name": "x-fm-api-key",
"in": "header",
"required": true,
"schema": {
"type": "string",
"description": "Your unique personal api key generated on https://app.fairmarkit.com/vendor/administration/api-settings",
"title": "X-Fm-Api-Key"
},
"description": "Your unique personal api key generated on https://app.fairmarkit.com/vendor/administration/api-settings"
}
],
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/DetailResponse"
}
}
}
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
}
}
}
}
},
"/services/supplier-public-api/api/v1/requests/{request_id}/": {
"get": {
"tags": [
"Requests",
"Requests",
"Requests"
],
"summary": "Get Request",
"description": "Returns full information about the Request by provided id",
"operationId": "get_request-Requests_Requests_Requests",
"security": [
{
"SupplierPublicAPIHeader": []
}
],
"parameters": [
{
"name": "request_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"format": "uuid",
"description": "Unique request ID.",
"examples": [
"b61da388-b09b-4334-ae8c-d7d89722a6d8"
],
"title": "Request Id"
},
"description": "Unique request ID."
},
{
"name": "x-fm-api-key",
"in": "header",
"required": true,
"schema": {
"type": "string",
"description": "Your unique personal api key generated on https://app.fairmarkit.com/vendor/administration/api-settings",
"title": "X-Fm-Api-Key"
},
"description": "Your unique personal api key generated on https://app.fairmarkit.com/vendor/administration/api-settings"
}
],
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/DetailRequestResponse"
}
}
}
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
}
}
}
}
},
"/services/supplier-public-api/api/v1/requests/{request_id}/submit/": {
"post": {
"tags": [
"Requests",
"Requests",
"Requests"
],
"summary": "Submit Response",
"description": "Creates a Response for the Request with provided request_id",
"operationId": "submit_response-Requests_Requests_Requests",
"security": [
{
"SupplierPublicAPIHeader": []
}
],
"parameters": [
{
"name": "request_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"format": "uuid",
"description": "Unique request ID.",
"examples": [
"b61da388-b09b-4334-ae8c-d7d89722a6d8"
],
"title": "Request Id"
},
"description": "Unique request ID."
},
{
"name": "x-fm-api-key",
"in": "header",
"required": true,
"schema": {
"type": "string",
"description": "Your unique personal api key generated on https://app.fairmarkit.com/vendor/administration/api-settings",
"title": "X-Fm-Api-Key"
},
"description": "Your unique personal api key generated on https://app.fairmarkit.com/vendor/administration/api-settings"
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ResponseSubmitRequest"
}
}
}
},
"responses": {
"204": {
"description": "Successful Response"
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
}
}
}
}
},
"/services/supplier-public-api/api/v1/requests/": {
"get": {
"tags": [
"Requests",
"Requests",
"Requests"
],
"summary": "Get Requests",
"description": "Returns a list of Requests that Buyer creates for your company",
"operationId": "get_requests-Requests_Requests_Requests",
"security": [
{
"SupplierPublicAPIHeader": []
}
],
"parameters": [
{
"name": "ordering",
"in": "query",
"required": false,
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/RequestOrdering"
},
"description": "Field name and direction in which result will be ordered. F.e.: \"-created_at\" means that result will be ordered by created_at DESC",
"examples": [
"created_at",
"-created_at",
"updated_at",
"-updated_at",
"closes_at",
"-closes_at"
],
"enum": [
"created_at",
"-created_at",
"updated_at",
"-updated_at",
"closes_at",
"-closes_at"
],
"default": [
"-created_at"
],
"title": "Ordering"
},
"description": "Field name and direction in which result will be ordered. F.e.: \"-created_at\" means that result will be ordered by created_at DESC"
},
{
"name": "status",
"in": "query",
"required": false,
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/RequestStatus"
},
"description": "Filter records by status value.",
"examples": [
"new",
"missed",
"canceled",
"viewed",
"ignored",
"submitted",
"waiting_for_award",
"lost",
"won",
"declined"
],
"enum": [
"new",
"missed",
"canceled",
"viewed",
"ignored",
"submitted",
"waiting_for_award",
"lost",
"won",
"declined"
],
"default": [
"new"
],
"title": "Status"
},
"description": "Filter records by status value."
},
{
"name": "limit",
"in": "query",
"required": false,
"schema": {
"type": "integer",
"maximum": 100,
"minimum": 1,
"description": "Use to specify the maximum number of records to return. By default, 20 records are returned.",
"default": 20,
"title": "Limit"
},
"description": "Use to specify the maximum number of records to return. By default, 20 records are returned."
},
{
"name": "offset",
"in": "query",
"required": false,
"schema": {
"type": "integer",
"minimum": 1,
"description": "Use to retrieve a specific batch of records. By default, this is set to 0.",
"default": 0,
"title": "Offset"
},
"description": "Use to retrieve a specific batch of records. By default, this is set to 0."
},
{
"name": "x-fm-api-key",
"in": "header",
"required": true,
"schema": {
"type": "string",
"description": "Your unique personal api key generated on https://app.fairmarkit.com/vendor/administration/api-settings",
"title": "X-Fm-Api-Key"
},
"description": "Your unique personal api key generated on https://app.fairmarkit.com/vendor/administration/api-settings"
}
],
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/ListRequestResponse"
},
"title": "Response Get Requests-Requests Requests Requests"
}
}
}
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
}
}
}
}
}
},
"components": {
"schemas": {
"HTTPValidationError": {
"properties": {
"detail": {
"items": {
"$ref": "#/components/schemas/ValidationError"
},
"type": "array",
"title": "Detail"
}
},
"type": "object",
"title": "HTTPValidationError"
},
"RejectionKind": {
"type": "string",
"enum": [
"out_of_stock",
"items_not_carried",
"more_information_needed_to_quote",
"price_not_competitive",
"ship_address_outside_our_coverage_area",
"other"
],
"title": "RejectionKind"
},
"RequestRejectRequest": {
"properties": {
"reject_kind": {
"$ref": "#/components/schemas/RejectionKind",
"description": "Available kinds of rejection. In case chosen \"other\", please should describe the reason.",
"examples": [
"out_of_stock",
"items_not_carried",
"more_information_needed_to_quote",
"price_not_competitive",
"ship_address_outside_our_coverage_area",
"other"
]
},
"reject_reason": {
"type": "string",
"title": "Reject Reason",
"description": "Reason of rejection. Should be described in case rejection kind \"other\"",
"default": "",
"examples": [
"We are not working at next week",
""
]
}
},
"type": "object",
"required": [
"reject_kind"
],
"title": "RequestRejectRequest"
},
"ValidationError": {
"properties": {
"loc": {
"items": {
"anyOf": [
{
"type": "string"
},
{
"type": "integer"
}
]
},
"type": "array",
"title": "Location"
},
"msg": {
"type": "string",
"title": "Message"
},
"type": {
"type": "string",
"title": "Error Type"
}
},
"type": "object",
"required": [
"loc",
"msg",
"type"
],
"title": "ValidationError"
},
"DetailResponse": {
"properties": {
"status": {
"$ref": "#/components/schemas/ResponseStatus",
"description": "Actual Response status.",
"examples": [
"sent",
"opened",
"submitted",
"awarded",
"no_bid"
]
},
"vendor_quote": {
"type": "string",
"title": "Vendor Quote",
"description": "Vendor quote number.",
"examples": [
"DFR440-DB"
]
},
"valid_for": {
"anyOf": [
{
"$ref": "#/components/schemas/ResponseValidFor"
},
{
"type": "null"
}
],
"description": "The number of days during which the offer will be valid.",
"examples": [
1,
5,
7,
10,
15,
30,
45,
60,
90,
180,
365
]
},
"is_shipping_included": {
"type": "boolean",
"title": "Is Shipping Included",
"description": "Is shipping included in the total price?",
"examples": [
true,
false
]
},
"shipping": {
"type": "string",
"title": "Shipping",
"description": "Cost of shipping in case it not included in the total price",
"examples": [
"49.99",
"0"
]
},
"is_partially_awarded": {
"type": "boolean",
"title": "Is Partially Awarded",
"description": "Means that minimum one of the proposed item by supplier was awarded",
"examples": [
true,
false
]
},
"notes": {
"type": "string",
"title": "Notes",
"description": "Additional notes from Supplier for Buyer related to the response, if exists.",
"examples": [
"Please contact us asap."
]
},
"currency": {
"type": "string",
"title": "Currency",
"description": "Currency of response.",
"examples": [
"USD",
"CAD",
"EUR",
"AUD"
]
},
"awarded_total": {
"type": "string",
"title": "Awarded Total",
"description": "Total awarded price by Buyer.",
"examples": [
"100",
"4.99",
"0"
]
},
"sent_at": {
"type": "string",
"title": "Sent At",
"description": "Date and time when request was sent to Supplier.",
"examples": [
"2025-09-01 08:39:24.205913+00:00"
]
},
"opened_at": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Opened At",
"description": "Date and time when request was viewed by Supplier first time.",
"examples": [
"2025-09-01 08:39:24.205945+00:00"
]
},
"submitted_at": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Submitted At",
"description": "Date and time when response was submitted by Supplier last time.",
"examples": [
"2025-09-01 08:39:24.205968+00:00"
]
},
"rejection_at": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Rejection At",
"description": "Date and time when response was rejected by Supplier last time.",
"examples": [
"2025-09-01 08:39:24.205987+00:00"
]
},
"rejection_kind": {
"$ref": "#/components/schemas/RejectionKindWithEmpty",
"description": "Rejection kind that was set by Supplier during rejection. Will be empty in case request wasn't rejected.",
"examples": [
"out_of_stock",
"items_not_carried",
"more_information_needed_to_quote",
"price_not_competitive",
"ship_address_outside_our_coverage_area",
"other",
""
]
},
"rejection_reason": {
"type": "string",
"title": "Rejection Reason",
"description": "Reason of rejection in case was chosen rejection kind \"other\". Could be empty in other cases.",
"examples": [
"We are on the vacation.",
""
]
},
"awarded_at": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Awarded At",
"description": "Date and time when response was awarded by Buyer.",
"examples": [
"2025-09-01 08:39:24.206048+00:00"
]
},
"items": {
"items": {
"$ref": "#/components/schemas/DetailResponseItem"
},
"type": "array",
"title": "Items"
}
},
"type": "object",
"required": [
"status",
"vendor_quote",
"valid_for",
"is_shipping_included",
"shipping",
"is_partially_awarded",
"notes",
"currency",
"awarded_total",
"sent_at",
"opened_at",
"submitted_at",
"rejection_at",
"rejection_kind",
"rejection_reason",
"awarded_at",
"items"
],
"title": "DetailResponse"
},
"DetailResponseItem": {
"properties": {
"id": {
"type": "string",
"title": "Id",
"description": "Response item unique ID.",
"examples": [
"3e31ad9c-a78a-4925-8266-665aef520719"
]
},
"title": {
"type": "string",
"title": "Title",
"description": "Request item title.",
"examples": [
"Apple Iphone 16 PRO MAX 1TB"
]
},
"quantity": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Quantity",
"description": "Amount of items that was proposed by supplier.",
"examples": [
"10",
"1.5",
null
]
},
"awarded_quantity": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Awarded Quantity",
"description": "Amount of items that Buyer was awarded.",
"examples": [
"10",
"1.5",
null
]
},
"uom": {
"type": "string",
"title": "Uom",
"description": "Unit of measurement.",
"examples": [
"each",
"bar",
"kilogram",
""
]
},
"unit_price": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Unit Price",
"description": "Item's unit price",
"examples": [
"10",
"1.5",
"0",
null
]
},
"delivery_days": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"title": "Delivery Days",
"description": "The number of days during which current item was planned to be delivered.",
"examples": [
1,
5,
null
]
},
"is_awarded": {
"type": "boolean",
"title": "Is Awarded",
"description": "Will be True in case item was awarded by buyer.",
"examples": [
true,
false
]
},
"is_rejected": {
"type": "boolean",
"title": "Is Rejected",
"description": "Will be True in case item was rejected by supplier.",
"examples": [
true,
false
]
},
"supplier_pn": {
"type": "string",
"title": "Supplier Pn",
"description": "Supplier part number",
"examples": [
"HDY66-X2"
]
},
"sku": {
"type": "string",
"title": "Sku",
"description": "Stock Keeping Unit.",
"examples": [
"ZG011AQA"
]
},
"quantity_change_reason_note": {
"type": "string",
"title": "Quantity Change Reason Note",
"description": "Note for buyer why will be bid not different quantity.",
"examples": [
"There are 12 bottles in the box."
]
},
"minimum_order_quantity": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"title": "Minimum Order Quantity",
"description": "Information for minimum order quantity",
"examples": [
"10",
"1.5",
null
]
},
"country_of_origin": {
"type": "string",
"title": "Country Of Origin",
"description": "Country of origin",
"examples": [
"US",
"Canada",
""
]
},
"comments": {
"type": "string",
"title": "Comments",
"description": "Comment for buyer related bid item.",
"examples": [
"Hot offer until the end of the week",
""
]
}
},
"type": "object",
"required": [
"id",
"title",
"quantity",
"awarded_quantity",
"uom",
"unit_price",
"delivery_days",
"is_awarded",
"is_rejected",
"supplier_pn",
"sku",
"quantity_change_reason_note",
"minimum_order_quantity",
"country_of_origin",
"comments"
],
"title": "DetailResponseItem"
},
"RejectionKindWithEmpty": {
"type": "string",
"enum": [
"out_of_stock",
"items_not_carried",
"more_information_needed_to_quote",
"price_not_competitive",
"ship_address_outside_our_coverage_area",
"other",
""
],
"title": "RejectionKindWithEmpty"
},
"ResponseStatus": {
"type": "string",
"enum": [
"sent",
"opened",
"submitted",
"awarded",
"no_bid"
],
"title": "ResponseStatus"
},
"ResponseValidFor": {
"type": "integer",
"enum": [
1,
5,
7,
10,
15,
30,
45,
60,
90,
180,
365
],
"title": "ResponseValidFor"
},
"CarrierKind": {
"type": "string",
"enum": [
"ups",
"fedex",
"dhl",
"usps",
""
],
"title": "CarrierKind"
},
"DetailRequestItemResponse": {
"properties": {
"id": {
"type": "string",
"title": "Id",
"description": "Unique request item ID.",
"examples": [
"ba309b6f-6161-4ca2-a43d-724dacc21e0c"
]
},
"kind": {
"type": "string",
"title": "Kind",
"description": "Request item kind.",
"examples": [
"item",
"service"
]
},
"title": {
"type": "string",
"title": "Title",
"description": "Request item title.",
"examples": [
"Apple Iphone 16 PRO MAX 1TB"
]
},
"manufacturer": {
"type": "string",
"title": "Manufacturer",
"description": "Request item manufacturer.",
"examples": [
"Amazing Dreams Inc."
]
},
"manufacturer_pn": {
"type": "string",
"title": "Manufacturer Pn",
"description": "Request item manufacturer part number.",
"examples": [
"YFD220125-i",
"70-107"
]
},
"comments": {
"type": "string",
"title": "Comments",
"description": "Buyer's comments for the request item",
"examples": [
"color: red"
]
},
"uom": {
"type": "string",
"title": "Uom",
"description": "Unit of measurement.",
"examples": [
"each",
"bar",
"kilogram"
]
},
"is_awarded": {
"type": "boolean",
"title": "Is Awarded",
"description": "Has request item already awarded",
"examples": [
true,
false
]
},
"awarded_at": {
"type": "string",
"title": "Awarded At",
"description": "Date and time of when request item was awarded. Will be None in case if request item still not awarded.",
"examples": [
"2025-09-01 08:39:24.201724+00:00",
""
]
},
"quantity": {
"type": "string",
"title": "Quantity",
"description": "Requested quantity of request item. Could be empty in case request item in uncountable.",
"examples": [
"10",
"1.5",
""
]
}
},
"type": "object",
"required": [
"id",
"kind",
"title",
"manufacturer",
"manufacturer_pn",
"comments",
"uom",
"is_awarded",
"awarded_at",
"quantity"
],
"title": "DetailRequestItemResponse"
},
"DetailRequestResponse": {
"properties": {
"id": {
"type": "string",
"title": "Id",
"description": "Unique request ID.",
"examples": [
"e3f18428-6e27-4b34-855f-e635a8c56b8b"
]
},
"ref_id": {
"type": "integer",
"title": "Ref Id",
"description": "Reference ID from platform.",
"examples": [
1,
100500
]
},
"title": {
"type": "string",
"title": "Title",
"description": "Request title.",
"examples": [
"Apple Iphone 16 PRO MAX 1TB"
]
},
"customer_title": {
"type": "string",
"title": "Customer Title
# --- truncated at 32 KB (51 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/fairmarkit/refs/heads/main/openapi/fairmarkit-supplier-openapi.json