MediaOS – API Documentation

Introduction

The MediaOS API is a REST API that returns JSON. It provides access to your account's CRM data, inventory, orders, and billing records.

Base URL

https://app.mediaos.com/API/

💡

All requests must use HTTPS. All responses are returned as JSON. For developer support, contact your account manager or email support@mediaos.com.

All API responses are UTF-8 encoded JSON.
Dates use the format YYYY-MM-DD HH:MM:SS.
Boolean fields accept true / false or 1 / 0.
Endpoints that list resources support pagination via per_page and page parameters.

Authentication

The API uses HTTP Basic Authentication. Your API key acts as the username and your API password as the password.

⚠️

HTTPS Required. All API requests must be made over HTTPS. Requests made over plain HTTP will be rejected.

🔒

Administrator Access Required. API credentials can only be generated by an administrator of your MediaOS account.

HTTP Basic Auth

Pass your API key as the username and your API password as the password in the Authorization header.

cURL
# Replace API_KEY and API_PASSWORD with your credentials
curl -u API_KEY:API_PASSWORD \
  https://yourdomain.mediaos.com/API/advertisers/

Query Parameter (Alternative)

You may alternatively pass your API key as a query string parameter named apiKey.

cURL
curl "https://yourdomain.mediaos.com/API/advertisers/?apiKey=YOUR_API_KEY"

Rate Limits

API usage is limited per account to prevent abuse and ensure service quality for all users.

Scope	Limit	Window
Per Account	5,000 requests	Rolling 24-hour window

⚠️

Exceeding the limit will result in a 429 Too Many Requests response. Implement exponential backoff in your integration to handle this gracefully. Rate limit counters reset at the start of each 24-hour window.

Pagination & Sorting

List endpoints support server-side pagination and sorting via query parameters.

Parameter	Type	Default	Description
`per_page`	integer	`25`	Number of records to return per page. Maximum value is 100.
`page`	integer	`1`	Page number to return. Starts at 1.
`sort_by`	string	Varies	Field to sort results by. Accepted values vary per endpoint.
`sort_order`	string	`asc`	Sort direction. Accepted values: `asc` or `desc`.

All paginated responses include a top-level count field with the total number of matching records:

JSON Response
{
  "count": 142,
  "data": [
    { "id": 1, "name": "Acme Corp", ... },
    { "id": 2, "name": "Beta LLC", ...  }
  ]
}

Error Codes

The API uses standard HTTP status codes to indicate success or failure.

200OK – Request succeeded. Body contains the response data.

204No Content – Request succeeded, no body returned (e.g., DELETE).

403Forbidden – Authentication failed or insufficient permissions.

404Not Found – The requested resource does not exist.

405Method Not Allowed – The HTTP method is not supported for this endpoint.

500Server Error – An unexpected server error occurred.

Error responses include a JSON body with a human-readable message:

JSON Error Response
{
  "error": "Advertiser not found."
}

Account

Retrieve top-level details about your MediaOS account.

GET /account/ Get account details ▼

Returns details for the authenticated account, including name, plan, and configuration settings.

Parameters

None.

Example Response

JSON
{
  "id": 1,
  "name": "Your Publication",
  "domain": "yourdomain.mediaos.com",
  "plan": "pro",
  "timezone": "America/New_York"
}

Advertisers

Advertisers are the companies or individuals that purchase advertising. Full CRUD operations are supported.

GET /advertisers/{id} Get a single advertiser ▼

Returns a single advertiser record by its numeric ID.

Path Parameters

Parameter	Type	Required	Description
`id`	integer	Required	Advertiser ID

Example Response

JSON
{
  "id": 42,
  "name": "Acme Corp",
  "is_lead": false,
  "active": true,
  "owned_by_user_id": 5,
  "date_created": "2024-01-15 09:30:00"
}

GET /advertisers/ List / search advertisers ▼

Returns a paginated list of advertisers. All parameters are optional and can be combined for filtering.

Query Parameters

