logo
API docs by Redocly

OVRSEA API (1.3.2)

Download OpenAPI specification:

Introduction

This API lets you fetch your data from OVRSEA's servers.

URL: https://api.cf.ovrsea.com

Authentication

To safely access the resources exposed by our API, you will need to provide an authenticated token in your requests headers. Please reach out to your OVRSEA’s Account Manager to get your token.

Name of the header Type of authentication
Authorization API AUTHORIZATION KEY

Please note that the API authorization key must be prefixed with "Bearer "

For example:

Authorization: Bearer 1234567890

Pagination

All endpoints fetching multiple items are paginated.

Use skip to skip to the items you want to retrieve.

Use take to define how many items you want to retrieve.

skip and take are optional parameters.

If you do not input them, skip equals to 0 and take equals to 10.

Example:

/v1/shipments?skip=20&take=10

Shipments

Fetch all shipments

Fetch all shipments of the account

query Parameters
skip
integer
Default: 0
take
integer <= 100
Default: 10

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Fetch a shipment

Fetch a shipment given its OVRSEA shipment id

path Parameters
ovrsea_shipment_id
required
string

Responses

Response samples

Content type
application/json
{
  • "name": "June Air Export USA",
  • "ovrsea_shipment_id": "CDEF",
  • "status": "booking_request",
  • "created_at": "2021-09-20T10:02:09+01:00",
  • "incoterm": "fob",
  • "freight_mode": "air",
  • "load_type": "fcl",
  • "freight_type": "port_to_door",
  • "route": {
    },
  • "cargo_ready_date": "2021-10-11",
  • "desired_delivery_date": "2021-10-11",
  • "specific_instructions": "string",
  • "cargo": {
    },
  • "transported_goods": {
    },
  • "commercial_value": {
    },
  • "needs_ad_valorem_insurance": false,
  • "purchase_order_references": [
    ],
  • "main_tracking_dates": {
    },
  • "booking_information": {
    },
  • "invoice_status": "available",
  • "invoice_references": [
    ],
  • "accepted_quote": {
    }
}

Tracking

Fetch a shipment's tracking.

Fetch a shipment's tracking with its OVRSEA shipment id.

path Parameters
ovrsea_shipment_id
required
string

Responses

Response samples

Content type
application/json
{
  • "ovrsea_shipment_id": "BATE",
  • "status": "string",
  • "tracking_steps": [
    ],
  • "ocean_coordinates": [
    ]
}

Purchase Orders

Fetch all purchase orders

Fetch all purchase orders

query Parameters
skip
integer
Default: 0
take
integer <= 100
Default: 10

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Create a purchase order

Create a purchase order with the information provided

Request Body schema: application/json
required
Array of objects
desired_delivery_date
string (SimpleDate)
desired_ex_factory_date
string (SimpleDate)
required
Array of objects
reference
required
string
supplier_id
required
string

Responses

Request samples

Content type
application/json
{
  • "custom_parameters": [
    ],
  • "desired_delivery_date": "2021-10-11",
  • "desired_ex_factory_date": "2021-10-11",
  • "product_lines": [
    ],
  • "reference": "PO5792303",
  • "supplier_id": "Detroit Factory"
}

Response samples

Content type
application/json
{
  • "reference": "string"
}

Update a purchase order

Updates a purchase order with the information provided. The existing product quantities and details will be overridden with the information provided. The update is forbidden if the Purchase Order is already associated to a shipment.

Request Body schema: application/json
required
required
Array of objects
reference
required
string

Responses

Request samples

Content type
application/json
{
  • "product_lines": [
    ],
  • "reference": "PO5792303"
}

Response samples

Content type
application/json
{
  • "reference": "string"
}

Fetch a purchase order

Fetch a purchase order with its reference

path Parameters
reference
required
string

Responses

Response samples

