Business Management APIs

Fonctions d’entreprise à entreprise

Depuis le 8 juin 2021, l’accès à ces points de terminaison est limité. Les applications dépourvues d’accès recevront une erreur.

Demander l’accès à des éléments

Il peut arriver qu’un Business Manager demande l’accès à un compte publicitaire ou à une Page appartenant à un autre Business Manager. Dans ce cas, il doit préciser dans la requête les tâches qu’il souhaite attribuer.

L’affectation d’une entreprise à une Page nécessite un token d’accès de Page, par exemple :

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

Pour demander l’accès AGENCY, vous devez indiquer les permitted_tasks dans votre requête. Vous pouvez envoyer des demandes d’accès uniquement aux Business Manager que vous avez l’intention d’approuver et qui connaissent déjà votre entreprise.

Par exemple, une entreprise qui souhaite accéder à adaccount_id et pouvoir attribuer à ses employé·es les tâches ['ADVERTISE', 'ANALYZE'] doit envoyer cette requête POST :

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

De même pour une Page, la requête suivante vous permet d’attribuer à une personne les tâches ['ADVERTISE', 'ANALYZE'] pour une Page qui ne lui appartient pas :

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

Ces appels envoient aux admins du compte publicitaire ou de la Page une notification qui les invite à accepter la demande d’accès. Les admins concerné·es verront la notification respectivement dans le Gestionnaire de publicités ou dans le Gestionnaire de Pages. Ils ou elles peuvent aussi accepter la demande dans l’interface utilisateur·ice. Pour obtenir la liste des demandes en attente via l’API, envoyez une requête GET portant sur l’attribut PENDING dans le champ access_status.

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

Réponse :

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

Accorder l’accès à des éléments pour un autre Business Manager

On parle également d’ajouter une Agence à votre objet.

Pour accepter une demande d’accès à un objet vous appartenant depuis un autre Business Manager ou pour accorder à un autre Business Manager l’accès à un objet vous appartenant, vous devez indiquer l’entreprise et la liste des tâches auxquelles elle doit avoir accès.

Si le token d’accès utilisé pour effectuer l’appel d’API appartient à un·e utilisateur·ice ou à un·e utilisateur·ice système ayant accès à l’élément demandé via une entreprise, l’accès à l’élément ne peut être accordé que si cette entreprise est OWNER de l’élément. Vous ne pouvez pas accorder l’accès aux éléments dont vous êtes simplement une AGENCY.

Par exemple, pour accorder à une personne l’accès à un compte publicitaire avec les tâches [ADVERTISE,ANALYZE], utilisez cette requête POST :

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

Pour accorder à une entreprise l’accès à votre Page avec les tâches [ADVERTISE], [MODERATE] et [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>"

Par mesure de sécurité, les autorisations d’accès à un compte publicitaire peuvent parfois être soumises à l’examen d’un·e autre admin de l’entreprise. L’approbation de ces autorisations s’effectue sur la page https://business.facebook.com/settings/requests/admin_reviews. Dans ce cas, la réponse comprend un champ supplémentaire indiquant qu’un examen est nécessaire.

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

Les admins d’une Page peuvent aussi accepter les demandes d’accès d’une agence dans les onglets Manage Admin Roles des paramètres de Page sur facebook.com.

Supprimer l’accès à des éléments

On parle également de supprimer une agence de votre entreprise. Pour supprimer l’accès d’un Business Manager à votre compte publicitaire :

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

De même, pour supprimer l’accès d’une entreprise à votre Page :

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

Lister les accès d’agence

Pour lister les entreprises qui ont accès à votre compte publicitaire, envoyez une requête GET :

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

Pour lister les entreprises qui ont accès à votre Page :

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

Pour lister les entreprises qui ont accès à vos éléments professionnels :

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

Lister vos accès client·es

Pour lister les entreprises qui vous ont donné accès à un·e ou plusieurs de leurs comptes publicitaires ou Pages, utilisez cette requête GET :

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

En savoir plus