Parameter	Type	Description
`id`	integer	Filter by exact advertiser ID
`name`	string	Filter by name (partial match)
`is_lead`	boolean	Filter by lead status
`active`	boolean	Filter by active status
`owned_by_user_id`	integer	Filter by owning sales rep
`created_by_user_id`	integer	Filter by creating user
`date_created_before`	datetime	Filter: created before this date (`YYYY-MM-DD HH:MM:SS`)
`date_created_after`	datetime	Filter: created after this date
`sort_by`	string	Sort field
`sort_order`	string	`asc` or `desc`
`per_page`	integer	Results per page (default 25, max 100)
`page`	integer	Page number (default 1)

PUT /advertisers/ Create an advertiser ▼

Creates a new advertiser record. Send parameters as JSON in the request body or as form fields.

Body Parameters

Parameter	Type	Required	Description
`name`	string	Required	Advertiser display name
`created_by_user_id`	integer	Optional	User who created the record
`owned_by_user_id`	integer	Optional	Sales rep / owner
`is_lead`	boolean	Optional	Mark as a lead (not yet a customer)
`sales_lock`	boolean	Optional	Lock record from other sales reps
`description`	string	Optional	Free-text description / notes
`general_ledger_account_code`	string	Optional	GL account code for accounting integrations

Example Request

cURL
curl -u API_KEY:API_PASSWORD -X PUT \
  -H "Content-Type: application/json" \
  -d '{"name":"Acme Corp","owned_by_user_id":5}' \
  https://yourdomain.mediaos.com/API/advertisers/

POST /advertisers/{id} Update an advertiser ▼

Updates an existing advertiser. Only the fields provided will be updated (partial update).

Path Parameters

Parameter	Type	Required	Description
`id`	integer	Required	Advertiser ID to update

Body Parameters

Same fields as Create — all optional. Only supplied fields are updated.

Agencies

Agencies represent advertising agencies that act on behalf of advertisers. Full CRUD is supported.

GET /agencies/{id} Get a single agency ▼

Returns a single agency record by its numeric ID.

Path Parameters

Parameter	Type	Required	Description
`id`	integer	Required	Agency ID

GET /agencies/ List / search agencies ▼

Returns a paginated list of agencies.

Query Parameters

Parameter	Type	Description
`id`	integer	Filter by agency ID
`name`	string	Filter by name (partial match)
`sort_by`	string	Sort field
`sort_order`	string	`asc` or `desc`
`per_page`	integer	Default 25, max 100
`page`	integer	Default 1

PUT /agencies/ Create an agency ▼

Creates a new agency record.

Body Parameters

Parameter	Type	Required	Description
`name`	string	Required	Agency name
`created_by_user_id`	integer	Optional	Creating user ID
`owned_by_user_id`	integer	Optional	Owning sales rep ID
`discount_percent`	decimal	Optional	Default agency discount (e.g. `15.00` for 15%)

POST /agencies/{id} Update an agency ▼

Updates an existing agency. All body fields are optional; only provided fields are changed.

Path Parameters

Parameter	Type	Required	Description
`id`	integer	Required	Agency ID to update

Contacts

Contacts are individual people associated with an advertiser or agency. Full CRUD is supported.

ℹ️

A contact can be assigned to either an advertiser or an agency — not both. Supplying both advertiser_id and agency_id will result in an error.

GET /contacts/{id} Get a single contact ▼

Returns a single contact by ID.

Path Parameters

Parameter	Type	Required	Description
`id`	integer	Required	Contact ID

GET /contacts/ Search contacts ▼

Returns a paginated list of contacts matching the given filters.

Query Parameters

Parameter	Type	Description
`id`	integer	Filter by contact ID
`name`	string	Filter by full name (partial match)
`advertiser_id`	integer	Filter by linked advertiser
`agency_id`	integer	Filter by linked agency
`owned_by_user_id`	integer	Filter by owning sales rep
`created_by_user_id`	integer	Filter by creating user
`is_lead`	boolean	Filter by lead status
`active`	boolean	Filter by active status
`date_created_before`	datetime	Created before date
`date_created_after`	datetime	Created after date
`sort_by`	string	`id`, `first_name`, `last_name`, `title`
`sort_order`	string	`asc` or `desc`
`per_page`	integer	Default 25, max 100
`page`	integer	Default 1

PUT /contacts/ Create a contact ▼

