v2.0.0
OAS 3.0.0

Advertiser API

Advertiser API provides developers with a flexible and scalable way to integrate advertising features into their applications.

Legacy API v1 is deprecated and will be retired in a future release. Use the current API for new integrations. Legacy documentation remains available at Legacy API v1 docs.

All requests performed will affect live entities. Make sure to use dedicated entity IDs when testing write operations (POST, PUT, PATCH, and DELETE).

Authorization

All endpoints require a bearer token.

Send the token in the Authorization header with the Bearer scheme.

Create tokens in the UI at Create API token.

For example: Authorization: Bearer api_token_example_12345678 

curl -g 'http://dsp.ampx.io/advertiser/api/v2/reports?dimensions=date&measures=clicks&filters[date]=2025-01-01' \
--header 'Authorization: Bearer api_token_example_12345678'

Rate limits

API requests are processed through an IP-based concurrency limiter.

If too many requests from the same IP are already active or waiting in queue, the server may reject the request with 503 Service Unavailable.

The server does not provide a precise retry timestamp.

Clients should retry with exponential backoff and jitter.

Methods overview

  • GET — read records, reports, and reference data.
  • POST — create new records.
  • PATCH — apply partial changes to an existing record. Omit fields that should remain unchanged.
  • DELETE — remove an existing record.

Date and time formats

Use YYYY-MM-DD for date-only values, including report date filters.

Use ISO 8601 strings for date-time values, for example 2024-01-01T00:00:00Z.

Error responses

Error responses use a consistent JSON shape with code, detail, and extra fields.

Common cases:

  • 401 Unauthorized — missing or invalid authorization credentials.
  • 403 Forbidden — the token is valid, but access to the requested resource is denied.
  • 422 Unprocessable Entity — the request is syntactically valid but fails body, query, or filter validation.
  • 503 Service Unavailable — the request queue for the current client IP is full or timed out.

Validation errors may include field-level details in extra.validationErrors or extra.fields, depending on the endpoint.

Reports requests

Report queries should include a valid date filter.

If the API responds with INVALID_REPORTS_FILTERS, correct the query before retrying it.

Server:http://dsp.ampx.io
Client Libraries
Shell Curl

Payment Transactions (Collapsed)

​

Payment transactions manage account payment records, amounts, and statuses. Use these to track billing history, verify payments, and reconcile account transactions.

Payment Transactions Operations

List payment transactions

​

Returns payment transactions that match the query.

Query Parameters
  • fields
    Type: array string[]enum

    Specify the fields to include in the response.

    • Omit fields to include all fields available on this route.
    • Use fields to request only the fields you need.
    • Set fields to an empty value (fields=) to request no non-primary-key fields.
    • Primary key fields are always included in the response.

    Hint: pass this query parameter once, with values joined by commas.

    URL query example: ?fields=timestamp,date,type

    values
    • timestamp
    • date
    • type
    • status
    • paymentSystem
    • amount
    • description
    • comments
  • orderBy
    Type: array string[] · Sorting expressions

    Specifies the field(s) and sorting direction for ordering the query results.

    Value format:

    • Array of sorting expressions
    • Each item format: field:direction
    • Allowed directions: asc (ascending), desc (descending)
    • Allowed fields: date, status, amount

    Hint: pass this query parameter once, with values joined by commas.

    URL query example: ?orderBy=date:asc,status:desc

  • filters
    Type: object

    Hint: pass each property as a separate query parameter using square brackets.

    URL query example: ?filters[id]=1,2

    • id
      Type: string · Separated values

      Value format:

      • A , separated value: An array of: An integer
  • pagination

    Pagination parameters. Use one of the following methods:

    • offset and limit for offset-based pagination
    • page and size for page-based pagination

    Hint: pass each property as a separate query parameter using square brackets.

    URL query example: ?pagination[offset]=0&pagination[limit]=10

    Offset-based pagination. Use offset and/or limit.

    • limit
      Type: integer
      min:  
      1

      The maximum number of items to return.

      For example, limit=10 will return up to 10 items.

    • offset
      Type: integer
      min:  
      0

      The offset indicating how many items to skip before starting to return results.

      For example, offset=0 will return the first limit items.

Responses
  • application/json
  • application/json
  • application/json
  • application/json
  • application/json
  • application/json
Request Example for get/advertiser/api/v2/payment-transactions 
curl 'http://dsp.ampx.io/advertiser/api/v2/payment-transactions?fields=timestamp%2Cdate%2Ctype&orderBy=date%3Aasc%2Cstatus%3Adesc&pagination[offset]=0&pagination[limit]=10' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN'

