GETTING STARTED

Send your first booking

Normalize a carrier-confirmed booking and submit it to your configured Foryn Ocean API host. All example data is fictional.

Before you begin

Arrange access with Foryn. Production credentials and API hostnames are not self-service.
Use an integration credential with intake permission. Store it in a secret manager and pass it as an environment variable.
Verify that the booking is carrier-confirmed and the source supplies a stable booking ID, monotonic revision and confirmation timestamp.
Commercial reference data and purchased lane coverage must already be configured by Foryn for a full assessment.

1. Inspect the contract

Download OpenAPI 3.1 from /developers/v1/openapi.json. Booking event properties, required fields, enums and constraints are generated from the same Zod schemas used by the API.

The sample booking is for a fictional carrier and agreement, with CNSHG to USLAX, quantity 2, equipment 40HC. Do not send this sample to a live customer tenant.

CODE / EXAMPLE

GET /developers/v1/openapi.json
GET /developers/v1/examples/booking-confirmed.json

2. Submit the request

CODE / EXAMPLE

export FORYN_OCEAN_API_BASE_URL='https://<onboarded-api-host>'
export FORYN_OCEAN_TOKEN='<securely-provisioned-token>'
curl --fail-with-body -sS -X POST "$FORYN_OCEAN_API_BASE_URL/api/ocean/v1/bookings" \
  -H "Authorization: Bearer $FORYN_OCEAN_TOKEN" \
  -H 'Content-Type: application/json' \
  --data-binary @booking-confirmed.json

The host is a placeholder. No production API URL, credential, or public sandbox is issued by this documentation.

3. Inspect the response

HTTP 200 means processing returned a result, not that the booking was accepted commercially. Inspect data.status and data.assessment.

The synthetic fixture used in CI returns ACCEPTED when a matching agreement and subscribed lane are present. Actual result depends on each customer's configured commercial context.

Keep the response x-request-id header for troubleshooting. Do not assume a monetary exposure from financialExposureMinor: null.

CODE / EXAMPLE

"ok": true
"data": {
  "accepted": true,
  "status": "ACCEPTED",
  "bookingReference": "synthetic-source-booking-001",
  "sourceRevision": 1,
  "assessment": { "status": "ASSESSED" },
  "exceptions": []
}

4. Add lifecycle handling

Retry the exact eventId and payload after uncertain network failures.
Send a higher revision for a meaningful accepted booking amendment. Never invent a revision from an interchange number.
Cancel only a previously qualified booking using a higher revision and a CANCELLED event without booking facts.
Treat OUT_OF_COVERAGE, NOT_QUALIFIED and INSUFFICIENT_EVIDENCE as distinct from commercial exceptions.

API v1 · Fictional examples · Production access requires coordinated onboarding · OpenAPI contract ↗