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. Responses include convenience fields primary_email, primary_phone, and primary_address — the resolved primary ContactData / Address objects (or null if not set).

ℹ️

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": [],
  "primary_email": { "id": 501, "value": "jane@acme.com", "type": "Email", "type_name": "Work" },
  "primary_phone": { "id": 502, "value": "555-0100", "type": "Phone", "type_name": "Mobile" },
  "primary_address": { "id": 301, "line1": "123 Main St", "city": "Denver", "state": "CO", "zip": "80202" }
}

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, including uploading creative files (image, PDF, or video) via URL or base64.

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 metadata record without a creative file. To create an ad with a creative file in a single call, use PUT /ads/upload.

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 }

PUT /ads/upload Create an ad and upload a creative file ▼

Creates a new ad and uploads the creative file in a single call. Supply the file either as a publicly reachable URL that the server fetches (file_url) or as base64-encoded bytes (file_base64). Raster image dimensions (jpg, jpeg, png, gif) are populated automatically. If the upload fails the ad is rolled back (archived).

Body Parameters

Parameter	Type	Required	Description
`advertiser_id`	integer	Required	Advertiser this ad belongs to
`file_url`	string	Required*	Publicly reachable URL of the creative file. Server fetches and stores it.
`file_base64`	string	Required*	Base64-encoded creative file bytes. One of `file_url` or `file_base64` is required.
`file_name`	string	Optional	Filename with extension (e.g. `banner.jpg`). Required when using `file_base64`; inferred from the URL otherwise.
`mime_type`	string	Optional	MIME type of the file (e.g. `image/jpeg`, `application/pdf`, `video/mp4`).
`name`	string	Optional	Ad name / title
`text`	string	Optional	Ad copy or description

Example Request

cURL
curl -u API_KEY:API_PASSWORD -X PUT \
  -H "Content-Type: application/json" \
  -d '{
    "advertiser_id": 42,
    "name": "Acme Full Page Jan 2025",
    "file_url": "https://cdn.example.com/creatives/acme-fullpage.pdf",
    "file_name": "acme-fullpage.pdf",
    "mime_type": "application/pdf"
  }' \
  https://yourdomain.mediaos.com/API/ads/upload

Example Response

JSON
{
  "id": 900,
  "name": "Acme Full Page Jan 2025",
  "advertiserID": 42,
  "url": "https://files.example.com/ads/acme-fullpage.pdf?token=…",
  "createDate": "2025-01-15 10:30:00"
}

Returns 201 Created on success.

POST /ads/{id}/upload Upload or replace the creative file on an existing ad ▼

Uploads a creative file and attaches it to an existing ad, replacing any current creative. Supply the file via file_url or file_base64. Raster image dimensions are populated automatically. Archived ads (soft-deleted) cannot be modified.

Body Parameters

Parameter	Type	Required	Description
`file_url`	string	Required*	Publicly reachable URL of the creative file.
`file_base64`	string	Required*	Base64-encoded creative file bytes. One of `file_url` or `file_base64` is required.
`file_name`	string	Optional	Filename with extension. Required when using `file_base64`.
`mime_type`	string	Optional	MIME type of the file.

Example Request

cURL
curl -u API_KEY:API_PASSWORD -X POST \
  -H "Content-Type: application/json" \
  -d '{
    "file_url": "https://cdn.example.com/creatives/acme-v2.jpg",
    "file_name": "acme-v2.jpg",
    "mime_type": "image/jpeg"
  }' \
  https://yourdomain.mediaos.com/API/ads/900/upload

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.

POST /ads/{id}/assign Assign an ad to an ad insertion ▼

Assigns the ad to the specified insertion. If the product supports multiple ads or is DFP-configured, the ad is added to adToInsertions; otherwise the insertion's primary adID is set. Child ads (any ad whose parentAdID equals this ad's adID) are assigned as well. Archived ads cannot be assigned.