[
  {
    "id": 1,
    "timestamp": "2024-01-01T00:00:00Z",
    "date": "2024-01-01",
    "type": "CHARGE",
    "status": "APPROVED",
    "paymentSystem": "STRIPE",
    "amount": 123.45,
    "description": "Payment for service",
    "comments": "Manual adjustment"
  }
]

Payment transactions that match the query. Each record includes the requested fields. The id field is always included in each record.

Get payment transaction

​

Returns the requested payment transaction. Use the fields query parameter to limit the response.

Path Parameters
  • paymentTransactionId
    Type: integer
    required

    Payment transaction ID.

Query Parameters
  • fields
    Type: array string[]enum

    Specify the fields to include in the response.

    • Omit fields to include all fields available on this route.
    • Use fields to request only the fields you need.
    • Set fields to an empty value (fields=) to request no non-primary-key fields.
    • Primary key fields are always included in the response.

    Hint: pass this query parameter once, with values joined by commas.

    URL query example: ?fields=timestamp,date,type

    values
    • timestamp
    • date
    • type
    • status
    • paymentSystem
    • amount
    • description
    • comments
Responses
  • application/json
  • application/json
  • application/json
  • application/json
  • application/json
  • application/json
  • application/json
Request Example for get/advertiser/api/v2/payment-transactions/{paymentTransactionId}
curl 'http://dsp.ampx.io/advertiser/api/v2/payment-transactions/1?fields=timestamp%2Cdate%2Ctype' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN'

{
  "id": 1,
  "timestamp": "2024-01-01T00:00:00Z",
  "date": "2024-01-01",
  "type": "CHARGE",
  "status": "APPROVED",
  "paymentSystem": "STRIPE",
  "amount": 123.45,
  "description": "Payment for service",
  "comments": "Manual adjustment"
}

The requested payment transaction record. The response includes the requested fields. The id field is always included in the response.

Campaign Groups (Collapsed)

​

Campaign groups help you organize and manage campaigns by structuring them into a higher-level entity. They enable grouping multiple campaigns under a single insertion order, shared budgets across multi-geo or multi-language campaigns, and scheduling management.

Campaign Groups Operations

Campaigns (Collapsed)

​

Campaigns organize and manage delivery of ads to target the right audience for better results. Configure budgets, bidding strategies, targeting, frequency caps, conversion tracking, and optimization settings.

Campaigns Operations

Creative Sizes (Collapsed)

​

Creative sizes define available dimensions and specifications for ad creatives. Use these to validate creative dimensions when creating or updating native and image ads.

Creative Sizes Operations

Creatives (Collapsed)

​

Creatives define the ad assets and settings that campaigns use for ad delivery. Support multiple formats: HTML, image, native, video, and audio. Use to manage creative assets, tracking pixels, destination URLs, and approval workflows before campaigns serve them.

Creatives Operations

Content Categories (Collapsed)

​

Content categories allow you to group content into categories and topics for contextual campaign targeting. Use these to target or exclude inventory based on content type, ensuring ads appear in brand-safe environments.

Content Categories Operations

User Segments (Collapsed)

​

User segments allow you to collect audiences from specific pages and sites and target them in campaigns. Access segment metadata, pricing, usage counts, and performance data.

User Segments Operations

App Lists (Collapsed)

​

App lists manage named lists of app bundle IDs for mobile app targeting and blocking. Create lists to target specific apps or exclude competitors from your campaigns.

App Lists Operations

Device ID Lists (Collapsed)

​

Device ID lists manage named lists of mobile device identifiers (IDFA, AAID, GAID) for targeting or excluding specific devices. Use for device-level audience targeting and frequency capping strategies.

Device ID Lists Operations

Domain Lists (Collapsed)

​

Domain lists manage named lists of domains for targeting and blocking specific websites. Create lists to target premium publishers or exclude low-quality inventory from campaigns.

Domain Lists Operations

EID Lists (Collapsed)

​

EID lists manage named lists of external IDs (from CRM systems, email platforms, etc.) for identity-based audience targeting. Use to leverage first-party data and match customers across channels.

EID Lists Operations

IP Lists (Collapsed)

​

IP lists manage named lists of IP addresses for geographic or network-based targeting. Use to target specific regions or exclude traffic from particular networks or ISPs.

IP Lists Operations

Universal Lists (Collapsed)