Content type
application/json
{
  • "po_number": "PO5792303",
  • "supplier_name": "Detroit Factory",
  • "purchase_order_lines": [
    ],
  • "desired_ex_factory_date": "2021-10-11",
  • "desired_delivery_date": "2021-10-11",
  • "custom_parameters": [
    ]
}

Documents

Fetch all documents

Fetch all your documents, or all documents associated to one of your shipments.

query Parameters
ovrsea_shipment_id
string
skip
integer
Default: 0
take
integer <= 100
Default: 10

Responses

Response samples

Content type
application/json
[]

Fetch a document

Fetch a document givent its id

path Parameters
id
required
string

Responses

Response samples

Content type
application/json
{}

Locations

Get all locations

This endpoint returns all the locations of the account.

query Parameters
skip
integer
Default: 0
take
integer <= 100
Default: 10

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get one location

This endpoint returns the location corresponding to the given ID.

path Parameters
id
required
string

Responses

Response samples

Content type
application/json
{
  • "id": 12345,
  • "company_name": "Logistics WorldWide Co",
  • "name": "Saint Quentin warehouse",
  • "address": "357 allée des Tilleuls",
  • "city": "Saint Quentin Fallavier",
  • "zip_code": 69300,
  • "country": "FR",
  • "contacts": [
    ],
  • "opening_hours": "Monday to Friday 8am to 5pm",
  • "requires_appointment": true,
  • "requires_tailgate_truck": false,
  • "additional_information": "Please avoid Friday after 4pm"
}

Invoices

Fetch all invoices

This endpoint returns all the invoices of the account.

query Parameters
skip
integer
Default: 0
take
integer <= 100
Default: 10

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Fetch an invoice

This endpoint returns the invoice corresponding to the given number.

path Parameters
reference
required
string

Responses

Response samples

Content type
application/json
{
  • "reference": "CDEF - 0342/7055 2022",
  • "number": "FAC2022-9567",
  • "ovrsea_shipment_id": "CDEF",
  • "type": "invoice",
  • "status": "available",
  • "sent_date": "2021-09-20T10:02:09+01:00",
  • "due_date": "2021-10-11",
  • "lines": [
    ],
  • "usd_to_eur_rate": 0.82
}

Users

Fetch all users

Fetch all users of the company

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Reporting

Fetch products delivery overview reporting

Fetch products delivery overview reporting

Responses

Response samples

Content type
application/json
[
  • {
    }
]

ShipmentObject

name
string
ovrsea_shipment_id
string
status
string
Enum: "booking_request" "awaiting_booking" "booked" "draft" "in_progress" "finished" "cancelled"
created_at
string (DateWithTime)
incoterm
string
Enum: "exw" "fca" "fas" "fob" "cpt" "cfr" "cif" "cip" "dap" "ddp" "dpu" "dat"
freight_mode
string
Enum: "air" "ocean" "rail" "truck"
load_type
string
Enum: "fcl" "lcl" "both"
freight_type
string
Enum: "port_to_door" "door_to_port" "door_to_door" "port_to_port"
object
cargo_ready_date
string (SimpleDate)
desired_delivery_date
string (SimpleDate)
specific_instructions
string

Optional field containing specific instruction given by the client

object
object
object (Price)
needs_ad_valorem_insurance
boolean
Default: false
purchase_order_references
Array of strings
object
object
invoice_status
string
Enum: "available" "awaiting_invoice" "due" "paid" "partially_paid"
invoice_references
Array of strings
object
{
  • "name": "June Air Export USA",
  • "ovrsea_shipment_id": "CDEF",
  • "status": "booking_request",
  • "created_at": "2021-09-20T10:02:09+01:00",
  • "incoterm": "fob",
  • "freight_mode": "air",
  • "load_type": "fcl",
  • "freight_type": "port_to_door",
  • "route": {
    },
  • "cargo_ready_date": "2021-10-11",
  • "desired_delivery_date": "2021-10-11",
  • "specific_instructions": "string",
  • "cargo": {
    },
  • "transported_goods": {
    },
  • "commercial_value": {
    },
  • "needs_ad_valorem_insurance": false,
  • "purchase_order_references": [
    ],
  • "main_tracking_dates": {
    },
  • "booking_information": {
    },
  • "invoice_status": "available",
  • "invoice_references": [
    ],
  • "accepted_quote": {
    }
}

