---
title: "Send conversions"
method: POST
path: "/ad_accounts/{ad_account_id}/events"
tags: ["conversion_events"]
---

# Send conversions

`POST /ad_accounts/{ad_account_id}/events`

The Pinterest API offers advertisers a way to send Pinterest their conversion information (including web conversions, in-app conversions, or even offline conversions) based on their `ad_account_id`. The request body should be a JSON object.
- This endpoint requires an `access_token` be generated through Ads Manager. Review the [Conversions Guide](/docs/api-features/conversion-overview/) for more details. (Note that the authorization header required is `Authorization: Bearer <access_token>`).
- The token's `user_account` must either be the Owner of the specified ad account, or have one of the necessary roles granted to them via [Business Access](https://help.pinterest.com/en/business/article/share-and-manage-access-to-your-ad-accounts): Admin, Analyst, Audience, Campaign. (Note that the token can be used across multiple ad accounts under an user ID.)
- This endpoint has a rate limit of 5,000 calls per minute per ad account.
- If the merchant is submitting this information using both Pinterest conversion tags and the Pinterest API, Pinterest will remove duplicate information before reporting. (Note that events that took place offline cannot be deduplicated.)

## Path parameters

- `ad_account_id` string, required

## Query parameters

- `test` boolean

## Request body