​

Universal lists manage flexible lists of values (app bundles, domains, emails, identifiers) for multi-purpose targeting. Create universal lists to reuse the same list across different campaign types and targeting scenarios.

Universal Lists Operations

Other lists (Collapsed)

​

Other lists provide reference data and enumeration values for targeting fields. Use these endpoints to validate location, carrier, language, audience segment, device, operating system, and browser values.

Other lists Operations

List browser families

​

Returns browser families that match the query.

Use this endpoint to retrieve available browser family values for campaign browser targeting.

Query Parameters
  • fields
    Type: array string[]enum
    const:  
    name

    Specify the fields to include in the response.

    • Omit fields to include all fields available on this route.
    • Use fields to request only the fields you need.
    • Set fields to an empty value (fields=) to request no non-primary-key fields.
    • Primary key fields are always included in the response.

    Hint: pass this query parameter once, with values joined by commas.

    URL query example: ?fields=name

    values
    • name
  • filters
    Type: object

    Hint: pass each property as a separate query parameter using square brackets.

    URL query example: ?filters[name]=value

    • name
      Type: string
  • pagination

    Pagination parameters. Use one of the following methods:

    • offset and limit for offset-based pagination
    • page and size for page-based pagination

    Hint: pass each property as a separate query parameter using square brackets.

    URL query example: ?pagination[offset]=0&pagination[limit]=10

    Offset-based pagination. Use offset and/or limit.

    • limit
      Type: integer
      min:  
      1

      The maximum number of items to return.

      For example, limit=10 will return up to 10 items.

    • offset
      Type: integer
      min:  
      0

      The offset indicating how many items to skip before starting to return results.

      For example, offset=0 will return the first limit items.

Responses
  • application/json
  • application/json
  • application/json
  • application/json
  • application/json
  • application/json
Request Example for get/advertiser/api/v2/lists/browser/family 
curl 'http://dsp.ampx.io/advertiser/api/v2/lists/browser/family?fields=name&pagination[offset]=0&pagination[limit]=10' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN'

[
  {
    "id": "CHROME",
    "name": "Chrome"
  }
]

Browser families that match the query. Each record includes the requested fields. The id field is always included in each record.

List browser versions

​

Returns browser versions that match the query.

Use this endpoint to retrieve available browser version values for campaign browser targeting.

Query Parameters
  • fields
    Type: array string[]enum

    Specify the fields to include in the response.

    • Omit fields to include all fields available on this route.
    • Use fields to request only the fields you need.
    • Set fields to an empty value (fields=) to request no non-primary-key fields.
    • Primary key fields are always included in the response.

    Hint: pass this query parameter once, with values joined by commas.

    URL query example: ?fields=family,name

    values
    • family
    • name
  • filters
    Type: object

    Hint: pass each property as a separate query parameter using square brackets.

    URL query example: ?filters[family]=CHROME&filters[name]=value

    • family
      Type: string · Separated values

      Value format:

      • A , separated value: An array of: A string
    • name
      Type: string
  • pagination

    Pagination parameters. Use one of the following methods:

    • offset and limit for offset-based pagination
    • page and size for page-based pagination

    Hint: pass each property as a separate query parameter using square brackets.

    URL query example: ?pagination[offset]=0&pagination[limit]=10

    Offset-based pagination. Use offset and/or limit.

    • limit
      Type: integer
      min:  
      1

      The maximum number of items to return.

      For example, limit=10 will return up to 10 items.

    • offset
      Type: integer
      min:  
      0

      The offset indicating how many items to skip before starting to return results.

      For example, offset=0 will return the first limit items.

Responses
  • application/json
  • application/json
  • application/json
  • application/json
  • application/json
  • application/json
Request Example for get/advertiser/api/v2/lists/browser/version 
curl 'http://dsp.ampx.io/advertiser/api/v2/lists/browser/version?fields=family%2Cname&pagination[offset]=0&pagination[limit]=10' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN'

[
  {
    "id": "CHROME#122",
    "family": "CHROME",
    "name": "Chrome 122"
  }
]

Browser versions that match the query. Each record includes the requested fields. The id field is always included in each record.

List carriers

​

Returns carriers that match the query.