Body Parameters

Parameter	Type	Required	Description
`insertion_id`	integer	Required	The ad insertion to assign this ad to

Example Request

cURL
curl -u API_KEY:API_PASSWORD -X POST \
  -H "Content-Type: application/json" \
  -d '{ "insertion_id": 12345 }' \
  https://yourdomain.mediaos.com/API/ads/900/assign

Returns the updated insertion.

POST /ads/{id}/unassign Unassign an ad from an ad insertion ▼

Removes the ad (and any child ads) from the specified insertion. If the ad was the insertion's primary adID, that reference is cleared.

Body Parameters

Parameter	Type	Required	Description
`insertion_id`	integer	Required	The ad insertion to unassign this ad from

Example Request

cURL
curl -u API_KEY:API_PASSWORD -X POST \
  -H "Content-Type: application/json" \
  -d '{ "insertion_id": 12345 }' \
  https://yourdomain.mediaos.com/API/ads/900/unassign

Memberships

Memberships track subscription or membership records associated with contacts. Includes member authentication, password management, and read-only membership type and level lookups.

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"
}

POST /memberships/authenticate Authenticate a member ▼

Authenticates a member by email combined with either their password or the zip code of one of their addresses (first 5 digits). Returns the contact record, the audience filter IDs the contact currently belongs to (from the memberAudienceFilterCache table), and their active (non-expired) memberships. Returns 401 when no member matches the supplied credentials.

Body Parameters

Parameter	Type	Required	Description
`email`	string	Required	The member's email address
`password`	string	Optional*	The member's password. Required if `zip` is not supplied.
`zip`	string	Optional*	Zip code of one of the member's addresses. Required if `password` is not supplied.

Example Response

JSON
{
  "authenticated": true,
  "authentication_method": "password",
  "contact": { "id": 12, "first_name": "Pat", "last_name": "Member" },
  "audience_ids": [14, 27, 31],
  "memberships": [ { "membershipID": 87 } ],
  "count": 1
}

POST /memberships/passwordReset Send a password reset email ▼

Sends the member an email containing a secure one-time login link for the given website — the same mechanism as the member portal's instant login. After clicking the link the member is logged in and can set a new password. A website_id is required so the email is branded and the member is redirected to the correct website.

Body Parameters

Parameter	Type	Required	Description
`email`	string	Required	The member's email address
`website_id`	integer	Required	The website used to brand the email and redirect the member
`url`	string	Optional	URL the member is redirected to after clicking the link. Defaults to the website's URL.

Example Response

JSON
{
  "success": true
}

POST /memberships/setPassword Set a member's password ▼

Sets the password for a member identified by contact_id or email. When identified by email, the password is applied to every non-deleted member contact matching that email.

Body Parameters

Parameter	Type	Required	Description
`password`	string	Required	The new password (minimum 6 characters)
`contact_id`	integer	Optional*	The member's contact ID. Required if `email` is not supplied.
`email`	string	Optional*	The member's email. Required if `contact_id` is not supplied.

Example Response

JSON
{
  "success": true,
  "contact_ids": [12]
}

GET /membershipTypes/ List membership types ▼

Read-only list of membership types.

Query Parameters

Parameter	Type	Required	Description
`membership_tier_type_id`	integer	Optional	Filter by membership tier type ID

Example Response

JSON
{
  "membership_types": [
    {
      "membershipTypeID": 3,
      "membershipTypeName": "Annual Digital",
      "membershipTypeMethod": "Time",
      "membershipTierTypeID": 1,
      "membershipTierTypeName": "Reader",
      "isTimeBased": true,
      "isIssueBased": false
    }
  ],
  "count": 1
}

GET /membershipTypes/{id} Get a single membership type ▼

Returns a single membership type record by ID. Read-only.

Path Parameters

Parameter	Type	Required	Description
`id`	integer	Required	Membership type ID

GET /membershipLevels/ List membership levels ▼