ContainerObject

container_type
string
Enum: "twenty_foot_standard" "twenty_foot_reefer" "twenty_foot_flat_rack" "twenty_foot_open_top" "forty_foot_standard" "forty_foot_reefer" "forty_foot_flat_rack" "forty_foot_open_top" "forty_foot_highcube_standard" "forty_foot_highcube_reefer" "forty_foot_highcube_flat_rack" "forty_foot_highcube_open_top" "forty_five_foot_highcube_standard"
container_number
string
seal_number
string
purchase_order_references
Array of strings
{
  • "container_type": "twenty_foot_standard",
  • "container_number": "TEMU8667058",
  • "seal_number": 1332641,
  • "purchase_order_references": [
    ]
}

CoordinatesObject

latitude
string
longitude
string
{
  • "latitude": "48.858093",
  • "longitude": "2.294694"
}

DocumentObject

id
string
name
string
type
string
Enum: null "packing_list" "commercial_invoice" "master_bill_of_lading" "house_bill_of_lading" "master_airway_bill" "house_airway_bill" "proof_of_delivery" "dangerous_goods_declaration" "material_safety_data_sheet" "exa" "cmr" "ima" "power_of_attorney_customs_declaration" "power_of_attorney_eur1" "eur1" "entry_summary" "t1" "cargo_manifest" "cargo_screening" "lithium_certificate"
ovrsea_shipment_id
string
link
string
size
integer
uploaded_at
string (SimpleDate)
{}

InvoiceObject

reference
string
number
string
ovrsea_shipment_id
string
type
string
Default: "invoice"
Enum: "invoice" "credit_note"
status
string
Enum: "available" "due" "in_modification" "litigious" "new" "paid" "partially_paid" "write_off"
sent_date
string (DateWithTime)
due_date
string (SimpleDate)
Array of objects
usd_to_eur_rate
number <float>
{
  • "reference": "CDEF - 0342/7055 2022",
  • "number": "FAC2022-9567",
  • "ovrsea_shipment_id": "CDEF",
  • "type": "invoice",
  • "status": "available",
  • "sent_date": "2021-09-20T10:02:09+01:00",
  • "due_date": "2021-10-11",
  • "lines": [
    ],
  • "usd_to_eur_rate": 0.82
}

LoadObject

count
number
type
string <LoadType>
Enum: "pallet" "package" "rigid_crate"
object (Weight)

Weight

volume_unit
string

(deprecated)

object (Size)

Size

object (Size)

Size

object (Size)

Size

{
  • "count": 3,
  • "type": "pallet",
  • "weight": {
    },
  • "volume_unit": "cm",
  • "length": {
    },
  • "width": {
    },
  • "height": {
    }
}

LocationObject

id
string
company_name
string
name
string
address
string
city
string
zip_code
string
country
string
Array of objects
opening_hours
string
requires_appointment
boolean

Specifies if appointments are required for loading and unloading at this location.

requires_tailgate_truck
boolean

Specifies if liftgate trucks are required for this location.

additional_information
string
{
  • "id": 12345,
  • "company_name": "Logistics WorldWide Co",
  • "name": "Saint Quentin warehouse",
  • "address": "357 allée des Tilleuls",
  • "city": "Saint Quentin Fallavier",
  • "zip_code": 69300,
  • "country": "FR",
  • "contacts": [
    ],
  • "opening_hours": "Monday to Friday 8am to 5pm",
  • "requires_appointment": true,
  • "requires_tailgate_truck": false,
  • "additional_information": "Please avoid Friday after 4pm"
}