- ConversionEventsCreate — Conversion events.
  - `data` ConversionEventsDataItems[], required — A list of events (one or more) encapsulated by a data object.
    - `action_source` string, required — The source indicating where the conversion event occurred. - `app_android` - `app_ios` - `web` - `offline`
    - `app_id` string, nullable — The app store app ID.
    - `app_info` ConversionEventAppInfo — Object containing information about the application where event occurred.
      - `app_id` string — App ID in Google Play Store, AppStore or other stores.
      - `app_name` string — Name of the app. Primarily used for Mobile Apps.
      - `app_package_name` string — App package name
      - `app_store` string — The name of the app distributor or store from which the app was installed. Some options: Samsung Galaxy Store, Google Play Store, Amazon Store, Apple App Store, F-Droid, Aptoide, Obtanium, Huawei AppGallery, Xiaomi Mi GetApps
      - `app_version` string — App version. Primarily used for mobile apps
      - `install_time` integer — App install time. Unix timestamp in seconds
      - `user_agent` string — User Agent request header. Primarily used for Web events
      - `window_height` integer — Inner height of the window or viewport.
      - `window_width` integer — Inner width of the window or viewport.
    - `app_name` string, nullable — Name of the app.
    - `app_version` string, nullable — Version of the app.
    - `custom_data` ConversionEventsDataItemsCustomData — Object containing other custom data.
      - `content_brand` string, nullable — The brand of the content associated with the event.
      - `content_category` string, nullable — The category of the content associated with the event.
      - `content_ids` string[] — List of products IDs. We recommend using this if you are a merchant for PageVisit, AddToCart and Checkouts. For detail, please check [here](https://help.pinterest.com/en/business/article/before-you-get-started-with-catalogs) (Install the Pinterest tag section).
      - `content_name` string, nullable — The name of the page or product associated with the event.
      - `contents` ConversionEventsDataItemsCustomDataContentsItems[] — A list of objects containing information about products, such as price and quantity. We recommend using this if you are a merchant for PageVisit, AddToCart and Checkouts. For detail, please check [here](https://help.pinterest.com/en/business/article/before-you-get-started-with-catalogs) (Install the Pinterest tag section).
        - `id` string — The id of a product. We recommend using this if you are a merchant for AddToCart and Checkouts. For detail, please check [here](https://help.pinterest.com/en/business/article/before-you-get-started-with-catalogs) (Install the Pinterest tag section).
        - `item_brand` string — The brand of a product.
        - `item_brand_id` string — The brand ID of a product.
        - `item_category` string — The category of a product.
        - `item_name` string — The name of a product.
        - `item_price` string — The price of a product. Accepted as a string in the request; it will be parsed into a double. This is the original item value before any discount. We recommend using this if you are a merchant for PageVisit, AddToCart and Checkouts. For detail, please check [here](https://help.pinterest.com/en/business/article/before-you-get-started-with-catalogs) (Install the Pinterest tag section).
        - `quantity` integer — The amount of a product. We recommend using this if you are a merchant for AddToCart and Checkouts. For detail, please check [here](https://help.pinterest.com/en/business/article/before-you-get-started-with-catalogs) (Install the Pinterest tag section).
      - `currency` string, nullable — The ISO-4217 currency code. If not provided, we will default to the advertiser's currency set during account creation. Your campaign performance needs this field to report right ROAS/CPA.
      - `external_measurement_id` string, nullable — Only use when instructed.
      - `external_measurement_vendor_id` integer, nullable — Only use when instructed.
      - `np` string, nullable — Named partner. Not required, this is for Pinterest internal use only. Please do not use this unless specifically guided.
      - `num_items` integer — Total number of products of the event. For example, the total number of items purchased in a checkout event. We recommend using this if you are a merchant for AddToCart and Checkouts. For detail, please check [here](https://help.pinterest.com/en/business/article/before-you-get-started-with-catalogs) (Install the Pinterest tag section).
      - `opt_out_type` string, nullable — Flags for different privacy rights laws to opt out users of sharing personal information. Separate values with commas. See the Help Center article about [limited data processing](https://help.pinterest.com/en/business/article/limited-data-processing) and the developer's guide for [tracking conversion events](/docs/track-conversions/track-conversions-in-the-api/#whether-the-user-has-opted-out-of-web-or-offline-conversion-events) for help with using this parameter.
      - `order_id` string, nullable — The order ID. We recommend sending order_id to help us deduplicate events when necessary. This also helps to run other measurement products at Pinterest.
      - `predicted_ltv` string, nullable — Predicted lifetime value of user associated with the event. Accepted as a string in the request; it will be parsed into a double.
      - `search_string` string, nullable — The search string related to the user conversion event.
      - `value` string, nullable — Total value of the event. Accepted as a string in the request; it will be parsed into a double. For example, if there are two items in a checkout event, the value should be the total price. We recommend to use pre-tax, pre-shipping final value.
    - `device_brand` string, nullable — Brand of the user device.
    - `device_carrier` string, nullable — User device's mobile carrier.
    - `device_info` ConversionEventDeviceInfo — Object containing information about the device where event occurred.
      - `battery_level` integer — Battery charge level percentage
      - `brand` string — Device brand
      - `carrier` string — User device's mobile carrier.
      - `cpu_cores` integer — Number of CPU cores
      - `external_storage_free_space` integer — External storage size in GB
      - `external_storage_size` integer — External storage size in GB
      - `form_factor` 'desktop' | 'laptop' | 'cellphone' | 'tablet' | 'smartwatch' | 'tv' | 'vr' | 'console' | 'other' — Device form factor
      - `kernel_version` string — Kernel version. Examples: Linux: 6.15. Obtain by running: uname -r MacOS: 24.3.0. Obtain by running: sysctl kern.version Android: 6.6. Obtain from OS.uname().release
      - `languages` string[] — List of user installed languages. ISO 639-1 format
      - `locale` string — Device locale BCP-47 format
      - `model` string — Device model name
      - `network_type` 'wifi' | 'cellular_2g' | 'cellular_3g' | 'cellular_4g' | 'cellular_5g' | 'cellular_6g' | 'ethernet' | 'unknown' — Type of network connection.
      - `os_family` 'ios' | 'android' | 'macos' | 'windows' | 'linux' | 'bsd' | 'other' — Operating system family.
      - `os_name` string — Short name of the OS. This value if specific to os family. Examples: Windows: 10, 11; Android: 16; iOS: 18; MacOS: 15; Linux: Debian, Ubuntu, Arch
      - `os_release_name` string — Marketing name for the release version iOS: Dawn Android: Baklava MacOS: Sequoia Ubuntu Linux: Plucky Puffin
      - `os_version` string — Full name of the version. Examples: iOS: 18.3 Android: 16.1 MacOS: 15.5 Windows: 24H2 Ubuntu Linux: 25.04
      - `screen_density` integer — Screen density, PPI
      - `screen_height` integer — Screen height in pixels
      - `screen_width` integer — Screen width in pixels
      - `storage_free_space` integer — Internal storage size in GB
      - `storage_size` integer — Internal storage size in GB
      - `timezone` string — Device timezone
      - `timezone_abbr` string — Timezone abbreviation
      - `type` string — Device type
    - `device_model` string, nullable — Model of the user device.
    - `device_type` string, nullable — Type of the user device.
    - `event_id` string, required — A unique id string that identifies this event and can be used for deduping between events ingested via both the conversion API and Pinterest tracking. Without this, event's data is likely to be double counted and will cause report metric inflation. Third-party vendors make sure this field is updated on both Pinterest tag and Conversions API side before rolling out template for Conversions API.
    - `event_name` string, required — The type of the user event. Please use the right event_name; otherwise the event will not be accepted and show up correctly in reports. - `add_payment_info` - `add_to_cart` - `add_to_wishlist` - `app_install` - `app_open` - `checkout` - `contact` - `custom` - `customize_product` - `find_location` - `initiate_checkout` - `lead` - `page_visit` - `schedule` - `search` - `signup` - `start_trial` - `submit_application` - `subscribe` - `view_category` - `view_content` - `watch_video`
    - `event_source_url` string, nullable — URL of the web conversion event.
    - `event_time` integer, required — The time when the event happened. Unix timestamp in seconds.
    - `language` string, nullable — Two-character ISO-639-1 language code indicating the user's language.
    - `opt_out` boolean — When action_source is web or offline, it defines whether the user has opted out of tracking for web conversion events. While when action_source is app_android or app_ios, it defines whether the user has enabled Limit Ad Tracking on their iOS device, or opted out of Ads Personalization on their Android device.
    - `os_version` string, nullable — Version of the device operating system.
    - `partner_name` string, nullable — The third party partner name responsible to send the event to Conversions API on behalf of the advertiser. The naming convention is "ss-partnername" lowercase. E.g 'ss-shopify'
    - `user_data` ConversionEventsUserDataProperties, required
      - `click_id` string, nullable — The unique identifier stored in _epik cookie on your domain or &epik= query parameter in the URL. We highly recommend this on checkout events at least. It may improve reporting performance such as ROAS/CPA.
      - `client_ip_address` string — The user's IP address, which can be either in IPv4 or IPv6 format. Used for matching. We highly recommend this for all events. It may improve reporting performance such as ROAS/CPA.
      - `client_user_agent` string — The user agent string of the user's web browser. We highly recommend this for all events. It may improve reporting performance such as ROAS/CPA.
      - `country` string[] — Sha256 hashes of two-character ISO-3166 country code indicating the user's country, in lowercase. The string should be in the UTF-8 format.
      - `ct` string[] — Sha256 hashes of user's city, in lowercase, and without spaces or punctuation. User residency city (mostly billing). The string should be in the UTF-8 format.
      - `db` string[] — Sha256 hashes of user's date of birthday, given as year, month, and day. The string should be in the UTF-8 format.
      - `em` string[] — Sha256 hashes of lowercase version of user's email addresses. Used for matching. We highly recommend this on checkout events at least. It may improve reporting performance such as ROAS/CPA. The string should be in the UTF-8 format.
      - `external_id` string[] — Sha256 hashes of the unique id from the advertiser that identifies a user in their space, e.g. user id, loyalty id, etc. We highly recommend this on all events. It may improve reporting performance such as ROAS/CPA. The string should be in the UTF-8 format.
      - `fn` string[] — Sha256 hashes of user's first name, in lowercase. We highly recommend this on checkout events at least. It may improve reporting performance such as ROAS/CPA. The string should be in the UTF-8 format.
      - `ge` string[] — Sha256 hashes of user's gender, in lowercase. Either "f" or "m" or "n" for non-binary gender. The string should be in the UTF-8 format.
      - `hashed_maids` string[] — Sha256 hashes of user's "Google Advertising IDs" (GAIDs) or "Apple's Identifier for Advertisers" (IDFAs). Used for matching. We highly recommend this on checkout events at least. It may improve reporting performance such as ROAS/CPA. The string should be in the UTF-8 format.
      - `ln` string[] — Sha256 hashes of user's last name, in lowercase. We highly recommend this on checkout events at least. It may improve reporting performance such as ROAS/CPA. The string should be in the UTF-8 format.
      - `partner_id` string, nullable — A unique identifier of visitors' information defined by third party partners. e.g RampID
      - `ph` string[] — Sha256 hashes of user's phone numbers, only digits with country code, area code, and number. Remove any symbols, letters, spaces and leading zeros. We highly recommend this on checkout events at least. It may improve reporting performance such as ROAS/CPA. The string should be in the UTF-8 format.
      - `st` string[] — Sha256 hashes of user's state, given as a two-letter code in lowercase. User residency state (mostly billing). The string should be in the UTF-8 format.
      - `zp` string[] — Sha256 hashes of user's zipcode, only digits. User residency zipcode (mostly billing). The string should be in the UTF-8 format.
    - `wifi` boolean — Whether the event occurred when the user device was connected to wifi.

## Response `200`

The request has succeeded.

- ConversionEvents — Conversion events.
  - `events` ConversionApiResponseEventsItems[], required — Specific messages for each event received. The order will match the order in which the events were received in the request.
    - `error_message` string, nullable — Error message containing more information about why the event failed to be processed.
    - `status` 'failed' | 'processed', required — Status of a single event in the response.
    - `warning_message` string, nullable — Warning messages about any fields in the event which are not standard. These are not critical to event processing.
  - `num_events_processed` integer, required — Number of events that were successfully processed from the events.
  - `num_events_received` integer, required — Total number of events received in the request.

## Other responses

- `400` — The request could not be understood by the server due to unexpected data.
- `401` — Authentication is required and has either failed or not been provided.
- `403` — The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource.
- `404` — The requested resource could not be found on this server.
- `422` — The request was well-formed but was unable to be followed due to semantic errors.
- `429` — The user has sent too many requests in a given amount of time and is being rate limited.
- `503` — The server is currently unable to handle the request due to a temporary overload or scheduled maintenance.
- `default` — An unexpected error response.

---

[API](https://skmtc.net/pinterest/apis/pinterest-rest-api.md) · [All operations](https://skmtc.net/pinterest/apis/pinterest-rest-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/pinterest/pinterest-rest-api/revisions/b698c180678a/schema)