Technical
description scope-rest-webservices
Quotation API
Overview
The Quotation API provides endpoints for creating, managing, and retrieving quotations in Scope. A quotation represents a commercial offer for a customer shipment request.
A quotation may contain multiple options. Each option represents a distinct transport solution with its own routing, carriers, and pricing. For example, a direct flight versus a multi-leg connection or services operated by different airlines.
The API currently supports the following operations:
- Create quotations with general information and goods details. Quotation options with carrier and price information are managed by a separate endpoint.
- View quotations
Additional capabilities are planned or under development:
- Create and delete quotation options including carriers and price information (in development)
- Calculate quotations based on activities and tariffs configured in Scope (planned)
- Update quotation statuses following customer acceptance or rejection (planned)
- Create shipments or bookings from existing quotations (planned)
⚠️ Stability notice
This API is under active development. Some endpoints are not yet implemented. For features marked as in development, the API contract, request and response schemas, and endpoint behavior may change without notice until the functionality is finalized.
Quotation resource
The quotation resource includes the following information:
- General quotation information, including prospect details, origin and destination locations, and goods information
- One or more quotation options, including:
- Carriers and products
- Income and cost details
- Carbon footprint calculation results
- Reference numbers
- Internal operational notes
- Documents associated with the quotation
Limitations
The following limitations currently apply:
- The API does not support the creation of quotations containing dangerous goods (DGR) information
- The API does not support quotations with multiple main transport legs, such as multiple flights or ocean vessel voyages
- The API does not support taxes on revenue items when taxation is enabled for quotations in Scope
Master data references
The Quotation API references various master data entities. These entities should be referenced using identifiers or standardized codes rather than embedded as complete objects within API requests.
| Master data entity | Reference details |
|---|---|
| Quotation template | Referenced by identifier. Currently, only the default template configured at the branch level is supported. An API for retrieving quotation templates is planned, enabling the application of specific templates. |
| Owner | Each quotation is owned by a branch in Scope. A branch is represented by a branch partner. Branch partners can be queried with a filter option branchPartnersOnly using the Partner API |
| Prospect, shipper or consignee | Can either be a Scope partner or postal address. Scope partners can be referenced by identifier or customer identification number. See Partner API |
| Sales person | Referenced by identifier, see Salesperson API |
| Package types | Scope package types are referenced by their immutable package type code. |
| Air carrier | Air carriers are referenced using IATA airline codes or AWB prefixes. |
| Sea container types | Seafreight containers are referenced using ISO-6346 container codes. |
| Sea / ocean carrier | Sea carriers are referenced using SCAC codes. |
| Booking agent | Seafreight booking agents are Scope partners with the role liner agent. Referenced by identifier or customer identification number, see Partner API |
| Road carrier | Road carriers are Scope partners with the role road carrier. Referenced by identifier or customer identification number, see Partner API |
| Buying products | Referenced by identifier. A Product API is planned. |
| Selling products | Referenced by identifier. A Product API is planned. |
| Charge types | Referenced by identifier, see Charge Type API |
| Cost center | Cost centers are optional and should only be set when explicitly required. Referenced by identifier. A Cost Center API is planned. |
| Airports | Referenced using three-letter IATA airport codes. |
| UN/Locodes | Referenced using five-letter codes for trade and transport locations. |
| Currency | Referenced using ISO-4217 three-letter currency codes. |
| Country | Referenced using ISO 3166-1 two-letter country codes. |
API request and response
Creating a quotation is a multi-step process. Quotations are built incrementally through a series of API requests.
- Create the quotation and provide the general quotation information. Once created, a quotation cannot be modified currently.
- Create one or more quotation options as required. Each option represents a transport solution with its own carriers, services, and pricing details. Quotation options cannot be modified after creation, but they can be deleted.
- Upload documents associated with the quotation using the document upload endpoint.
This approach allows quotation data, transport options, and supporting documents to be managed independently.
Data formats
The API supports both XML and JSON representations. Regardless of the selected format, requests and responses follow the same logical data model and contain equivalent information.
Current XML schema version 1: quotation-v1.xsd
Imported schemas:
Examples: View quotation
Examples: Create quotation
- Air: quotation-air-creation-1.0.xml / quotation-air-creation-1.0.json
- Sea FCL: quotation-seafcl-creation-1.0.xml / quotation-seafcl-creation-1.0.json
- Sea LCL: quotation-sealcl-creation-1.0.xml / quotation-sealcl-creation-1.0.json
- Simple shipment road: quotation-sh-creation-1.0.xml / quotation-sh-creation-1.0.json
Examples: Create quotation option
API documentation
The API is described using the OpenAPI Specification (OAS), enabling tools such as Swagger UI and OpenAPI Generator to visualize the API and generate client code for a wide range of programming languages.
Version 1
- Open in Swagger Editor Next
- Specification file: quotation-api-1.0.json