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://api.mediaos.com/

💡

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

📄

OpenAPI Specification available. Download the machine-readable API spec for use with tools like Swagger UI, Postman, or code generators: openapi.yaml ↗

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)

Example Response

JSON
{
  "advertisers": [{
    "id": 42,
    "name": "Acme Corp",
    "is_lead": false,
    "active": true,
    "date_created": "2024-01-15 09:30:00"
  }],
  "count": 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/

Example Response

JSON
{ "id": 42 }

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

Example Response

JSON
{
  "id": 7,
  "name": "Hill & Partners",
  "date_created": "2023-06-01 00:00:00",
  "discount_percent": 15,
  "primary_address": null,
  "primary_phone": null,
  "primary_email": null
}

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

Example Response

JSON
{
  "agencies": [{
    "id": 7,
    "name": "Hill & Partners",
    "date_created": "2023-06-01 00:00:00",
    "discount_percent": 15
  }],
  "count": 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%)

Example Response

JSON
{ "id": 7 }

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

Example Response

JSON
{
  "id": 12,
  "full_name": "Jane Smith",
  "first_name": "Jane",
  "last_name": "Smith",
  "title": "Marketing Director",
  "advertiser_id": 42,
  "advertiser_name": "Acme Corp",
  "active": 1,
  "date_created": "2024-03-10",
  "addresses": [],
  "contact_data": []
}

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

Example Response

JSON
{
  "contacts": [{
    "id": 12,
    "full_name": "Jane Smith",
    "first_name": "Jane",
    "last_name": "Smith",
    "title": "Marketing Director",
    "advertiser_id": 42,
    "active": 1
  }],
  "count": 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

Example Response

JSON
{ "id": 12 }

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

Example Response

JSON
{
  "contact_data_types": [
    { "id": 1, "name": "Phone: Main" },
    { "id": 2, "name": "Email: Work" },
    { "id": 3, "name": "Website: Main" }
  ]
}

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

Returns a single contact data record by ID.

Example Response

JSON
{
  "id": 55,
  "contact_id": 12,
  "advertiser_id": 42,
  "agency_id": null,
  "value": "jane@acmecorp.com",
  "type": "Email",
  "type_name": "Work"
}

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

Example Response

JSON
{
  "contact_data": [{
    "id": 55,
    "contact_id": 12,
    "advertiser_id": 42,
    "agency_id": null,
    "value": "jane@acmecorp.com",
    "type": "Email",
    "type_name": "Work"
  }]
}

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)

Example Response

JSON
{ "id": 55 }

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.

Example Response

JSON
{
  "id": 18,
  "advertiser_id": 42,
  "contact_id": null,
  "agency_id": null,
  "line1": "123 Main St",
  "line2": null,
  "city": "Springfield",
  "state": "IL",
  "postal_code": "62701",
  "country": { "id": 1, "name": "United States", "code": "US" },
  "date_created": "2024-01-20"
}

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

Example Response

JSON
{
  "addresses": [{
    "id": 18,
    "advertiser_id": 42,
    "line1": "123 Main St",
    "city": "Springfield",
    "state": "IL",
    "postal_code": "62701"
  }],
  "count": 1
}

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

Example Response

JSON
{ "id": 18 }

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.

Example Response

JSON
{
  "id": 5,
  "first_name": "Alice",
  "last_name": "Johnson",
  "email": "alice@example.com",
  "is_admin": false,
  "is_sales": true,
  "is_accounting": false,
  "active": true,
  "date_created": "2022-09-01 00:00:00"
}

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

Example Response

JSON
{
  "users": [{
    "id": 5,
    "first_name": "Alice",
    "last_name": "Johnson",
    "email": "alice@example.com",
    "is_sales": true,
    "active": true
  }],
  "count": 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.

Example Response

JSON
{
  "id": 3,
  "name": "Springfield Monthly",
  "active": true,
  "product_type": { "id": 1, "name": "Print" }
}

GET /products/ List all products ▼

Returns all products in the account. No filters required.

Example Response

JSON
{
  "products": [
    { "id": 3, "name": "Springfield Monthly", "active": true, "product_type": { "id": 1, "name": "Print" } },
    { "id": 4, "name": "Daily Digital", "active": true, "product_type": { "id": 2, "name": "Digital" } }
  ]
}

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.

Example Response

JSON
{
  "id": 9,
  "name": "Full Page",
  "description": "Full page print ad",
  "product_id": 3,
  "width": 8.5,
  "height": 11,
  "scheduling_units": 1,
  "date_created": "2022-01-01 00:00:00",
  "date_deleted": null
}

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

Example Response

JSON
{
  "ad_sizes": [
    { "id": 9, "name": "Full Page", "product_id": 3, "width": 8.5, "height": 11 },
    { "id": 10, "name": "Half Page", "product_id": 3, "width": 8.5, "height": 5.5 }
  ]
}

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.

Example Response

JSON
{
  "id": 22,
  "name": "Full Page Rate",
  "ad_size_id": 9,
  "publication_id": 3,
  "rate": 1200.00,
  "units": 1,
  "location_id": null,
  "date_created": "2022-01-01 00:00:00",
  "date_deleted": null
}

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

Example Response

JSON
{
  "ad_rates": [
    { "id": 22, "name": "Full Page Rate", "ad_size_id": 9, "rate": 1200.00, "units": 1 },
    { "id": 23, "name": "Half Page Rate", "ad_size_id": 10, "rate": 650.00, "units": 1 }
  ]
}

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.

Example Response

JSON
{
  "id": 101,
  "name": "January 2025",
  "product_id": 3,
  "date_print": "2025-01-01",
  "date_mail": "2024-12-28",
  "date_sell_close": "2024-12-01"
}

GET /issues/ List issues for a product ▼

Query Parameters

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

Example Response

JSON
{
  "issues": [
    { "id": 101, "name": "January 2025", "product_id": 3, "date_print": "2025-01-01", "date_sell_close": "2024-12-01" },
    { "id": 102, "name": "February 2025", "product_id": 3, "date_print": "2025-02-01", "date_sell_close": "2025-01-01" }
  ]
}

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.

Example Response

JSON
{
  "id": 30,
  "name": "Downtown Kiosk",
  "product_id": 3,
  "number": "K-01",
  "city": "Springfield",
  "state": "IL",
  "date_created": "2023-01-15 00:00:00",
  "date_deleted": null
}

GET /locations/ List locations for a product ▼

Query Parameters

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

Example Response

JSON
{
  "locations": [
    { "id": 30, "name": "Downtown Kiosk", "product_id": 3, "number": "K-01", "city": "Springfield", "state": "IL" }
  ]
}

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.

Example Response

JSON
{
  "id": 14,
  "name": "Back Cover",
  "product_id": 3,
  "date_created": "2022-01-01 00:00:00"
}

GET /sections/ List sections for a product ▼

Query Parameters

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

Example Response

JSON
{
  "sections": [
    { "id": 14, "name": "Back Cover", "product_id": 3 },
    { "id": 15, "name": "Inside Front Cover", "product_id": 3 }
  ]
}

Contracts

Contracts represent advertising orders / sales agreements. Full CRUD and status-transition actions are supported.

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

Returns a single contract record by ID.

Example Response

JSON
{
  "id": 200,
  "advertiser_id": 42,
  "agency_id": null,
  "status": "signed",
  "is_proposal": false,
  "total": 2400.00,
  "date_created": "2024-11-01 00:00:00",
  "date_sold": "2024-11-05 00:00:00",
  "insertions": [],
  "line_items": []
}

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

Example Response

JSON
{
  "contracts": [{
    "id": 200,
    "advertiser_id": 42,
    "status": "signed",
    "is_proposal": false,
    "total": 2400.00,
    "date_created": "2024-11-01 00:00:00"
  }],
  "count": 1
}

PUT /contracts/ Create a contract ▼

Creates a new contract (proposal). The new contract starts in open status.

Body Parameters

Parameter	Type	Required	Description
`advertiser_id`	integer	Required	Advertiser this contract belongs to
`agency_id`	integer	Optional	Agency acting on behalf of advertiser
`sold_by_user_id`	integer	Optional	Sales rep responsible for this contract
`notes`	string	Optional	Internal notes
`insertion_order_number`	string	Optional	External IO number
`down_payment_amount`	decimal	Optional	Required down payment amount
`term_id`	integer	Optional	Payment term
`percent_discount`	decimal	Optional	Discount percentage applied to total
`tax_rate_id`	integer	Optional	Tax rate to apply
`business_unit_id`	integer	Optional	Business unit assignment

Example Request

cURL
curl -u API_KEY:API_PASSWORD -X PUT \
  -H "Content-Type: application/json" \
  -d '{"advertiser_id":42,"sold_by_user_id":5}' \
  https://yourdomain.mediaos.com/API/contracts/

Example Response

JSON
{ "id": 200 }

POST /contracts/{id} Update a contract ▼

Updates an existing contract. Won contracts cannot be modified via this endpoint — use the action endpoints instead.

⚠️

Won contracts are protected. Attempting to update a Won contract returns 400. Use setToLost or setToOpen to change status.

Path Parameters

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

Body Parameters

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

POST /contracts/{id}/setToWon Mark contract as Won ▼

Marks a contract as Won (sold). Enforces all business rules: sales lock, pending forecast items, DocuSign requirements, and down payment checks.

Body Parameters

Parameter	Type	Required	Description
`sold_date`	date	Optional	Date contract was sold (defaults to today)

Example Request

cURL
curl -u API_KEY:API_PASSWORD -X POST \
  -H "Content-Type: application/json" \
  -d '{"sold_date":"2025-01-15"}' \
  https://yourdomain.mediaos.com/API/contracts/200/setToWon

POST /contracts/{id}/setToLost Mark contract as Lost ▼

Marks a contract as Lost. Cannot be applied to Won (sold) contracts or forecast contracts.

POST /contracts/{id}/setToOpen Move Lost contract back to Open ▼

Moves a Lost contract back to Open (Proposal) status. Only Lost→Open transitions are allowed. Won contracts cannot be moved back to Open.

POST /contracts/{id}/approveDiscount Approve a discount ▼

Approves a discount that exceeds the account threshold. The calling user must be an admin or sales manager.

Contract Line Items

Individual line items within a contract, describing adjustments such as discounts and fees. Full CRUD is supported on non-Won contracts.

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

Returns a single contract line item by ID.

Example Response

JSON
{
  "id": 301,
  "contract_id": 200,
  "contract_line_item_type_id": 2,
  "notes": "Agency commission",
  "amount": -240.00,
  "taxable": false,
  "apply_to_insertion_id": null
}

GET /contractLineItems/ Get line items for a contract ▼

Query Parameters

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

Example Response

JSON
{
  "contract_line_items": [{
    "id": 301,
    "contract_id": 200,
    "contract_line_item_type_id": 2,
    "notes": "Agency commission",
    "amount": -240.00,
    "taxable": false
  }]
}

PUT /contractLineItems/ Create a contract line item ▼

Creates a new line item on a contract. Cannot add to a Won contract.

Body Parameters

Parameter	Type	Required	Description
`contract_id`	integer	Required	Contract this line item belongs to
`contract_line_item_type_id`	integer	Required	Type of line item
`amount`	decimal	Required	Amount (positive for additions, negative for discounts)
`notes`	string	Optional	Description or notes
`taxable`	boolean	Optional	Whether this line item is taxable
`apply_to_insertion_id`	integer	Optional	Apply only to a specific insertion

Example Response

JSON
{ "id": 301 }

POST /contractLineItems/{id} Update a contract line item ▼

Updates an existing line item. Cannot modify line items on a Won contract.

Body Parameters

Same fields as Create. Only supplied fields are updated.

DELETE /contractLineItems/{id} Delete a contract line item ▼

Deletes a contract line item. Cannot delete from a Won contract. Returns 204 No Content on success.

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

Returns a single contract line item type by ID.

Example Response

JSON
{
  "id": 2,
  "name": "Agency Commission",
  "type": "discount",
  "visibility": "internal",
  "date_created": "2021-05-01 00:00:00",
  "date_deleted": null
}

GET /contractLineItemTypes/ List all line item types ▼

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

Example Response

JSON
{
  "contact_line_item_types": [
    { "id": 1, "name": "Discount", "type": "discount", "visibility": "all" },
    { "id": 2, "name": "Agency Commission", "type": "discount", "visibility": "internal" }
  ]
}

Insertions

Ad insertions represent a single placement of an advertisement — linking a contract, product, issue, section, and location. Full CRUD is supported on non-Won contracts.

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

Returns a single insertion record by ID.

Example Response

JSON
{
  "id": 450,
  "contract_id": 200,
  "product_id": 3,
  "ad_size_id": 9,
  "ad_rate_id": 22,
  "issue_id": 101,
  "section_id": 14,
  "location_id": null,
  "quantity": 1,
  "taxable": true,
  "date_delivery": "2025-01-01",
  "date_canceled": null,
  "schedule": null
}

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

Example Response

JSON
{
  "insertions": [{
    "id": 450,
    "contract_id": 200,
    "product_id": 3,
    "ad_size_id": 9,
    "issue_id": 101,
    "quantity": 1,
    "date_delivery": "2025-01-01"
  }],
  "count": 1
}

PUT /insertions/ Create an insertion ▼

Creates a new insertion on a contract. The contract must not be Won.

Body Parameters

Parameter	Type	Required	Description
`contract_id`	integer	Required	Contract this insertion belongs to
`product_id`	integer	Required	Publication / product
`ad_size_id`	integer	Optional	Ad size
`ad_rate_id`	integer	Optional	Ad rate
`issue_id`	integer	Optional	Issue
`section_id`	integer	Optional	Section
`location_id`	integer	Optional	Location
`ad_id`	integer	Optional	Associated ad creative
`quantity`	integer	Optional	Number of insertions
`discount`	decimal	Optional	Discount amount
`placement`	string	Optional	Placement notes
`description`	string	Optional	Description
`deliver_date`	date	Optional	Delivery date (`YYYY-MM-DD`)
`taxable`	boolean	Optional	Whether this insertion is taxable

Example Response

JSON
{ "id": 450 }

POST /insertions/{id} Update an insertion ▼

Updates an existing insertion. The parent contract must not be Won.

Body Parameters

Same fields as Create. Only supplied fields are updated.

DELETE /insertions/{id} Delete an insertion ▼

Deletes an insertion. Cannot delete if the insertion has already been invoiced. Returns 204 No Content on success.

Invoices

Invoices track billing records generated from contracts. Supports search, generation from Won contracts, deletion, and write-off actions.

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

Returns a single invoice by ID.

Example Response

JSON
{
  "id": 500,
  "contract_id": 200,
  "advertiser_id": 42,
  "status": "open",
  "sub_total": 2400.00,
  "tax_total": 192.00,
  "discount_total": 0.00,
  "total": 2592.00,
  "date_created": "2024-11-15 00:00:00",
  "date_due": "2024-12-15",
  "line_items": []
}

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

Example Response

JSON
{
  "invoices": [{
    "id": 500,
    "contract_id": 200,
    "advertiser_id": 42,
    "status": "open",
    "total": 2592.00,
    "date_due": "2024-12-15"
  }],
  "count": 1
}

PUT /invoices/ Generate an invoice from a Won contract ▼

Generates a new invoice for a Won contract. The contract must have a soldDate set. All insertion_ids must belong to the specified contract.

Body Parameters

Parameter	Type	Required	Description
`contract_id`	integer	Required	ID of the Won contract to invoice
`insertion_ids`	integer[]	Required	Array of insertion IDs to include on this invoice
`create_date`	date	Optional	Invoice creation date (defaults to today)
`due_date`	date	Optional	Invoice due date

Example Request

cURL
curl -u API_KEY:API_PASSWORD -X PUT \
  -H "Content-Type: application/json" \
  -d '{
    "contract_id": 200,
    "insertion_ids": [450, 451],
    "due_date": "2025-02-01"
  }' \
  https://yourdomain.mediaos.com/API/invoices/

Example Response

JSON
{ "id": 500 }

DELETE /invoices/{id} Delete an invoice ▼

Deletes an invoice. Cannot delete if the invoice has any applied payments — unapply all payments first. Returns 204 No Content on success.

POST /invoices/{id}/writeOff Write off remaining balance ▼

Writes off the remaining balance on an invoice. Requirements:

Invoice must be editable (canEdit())
Invoice must not be a credit memo
Invoice must have a positive remaining balance

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.

Example Response

JSON
{
  "id": 601,
  "invoice_id": 500,
  "invoice_line_item_type_id": 1,
  "insertion_id": 450,
  "description": "Full Page – January 2025",
  "amount": 1200.00,
  "total": 1200.00,
  "taxable": true
}

GET /invoiceLineItemTypes/ List all invoice line item types ▼

Returns all invoice line item type definitions for the account.

Example Response

JSON
{
  "invoiceLineItemTypes": [
    { "id": 1, "name": "Ad Insertion", "type": "insertion" },
    { "id": 2, "name": "Discount", "type": "discount" }
  ]
}

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

Returns a single invoice line item type by ID.

Example Response

JSON
{
  "id": 1,
  "name": "Ad Insertion",
  "type": "insertion",
  "date_created": "2021-01-01 00:00:00",
  "date_deleted": null
}

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.

Example Response

JSON
{
  "id": 700,
  "advertiser_id": 42,
  "contract_id": 200,
  "entered_by_user_id": 5,
  "type": "check",
  "amount": 500.00,
  "date_created": "2025-01-15",
  "date_refunded": null,
  "notes": "Check #4521"
}

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

Example Response

JSON
{
  "payments": [{
    "id": 700,
    "advertiser_id": 42,
    "contract_id": 200,
    "type": "check",
    "amount": 500.00,
    "date_created": "2025-01-15"
  }],
  "count": 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

Example Response

JSON
{
  "payment": {
    "id": 700,
    "advertiser_id": 42,
    "contract_id": 200,
    "type": "check",
    "amount": 500.00,
    "date_created": "2025-01-15",
    "notes": "Check #4521"
  }
}

DELETE /payments/{id} Delete (void) a payment ▼

Deletes a payment and unapplies it from all invoices. Requirements:

Calling user must be an admin, sales manager, or accounting
Payment must not fall within an accounting lock date period

Returns 204 No Content on success.

Ad Requests

Ad requests track incoming creative submission requests tied to insertions. Full CRUD and cancel action are supported.

GET /adRequests/{id} Get a single ad request ▼

Returns a single ad request record by ID.

Example Response

JSON
{
  "id": 800,
  "advertiser_id": 42,
  "insertion_id": 450,
  "ad_id": null,
  "status": "pending",
  "due_date": "2025-01-10",
  "date_created": "2024-12-01 00:00:00",
  "date_canceled": null
}

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

Example Response

JSON
{
  "adRequests": [{
    "id": 800,
    "advertiser_id": 42,
    "insertion_id": 450,
    "ad_id": null,
    "status": "pending",
    "due_date": "2025-01-10",
    "date_created": "2024-12-01 00:00:00",
    "date_canceled": null
  }],
  "count": 1
}

PUT /adRequests/ Create an ad request ▼

Creates a new ad request. The new request starts in pending status.

Body Parameters

Parameter	Type	Required	Description
`advertiser_id`	integer	Required	Advertiser this request belongs to
`requested_by_user_id`	integer	Optional	User who created the request (defaults to authenticated user)
`assigned_to_user_id`	integer	Optional	Designer or user assigned to fulfill the request
`insertion_id`	integer	Optional	Insertion this request is associated with
`ad_id`	integer	Optional	Ad creative to use
`details`	string	Optional	Instructions or notes for the request
`due_date`	date	Optional	Due date (`YYYY-MM-DD`)

Example Response

JSON
{ "id": 800 }

POST /adRequests/{id} Update an ad request ▼

Updates an existing ad request. Only supplied fields are updated.

Body Parameters

Same fields as Create. All fields optional except advertiser_id.

POST /adRequests/{id}/cancel Cancel an ad request ▼

Cancels an ad request. Cannot cancel an already-canceled request.

DELETE /adRequests/{id} Delete an ad request ▼

Deletes an ad request. Cannot delete if the request has proofs or a designer is assigned. Returns 204 No Content on success.

Ads

Ads represent the creative assets and metadata for delivered advertisements. Full CRUD is supported. File uploads are not supported via the API — use the application UI for uploading creative files.

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

Example Response

JSON
{
  "id": 900,
  "name": "Acme Full Page Jan 2025",
  "advertiserID": 42,
  "url": "https://files.example.com/ads/acme-fullpage.pdf",
  "preFlighted": true,
  "createDate": "2024-12-10 00:00:00",
  "deleteDate": null
}

GET /ads/ List / search ads ▼

Query Parameters

Parameter	Type	Description
`id`	integer	Filter by ad ID
`advertiser_id`	integer	Filter by advertiser
`name`	string	Filter by name (partial match)
`active`	boolean	Filter active (not deleted) ads
`sort_by`	string	`id`, `name`, `date_created`
`sort_order`	string	`asc` or `desc`
`per_page`	integer	Default 25, max 100
`page`	integer	Default 1

Example Response

JSON
{
  "ads": [{
    "id": 900,
    "name": "Acme Full Page Jan 2025",
    "advertiserID": 42,
    "createDate": "2024-12-10 00:00:00"
  }],
  "count": 1
}

PUT /ads/ Create an ad ▼

Creates a new ad record. File uploads are not supported via the API — use the application UI to attach creative files.

Body Parameters

Parameter	Type	Required	Description
`advertiser_id`	integer	Required	Advertiser this ad belongs to
`name`	string	Optional	Ad name / title
`text`	string	Optional	Ad copy or description

Example Response

JSON
{ "id": 900 }

POST /ads/{id} Update an ad ▼

Updates an existing ad's metadata. Only supplied fields are updated.

Body Parameters

Same fields as Create. Only supplied fields are updated.

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

Example Response

JSON
{
  "id": 87,
  "contact_id": 12,
  "plan": "Annual",
  "status": "active",
  "date_start": "2025-01-01",
  "date_expires": "2025-12-31"
}