Get the Apple Ads connection status

curl --request GET \
  --url https://api.qonversion.io/v4/integrations/apple-ads/connection \
  --header 'Authorization: Bearer <token>'

import requests

url = "https://api.qonversion.io/v4/integrations/apple-ads/connection"

headers = {"Authorization": "Bearer <token>"}

response = requests.get(url, headers=headers)

print(response.text)

const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

fetch('https://api.qonversion.io/v4/integrations/apple-ads/connection', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.qonversion.io/v4/integrations/apple-ads/connection",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

require 'uri'
require 'net/http'

url = URI("https://api.qonversion.io/v4/integrations/apple-ads/connection")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'

response = http.request(request)
puts response.read_body

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.qonversion.io/v4/integrations/apple-ads/connection"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

{
  "object": "apple_ads_connection",
  "url": "/v4/integrations/apple-ads/connection",
  "state": "not_connected",
  "reporting": {
    "state": "ready",
    "reason_code": "legacy_credentials",
    "can_write": true,
    "checked_at": "2023-11-07T05:31:56Z",
    "is_stale": true
  },
  "campaign_management": {
    "state": "ready",
    "reason_code": "legacy_credentials",
    "can_write": true,
    "checked_at": "2023-11-07T05:31:56Z",
    "is_stale": true
  },
  "orgs": [
    {
      "org_id": "<string>",
      "can_write": true,
      "role_names": [
        "<string>"
      ],
      "org_name": "<string>",
      "currency": "<string>"
    }
  ],
  "dashboard_url": "<string>",
  "connection_method": "customer_key",
  "granted_at": "2023-11-07T05:31:56Z",
  "last_verified_at": "2023-11-07T05:31:56Z",
  "next_action": "connect_apple_ads"
}

{
  "error": {
    "type": "request",
    "code": "<string>",
    "message": "<string>",
    "details": [
      {
        "field": "<string>",
        "message": "<string>",
        "reason": "unsupported_parameter"
      }
    ]
  }
}

{
  "error": {
    "type": "request",
    "code": "<string>",
    "message": "<string>",
    "details": [
      {
        "field": "<string>",
        "message": "<string>",
        "reason": "unsupported_parameter"
      }
    ]
  }
}

{
  "error": {
    "type": "request",
    "code": "<string>",
    "message": "<string>",
    "details": [
      {
        "field": "<string>",
        "message": "<string>",
        "reason": "unsupported_parameter"
      }
    ]
  }
}

{
  "error": {
    "type": "request",
    "code": "<string>",
    "message": "<string>",
    "details": [
      {
        "field": "<string>",
        "message": "<string>",
        "reason": "unsupported_parameter"
      }
    ]
  }
}

{
  "error": {
    "type": "request",
    "code": "<string>",
    "message": "<string>",
    "details": [
      {
        "field": "<string>",
        "message": "<string>",
        "reason": "unsupported_parameter"
      }
    ]
  }
}

{
  "error": {
    "type": "request",
    "code": "<string>",
    "message": "<string>",
    "details": [
      {
        "field": "<string>",
        "message": "<string>",
        "reason": "unsupported_parameter"
      }
    ]
  }
}

{
  "error": {
    "type": "request",
    "code": "<string>",
    "message": "<string>",
    "details": [
      {
        "field": "<string>",
        "message": "<string>",
        "reason": "unsupported_parameter"
      }
    ]
  }
}

Apple Ads

Get the Apple Ads connection status

Whether this project’s Apple Ads connection is authorized, whether reporting is available, and the next step (next_action). Status only: this endpoint never returns a private key, client secret, access or refresh token, authorization code, or OAuth state, and it does not start or complete authorization — use dashboard_url to connect or reconnect in the dashboard.

Reporting. reporting.state is ready when performance data can flow, verifying while Apple confirms access, and not_ready otherwise.

legacy_credentials is a working connection with an API key; migrating to Apple authorization is recommended.

verifying means the connection is awaiting confirmation from Apple.

Availability: the Apple Ads report is enabled on all accounts except a few that keep the legacy page; an account that gets 404 here does not have it — contact support.

GET

integrations

apple-ads

connection

Get the Apple Ads connection status

curl --request GET \
  --url https://api.qonversion.io/v4/integrations/apple-ads/connection \
  --header 'Authorization: Bearer <token>'

import requests

url = "https://api.qonversion.io/v4/integrations/apple-ads/connection"

headers = {"Authorization": "Bearer <token>"}

response = requests.get(url, headers=headers)

print(response.text)

const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

fetch('https://api.qonversion.io/v4/integrations/apple-ads/connection', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.qonversion.io/v4/integrations/apple-ads/connection",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

require 'uri'
require 'net/http'

url = URI("https://api.qonversion.io/v4/integrations/apple-ads/connection")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'

response = http.request(request)
puts response.read_body

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.qonversion.io/v4/integrations/apple-ads/connection"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

{
  "object": "apple_ads_connection",
  "url": "/v4/integrations/apple-ads/connection",
  "state": "not_connected",
  "reporting": {
    "state": "ready",
    "reason_code": "legacy_credentials",
    "can_write": true,
    "checked_at": "2023-11-07T05:31:56Z",
    "is_stale": true
  },
  "campaign_management": {
    "state": "ready",
    "reason_code": "legacy_credentials",
    "can_write": true,
    "checked_at": "2023-11-07T05:31:56Z",
    "is_stale": true
  },
  "orgs": [
    {
      "org_id": "<string>",
      "can_write": true,
      "role_names": [
        "<string>"
      ],
      "org_name": "<string>",
      "currency": "<string>"
    }
  ],
  "dashboard_url": "<string>",
  "connection_method": "customer_key",
  "granted_at": "2023-11-07T05:31:56Z",
  "last_verified_at": "2023-11-07T05:31:56Z",
  "next_action": "connect_apple_ads"
}

{
  "error": {
    "type": "request",
    "code": "<string>",
    "message": "<string>",
    "details": [
      {
        "field": "<string>",
        "message": "<string>",
        "reason": "unsupported_parameter"
      }
    ]
  }
}

{
  "error": {
    "type": "request",
    "code": "<string>",
    "message": "<string>",
    "details": [
      {
        "field": "<string>",
        "message": "<string>",
        "reason": "unsupported_parameter"
      }
    ]
  }
}

{
  "error": {
    "type": "request",
    "code": "<string>",
    "message": "<string>",
    "details": [
      {
        "field": "<string>",
        "message": "<string>",
        "reason": "unsupported_parameter"
      }
    ]
  }
}

{
  "error": {
    "type": "request",
    "code": "<string>",
    "message": "<string>",
    "details": [
      {
        "field": "<string>",
        "message": "<string>",
        "reason": "unsupported_parameter"
      }
    ]
  }
}

{
  "error": {
    "type": "request",
    "code": "<string>",
    "message": "<string>",
    "details": [
      {
        "field": "<string>",
        "message": "<string>",
        "reason": "unsupported_parameter"
      }
    ]
  }
}

{
  "error": {
    "type": "request",
    "code": "<string>",
    "message": "<string>",
    "details": [
      {
        "field": "<string>",
        "message": "<string>",
        "reason": "unsupported_parameter"
      }
    ]
  }
}

{
  "error": {
    "type": "request",
    "code": "<string>",
    "message": "<string>",
    "details": [
      {
        "field": "<string>",
        "message": "<string>",
        "reason": "unsupported_parameter"
      }
    ]
  }
}

Authorizations

Authorization

string

header

required

Bearer authentication using the project Secret Key (prefixed with sk_), used exactly as shown in the dashboard. Endpoints that support sandbox data take an explicit environment field or parameter. All v4 public endpoints require the Secret Key — see Authentication. Never expose the Secret Key in client-side code.

Response

Connection status.

object

string

required

Example:

"apple_ads_connection"

url

string

required

Example:

"/v4/integrations/apple-ads/connection"

state

enum<string>

required

State of the Apple Ads authorization: not_connected; legacy_credentials — a working connection with an API key; verifying — awaiting confirmation from Apple; connected; needs_reauthorization — reconnect Apple Ads in the dashboard. This field does not indicate campaign-management access; see campaign_management.

Available options:

not_connected,

legacy_credentials,

verifying,

connected,

needs_reauthorization

reporting

object

required

Readiness of one capability of the integration.

Show child attributes

campaign_management

object

required

Readiness of one capability of the integration.

Show child attributes

orgs

object[]

required

Apple Ads organizations the connection can access. An empty list while campaign-management permissions are not confirmed yet (campaign_management.state is unknown) does not mean the account has no organizations.

Show child attributes

dashboard_url

string

required

Dashboard page where a user connects, reconnects, or migrates the Apple Ads connection. Always present.

connection_method

enum<string> | null

How the authorization is held. null when there is none.

Available options:

customer_key,

service_provider_oauth,

null

granted_at

string<date-time> | null

When the authorization was granted (RFC 3339, UTC).

last_verified_at

string<date-time> | null

When Apple last confirmed it (RFC 3339, UTC).

next_action

enum<string> | null

The next step, or null when nothing is pending. grant_campaign_role_in_apple_ads is done in Apple Ads, not in Qonversion, and is not used on accounts with the Apple Ads report only. wait_for_app_scope — report data for the project is not available yet (app_scope_not_ready); reconnecting does not help.

Available options:

connect_apple_ads,

reconnect_apple_ads,

wait_for_verification,

migrate_to_apple_authorization,

grant_campaign_role_in_apple_ads,

wait_for_app_scope,

null

Start here

Resource guides

REST API v4

Analytics API

Legacy: API v3

Get the Apple Ads connection status

Authorizations

Response