Business Management APIs

Business-to-Business-Funktionen

Seit dem 8. Juni 2021 ist der Zugriff auf diese Endpunkte eingeschränkt. Apps ohne Zugriff erhalten einen Fehler.

Zugriff auf Assets anfragen

Der Business Manager kann Zugriff auf Werbekonten oder Seiten anfragen, die einem anderen Business Manager gehören. Er muss die Aufgaben, die zugewiesen werden sollen, in der Anfrage angeben.

Für die Zuweisung eines Unternehmens zu einer Seite ist ein Seitenschlüssel erforderlich: Beispiel:

curl 
  -F "business=<BUSINESS_ID>"
  -F "permitted_tasks=['MODERATE', 'ADVERTISE', 'ANALYZE']"   
  "https://graph.facebook.com/<API_VERSION>/<PAGE_ID>/agencies?access_token=<ACCESS_TOKEN>"

Um AGENCY-Zugriff anzufragen, musst du permitted_tasks in deiner Anfrage angeben. Du kannst nur Asset-Anfragen an den Business Manager senden, die du vorhast zu genehmigen. Außerdem muss der Business Manager dein Unternehmen bereits kennen.

Ein Unternehmen, das Zugriff auf adaccount_id benötigt und seine Mitarbeiter*innen als ['ADVERTISE', 'ANALYZE'] zuweisen möchte, würde beispielsweise diesen POST-Aufruf tätigen:

curl \
  -F "adaccount_id=act_<AD_ACCOUNT_ID>" \
  -F "permitted_tasks=['ADVERTISE','ANALYZE']" \
  "https://graph.facebook.com/<API_VERSION>/<BUSINESS_ID>/client_ad_accounts?access_token=<ACCESS_TOKEN>"

Entsprechend kannst du diesen Aufruf verwenden, wenn du ['ADVERTISE', 'ANALYZE']-Aufgaben für eine Seite zuweisen möchtest, die nicht im Besitz einer Person ist:

curl \
  -F "page_id=<PAGE_ID>" \
  -F "permitted_tasks=['ADVERTISE','ANALYZE']" \
  "https://graph.facebook.com/<API_VERSION>/<BUSINESS_ID>/client_pages?access_token=<ACCESS_TOKEN>"

Diese Aufrufe senden eine Benachrichtigung an die jeweiligen Administrator*innen des Werbekontos oder der Seite, in der diese aufgefordert werden, der Zugriffsanfrage zuzustimmen. Die jeweiligen Administrator*innen sehen die Benachrichtigung im Werbeanzeigenmanager oder Seitenmanager. Sie können der Anfrage auch in der Benutzeroberfläche zustimmen. Wenn du ausstehende Anfragen über die API einsehen möchtest, tätige eine GET-Anfrage und suche nach PENDING im Feld access_status.

curl "https://graph.facebook.com/<API_VERSION>/<BUSINESS_ID>/clients?access_token=<ACCESS_TOKEN>"

Die Antwort:

