Developer
Start typing to search…

Data Types

Data Types for Conversions API and Nextdoor Platform

Understanding the data types supported by Nextdoor's APIs, especially for the Conversions API (CAPI), is crucial for accurate data transmission, robust user matching, and effective campaign optimization. By adhering to these specifications, you ensure your data is correctly processed, leading to more precise attribution and improved ad performance.

Our data types are designed to support seamless integration and ensure the secure, normalized transmission of information.

Key Principles for Data Transmission

To ensure optimal data quality and privacy, please adhere to the following principles when sending data via CAPI:

  • Normalization: For certain fields (e.g., email, phone number, names), data should be normalized before hashing. This typically involves converting to lowercase, removing leading/trailing spaces, and standardizing formats (e.g., E.164 for phone numbers).
  • Hashing: Sensitive user data (like emails, phone numbers, and certain address components) must be hashed using SHA256 before transmission. This ensures data privacy and security while still allowing for effective matching.
  • Completeness: Providing as many relevant data points as possible significantly improves match rates, enhancing the accuracy of your attribution and the effectiveness of your ad delivery.

Fundamental Data Types

Nextdoor's APIs utilize standard programming data types as building blocks:

  • Integer: A signed 32-bit integer, represented as int.
  • Long: A signed 64-bit integer, represented as long.
  • String: A double-quote delineated sequence of characters, represented as string.
  • Boolean: A binary value representing either true or false, represented as bool.

Basic Scalar Types (Specific to Nextdoor Ad Management (NAM) API)

These are specific scalar types used across the Nextdoor Ad Management (NAM) API:

  • AdsId: A string representing a unique identifier for NAM resources (e.g., "139845984734598").
  • LocalDate: A string representing a local date in ISO8601 format (e.g., "2023-06-22").
  • LocalTime: A string representing a local time in ISO8601 format (e.g., "13:37:00").
  • LocalDateTime: A string combining a local date and time in ISO8601 format (e.g., "2023-06-22T13:37:00").
  • Instant: A string representing a UTC Instant on the Epoch timeline in ISO8601 format (e.g., "2023-06-22T13:37:00Z").
  • ZonedDateTime: A string representing an Instant with offset and timezone information in ISO8601 format (e.g., "2023-06-22T13:37:00-07:00[America/Los_Angeles]").
  • Duration: A string representing a time interval in ISO8601 duration format (e.g., "PT20.345S").
  • ZoneId: A string directly representing a Timezone ID from the IANA Timezone database (e.g., "[America/New_York]").
  • Money: A string representing a monetary amount as ISO4217 currency units followed by decimal values (e.g., "USD 10").
  • CurrencyUnit: A string representing an individual currency unit as an ISO4127 currency code (e.g., "USD").

Conversions API Parameters

The following parameters are used in the Conversions API payload. Many sensitive fields now require Recommended Hashing using SHA256 before transmission.

Event-Level Parameters

These parameters provide essential context for the event itself:

  • event_name: (String) The name of the event (e.g., Purchase, Lead, PageView).
  • event_id: (String) A unique identifier chosen by the advertiser. The event_id and event_name parameters are used to deduplicate events sent by both Pixel and CAPI. Note that while event_id is marked optional, it is recommended for event deduplication.
  • event_time_epoch: (Integer) The time the event occurred, represented as a Unix epoch timestamp in seconds.
  • event_source_url: (String) The URL where the event occurred.
  • action_source_url: (String) The URL where the event occurred.
  • action_source: (String) Where the event originated (e.g., website, app, offline).
  • data_source_id: (String) Pixel ID for which the CAPI event should be tied to.
  • opt_out: (Boolean) Indicates if the user has opted out of data collection for this event.

Customer Object Parameters (for User Matching)

The customer object contains user attributes that facilitate accurate user matching through Advanced Event Matching. These fields require Recommended Hashing unless otherwise specified.

  • email: (String) User's email address. Recommended Hashing.
  • phone_number: (String) User's phone number (E.164 format). Recommended Hashing.
  • first_name: (String) User's first name. Recommended Hashing.
  • last_name: (String) User's last name. Recommended Hashing.
  • date_of_birth: (String) User's date of birth in YYYYMMDD format (e.g., "19900115").
  • gender: (String) User's gender (f for female, m for male).
  • street_address: (String) User's street address. Recommended Hashing.
  • city: (String) User's city. Recommended Hashing.
  • state: (String) User's state (2-letter ISO code, e.g., "CA").
  • zip_code: (String) User's postal code.
  • country: (String) User's country (2-letter ISO code, e.g., "US").
  • external_id: (String) Your unique internal identifier for the user.
  • client_ip_address: (String) The client's IP address (raw).
  • client_user_agent: (String) The client's user agent string (raw).
  • click_id: (String) A unique identifier (as ndclid) from an ad click from the Nextdoor platform (e.g. https://www.YOURLANDINGPAGE.COM/?**ndclid=123e4567-e89b-12d3-a456-426614174000**)

Deprecation Notice:
The following fields are now Deprecated and should no longer be sent in your CAPI payloads:

  • event_time
  • client_id
  • pixel_id

Custom Data Parameters

The custom_data object allows you to send additional event-specific details relevant to your business goals. These fields do not typically require hashing unless they contain sensitive information that you choose to hash for added privacy.

  • order_value: (String) The monetary value of the conversion.
  • order_id: (String) A unique transaction identifier/id for the conversion event.
  • delivery_category: (String)
  • app_id: (String)
  • app_tracking_enabled: (Boolean)
  • platform: (String)
  • app_version: (String)
  • product_context: (Array)
    • product_context[].id: (String)
    • product_context[].quantity: (Integer)
    • product_context[].item_price: (Integer)
  • currency: (String) The currency of the value (e.g., "USD").

General API Resource Types (Custom Objects)

These custom objects represent core resources within the Nextdoor Ad Management (NAM) API:

  • Profile: Represents the top-level entity that owns other advertisers.
  • Advertiser: The entity that owns its own namespaced campaigns, creatives, etc.
  • Campaign: A mapping of AdGroup(s) that serve end Ad(s).
  • AdGroup: A group of Ad(s) that are set to serve Creative(s), also holds targeting info, budget, etc.
  • Ad: The actual Ad that is being served to end users on Nextdoor.
  • Creative: The visual users see on the Nextdoor app which includes an image, logo, and text data.
  • Media: The media, such as an image, that can be referenced for creatives.
  • Report: A CSV report, typically representing generated data files.