The Publisher API lets your own system work on Medialister orders without the dashboard. Medialister tells your server when an order needs your action, and your system reads the order and answers through the API.
This article tells you how to get access and where the reference is. The requests and responses are in the Publisher API reference.
How it works at a glance:
A client does something that needs your action, for example sends a new order to review.
Medialister sends a signed event to your webhook URL.
Your system reads the order through the API: status, content and images.
Your system answers through the API: it reports the placement link, asks for changes, or decides on a cancellation request.
Medialister sends the client the usual notification, the same as after an action in the dashboard.
What Can You Do Through the API
Task | In the dashboard this is |
|---|---|
Read an order with its content and images | Open the order |
Mark the content as taken into work | Download the content |
Ask the client to change the content | Request changes |
Report the link of the published article | Add the placement link |
Accept a cancellation request (cancel the order) | Cancel the order |
Decline a cancellation request (keep the order) | Keep the order |
Read your balance | Balance |
Connect, test and pause your webhook URL |
|
The order rules are the same as in the dashboard. See Orders Processing.
How to Get an API Key
API access is given on request. Write to [email protected] or to your Medialister manager. Tell us which publisher organization will use the API. We issue an API key for a user of that organization.
The key acts as the user who owns it. It can do with orders only what this user can do in the publisher dashboard.
Use a separate user for the integration. The key works in the organization and on the side (publisher or client) that its user has open. If this user changes to a different organization or to the client side in the dashboard, the API calls of your integration can start to answer
403.
Keep the key on your server. Do not put it in a browser, in a mobile app or in a message to support. 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 |
|---|---|
Publisher API reference: all routes, fields and webhook events | |
Base URL for all requests |
|
Send the key in the apikey header of each request. The API speaks JSON-LD (application/ld+json).
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 |
|---|---|---|
All publisher routes | 3,000 requests | 100,000 requests |
When you go above a limit, the API answers 429. Wait, then send the request again. Do not retry in a tight loop.
With webhooks you do not have to poll your orders, so a normal integration stays far below these limits.
How to Get Order Updates with Webhooks
Webhooks are the other half of the integration: they tell your system when to call the API. Medialister switches them on for each organization. Ask your manager or support.
The setup is in the Webhooks article.
How Do Payouts Work with the API
The API does not change how you are paid. Your earnings and payouts work the same as for orders that you handle in the dashboard. See Payouts.
Need Help?
Write to [email protected]. Give the public ID of the order and the time of the request. Do not put your API key in the message.