Skip to content

Privacy and analytics

We use necessary technical cookies and, only with your consent, analytics and marketing pixels to improve the website and measure campaigns.

Privacy policyCookie policy
Docs
GuidesDevelopers
English
EspañolEnglishFrançaisDeutschItalianoPortuguês

Start building

  • Your first API call
  • Limits, versions and headers
  • Seller API

API

  • Brand API

MCP

  • MCP server

Connectors

  • Brand connectors
Start building
Guide10 min read

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.

Русский
한국어
日本語
中文
हिन्दी
Open the app
Where
Nömad Medios › API
Who can
OwnerAdmin
On this page
  • 1. Create a service account
  • 2. Calling the API
  • 3. List your spaces
  • 4. Open and close dates
  • 5. Change your prices
  • 6. List the bookings to answer
  • 7. Accept or decline a booking
  • 8. Upload the proof
  • 9. Receive webhooks
  • Only in the portal
  • Common errors

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:

  • A seller account on Nömad Media. Before Nömad approves your sign-up you can already prepare properties, spaces and calendar, but not publish.
  • To be the owner or an admin of that account, to create the service account.
  • curl or any HTTP client.

Note

Nömad Media has no MCP for sellers: seller operations are only available through the HTTP API.

1. Create a service account

A service account is an identity of your organisation, not of a person: it keeps working when whoever created it leaves.

  1. In 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".
  2. Issue it a token. In its permissions, give it read (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).
  3. Copy the token: it is shown only once. It looks like nmw_live_v1_….
  4. In 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_…"

2. Calling the API

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:

  • Amounts in cents, excluding VAT. unitCostMinor: 45000 is €450.00. For now everything is in euros.
  • Dates as YYYY-MM-DD.
  • Lists are paginated: limit from 1 to 50 (20 by default); when nextCursor is not null, pass it as cursor.
  • What you never get: no answer carries what the brand pays or Nömad's margin. 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).

3. List your spaces

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.

4. Open and close dates

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.
  • 1 to 200 windows per call.
  • To remove them: adspaces.seller.availability.remove with listingId and ids or externalRefs. It returns removed; unknown ids are ignored.
  • To read the calendar and the days bookings take: 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.

5. Change your prices

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.

6. List the bookings to answer

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).

7. Accept or decline a booking

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.
  • If the dates were taken meanwhile: 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.

8. Upload the proof

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

9. Receive webhooks

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.

Only in the portal

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.

Common errors

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.

Keep reading

  • Your first API callCreate a personal token, check who you are with GET /api/v1/me, list your brands and read their works; then connect an agent over MCP.
  • Limits, versions and headersThe exact numbers of the Nömad API and MCP (requests per minute, body size, pagination, token lifetime and count) plus the headers, the version and the machine-readable documents.
  • MediaAdvertising spaces of approved media owners: search and book them and, for a media owner, sell them and keep their stock.
  • Events and webhooksWhat changes, in order, and signed notices to your systems.
  • Tokens and service accountsCreate, limit, rotate and revoke personal and organisation tokens.
  • Selling on NömadWhat Nömad Media is for whoever sells advertising spaces, who it is for, how a booking goes from start to finish and what Nömad does in the middle.

Updated on November 18, 2026

PreviousLimits, versions and headersNextBrand API
Can't find what you need? Write to usWrite to usGo to the app
© 2026 Nömad · Nömad documentationLinkedInInstagramThreadsFacebookTikTokYouTubeX
Go to nomad.oooBack to top

On this page

  • 1. Create a service account
  • 2. Calling the API
  • 3. List your spaces
  • 4. Open and close dates
  • 5. Change your prices
  • 6. List the bookings to answer
  • 7. Accept or decline a booking
  • 8. Upload the proof
  • 9. Receive webhooks
  • Only in the portal
  • Common errors