Creates a new contact. The contact must be linked to either an advertiser or an agency (not both).

Body Parameters

Parameter	Type	Required	Description
`advertiser_id`	integer	Optional*	Link to an advertiser
`agency_id`	integer	Optional*	Link to an agency (use one or the other)
`title`	string	Optional	Job title
`first_name`	string	Optional	First name
`last_name`	string	Optional	Last name
`owned_by_user_id`	integer	Optional	Owning sales rep

POST /contacts/{id} Update a contact ▼

Updates an existing contact. All body fields are optional.

Path Parameters

Parameter	Type	Required	Description
`id`	integer	Required	Contact ID

Contact Data

Contact data stores typed attributes for contacts, advertisers, or agencies — such as phone numbers, email addresses, and websites.

GET /contactDataTypes/ List all contact data types ▼

Returns the full list of available contact data types (e.g., Phone, Email, Website).

GET /contactData/{id} Get a single contact data item ▼

Returns a single contact data record by ID.

GET /contactData/ Search contact data ▼

Returns contact data records. If no filters are supplied, the most recent 100 records are returned.

Query Parameters

Parameter	Type	Description
`advertiser_id`	integer	Filter by advertiser
`contact_id`	integer	Filter by contact
`agency_id`	integer	Filter by agency

PUT /contactData/ Create a contact data item ▼

Creates a new contact data record. The record must be linked to exactly one of: advertiser_id, agency_id, or contact_id.

Body Parameters

Parameter	Type	Required	Description
`contact_data_type_id`	integer	Required	The type of data (from `/contactDataTypes/`)
`value`	string	Required	The data value (e.g., phone number)
`advertiser_id`	integer	Required*	Link to an advertiser
`agency_id`	integer	Required*	Link to an agency
`contact_id`	integer	Required*	Link to a contact (one of the three is required)

POST /contactData/{id} Update a contact data item ▼

Updates the value of an existing contact data record.

Body Parameters

Parameter	Type	Required	Description
`value`	string	Required	Updated value

Addresses

Postal addresses for advertisers, agencies, or contacts. Full CRUD is supported.

GET /addresses/{id} Get a single address ▼

Returns a single address by ID.

GET /addresses/ Search addresses ▼

Query Parameters

Parameter	Type	Description
`id`	integer	Filter by address ID
`advertiser_id`	integer	Filter by advertiser
`agency_id`	integer	Filter by agency
`contact_id`	integer	Filter by contact

PUT /addresses/ Create an address ▼

Creates a new address. Must be assigned to one of: advertiser, agency, or contact.

Body Parameters

Parameter	Type	Required	Description
`country_code`	string	Required	ISO country code (e.g. `US`)
`advertiser_id`	integer	Optional*	Link to advertiser
`agency_id`	integer	Optional*	Link to agency
`contact_id`	integer	Optional*	Link to contact (one of three required)
`line1`	string	Optional	Address line 1
`line2`	string	Optional	Address line 2
`line3`	string	Optional	Address line 3
`line4`	string	Optional	Address line 4
`city`	string	Optional	City
`state`	string	Optional	State / Province
`postal_code`	string	Optional	ZIP / Postal code

POST /addresses/{id} Update an address ▼

Updates an existing address. All fields are optional.

Users

Retrieve user records for members of your MediaOS account. Users are read-only via the API.

GET /users/{id} Get a single user ▼

Returns a single user record by ID.

GET /users/ Search users ▼

Query Parameters

Parameter	Type	Description
`id`	integer	Filter by user ID
`first_name`	string	Filter by first name
`last_name`	string	Filter by last name
`email`	string	Filter by email address
`active`	boolean	Filter by active status
`is_administrator`	boolean	Filter by admin role
`is_sales`	boolean	Filter by sales role
`is_production`	boolean	Filter by production role
`is_accounting`	boolean	Filter by accounting role
`sort_by`	string	`id`, `firstName`, `lastName`, `email`
`sort_order`	string	`asc` or `desc`
`per_page`	integer	Default 25, max 100
`page`	integer	Default 1

Products

Products represent the publications, websites, or media channels in your account. Read-only.

GET /products/{id} Get a single product ▼

Returns a single product by ID.

