End-to-end Examples

In the following example, you'll go through the complete proces of verifying the correectness of an API token, creating an advertiser profile, and finally setting up a basic Campaign with a single Ad Gruop and Ad. For the full API reference, please see the sections below.

Basic Usage

Once you have your API token, you can test it out quickly by using the /me endpoint, which returns basic information about the currently authenticated user:

curl 'https://ads.nextdoor.com/v2/api/me' --header 'Authorization: Bearer token123'

Example response:

{
    "user": {
      "id": "01234",
      "name": "Me",
      "email": "[email protected]",
      "email_confirmed": true,
      "advertisers_with_access": [
        {
          "advertiser_id": "404",
          "role": "CLIENT_ADMIN"
        }
      ]
    },
    "profile": {
      "id": "32532",
      "name": "my profile",
      "associated_user_ids": ["01234"],
      "payment_profile_id": null,
      "is_ad_agency": false
    }
}

Create and Get an Advertiser

Once you've verified your API token works, you can create an advertiser, and verify that the new advertiser can be queried for via its id.

To create an advertiser, use the /advertiser/create endpoint:

curl 'https://ads.nextdoor.com/v2/api/advertiser/create' \
--header 'Authorization: Bearer token123' \
--header 'Content-Type: application/json' \
--data '{
    "name": "my advertiser",
    "website_url": "https://example.com",
    "category_id": "121"
}'

Example response:

{
    "id": "12",
    "name": "my advertiser",
    "website_url": "https://example.com",
    "category_id": "121",
    "address": null,
    "billing_limit": "USD 10",
    "payment_profile_id": null,
    "bill_to_paymnet_profile_id": null,
    "account_balance": "USD 0"
}

You can also directly query for an advertiser via the /advertiser/get/[id] endpoint:

curl 'https://ads.nextdoor.com/v2/api/advetiser/get/12' --header 'Authorization: Bearer mytoken123'

Example response:

{
    "id": "12",
    "name": "my advertiser",
    "website_url": "example.com",
    "category_id": "121",
    "address": null,
    "billing_limit": "USD 10",
    "payment_profile_id": null,
    "bill_to_paymnet_profile_id": null,
    "account_balance": "USD 0"
}

Create and Get a Campaign

Now that there's an advertiser, you can create a new campaign using the /campaign/create endpoint:

curl 'https://ads.nextdoor.com/v2/api/campaign/create' \
--header 'Authorization: Bearer token123' \
--header 'Content-Type: application/json' \
--data '{
    "advertiser_id": "12",
    "name": "my campaign",
    "objective": "AWARENESS"
}

Example response:

{
    "id": "123",
    "name": "my campaign",
    "objective": "AWARENESS"
}

Similar to advertisers, you can directly query campaigns via the /campaign/get/[id] endpoint:

curl 'https://ads.nextdoor.com/v2/api/campaign/get/123' --header 'Authorization: Bearer mytoken123'

Example response:

{
    "id": "123",
    "name": "my campaign",
    "objective": "AWARENESS"
}

Get Targeting Options

In order to create a new AdGroup for your campaign, you may want to find out what targeting options are supported. For example, to list the different device targeting options, use the /targeting/device/list endpoint:

curl 'https://ads.nextdoor.com/v2/api/targeting/device/list' --header 'Authorization: Bearer'

Example response:

{
    [
        {
            "id": "1",
            "value": "Android"
        },
        {
            "id": "2",
            "value": "iOS"
        }                
    ]
}

Create an AdGroup

Now that you have the targeting values, you can use those to create your own AdGroup for your campaign created earlier. For example let's say you want to create an AdGroup that targets "Android" users only, with a budget of $1,000 and a bid of $10 across all placements options. To do this, use the adgroup/create endpoint:

curl 'https://ads.nextdoor.com/v2/api/adgroup/create' \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '{
    "advertiser_id": "12",
    "campaign_id": "123",
    "name": "my api adgroup",
    "placements": ["FEED", "FSF", "RHR"],
    "bid": {
        "amount": "USD 10",
        "pricing_type": "CPM"
    },
    "budget": {
        "amount": "USD 1000",
        "budget_type": "DAILY_CAP_MONEY"
    },
    "start_time": "2023-08-03T10:15:30-07:00[America/Los_Angeles]",
    "end_time": null,
    "targeting": {
        "audience_targeting_features": ["1"],
    },  
}'

Example response:

{
    "id": "231",
    "advertiser_id": "12",
    "campaign_id": "123",
    "name": "my api adgroup",
    "status": "NO_ACTIVE_ADS",
    "user_status": "ACTIVE",
    "placements": ["FEED", "FSF", "RHR"],
    "bid": {
        "amount": "USD 10",
        "pricing_type": "CPM"
    },
    "budget": {
        "amount": "USD 1000",
        "budget_type": "DAILY_CAP_MONEY"
    },
    "start_time": "2023-08-03T10:15:30-07:00[America/Los_Angeles]",
    "end_time": null,
    "frequency_caps": [],
    "targeting": {
        "included_location_targeting_features": [],
        "excluded_location_targeting_features": [],
        "audience_targeting_features": ["1"],
        "time_of_day": {
            "included": [],
            "excluded": []
        }
    },  
    "custom_audience_ids": [],
    "created_at": "2023-08-03T17:15:30Z",
    "updated_at": "2023-08-03T17:15:30Z"
}

Creating an Ad

At this point you have an Advertiser with its own Campaign; the Campaign also has its AdGroup. However, there is no ad traffic being served yet since you need to associate active Ad(s) to the newly created AdGroup above.

Say you already have a Creative that's been used successfully running for a different Campaign/AdGroup. We can use that Creative's id when hitting the ad/create endpoint:

curl 'https://ads.nextdoor.com/v2/api/ad/create' \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '{
    "name": "my api ad",
    "advertiser_id": "12",
    "adgroup_id": "231",
    "creative_id": "989"
}'

Example response:

{
    "id": "787",
    "advertiser_id": "12",
    "adgroup_id": "231",
    "creative_id": "989",
    "name": "my api ad",
    "status": "ACTIVE",
    "user_status": "ACTIVE",
    "created_at": "2023-08-03T17:23:30Z",
    "updated_at": "2023-08-03T17:23:30Z"
}

Creating a Scheduled Report

So now that you have a campaign that is serving a live Ad to user on Nextdoor, you will want to get metrics for how the Campaign, AdGroup, and Ad are performing over time. For example, to get a weekly report emailed to you that has a breakdown of impression metrics at the campaign level, you can use the reporting/scheduled/create endpoint:

curl 'https://ads.nextdoor.com/v2/api/reporting/scheduled/create' \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '{
    "advertiser_id": "12",
    "name": "my api scheduled report",
    "schedule": "WEEKLY",
    "timezone": "America/Los_Angeles",
    "recipient_emails": ["[email protected]"],
    "dimension_granularity": ["CAMPAIGN"],
    "time_granularity": ["DAY"],
    "metrics": ["IMPRESSIONS"],
    "campaign_ids": ["123"],
    "adgroup_ids": [],
    "ad_ids": []
}'

Example response:

{
    "id": "31",
    "advertiser_id": "12",
    "name": "my api scheduled report",
    "schedule": "WEEKLY",
    "timezone": "America/Los_Angeles",
    "recipient_emails": ["[email protected]"],
    "dimension_granularity": ["CAMPAIGN"],
    "time_granularity": ["DAY"],
    "metrics": ["IMPRESSIONS"],
    "campaign_ids": ["123"],
    "adgroup_ids": [],
    "ad_ids": [],
    "is_archived": false
}