Check App Eligibility

Check whether an app is eligible to run on certain Apple Ads placements and in specific countries or regions.

URL

POST https://api.ads.apple.com/v1/eligibilities/apps/query

Header Parameters

Name	Type	Description
`X-Ap-Context` Required	string

Response Codes

Status	Reason	Type
200	OK Content-Type: application/json	`EligibilityQueryResponse`
400	Bad Request Content-Type: application/json	`Error`
401	Unauthorized Content-Type: application/json	`Error`
403	Forbidden Content-Type: application/json	`Error`
404	Not Found Content-Type: application/json	`Error`
429	Too Many Requests Content-Type: application/json	`Error`
500	Internal Server Error Content-Type: application/json	`Error`

Discussion

This endpoint checks whether an app is eligible to run Apple Ads campaigns in specified countries or regions. The response contains per-app eligibility status, along with the specific supply placements and markets where advertising is allowed or blocked.

To confirm that your app can be promoted in the target markets, use this endpoint before creating campaigns. Attempting to run campaigns in ineligible markets will result in zero delivery. Calling this endpoint early in the campaign setup workflow avoids wasted configuration.

Ineligibility reasons can include: the app is not available in that market, regional distribution restrictions set in App Store Connect, or Apple Ads policy violations.

See QueryFilterOperator for the full set of supported comparison operators.

Filterable Fields

Field	Type	Operators	Sortable	Description
`adamId`	integer (int64)	`EQUALS`	No	The Adam ID of the app
`supplyPlacement`	string	`EQUALS`, `IN`	Yes	The supply placement being checked
`state`	string	`EQUALS`, `IN`	Yes	Eligibility state: `ELIGIBLE` or `INELIGIBLE`
`countryOrRegion`	string	`EQUALS`, `IN`	Yes	The country or region evaluated
`deviceClass`	string	`EQUALS`, `IN`	Yes	The device class evaluated

See EligibilityQueryRequest for the full field list. The request body is a QueryRequest-shaped object composed of QueryFilter conditions and QuerySort directives (QuerySortOrder), controlled by QueryPagination.

Request Body

The state field resolves to one of the following values:

Status	Description
`ELIGIBLE`	The app is approved to run ads in the specified country or region.
`INELIGIBLE`	The app cannot run ads in the specified country or region.

Response Structure

Each item in result is a flat EligibilityResponse row for a specific combination of app, supply placement, supply source, country, and device class.

Field	Type	Description
`adamId`	integer (int64)	The Adam ID of the app
`supplyPlacement`	string	The supply placement being checked
`supplySource`	string	The supply source being checked
`minAge`	number	The minimum age rating required to serve ads for this app in this market
`state`	string	Eligibility state: `ELIGIBLE` or `INELIGIBLE` (default `ELIGIBLE`)
`countryOrRegion`	string	The country or region evaluated
`deviceClass`	string	The device class evaluated
`creationTime`	string (ISO 8601)	When this eligibility record was created
`modificationTime`	string (ISO 8601)	When this eligibility record was last modified

An app that is eligible in some placements and ineligible in others appears as multiple rows, one per combination.

Keep the following constraints in mind when checking eligibility:

Constraint	Detail
Pre-campaign check	Always call this endpoint before creating campaigns in new markets.
Distribution restrictions	Ineligibility may reflect App Store Connect distribution settings, not just policy violations.

Payload Examples

HTTP Body

See EligibilityQueryRequest.