GET /products/ List all products ▼

Returns all products in the account. No filters required.

Ad Sizes

Ad sizes define the available creative dimensions for a product. Read-only.

GET /adSizes/{id} Get a single ad size ▼

Returns a single ad size record by ID.

GET /adSizes/ Search ad sizes ▼

Query Parameters

Parameter	Type	Required	Description
`product_id`	integer	Required	Filter by product
`active`	boolean	Optional	Filter by active status

Ad Rates

Ad rates define the pricing for ad sizes within a product. Read-only.

GET /adRates/{id} Get a single ad rate ▼

Returns a single ad rate record by ID.

GET /adRates/ Search ad rates ▼

Query Parameters

Parameter	Type	Required	Description
`product_id`	integer	Required	Filter by product
`ad_size_id`	integer	Optional	Filter by ad size
`active`	boolean	Optional	Filter by active status

Issues

Issues are publication dates / editions for a product (e.g., January 2025 magazine issue). Read-only.

GET /issues/{id} Get a single issue ▼

Returns a single issue by ID.

GET /issues/ List issues for a product ▼

Query Parameters

Parameter	Type	Required	Description
`product_id`	integer	Required	Product to list issues for

Locations

Locations are geographic zones used for targeting ad insertions. Read-only.

GET /locations/{id} Get a single location ▼

Returns a single location record by ID.

GET /locations/ List locations for a product ▼

Query Parameters

Parameter	Type	Required	Description
`product_id`	integer	Required	Product to list locations for

Sections

Sections are content areas within a product (e.g., "Back Cover", "Page 4"). Read-only.

GET /sections/{id} Get a single section ▼

Returns a single section record by ID.

GET /sections/ List sections for a product ▼

Query Parameters

Parameter	Type	Required	Description
`product_id`	integer	Required	Product to list sections for

Contracts

Contracts represent advertising orders / sales agreements. Read-only.

GET /contracts/{id} Get a single contract ▼

Returns a single contract record by ID.

GET /contracts/ Search contracts ▼

Query Parameters

Parameter	Type	Description
`id`	integer	Filter by contract ID
`advertiser_id`	integer	Filter by advertiser
`date_created_before`	datetime	Created before date
`date_created_after`	datetime	Created after date
`date_sold_before`	datetime	Sold before date
`date_sold_after`	datetime	Sold after date
`amount_from`	decimal	Minimum contract total
`amount_to`	decimal	Maximum contract total
`status`	string	Filter by contract status
`is_proposal`	boolean	Filter proposals vs. signed contracts
`sort_by`	string	`id`, `date_created`, `date_sold`, `total`, `status`
`sort_order`	string	`asc` or `desc`
`per_page`	integer	Default 25, max 100
`page`	integer	Default 1

Contract Line Items

Individual line items within a contract, describing what was sold. Read-only.

GET /contractLineItems/{id} Get a single line item ▼

Returns a single contract line item by ID.

GET /contractLineItems/ Get line items for a contract ▼

Query Parameters

Parameter	Type	Required	Description
`contract_id`	integer	Required	Contract to retrieve line items for

GET /contractLineItemTypes/{id} Get a single line item type ▼

Returns a single contract line item type by ID.

GET /contractLineItemTypes/ List all line item types ▼

Returns the full list of contract line item types available in the account.

Insertions

Ad insertions represent a single placement of an advertisement — linking a contract, product, issue, section, and location. Read-only.

GET /insertions/{id} Get a single insertion ▼

Returns a single insertion record by ID.

GET /insertions/ Search insertions ▼

Query Parameters

Parameter	Type	Description
`id`	integer	Filter by insertion ID
`contract_id`	integer	Filter by contract
`product_id`	integer	Filter by product
`advertiser_id`	integer	Filter by advertiser
`section_id`	integer	Filter by section
`issue_id`	integer	Filter by issue
`location_id`	integer	Filter by location
`sort_by`	string	`id`, `contract_id`, `product_id`, `advertiser_id`, `section_id`, `issue_id`, `location_id`
`sort_order`	string	`asc` or `desc`
`per_page`	integer	Default 25, max 100
`page`	integer	Default 1

Invoices