Read-only list of membership tier levels, grouped by tier type.

Query Parameters

Parameter	Type	Required	Description
`tier_type_id`	integer	Optional	Filter by membership tier type ID

Example Response

JSON
{
  "membership_levels": [
    {
      "membershipTierTypeID": 1,
      "name": "Reader",
      "tierLevels": [
        { "membershipTierLevelID": 4, "tierName": "Gold", "tierLevel": 2 }
      ]
    }
  ],
  "count": 1
}

GET /membershipLevels/{id} Get a single membership level ▼

Returns a single membership tier level by ID. Read-only.

Path Parameters

Parameter	Type	Required	Description
`id`	integer	Required	Membership tier level ID

Example Response

JSON
{
  "membershipTierLevelID": 4,
  "membershipTierTypeID": 1,
  "tierName": "Gold",
  "tierLevel": 2
}

Audiences

Audiences are saved member segments built from filter criteria. Use these endpoints to list configured audiences and look up a single audience. Contact-to-audience membership for an authenticated member is returned by POST /memberships/authenticate.

GET /audiences/{id} Get a single audience ▼

Returns a single audience filter by ID.

Example Response

JSON
{
  "id": 14,
  "parent_id": null,
  "name": "Active Subscribers",
  "description": "Members with an active subscription.",
  "type": "Member",
  "status": "Active",
  "process_status": "Complete",
  "match_count": 2504,
  "saved_by_user_id": 5,
  "date_created": "2024-11-01 09:15:00",
  "date_deleted": null,
  "last_processed": "2025-01-15 02:00:00"
}

GET /audiences/ List / search audiences ▼

Returns saved member audience filters. By default only active (non-deleted) audiences are returned.

Query Parameters

Parameter	Type	Description
`id`	integer	Filter by audience ID
`saved_by_user_id`	integer	Filter by the user who saved the audience
`name`	string	Case-insensitive contains-match on audience name
`status`	string	Filter by audience status
`include_deleted`	boolean	Include soft-deleted audiences. Defaults to `false`.
`per_page`	integer	Default 25, max 100
`page`	integer	Default 1

Example Response

JSON
{
  "audiences": [{
    "id": 14,
    "name": "Active Subscribers",
    "status": "Active",
    "match_count": 2504
  }],
  "count": 1
}

Touch Points

Touch points log sales activity — phone calls, emails, SMS messages, appointments, and follow-ups — against advertisers, agencies, and contacts. Creating a touch point updates the advertiser's last-activity date.

GET /touchPoints/{id} Get a single touch point ▼

Returns a single touch point record by ID.

Example Response

JSON
{
  "id": 910,
  "type": "Phone",
  "advertiser_id": 42,
  "agency_id": null,
  "contact_id": 12,
  "sent_by_user_id": 5,
  "subject": "Q1 renewal call",
  "body": "Discussed renewing the Q1 campaign.",
  "date": "2025-01-15 10:30:00",
  "call_result": "Connected",
  "call_direction": "Outbound",
  "call_duration": 420,
  "appointment_duration": null
}

PUT /touchPoints/ Create a touch point ▼

Logs a new touch point. At least one of advertiser_id, agency_id, or contact_id is required. When only contact_id is provided, the advertiser or agency is inherited from the contact.

Body Parameters

Parameter	Type	Required	Description
`type`	string	Required	`Appointment`, `Email`, `Follow-up`, `Phone`, or `SMS`
`advertiser_id`	integer	—	Advertiser the activity is logged against
`agency_id`	integer	—	Agency the activity is logged against
`contact_id`	integer	—	Contact involved in the activity
`subject`	string	—	Short summary of the activity
`body`	string	—	Full notes / details
`date`	datetime	—	When the activity occurred. Defaults to now.
`sent_by_user_id`	integer	—	User who performed the activity. Defaults to the API user.
`call_result`	string	—	Outcome of a phone call (e.g. `Connected`, `Voicemail`)
`call_direction`	string	—	`Inbound` or `Outbound`
`call_duration`	integer	—	Call duration in seconds
`appointment_duration`	integer	—	Appointment duration in minutes

