Create a shipment request

POST

/api/integrations/v1/shipment-requests

using System.Net.Http.Headers;
var client = new HttpClient();
var request = new HttpRequestMessage
{
    Method = HttpMethod.Post,
    RequestUri = new Uri("https://app.quatlasglobal.com/api/integrations/v1/shipment-requests"),
    Headers =
    {
        { "Authorization", "Bearer <token>" },
    },
    Content = new StringContent("{ \"cargo\": { \"description\": \"example\", \"dimensions\": \"example\", \"exceedsStandard\": true, \"fragile\": true, \"hazardous\": true, \"maxStackLayers\": 1, \"maxTopLoadKg\": 1, \"outOfGauge\": true, \"packageCount\": 1, \"stackable\": true, \"standardType\": \"example\", \"temperatureMaxC\": 1, \"temperatureMinC\": 1, \"volumeM3\": 1, \"weightKg\": 1 }, \"costCenter\": \"example\", \"destination\": { \"addressLine\": \"example\", \"city\": \"example\", \"contactName\": \"example\", \"contactPhone\": \"example\", \"countryCode\": \"example\", \"handling\": \"example\", \"locationType\": \"example\", \"postalCode\": \"example\", \"unLocode\": \"example\", \"windowFrom\": \"example\", \"windowTo\": \"example\" }, \"externalReference\": \"example\", \"incoterm\": \"example\", \"isFlexibleSchedule\": true, \"metadata\": \"example\", \"modePolicy\": \"example\", \"notes\": \"example\", \"origin\": { \"addressLine\": \"example\", \"city\": \"example\", \"contactName\": \"example\", \"contactPhone\": \"example\", \"countryCode\": \"example\", \"handling\": \"example\", \"locationType\": \"example\", \"postalCode\": \"example\", \"unLocode\": \"example\", \"windowFrom\": \"example\", \"windowTo\": \"example\" }, \"preferredDeliveryDate\": \"2026-04-15\", \"preferredDeliveryTime\": \"example\", \"preferredPickupDate\": \"2026-04-15\", \"publish\": true, \"purchaseOrderNumber\": \"example\", \"transportMode\": \"example\" }")
    {
        Headers =
        {
            ContentType = new MediaTypeHeaderValue("application/json")
        }
    }
};
using (var response = await client.SendAsync(request))
{
    response.EnsureSuccessStatusCode();
    var body = await response.Content.ReadAsStringAsync();
    Console.WriteLine(body);
}

HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://app.quatlasglobal.com/api/integrations/v1/shipment-requests"))
    .header("Authorization", "Bearer <token>")
    .header("Content-Type", "application/json")
    .method("POST", HttpRequest.BodyPublishers.ofString("{ \"cargo\": { \"description\": \"example\", \"dimensions\": \"example\", \"exceedsStandard\": true, \"fragile\": true, \"hazardous\": true, \"maxStackLayers\": 1, \"maxTopLoadKg\": 1, \"outOfGauge\": true, \"packageCount\": 1, \"stackable\": true, \"standardType\": \"example\", \"temperatureMaxC\": 1, \"temperatureMinC\": 1, \"volumeM3\": 1, \"weightKg\": 1 }, \"costCenter\": \"example\", \"destination\": { \"addressLine\": \"example\", \"city\": \"example\", \"contactName\": \"example\", \"contactPhone\": \"example\", \"countryCode\": \"example\", \"handling\": \"example\", \"locationType\": \"example\", \"postalCode\": \"example\", \"unLocode\": \"example\", \"windowFrom\": \"example\", \"windowTo\": \"example\" }, \"externalReference\": \"example\", \"incoterm\": \"example\", \"isFlexibleSchedule\": true, \"metadata\": \"example\", \"modePolicy\": \"example\", \"notes\": \"example\", \"origin\": { \"addressLine\": \"example\", \"city\": \"example\", \"contactName\": \"example\", \"contactPhone\": \"example\", \"countryCode\": \"example\", \"handling\": \"example\", \"locationType\": \"example\", \"postalCode\": \"example\", \"unLocode\": \"example\", \"windowFrom\": \"example\", \"windowTo\": \"example\" }, \"preferredDeliveryDate\": \"2026-04-15\", \"preferredDeliveryTime\": \"example\", \"preferredPickupDate\": \"2026-04-15\", \"publish\": true, \"purchaseOrderNumber\": \"example\", \"transportMode\": \"example\" }"))
    .build();
HttpResponse<String> response = HttpClient.newHttpClient().send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());