Invoices track billing records generated from contracts. Read-only.

GET /invoices/{id} Get a single invoice ▼

Returns a single invoice by ID.

GET /invoices/ Search invoices ▼

Query Parameters

Parameter	Type	Description
`id`	integer	Filter by invoice ID
`contract_id`	integer	Filter by contract
`advertiser_id`	integer	Filter by advertiser
`date_created_before`	datetime	Created before date
`date_created_after`	datetime	Created after date
`date_due_before`	datetime	Due before date
`date_due_after`	datetime	Due after date
`amount_from`	decimal	Minimum invoice total
`amount_to`	decimal	Maximum invoice total
`sort_by`	string	`id`, `date_created`, `date_due`, `total`
`sort_order`	string	`asc` or `desc`
`per_page`	integer	Default 25, max 100
`page`	integer	Default 1

Invoice Line Items

Individual charges on an invoice. Read-only.

GET /invoiceLineItems/{id} Get a single invoice line item ▼

Returns a single invoice line item by ID.

GET /invoiceLineItemTypes/ List all invoice line item types ▼

Returns all invoice line item type definitions for the account.

GET /invoiceLineItemTypes/{id} Get a single invoice line item type ▼

Returns a single invoice line item type by ID.

Payments

Payments record money received against invoices. Supports search and creation.

GET /payments/{id} Get a single payment ▼

Returns a single payment record by ID.

GET /payments/ Search payments ▼

Query Parameters

Parameter	Type	Description
`id`	integer	Filter by payment ID
`entered_by_user_id`	integer	Filter by user who entered the payment
`date_created_before`	datetime	Created before date
`date_created_after`	datetime	Created after date
`amount_from`	decimal	Minimum payment amount
`amount_to`	decimal	Maximum payment amount
`contract_id`	integer	Filter by contract
`advertiser_id`	integer	Filter by advertiser
`sort_by`	string	`id`, `date_created`, `amount`
`sort_order`	string	`asc` or `desc`
`per_page`	integer	Default 25, max 100
`page`	integer	Default 1

POST /payments/single Create a payment ▼

Records a new payment against an invoice.

Body Parameters

Parameter	Type	Required	Description
`invoice_id`	integer	Required	Invoice this payment applies to
`amount`	decimal	Required	Payment amount
`notes`	string	Required	Internal notes about the payment
`payment_type`	string	Required	Payment method (e.g. `check`, `credit_card`, `wire`)
`payment_date`	datetime	Required	Date the payment was received (`YYYY-MM-DD HH:MM:SS`)

Example Request

cURL
curl -u API_KEY:API_PASSWORD -X POST \
  -H "Content-Type: application/json" \
  -d '{
    "invoice_id": 1234,
    "amount": 500.00,
    "notes": "Check #4521",
    "payment_type": "check",
    "payment_date": "2025-01-15 00:00:00"
  }' \
  https://yourdomain.mediaos.com/API/payments/single

Ad Requests

Ad requests track incoming creative submission requests tied to insertions. Read-only.

GET /adRequests/ Search ad requests ▼

Query Parameters

Parameter	Type	Description
`id`	integer	Filter by ad request ID
`sort_by`	string	`id`
`sort_order`	string	`asc` or `desc`
`per_page`	integer	Default 25, max 100
`page`	integer	Default 1

Ads

Ads represent the creative assets and metadata for delivered advertisements. Read-only.

GET /ads/{id} Get a single ad ▼

Returns a single ad record including creative metadata and delivery status.

Path Parameters

Parameter	Type	Required	Description
`id`	integer	Required	Ad ID

Memberships

Memberships track subscription or membership records associated with contacts. Read-only.

GET /memberships/verify Verify a member by email ▼

Checks whether a given email address has an active membership record.

Query Parameters

Parameter	Type	Required	Description
`email`	string	Required	Email address to verify

Example Response

JSON
{
  "email": "member@example.com",
  "is_member": true,
  "membership_id": 87,
  "expires": "2025-12-31 23:59:59"
}

GET /memberships/{id} Get a single membership ▼

Returns a single membership record by ID.

Path Parameters

Parameter	Type	Required	Description
`id`	integer	Required	Membership ID