Query Parameters
  • fields
    Type: array string[]enum

    Specify the fields to include in the response.

    • Omit fields to include all fields available on this route.
    • Use fields to request only the fields you need.
    • Set fields to an empty value (fields=) to request no non-primary-key fields.
    • Primary key fields are always included in the response.

    Hint: pass this query parameter once, with values joined by commas.

    URL query example: ?fields=name,countries

    values
    • name
    • countries
  • pagination

    Pagination parameters. Use one of the following methods:

    • offset and limit for offset-based pagination
    • page and size for page-based pagination

    Hint: pass each property as a separate query parameter using square brackets.

    URL query example: ?pagination[offset]=0&pagination[limit]=10

    Offset-based pagination. Use offset and/or limit.

    • limit
      Type: integer
      min:  
      1

      The maximum number of items to return.

      For example, limit=10 will return up to 10 items.

    • offset
      Type: integer
      min:  
      0

      The offset indicating how many items to skip before starting to return results.

      For example, offset=0 will return the first limit items.

Responses
  • application/json
  • application/json
  • application/json
  • application/json
  • application/json
  • application/json
Request Example for get/advertiser/api/v2/lists/carrier 
curl 'http://dsp.ampx.io/advertiser/api/v2/lists/carrier?fields=name%2Ccountries&pagination[offset]=0&pagination[limit]=10' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN'

[
  {
    "id": 1,
    "name": "AT&T",
    "countries": "US"
  }
]

Carriers that match the query. Each record includes the requested fields. The id field is always included in each record.

List data provider segments

​

Returns data provider segments that match the query.

Use this endpoint to retrieve available data provider segment values for campaign dataProviderSegmentIds targeting.

Query Parameters
  • fields
    Type: array string[]enum
    const:  
    name

    Specify the fields to include in the response.

    • Omit fields to include all fields available on this route.
    • Use fields to request only the fields you need.
    • Set fields to an empty value (fields=) to request no non-primary-key fields.
    • Primary key fields are always included in the response.

    Hint: pass this query parameter once, with values joined by commas.

    URL query example: ?fields=name

    values
    • name
  • filters
    Type: object

    Hint: pass each property as a separate query parameter using square brackets.

    URL query example: ?filters[name]=value

    • name
      Type: string
  • pagination

    Pagination parameters. Use one of the following methods:

    • offset and limit for offset-based pagination
    • page and size for page-based pagination

    Hint: pass each property as a separate query parameter using square brackets.

    URL query example: ?pagination[offset]=0&pagination[limit]=10

    Offset-based pagination. Use offset and/or limit.

    • limit
      Type: integer
      min:  
      1

      The maximum number of items to return.

      For example, limit=10 will return up to 10 items.

    • offset
      Type: integer
      min:  
      0

      The offset indicating how many items to skip before starting to return results.

      For example, offset=0 will return the first limit items.

Responses
  • application/json
  • application/json
  • application/json
  • application/json
  • application/json
  • application/json
Request Example for get/advertiser/api/v2/lists/data-provider-segment 
curl 'http://dsp.ampx.io/advertiser/api/v2/lists/data-provider-segment?fields=name&pagination[offset]=0&pagination[limit]=10' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN'

[
  {
    "id": 100,
    "name": "Sports enthusiasts"
  }
]

Data provider segments that match the query. Each record includes the requested fields. The id field is always included in each record.

List device brands

​

Returns device brands that match the query.

Use this endpoint to retrieve available device brand values for campaign device brand targeting.

Query Parameters
  • fields
    Type: array string[]enum
    const:  
    name

    Specify the fields to include in the response.

    • Omit fields to include all fields available on this route.
    • Use fields to request only the fields you need.
    • Set fields to an empty value (fields=) to request no non-primary-key fields.
    • Primary key fields are always included in the response.

    Hint: pass this query parameter once, with values joined by commas.

    URL query example: ?fields=name

    values
    • name
  • filters
    Type: object

    Hint: pass each property as a separate query parameter using square brackets.

    URL query example: ?filters[name]=value

    • name
      Type: string
  • pagination

    Pagination parameters. Use one of the following methods:

    • offset and limit for offset-based pagination
    • page and size for page-based pagination

    Hint: pass each property as a separate query parameter using square brackets.

    URL query example: ?pagination[offset]=0&pagination[limit]=10

    Offset-based pagination. Use offset and/or limit.

    • limit
      Type: integer
      min:  
      1

      The maximum number of items to return.

      For example, limit=10 will return up to 10 items.

    • offset
      Type: integer
      min:  
      0

      The offset indicating how many items to skip before starting to return results.

      For example, offset=0 will return the first limit items.

Responses
  • application/json
  • application/json
  • application/json
  • application/json
  • application/json
  • application/json