const url = 'https://app.quatlasglobal.com/api/integrations/v1/shipment-requests';
const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: '{"cargo":{"description":"example","dimensions":"example","exceedsStandard":true,"fragile":true,"hazardous":true,"maxStackLayers":1,"maxTopLoadKg":1,"outOfGauge":true,"packageCount":1,"stackable":true,"standardType":"example","temperatureMaxC":1,"temperatureMinC":1,"volumeM3":1,"weightKg":1},"costCenter":"example","destination":{"addressLine":"example","city":"example","contactName":"example","contactPhone":"example","countryCode":"example","handling":"example","locationType":"example","postalCode":"example","unLocode":"example","windowFrom":"example","windowTo":"example"},"externalReference":"example","incoterm":"example","isFlexibleSchedule":true,"metadata":"example","modePolicy":"example","notes":"example","origin":{"addressLine":"example","city":"example","contactName":"example","contactPhone":"example","countryCode":"example","handling":"example","locationType":"example","postalCode":"example","unLocode":"example","windowFrom":"example","windowTo":"example"},"preferredDeliveryDate":"2026-04-15","preferredDeliveryTime":"example","preferredPickupDate":"2026-04-15","publish":true,"purchaseOrderNumber":"example","transportMode":"example"}'
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}

curl --request POST \
  --url https://app.quatlasglobal.com/api/integrations/v1/shipment-requests \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "cargo": { "description": "example", "dimensions": "example", "exceedsStandard": true, "fragile": true, "hazardous": true, "maxStackLayers": 1, "maxTopLoadKg": 1, "outOfGauge": true, "packageCount": 1, "stackable": true, "standardType": "example", "temperatureMaxC": 1, "temperatureMinC": 1, "volumeM3": 1, "weightKg": 1 }, "costCenter": "example", "destination": { "addressLine": "example", "city": "example", "contactName": "example", "contactPhone": "example", "countryCode": "example", "handling": "example", "locationType": "example", "postalCode": "example", "unLocode": "example", "windowFrom": "example", "windowTo": "example" }, "externalReference": "example", "incoterm": "example", "isFlexibleSchedule": true, "metadata": "example", "modePolicy": "example", "notes": "example", "origin": { "addressLine": "example", "city": "example", "contactName": "example", "contactPhone": "example", "countryCode": "example", "handling": "example", "locationType": "example", "postalCode": "example", "unLocode": "example", "windowFrom": "example", "windowTo": "example" }, "preferredDeliveryDate": "2026-04-15", "preferredDeliveryTime": "example", "preferredPickupDate": "2026-04-15", "publish": true, "purchaseOrderNumber": "example", "transportMode": "example" }'

Requires the requests:write scope and an X-Idempotency-Key header (the same key with a different body answers 422 Integration.IdempotencyKeyReused). A repeated externalReference returns 409 with the existing request’s id. With a test key (qk_test_…) the request goes to your sandbox and the answer says livemode: false.

Authorizations

IntegrationKey
IntegrationOAuth

Parameters

Header Parameters

X-Idempotency-Key

string

Request Body^required

application/json

object

cargo

required

One of:

null
object

null

costCenter

required

Optional, at most 100 characters. Kept with the request and visible only to your company.

null | string

destination

required

One of:

null
object

null

externalReference

required

Your own id for the request (for example the eBA record number). Required, at most 100 characters, unique within your company: the same reference again returns 409 with the first request’s id.

null | string

incoterm

required

An Incoterms 2020 code: EXW, FCA, FAS, FOB, CFR, CIF, CPT, CIP, DAP, DPU or DDP. Optional.

null | string

isFlexibleSchedule

required

boolean

metadata

Your own fields on the request (a cost centre, a PO number, a process number): at most 20 keys of 1 to 40 characters from A-Z, a-z, 0-9, ‘_’ and ‘-’, string values of at most 500 characters, 8 KB in all. Visible only to your company: returned in your reads and in webhooks sent to you, never to a carrier or anyone else. Empty or absent: none.

null | object

modePolicy

required

Required (default) or Open.

null | string

notes

required

null | string

origin

required

One of:

null
object

null

preferredDeliveryDate

required

null | string format: date

preferredDeliveryTime

required

null | string format: time

preferredPickupDate

required

null | string format: date

publish

required

False (default): the request is created as a Draft. True: it is also published to the open market when the acting member may publish.

boolean

purchaseOrderNumber

required

Optional, at most 100 characters. Kept with the request and visible only to your company.

null | string

transportMode

required

Road, Sea, Air, Rail, Multimodal or HandCarry. Leave empty with modePolicy Open.

null | string

Example^generated

