Seller API
Connect your system to Nömad Media with an API key; keep your stock, prices and bookings, upload proofs and receive webhooks, with curl examples.
Privacy and analytics
We use necessary technical cookies and, only with your consent, analytics and marketing pixels to improve the website and measure campaigns.
Connect your system to Nömad Media with an API key; keep your stock, prices and bookings, upload proofs and receive webhooks, with curl examples.
This guide is for whoever integrates a seller's system (its inventory manager, its ERP or a script) with Nömad Media. Everything you do in your portal is an API operation with the same permissions: open and close dates, change prices, handle bookings and upload proofs without opening the screen.
What you need:
curl or any HTTP client.Note
Nömad Media has no MCP for sellers: seller operations are only available through the HTTP API.
In Nömad Medios › API (app.nomad.ooo/seller/<id>/api), click Create key:
nmw_live_v1_….The key is ready to use: it only reaches Media (adspaces.read and adspaces.write), only through the API and only with what you chose. A write outside that answers 403 forbidden. If you lose it or stop using it, Revoke disables it at once. Creating or revoking asks you to confirm it's you.
export NOMAD_TOKEN="nmw_live_v1_…"
| What | Value |
|---|---|
| Base | https://app.nomad.ooo/api/v1 |
| Call an operation | POST /api/v1/<operation>, for example POST /api/v1/adspaces.seller.listings.list |
| Authentication | Authorization: Bearer nmw_live_v1_… |
| Body | JSON with the operation's input and workspace: the id (UUID) of your seller account |
| Writes | Send Idempotency-Key on every write you may retry |
| Success | { "data": … } |
| Error | application/problem+json with a stable code and, for Media refusals, the reason in detail |
Find the workspace with the credential itself:
curl https://app.nomad.ooo/api/v1/me \
-H "Authorization: Bearer $NOMAD_TOKEN"
For an API key, data.credential.workspace_id is your seller account:
export SELLER="3f6c0c1e-…"
Check that the account sells spaces and where its sign-up stands:
curl https://app.nomad.ooo/api/v1/adspaces.seller.access.get \
-H "Authorization: Bearer $NOMAD_TOKEN" \
-H "Content-Type: application/json" \
-d "{ \"workspace\": \"$SELLER\" }"
{ "data": { "enabled": true, "status": "approved" } }
Rules for every seller operation:
unitCostMinor: 45000 is €450.00. For now everything is in euros.YYYY-MM-DD.limit from 1 to 50 (20 by default); when nextCursor is not null, pass it as cursor.earnsMinor is what you earn.Request limits and maximum size are in Limits, versions and headers. The exact input and output of each operation are in the OpenAPI specification (GET /api/v1/openapi.json, with your token).
curl https://app.nomad.ooo/api/v1/adspaces.seller.listings.list \
-H "Authorization: Bearer $NOMAD_TOKEN" \
-H "Content-Type: application/json" \
-d "{ \"workspace\": \"$SELLER\", \"status\": \"published\", \"limit\": 50 }"
{
"data": {
"items": [
{
"id": "8b1e…", "propertyId": "c2a4…", "propertyName": "Example Daily", "channel": "digital",
"title": "Homepage billboard", "status": "published", "isActive": true, "hasPendingChanges": false,
"saleUnit": "period", "periodUnit": "week", "availabilityMode": "exclusive", "capacity": null,
"currency": "EUR", "unitCostMinor": 45000, "listPriceMinor": 60000, "updatedAt": "2026-11-18T09:12:00Z"
}
],
"nextCursor": null
}
}
Filter by propertyId or by status (draft, in_review, published, paused, rejected). The full space, with its version, limits and price rules, comes from adspaces.seller.listings.get with listingId.
adspaces.seller.availability.upsert creates or updates a space's calendar windows, at once and without review. Send your own id in each window's externalRef: when it already exists that window is updated instead of creating another, so repeating the sync never duplicates anything.
curl https://app.nomad.ooo/api/v1/adspaces.seller.availability.upsert \
-H "Authorization: Bearer $NOMAD_TOKEN" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: sync-8b1e-2026-11-18" \
-d "{
\"workspace\": \"$SELLER\",
\"listingId\": \"8b1e…\",
\"windows\": [
{ \"externalRef\": \"erp-closed-2026-12-24\", \"kind\": \"closed\", \"startsOn\": \"2026-12-24\", \"endsOn\": \"2026-12-26\", \"note\": \"Christmas closure\" },
{ \"externalRef\": \"erp-open-2027-02\", \"kind\": \"open\", \"startsOn\": \"2027-02-01\", \"endsOn\": \"2027-02-28\", \"capacity\": 3 }
]
}"
{
"data": {
"windows": [
{ "id": "e41f…", "kind": "closed", "startsOn": "2026-12-24", "endsOn": "2026-12-26", "capacity": null, "note": "Christmas closure", "externalRef": "erp-closed-2026-12-24" },
{ "id": "9a07…", "kind": "open", "startsOn": "2027-02-01", "endsOn": "2027-02-28", "capacity": 3, "note": null, "externalRef": "erp-open-2027-02" }
]
}
}
closed blocks dates. open opens them (needed when the space only sells opened dates, calendarMode: "listed") and may carry its own capacity; a capacity on a closed window is refused.adspaces.seller.availability.remove with listingId and ids or externalRefs. It returns removed; unknown ids are ignored.adspaces.seller.availability.list with listingId and, optionally, from and to (by default, today and the next twelve months).Removing or closing dates never touches bookings: a booking already accepted keeps its dates.
A space's base price changes with adspaces.seller.listings.save. Send expectedVersion (the version you read) so you never overwrite someone else's change: if it does not match, the answer is 409 revision_conflict.
curl https://app.nomad.ooo/api/v1/adspaces.seller.listings.save \
-H "Authorization: Bearer $NOMAD_TOKEN" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: price-8b1e-v7" \
-d "{ \"workspace\": \"$SELLER\", \"listingId\": \"8b1e…\", \"expectedVersion\": 7, \"unitCostMinor\": 48000 }"
Only the fields you send change. Price, capacity, quantities and deadlines apply at once; the editorial fields (title, copy, specs, templates, images) of a published space wait for Nömad's review and come back under pending.
Price rules are replaced in one go with adspaces.seller.rates.set. The list you send replaces the previous one; an empty list clears them all.
curl https://app.nomad.ooo/api/v1/adspaces.seller.rates.set \
-H "Authorization: Bearer $NOMAD_TOKEN" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: rates-8b1e-2026-11-18" \
-d "{
\"workspace\": \"$SELLER\",
\"listingId\": \"8b1e…\",
\"rules\": [
{ \"label\": \"Christmas\", \"startsOn\": \"2026-12-01\", \"endsOn\": \"2027-01-06\", \"unitCostMinor\": 60000 },
{ \"label\": \"Weekend\", \"weekdays\": [6, 7], \"unitCostMinor\": 52000 },
{ \"label\": \"Four weeks or more\", \"minQuantity\": 4, \"unitCostMinor\": 40000 }
]
}"
weekdays are ISO weekdays of the day the booking starts (1 = Monday). Every rule needs at least one condition. When several match the most specific wins; with no rules the space's unitCostMinor applies. Up to 50 rules. A booking already requested keeps its price.
curl https://app.nomad.ooo/api/v1/adspaces.seller.bookings.list \
-H "Authorization: Bearer $NOMAD_TOKEN" \
-H "Content-Type: application/json" \
-d "{ \"workspace\": \"$SELLER\", \"state\": \"to_answer\" }"
{
"data": {
"items": [
{
"id": "5d2c…", "number": "…", "status": "pending_publisher", "materialStatus": "pending",
"listingId": "8b1e…", "startsOn": "2027-02-01", "endsOn": "2027-02-14", "quantity": 2,
"currency": "EUR", "materialDueOn": "2027-01-25", "createdAt": "2026-11-18T10:03:00Z",
"brandName": "Example Brand", "earnsMinor": 96000, "payoutId": null,
"snapshot": { "listingTitle": "Homepage billboard", "saleUnit": "period", "periodUnit": "week", "propertyName": "Example Daily", "channel": "digital", "…": "…" }
}
],
"nextCursor": null
}
}
state is to_answer (waiting for you to accept or decline), open (in progress) or closed. You can filter by listingId. A booking only appears once Nömad has passed it to your account (pending_publisher). snapshot keeps what was booked as it was when requested.
adspaces.seller.bookings.get with bookingId returns the full booking: the brief (brief), the delivered material (materials), the proofs (proofs), the history (events) and can, what you may do now (decide, reviewMaterial, deliver).
curl https://app.nomad.ooo/api/v1/adspaces.seller.bookings.decide \
-H "Authorization: Bearer $NOMAD_TOKEN" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: decide-5d2c" \
-d "{ \"workspace\": \"$SELLER\", \"bookingId\": \"5d2c…\", \"decision\": \"accept\" }"
{ "data": { "id": "5d2c…", "status": "accepted" } }
accept holds the dates while the brand pays; if it does not pay in time, the booking expires.decline needs a note, which the brand reads.409 conflict with detail: "dates_unavailable".When the brand delivers its material, materialStatus becomes submitted. Download each file with adspaces.seller.bookings.file_open (bookingId and fileId = materials[].id; the address expires in minutes) and answer with adspaces.seller.bookings.material_review: decision: "approve", or "changes" with a note saying what to change.
Files are uploaded in two steps: you ask for an upload address and send the bytes; then you pass the path to the operation that uses them.
Step 1. Ask for the address with adspaces.seller.uploads.prepare:
curl https://app.nomad.ooo/api/v1/adspaces.seller.uploads.prepare \
-H "Authorization: Bearer $NOMAD_TOKEN" \
-H "Content-Type: application/json" \
-d "{ \"workspace\": \"$SELLER\", \"purpose\": \"proof\", \"fileName\": \"homepage-screenshot.png\", \"mimeType\": \"image/png\", \"sizeBytes\": 482113 }"
{ "data": { "path": "…", "uploadUrl": "https://…", "token": "…", "bucket": "adspace-files", "publicUrl": null } }
Do not send Idempotency-Key here: the address is a secret given only once, and repeating the call with the same key answers 409 secret_already_issued. If it fails, ask for another one.
Step 2. Send the bytes with PUT to uploadUrl. The address is single-use:
curl -X PUT "$UPLOAD_URL" \
-H "Content-Type: image/png" \
--data-binary @homepage-screenshot.png
Step 3. Deliver the proof with adspaces.seller.bookings.deliver, with the files, the figures and a note:
curl https://app.nomad.ooo/api/v1/adspaces.seller.bookings.deliver \
-H "Authorization: Bearer $NOMAD_TOKEN" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: deliver-5d2c" \
-d "{
\"workspace\": \"$SELLER\",
\"bookingId\": \"5d2c…\",
\"files\": [ { \"path\": \"…\", \"name\": \"homepage-screenshot.png\", \"mimeType\": \"image/png\", \"sizeBytes\": 482113 } ],
\"metrics\": [ { \"label\": \"Impressions\", \"value\": \"184,300\" } ],
\"note\": \"Ran on the homepage from 1 to 14 February.\"
}"
It only works on a paid booking that has started (otherwise 409 conflict with detail: "not_started" or "wrong_status"). Up to 12 files and 12 figures.
purpose |
For | Types and size | Function it needs |
|---|---|---|---|
logo, cover, gallery |
Images of the profile, property or space | JPEG, PNG, WebP or AVIF, up to 10 MB | Editor |
template |
A space's templates | Any type, up to 50 MB | Editor |
proof |
Proofs | Any type, up to 50 MB | Sales |
invoice |
A payout's invoice | Any type, up to 50 MB | Payouts |
A webhook sends your system a signed POST each time something you can read changes. Create it in Nömad Medios › API with a public HTTPS address and the event types you want.
adspaces.seller.booking.updated: every step of a booking that is yours. It arrives when Nömad passes you a new request, when the brand pays or sends its material, when Nömad cancels it and when you handle it. It carries the booking id in data.object_ids; ask for its state with adspaces.seller.bookings.get. It never says who on the brand's or Nömad's side made the change.adspaces.seller.availability.upsert, adspaces.seller.rates.set…).With adspaces.* you receive them all. The signature (Nomad-Signature), retries, how to avoid processing the same event twice and the code to check the signature are in Events and webhooks.
| Operation | Why |
|---|---|
Signing up (adspaces.seller.signup) |
A person does it with their own account, never a token. |
Changing the bank account (adspaces.seller.payout_account.set) |
It needs a person's recent sign-in. |
Giving the team functions (adspaces.seller.team.duties_set) |
A person who manages the team decides it. |
Everything else (profile, social accounts, properties, spaces, calendar, rates, bookings, material, proofs, payouts and invoices) has its adspaces.seller.* operation. The full list is in the Media reference.
| Answer | What happened | What to do |
|---|---|---|
403 insufficient_scope |
The token lacks adspaces.read or adspaces.write. |
Issue another token with those permissions. |
403 token_brand_restricted |
The token is limited to brands. | Issue one with no brand limit. |
403 forbidden |
The key has no permission for that part. | Create a key with Inventory, Bookings or Payouts, as you need. |
404 workspace_not_found |
The workspace is not yours or does not exist. |
Use credential.workspace_id from GET /api/v1/me. |
404 not_found |
That account does not sell spaces, or the record does not exist. | Check with adspaces.seller.access.get. |
409 conflict |
The current state does not allow it; the reason is in detail (dates_unavailable, wrong_status, not_ready, publisher_not_approved…). |
Read the state with the get operation and decide again. |
409 revision_conflict |
Someone changed the space first. | Read it again and resend with its version. |
422 invalid_input |
A field is not valid; issues says which. |
Fix the field. |
Every code is in Errors.
Updated on November 18, 2026