The Medialister API lets your own system search the media catalog, buy placements and follow each order to publication. You can also order for your own customers: they do not need a Medialister account.
This article tells you how to get access and what to prepare before your first order. The requests and responses are in the API reference.
The path at a glance:
Get an API key from Medialister support.
Read the API reference in the
API referencetab of the help center.Save a card and your billing details in the dashboard:
Settings, thenBilling.Get test credits from support and place a test order through the API.
Connect webhooks on the
Integrationspage of the dashboard. This step is optional.
How to Get an API Key
API access is given on request. Write to [email protected] and tell us two things: which organization will use the API, and what you plan to build. We reply with the terms and pricing. When access is agreed, we issue an API key for your organization.
The key acts for one organization. The balance and the card of that organization pay for the orders, and each cart and order that the key creates belongs to it.
Keep the key on your server. The key can spend the money of your organization. Call the API from your backend, never from a browser or a mobile app. If you think that a key has leaked, write to support at once.
Where to Find the API Reference
| What you need | Where it is |
|---|---|
| Client API reference: all routes, fields, statuses and webhook events | roadmap.medialister.com/docs/api-reference |
| Guide "Saving a payment card" | api.medialister.com/api/docs/client/payment-card |
| Base URL for all requests | https://api.medialister.com |
Send the key in the apikey header of each request. A request without a valid key gets the answer 401. The API speaks JSON-LD (application/ld+json).
curl 'https://api.medialister.com/api/offers?q=fintech' \
-H 'apikey: <your-api-key />'The reference is the one source for routes and fields. It is built from the code, so it changes together with the API. This article does not repeat it.
What Are the Rate Limits
The limits are counted for each API key.
| Route | In one minute | In one hour |
|---|---|---|
Catalog search, GET /api/offers |
20 requests | 600 requests |
| All other routes | 3,000 requests | 100,000 requests |
When you go above a limit, the API answers 429. Read the Retry-After header, wait, then send the request again. Do not retry in a tight loop.
The catalog search has the tightest limit, so two habits help. Keep search results in a cache on your side. Use webhooks to hear about order changes, and do not poll each order.
How to Add a Payment Method for API Using
A checkout through the API charges the card of your organization with nobody present. The API never takes card details. You save the card one time in the billing settings of the dashboard, and each API checkout after that uses it.
Sign in to the Medialister dashboard as an admin of the organization that your API key belongs to.
Open the account menu and choose `Settings`. In the sidebar, under Organization Settings, choose `Billing`.
In Billing Profile, enter your billing details (name, company name and address), then click `Save`. Invoices are issued to these billing details.
In Payment Details, click `New Payment Method`. The Add New Payment Method form opens. It is the same form as at the checkout.
Choose `Card`, enter the card details, then click `Save Payment Method`.
The form closes and the card shows in the list of saved payment methods. Your card is now saved for API payments. Nothing is bought and nothing is charged.
To add a different card, click New Payment Method again. If the organization has more than one card, the default card is charged. A card that you save when you pay for a cart in the dashboard is used for API payments too.
How an API Checkout Pays
The checkout uses the balance of your organization first. The card pays only the part that the balance does not cover.
| Your balance | What the checkout does |
|---|---|
| Covers the full cart total | The balance pays. The card is not charged. |
| Covers a part of the total | The balance pays its part. The card pays the remainder. |
| Is empty | The card pays the full total. |
The card charge is rounded up to whole cents, and it cannot be less than 0.50 USD. Money that stays after such a minimum charge remains on your balance for the next checkout.
The cart shows the placement prices, the Medialister service fees and the total before you pay. For the fees, see Client and Top-Up Service Fees.
A cart is paid one time only. If a checkout request times out, send the same request again: a paid cart answers with its orders and makes no new charge.
| Answer | What it means | What to do |
|---|---|---|
402 |
The card was declined, has not enough money, or needs authentication. Nothing was charged. | Save the card again in the billing settings, or use a different card. |
409 |
The payment is still in process. No order is booked yet. | Do not pay again. Send the same checkout later. |
422 |
No card or no billing details are saved, or the cart cannot be checked out. | Read detail in the answer. Do the steps in "How to Add a Payment Method for API Using". |
How to Test Without a Sandbox
The client API has no sandbox and no test mode. Each checkout makes a real order, and a real publisher receives it.
To test your integration safely, ask us for test credits.
Write to [email protected] or to your Medialister manager. Say that you want to test the API.
We add free credits to the balance of your organization. We also tell you which media to use for the test, for example
startupmafia.eu.Find the test media in the catalog:
GET /api/offers?q=startupmafia.eu.Add its offer to a cart and check out. The checkout uses the balance first. Thus the credits pay for the test order, and the card is not charged while the credits cover the cart total.
Follow the order through its statuses, as your integration will do in production.
Use the credits only on the media that we name. An order on a different media will be cancelled.
Save your card and your billing details before the test. A checkout can refuse a cart when they are missing. To see how many credits remain, read your balance: the route is in the API reference.
How to Get Order Updates with Webhooks
Medialister can call a URL on your server when one of your orders needs you. Then you do not have to poll. Webhooks are switched on for each organization by Medialister: ask your manager or support.
The setup is in the Webhooks article.
Need Help?
Write to [email protected]. Give the public ID of the order or the ID of the cart, and the time of the request. Do not put your API key in the message.