PortObject

unlocode
string
city
string
country
string
{
  • "unlocode": "FR/LEH",
  • "city": "Le Havre",
  • "country": "FR"
}

PriceObject

amount
number <float>
currency
string
Enum: "AED" "AUD" "BHD" "BRL" "CAD" "CHF" "CNY" "EUR" "GBP" "HKD" "IDR" "INR" "JPY" "MXN" "KRW" "KWD" "MYR" "NZD" "PLN" "SEK" "SGD" "THB" "TWD" "USD" "XOF" "XPF" "ZAR"
{
  • "amount": 150357.99,
  • "currency": "USD"
}

PurchaseOrderObject

po_number
string
supplier_name
string

Supplier name as per client convention

Array of objects
desired_ex_factory_date
string (SimpleDate)
desired_delivery_date
string (SimpleDate)
Array of objects

Array of up to 6 custom parameters

{
  • "po_number": "PO5792303",
  • "supplier_name": "Detroit Factory",
  • "purchase_order_lines": [
    ],
  • "desired_ex_factory_date": "2021-10-11",
  • "desired_delivery_date": "2021-10-11",
  • "custom_parameters": [
    ]
}

ProductObject

sku
required
string
hs_code
string
description
string
is_hazardous
boolean
Default: "false"
hazardous_description
string
Array of objects

Array of up to 3 custom parameters

{
  • "sku": "REF0123458",
  • "hs_code": "96032930",
  • "description": "blue shirt with a T shape",
  • "is_hazardous": "false",
  • "hazardous_description": "UN1993",
  • "custom_parameters": [
    ]
}

QuantityObject

value
number <float>
unit
string
Enum: "tc" "teu" "t" "pallet" "cbm" "kg" "cm" "chargeable_weight" "weight_measurement_lcl" "km" "null"
{
  • "value": 350.25,
  • "unit": "tc"
}

SimpleDateObject

string (SimpleDate)
"2021-10-11"

DateWithTimeObject

string (DateWithTime)
"2021-09-20T10:02:09+01:00"

SizeObject

value
number <float>
unit
string
Enum: "cm" "in"
{
  • "value": 10.25,
  • "unit": "cm"
}

TrackingObject

ovrsea_shipment_id
string
status
string
Array of objects (TrackingStep)
Array of objects (Coordinates)
{
  • "ovrsea_shipment_id": "BATE",
  • "status": "string",
  • "tracking_steps": [
    ],
  • "ocean_coordinates": [
    ]
}

TrackingDateObject

date
string (DateWithTime)
status
string
Enum: "estimated" "actual" "planned" "problem"
{
  • "date": "2021-09-20T10:02:09+01:00",
  • "status": "estimated"
}

TrackingEventObject

description
string
container_number
string
date
string (DateWithTime)
status
string
Enum: "estimated" "actual" "planned" "problem"
{
  • "description": "Loaded on Vessel",
  • "container_number": "MSDU8878398",
  • "date": "2021-09-20T10:02:09+01:00",
  • "status": "estimated"
}

TrackingStepObject

type
string
Enum: "location" "port"
object (Location)
object (Port)
Array of objects (TrackingEvent)
{
  • "type": "location",
  • "location": {
    },
  • "port": {
    },
  • "events": [
    ]
}

UserObject

id
string
email
string
first_name
string
last_name
string
phone
string
role
string
{
  • "id": "12345",
  • "email": "user@email.com",
  • "first_name": "John",
  • "last_name": "Doe",
  • "phone": "0776655443",
  • "role": "manager"
}

VolumeObject

value
number <float>
unit
string
{
  • "value": 10.25,
  • "unit": "cbm"
}

WeightObject

value
number <float>
unit
string
Enum: "kg" "lbs"
{
  • "value": 350.25,
  • "unit": "kg"
}