Overview

The Qvian External Requests API allows programmatic access to public requests on the Qvian platform. This API is designed for businesses to integrate Qvian's functionality into their own applications or systems.

Base URL

https://qvian.com/express/

Authentication

All API requests require an API key to be included in the request header:

To obtain an API key, log in to your Qvian account and navigate to the general settings section in your settings.

Rate Limiting

Requests are limited to 100 per 15-minute window per IP address. If you exceed this limit, you'll receive a 429 Too Many Requests response.

Endpoints

1. Requests List

Retrieves a list of public requests for the buyer associated with the provided API key.

• URL: /external-requests/requests
• Method: GET
• Auth required: Yes

Request Headers

Header	Type	Required	Description
X-API-Key	string	Yes	Your API key for authentication

Query Parameters

Parameter	Type	Required	Description
page	number	No	Page number for pagination (default: 1)
limit	number	No	Number of items per page (default: 10, max: 100)
publicRequest	boolean	No	Filter by public/private requests (default: true)

Success Response

• Code: 200 OK

Error Responses

• Code: 401 Unauthorized
  • Content: { "message": "API key is required" } or { "message": "Invalid or inactive API key" }
• Code: 404 Not Found
  • Content: { "message": "Buyer not found" }
• Code: 429 Too Many Requests
  • Content: { "message": "Too many requests, please try again later" }
• Code: 500 Internal Server Error
  • Content: { "message": "Server error", "error": "Error details" }

2. Get Single Request

Retrieves details of a single public request by its ID.

• URL: /external-requests/requests/:requestId
• Method: GET
• URL Params:
  • requestId=[string] (MongoDB ObjectId)
• Auth required: Yes

Request Headers

Header	Type	Required	Description
X-API-Key	string	Yes	Your API key for authentication

Success Response

• Code: 200 OK
• Content example:

Error Responses

• Code: 400 Bad Request
  • Content: { "errors": [{ "msg": "Invalid value", "param": "requestId", "location": "params" }] }
• Code: 401 Unauthorized
  • Content: { "message": "API key is required" } or { "message": "Invalid or inactive API key" }
• Code: 404 Not Found
  • Content: { "message": "Request not found or not public" }
• Code: 429 Too Many Requests
  • Content: { "message": "Too many requests, please try again later" }
• Code: 500 Internal Server Error
  • Content: { "message": "Server error", "error": "Error details" }

Data Models

Request Object

Field	Type	Description
id	string	Unique identifier for the request
title	string	Title/heading of the request
description	string	Detailed description of the request
requestNumber	string	Unique request reference number
requestDate	string	ISO 8601 formatted date when request was created
expiryDate	string	ISO 8601 formatted date when request expires
expiryTime	string	Time when the request expires
requestedCountry	string	Country where service is requested
requestedCity	string	City where service is requested
requestDocuments	string[]	Array of document URLs attached to request
category	string	Category of the request
categoryTypes	string[]	General categories of the request
userName	string	Name of the user who created the request
quotationCount	number	Number of quotations received for this request
profileName	string	Name of the company/organization
logo	string	logo of the company/organization
items	RequestItem[]	Array of items requested in the request

RequestItem Object

Field	Type	Required	Description
itemId	string	Yes	Unique identifier for the item
categoryName	string	Yes	Category of the item
qty	number	Yes	Quantity of the item
unit	string	No	Unit of measurement
formFields	object	Yes	Additional form fields for the item

Changelog

• 2024-09-15: Initial release of the External Requests API