{
  "cargo": {
    "description": "example",
    "dimensions": "example",
    "exceedsStandard": true,
    "fragile": true,
    "hazardous": true,
    "maxStackLayers": 1,
    "maxTopLoadKg": 1,
    "outOfGauge": true,
    "packageCount": 1,
    "stackable": true,
    "standardType": "example",
    "temperatureMaxC": 1,
    "temperatureMinC": 1,
    "volumeM3": 1,
    "weightKg": 1
  },
  "costCenter": "example",
  "destination": {
    "addressLine": "example",
    "city": "example",
    "contactName": "example",
    "contactPhone": "example",
    "countryCode": "example",
    "handling": "example",
    "locationType": "example",
    "postalCode": "example",
    "unLocode": "example",
    "windowFrom": "example",
    "windowTo": "example"
  },
  "externalReference": "example",
  "incoterm": "example",
  "isFlexibleSchedule": true,
  "metadata": "example",
  "modePolicy": "example",
  "notes": "example",
  "origin": {
    "addressLine": "example",
    "city": "example",
    "contactName": "example",
    "contactPhone": "example",
    "countryCode": "example",
    "handling": "example",
    "locationType": "example",
    "postalCode": "example",
    "unLocode": "example",
    "windowFrom": "example",
    "windowTo": "example"
  },
  "preferredDeliveryDate": "2026-04-15",
  "preferredDeliveryTime": "example",
  "preferredPickupDate": "2026-04-15",
  "publish": true,
  "purchaseOrderNumber": "example",
  "transportMode": "example"
}

Responses

201

Created

application/json

object

externalReference

required

string

required

string format: uuid

livemode

required

True for a live key. False for a test key (qk_test_…): the request is in the sandbox and never touches real data.

boolean

publish

required

object

published

required

The request is on the market.

boolean

refusalCode

required

Why it was not published; the request stays a Draft a person can publish in the app.

null | string

refusalDetail

required

null | string

requested

required

You sent publish: true.

boolean

requestNumber

The request’s business number (REQ-048213): the number a person reads out and your system can store. Never changes.

null | string

status

required

Draft or Published.

string

webUrl

required

Where a person opens the request in the app.

string

Example^generated

{
  "externalReference": "example",
  "id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0",
  "livemode": true,
  "publish": {
    "published": true,
    "refusalCode": "example",
    "refusalDetail": "example",
    "requested": true
  },
  "requestNumber": "example",
  "status": "example",
  "webUrl": "example"
}

400

Bad Request

application/problem+json

object

detail

null | string

instance

null | string

status

null | integer | string format: int32

/^-?(?:0|[1-9]\d*)$/

title

null | string

type

null | string

Example^generated

{
  "detail": "example",
  "instance": "example",
  "status": 1,
  "title": "example",
  "type": "example"
}

401

Unauthorized

application/problem+json

object

detail

null | string

instance

null | string

status

null | integer | string format: int32

/^-?(?:0|[1-9]\d*)$/

title

null | string

type

null | string

Example^generated

{
  "detail": "example",
  "instance": "example",
  "status": 1,
  "title": "example",
  "type": "example"
}

403

Forbidden

application/problem+json

object

detail

null | string

instance

null | string

status

null | integer | string format: int32

/^-?(?:0|[1-9]\d*)$/

title

null | string

type

null | string

Example^generated

{
  "detail": "example",
  "instance": "example",
  "status": 1,
  "title": "example",
  "type": "example"
}

409

Conflict

application/problem+json

object

detail

null | string

instance

null | string

status

null | integer | string format: int32

/^-?(?:0|[1-9]\d*)$/

title

null | string

type

null | string

Example^generated

{
  "detail": "example",
  "instance": "example",
  "status": 1,
  "title": "example",
  "type": "example"
}

422

Unprocessable Entity

application/problem+json

object

detail

null | string

errors

object

key

additional properties

Array<string>

instance

null | string

status

null | integer | string format: int32

/^-?(?:0|[1-9]\d*)$/

title

null | string

type

null | string

Example^generated

{
  "detail": "example",
  "errors": {
    "additionalProperty": [
      "example"
    ]
  },
  "instance": "example",
  "status": 1,
  "title": "example",
  "type": "example"
}

429

Too Many Requests

application/problem+json

object

detail

null | string

instance

null | string

status

null | integer | string format: int32

/^-?(?:0|[1-9]\d*)$/

title

null | string

type

null | string

Example^generated

{
  "detail": "example",
  "instance": "example",
  "status": 1,
  "title": "example",
  "type": "example"
}

Create a shipment request

Authorizations

Parameters

Header Parameters

Request Bodyrequired

Examplegenerated

Responses

201

Examplegenerated

400

Examplegenerated

401

Examplegenerated

403

Examplegenerated

409

Examplegenerated

422

Examplegenerated

429

Examplegenerated

Request Body^required

Example^generated

Example^generated

Example^generated

Example^generated

Example^generated

Example^generated

Example^generated

Example^generated