Example Request

cURL
curl -u API_KEY:API_PASSWORD -X PUT \
  -H "Content-Type: application/json" \
  -d '{
    "type": "Phone",
    "advertiser_id": 42,
    "contact_id": 12,
    "subject": "Q1 renewal call",
    "body": "Discussed renewing the Q1 campaign.",
    "call_result": "Connected",
    "call_direction": "Outbound",
    "call_duration": 420
  }' \
  https://yourdomain.mediaos.com/API/touchPoints/

Example Response

JSON
{
  "id": 910
}

Returns 201 Created on success. Creating a touch point clears the advertiser's fair-game flag and updates its last-activity date.

Tasks & Notes

Tasks and notes are post board items attached to any object — advertisers, agencies, contacts, contracts, invoices, and more. Tasks are assignable with due dates and trigger notifications; notes are simple annotations.

GET /posts/{id} Get a single post (task or note) ▼

Returns a single post board item (task or note) by ID.

Example Response

JSON
{
  "id": 1500,
  "type": "task",
  "subject": "Send renewal proposal",
  "message": "Put together the Q2 renewal proposal.",
  "object_type": "advertisers",
  "object_id": 42,
  "created_by_user_id": 5,
  "assigned_to_user_id": 8,
  "due_date": "2025-02-01",
  "start_date": null,
  "status": "Pending",
  "percent_complete": 0,
  "created_date": "2025-01-15 10:30:00"
}

PUT /tasks/ Create a task ▼

Creates a task attached to an object. Provide object_type and object_id, or use advertiser_id as a shortcut. The assigned user is notified.

Body Parameters

Parameter	Type	Required	Description
`message`	string	Required	The body of the task
`subject`	string	—	Short task title
`object_type`	string	—	Object type the task is attached to (e.g. `advertisers`, `agencies`, `contacts`, `contracts`, `invoices`)
`object_id`	integer	—	ID of the attached object
`advertiser_id`	integer	—	Shortcut for `object_type=advertisers` and `object_id`
`assigned_to_user_id`	integer	—	User the task is assigned to. Defaults to the API user.
`due_date`	date	—	Due date. Defaults to today.
`start_date`	date	—	Start date

Example Request

cURL
curl -u API_KEY:API_PASSWORD -X PUT \
  -H "Content-Type: application/json" \
  -d '{
    "message": "Put together the Q2 renewal proposal.",
    "subject": "Send renewal proposal",
    "advertiser_id": 42,
    "assigned_to_user_id": 8,
    "due_date": "2025-02-01"
  }' \
  https://yourdomain.mediaos.com/API/tasks/

Example Response

JSON
{
  "id": 1500
}

Returns 201 Created on success. The assigned user receives a task-assigned notification.

PUT /notes/ Create a note ▼

Creates a note attached to an object. Provide object_type and object_id, or use advertiser_id as a shortcut. Notes do not trigger notifications.

Body Parameters

Parameter	Type	Required	Description
`message`	string	Required	The body of the note
`subject`	string	—	Short note title
`object_type`	string	—	Object type the note is attached to (e.g. `advertisers`, `agencies`, `contacts`, `contracts`, `invoices`)
`object_id`	integer	—	ID of the attached object
`advertiser_id`	integer	—	Shortcut for `object_type=advertisers` and `object_id`

Example Request

cURL
curl -u API_KEY:API_PASSWORD -X PUT \
  -H "Content-Type: application/json" \
  -d '{
    "message": "Prefers email contact over phone.",
    "advertiser_id": 42
  }' \
  https://yourdomain.mediaos.com/API/notes/

Example Response

JSON
{
  "id": 1501
}

Returns 201 Created on success.