List the ad accounts a token can read

Checks an access token with Meta and lists the ad accounts it can read, suggested ones first, marking those this project already connected.

The token is used for these reads only and not stored; connect accounts with POST /ads/accounts. A token without ads_read lists no accounts. Safe to repeat. Needs project:ads:manage.

Guide: Connect Meta Ads

Errors

Status	`type`	`code`	When
400	`invalid_request`	`ad_account_rejected`	When Meta rejects the token, with `param` set to `accessToken`.

It can also fail with the errors every operation shares, such as unauthenticated; see Errors.

More in Ad accounts

Something wrong or missing on this page? Tell us by email or on Discord.

Path parameters

projectId*string

The project's id, proj_.... A secret key works only in the project it belongs to.

Request body

application/json

TypeScript definitions

Use the request body type in TypeScript.

platform*

The ad platform: meta (Facebook and Instagram ads), the only one today.

accessToken*string

A system user access token to check; it needs ads_read on the accounts to list them. Used for this request only and not stored.

Length1 <= length <= 4096

Examples

curl -X POST "https://api.voidhash.com/api/v1/projects/proj_tz4a98xxat96iws9zmbrgj3a/ads/accounts/available" \  -H "Authorization: Bearer vh_sk_..." \  -H "Content-Type: application/json" \  -d '{    "platform": "meta",    "accessToken": "EAAB..."  }'

{  "token": {    "maskedToken": "EAAB…x9Zq",    "hasRequiredPermission": true,    "permissions": [      "ads_read"    ],    "businessName": "Acme"  },  "accounts": [    {      "externalId": "1234567890",      "name": "Acme Fitness",      "currency": "USD",      "timezone": "Europe/Prague",      "status": "has_spend",      "inactiveReason": null,      "amountSpent": 1284500,      "isSuggested": true,      "isConnected": false    },    {      "externalId": "1234567891",      "name": "Acme Fitness - tests",      "currency": "USD",      "timezone": "Europe/Prague",      "status": "no_spend",      "inactiveReason": null,      "amountSpent": 0,      "isSuggested": false,      "isConnected": false    }  ]}

{  "error": {    "type": "invalid_request",    "code": "ad_account_rejected",    "message": "The access token does not grant ads_read. Generate the system user token with the ads_read permission."  }}

{  "error": {    "type": "unauthenticated",    "code": "invalid_api_key",    "message": "This secret key is not valid."  }}

{  "error": {    "type": "permission_denied",    "code": "permission_denied",    "message": "Insufficient permissions."  }}

{  "error": {    "type": "not_found",    "code": "project_not_found",    "message": "There is no project proj_tz4a98xxat96iws9zmbrgj3a, or this credential cannot use it.",    "param": "projectId"  }}

{  "error": {    "type": "internal",    "code": "internal_error",    "message": "Something went wrong on our side. Try again, and contact support with the Request-Id header if it keeps failing."  }}

List the ad accounts a token can read

Errors

More in Ad accounts

List the ad accounts a token can read

Errors

More in Ad accounts

Authorization

Path parameters

Request body

Examples

Response body

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

List the ad accounts a token can read

List the ad accounts a token can read

200application/json

400application/json

401application/json

403application/json

404application/json

500application/json

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`