Seller API
Connect your system to Nömad Media with a service account; 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 a service account; 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.
A service account is an identity of your organisation, not of a person: it keeps working when whoever created it leaves.
Nömad Medios › API (app.nomad.ooo/seller/<id>/api), create a service account with a name that says which system uses it, for example "Inventory".adspaces.read) and change (adspaces.write) in the Media area. Do not limit it to brands: a token limited to brands cannot call operations of your seller account (403 token_brand_restricted).nmw_live_v1_….Nömad Medios › Team, the service account appears as a Member. Give it the functions it needs: Spaces editor for stock, prices and spaces, and Spaces sales for bookings, material and proofs.Without functions the service account can only read and writes answer 403 forbidden. Creating, rotating and revoking tokens is in Tokens and service accounts.
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 a service account, 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. For seller operations, the type is the id of the operation that made the change (adspaces.seller.bookings.decide, adspaces.seller.availability.upsert…), so adspaces.seller.* catches them all.
Today those events report changes made in your seller account, by your team, through the portal or by your integration. To learn about new bookings, call adspaces.seller.bookings.list with state: "to_answer" from time to time.
The signature (Nomad-Signature), retries, how to avoid processing the same event twice and the code to verify 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 service account lacks the function for that part. | Give it Editor, Sales or Payouts in Team. |
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