Request Example for get/advertiser/api/v2/lists/device-brand/brand 
curl 'http://dsp.ampx.io/advertiser/api/v2/lists/device-brand/brand?fields=name&pagination[offset]=0&pagination[limit]=10' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN'

[
  {
    "brand": "APPLE",
    "name": "Apple"
  }
]

Device brands that match the query. Each record includes the requested fields. The brand field is always included in each record.

List device models

​

Returns device models that match the query.

Use this endpoint to retrieve available device model values for campaign device model targeting.

Query Parameters
  • fields
    Type: array string[]

    Specify the fields to include in the response.

    • Omit fields to include all fields available on this route.
    • Use fields to request only the fields you need.
    • Set fields to an empty value (fields=) to request no non-primary-key fields.
    • Primary key fields are always included in the response.

    Hint: pass this query parameter once, with values joined by commas.

    URL query example: ?fields=

  • filters
    Type: object

    Hint: pass each property as a separate query parameter using square brackets.

    URL query example: ?filters[brand]=APPLE

    • brand
      Type: string · Separated values

      Value format:

      • A , separated value: An array of: A string
  • pagination

    Pagination parameters. Use one of the following methods:

    • offset and limit for offset-based pagination
    • page and size for page-based pagination

    Hint: pass each property as a separate query parameter using square brackets.

    URL query example: ?pagination[offset]=0&pagination[limit]=10

    Offset-based pagination. Use offset and/or limit.

    • limit
      Type: integer
      min:  
      1

      The maximum number of items to return.

      For example, limit=10 will return up to 10 items.

    • offset
      Type: integer
      min:  
      0

      The offset indicating how many items to skip before starting to return results.

      For example, offset=0 will return the first limit items.

Responses
  • application/json
  • application/json
  • application/json
  • application/json
  • application/json
  • application/json
Request Example for get/advertiser/api/v2/lists/device-brand/model 
curl 'http://dsp.ampx.io/advertiser/api/v2/lists/device-brand/model?fields=&pagination[offset]=0&pagination[limit]=10' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN'

[
  {
    "brand": "APPLE",
    "model": "ipad air 4"
  }
]

Device models that match the query. Each record includes the requested fields. The brand, model fields are always included in each record.

List IAB Categories

​

Returns IAB Categories that match the query.

Use this endpoint to retrieve available IAB category codes for campaign and ad unit category fields.

Query Parameters
  • fields
    Type: array string[]enum

    Specify the fields to include in the response.

    • Omit fields to include all fields available on this route.
    • Use fields to request only the fields you need.
    • Set fields to an empty value (fields=) to request no non-primary-key fields.
    • Primary key fields are always included in the response.

    Hint: pass this query parameter once, with values joined by commas.

    URL query example: ?fields=parentId,code,name

    values
    • parentId
    • code
    • name
  • filters
    Type: object

    Hint: pass each property as a separate query parameter using square brackets.

    URL query example: ?filters[id]=1,2&filters[parentId]=1,2&filters[code]=value,another-value

    • code
      Type: string · Separated values

      Value format:

      • A , separated value: An array of: A string
    • id
      Type: string · Separated values

      Value format:

      • A , separated value: An array of: An integer
    • parentId
      Type: string · Separated values

      Value format:

      • A , separated value: An array of: An integer
  • pagination

    Pagination parameters. Use one of the following methods:

    • offset and limit for offset-based pagination
    • page and size for page-based pagination

    Hint: pass each property as a separate query parameter using square brackets.

    URL query example: ?pagination[offset]=0&pagination[limit]=10

    Offset-based pagination. Use offset and/or limit.

    • limit
      Type: integer
      min:  
      1

      The maximum number of items to return.

      For example, limit=10 will return up to 10 items.

    • offset
      Type: integer
      min:  
      0

      The offset indicating how many items to skip before starting to return results.

      For example, offset=0 will return the first limit items.

Responses
  • application/json
  • application/json
  • application/json
  • application/json
  • application/json
  • application/json
Request Example for get/advertiser/api/v2/lists/iab-categories 
curl 'http://dsp.ampx.io/advertiser/api/v2/lists/iab-categories?fields=parentId%2Ccode%2Cname&pagination[offset]=0&pagination[limit]=10' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN'

[
  {
    "id": 1,
    "parentId": 1,
    "code": "IAB1",
    "name": "Arts & Entertainment"
  }
]

IAB Categories that match the query. Each record includes the requested fields. The id field is always included in each record.