"data": [
 {
    "name": "Random Page", 
    "page_permissions": [
    {
    "id": "1900952844321", 
    "permitted_tasks": [
        'MANAGE',
        'CREATE_CONTENT', 
        'MODERATE',  
        'ADVERTISE', 
        'ANALYZE',
    ], 
    "access_status": "CLIENT_RESPONSE_PENDING", 
    "access_requested_time": "2014-01-07T23:26:09+0000", 
    "access_updated_time": "2014-01-07T23:26:09+0000"
    }
    ], 
    "id": "190137931178903"
 },

Einem anderen Business Manager Zugriff auf Assets gewähren

Das ist gleichzusetzen mit dem Hinzufügen einer Agentur zu deinem Objekt.

Um einer Zugriffsanfrage eines anderen Business Manager für ein Objekt zuzustimmen, das dir gehört, oder um einem anderen Business Manager Zugriff auf eines der Objekte zu gewähren, die dir gehören, musst du das Unternehmen und die Liste der Aufgaben angeben, auf die er Zugriff haben soll.

Wenn der Zugriffsschlüssel, der im API-Aufruf verwendet wird, zu einem Nutzer oder Systemnutzer gehört, der über ein Unternehmen Zugriff auf das angefragte Asset hat, kann der Zugriff auf das Asset nur gewährt werden, wenn dieses Unternehmen der OWNER des Assets ist. Für Assets, für die du nur eine AGENCY bist, kannst du keinen Zugriff gewähren.

Um beispielsweise einer Person Zugriff auf ein Werbekonto mit den Aufgaben [ADVERTISE,ANALYZE] zu gewähren, verwende diese POST-Anfrage:

curl \
  -F "business=<BUSINESS_ID>" \
  -F "permitted_tasks=['ADVERTISE', 'ANALYZE']" \
  "https://graph.facebook.com/<API_VERSION>/act_<AD_ACCOUNT_ID>/agencies?access_token=<ACCESS_TOKEN>"

So erteilst du einem Unternehmen Zugriff auf deine Seite mit [ADVERTISE], [MODERATE] und [ANALYZE]:

curl \
  -F "business=<BUSINESS_ID>" \
  -F "permitted_tasks=['MODERATE', 'ADVERTISE', 'ANALYZE']" \
  "https://graph.facebook.com/<API_VERSION>/<PAGE_ID>/agencies?access_token=<ACCESS_TOKEN>"

Wenn Zugriff auf ein Werbekonto gewährt wird, ist als Sicherheitsmaßnahme manchmal eine Überprüfung durch einen anderen Business-Admin erforderlich. Diese Überprüfung kann genehmigt werden, indem du zu https://business.facebook.com/settings/requests/admin_reviews navigierst. In diesem Fall enthält die Antwort ein zusätzliches Feld mit der Angabe, dass eine Überprüfung erforderlich ist.

{
  "success": true,
  "requires_admin_approval": true
}

Seitenadministrator*innen können den Zugriffsanfragen einer Agentur auch in den Tabs für Manage Admin Roles in den Seiteneinstellungen auf facebook.com zustimmen.

Zugriff auf Assets entfernen

Das ist gleichzusetzen mit dem Entfernen einer Agentur von deinem Unternehmen. So entfernst du den Zugriff eines Business Manager von deinem Werbekonto:

curl \
  -X DELETE \
  -F "business=<BUSINESS_ID>" \
  "https://graph.facebook.com/<API_VERSION>/act_<AD_ACCOUNT_ID>/agencies?access_token=<ACCESS_TOKEN>"

Entsprechend entfernst du den Zugriff eines Unternehmens auf deine Seite wie folgt:

curl \
  -X DELETE \
  -F "business=<BUSINESS_ID>" \
  "https://graph.facebook.com/<API_VERSION>/<PAGE_ID>/agencies?access_token=<ACCESS_TOKEN>"

Agenturzugriff anzeigen

So zeigst du alle Unternehmen, die Zugriff auf dein Werbekonto haben, mit einem GET-Aufruf an:

curl "https://graph.facebook.com/<API_VERSION>/act_<AD_ACCOUNT_ID>/agencies?access_token=<ACCESS_TOKEN>"

So zeigst du alle Unternehmen mit Zugriff auf deine Seite an:

curl "https://graph.facebook.com/<API_VERSION>/<PAGE_ID>/agencies?access_token=<ACCESS_TOKEN>"

So zeigst du alle Unternehmen mit Zugriff auf deine Business-Assets an:

curl "https://graph.facebook.com/<API_VERSION>/<BUSINESS_ID>/agencies?access_token=<ACCESS_TOKEN>"

Kundenzugriff anzeigen

Verwende diesen GET-Aufruf, um alle Unternehmen anzuzeigen, die dir Zugriff auf mindestens eines ihrer Werbekonten oder mindestens eine ihrer Seiten erteilt haben:

curl "https://graph.facebook.com/<API_VERSION>/<BUSINESS_ID>/clients?access_token=<ACCESS_TOKEN>"

Managing Your Relationship as an Ad Agency Acting on Behalf of Another Business

These APIs allow you to manage the relationship between your Ad Accounts and the businesses for which you are acting on behalf of (OBO). Creating these relationships allows you to access custom audiences for the business and use of the audience overlap tool.

View OBO Request Details

To view the details of an OBO request, make this GET request:

curl -G \
  -F "access_token=<ACCESS_TOKEN>" \
  "https://graph.facebook.com/<API_VERSION>/<OBO_REQUEST_ID>?fields=id,receiving_business,requesting_business,status,business_owned_object"

The response contains the details of the OBO request and looks like this:

{
  "id": "1111111111",
  "receiving_business": {
    "id": "2222222222",
    "name": "Example Business Name"
  },
  "requesting_business": {
    "id": "3333333333",
    "name": "Example Business Name"
  },
  "status": "IN_PROGRESS",
  "business_owned_object": "1111111111"
}

Delete OBO Request

To cancel a pending request to act OBO another business, make this DELETE request:

curl \
  -X DELETE \
  -F "access_token=<ACCESS_TOKEN>" \
  "https://graph.facebook.com/<API_VERSION>/<OBO_REQUEST_ID>"

The response, indicating success or failure, looks like this:

{
  "success": "true" 
}

View the Status of OBO Requests for an Ad Account

To view the status of requests to act OBO another business for an Ad account, make this GET request:

curl -G \
  -F "access_token=<ACCESS_TOKEN>" \
  "https://graph.facebook.com/<API_VERSION>/act_<AD_ACCOUNT_ID>/onbehalf_requests?
    fields=id,status,receiving_business,requesting_business&status=<STATUS>"

The status parameter in the request must be APPROVE, DECLINE, or IN_PROGRESS.

The response contains an array with the OBO request objects for an Ad account matching the requested status.

Example response:

{
  "data": [
    {
      "id": "1111111111",
      "status": "IN_PROGRESS",
      "receiving_business": {
        "id": "2222222222",
        "name": "Example Business Name"
      },
      "requesting_business": {
        "id": "3333333333",
        "name": "Example Business Name"
      }
    }
  ]
}

View OBO Requests Received From Other Businesses

To view requests of IN_PROGRESS OBO requests sent to your business, make this GET request:

curl -G \
  -F "access_token=<ACCESS_TOKEN>" \
  "https://graph.facebook.com/<API_VERSION>/<BUSINESS_ID>/received_inprogress_onbehalf_requests"

The response contains the IN_PROGRESS OBO request IDs and looks like this:

{
  "data": [
    {
      "id": "1111111111"
    },
    {
      "id": "2222222222"
    },
    {
      "id": "3333333333"
    }
  ]
}

View Pending OBO Requests Sent by Your Business

To view OBO requests that were sent by your business that are still in the IN_PROGRESS state, make this GET request:

curl -G \
  -F "access_token=<ACCESS_TOKEN>" \
  "https://graph.facebook.com/<API_VERSION>/<BUSINESS_ID>/sent_inprogress_onbehalf_requests"

The response contains the IN_PROGRESS OBO request IDs and looks like this:

{
  "data": [
    {
      "id": "1111111111"
    },
    {
      "id": "2222222222"
    },
    {
      "id": "3333333333"
    }
  ]
}

Mehr dazu