Embedding a Nonprofit Search Form

Embed Script & Partner Key

Make sure to read our guide on the embed script and partner key and include the script on your page before embedding the organization search form.

You can embed a nonprofit organization search form on your website to allow users to choose a nonprofit organization to donate to, or to choose nonprofits to create a fundraiser for.

Put this embed code where you want the search form to appear.

<div class="plg-search" data-partner-key="[PARTNER KEY]"></div>

Tip

You can also search our vast database of nonprofit organizations via our API.

Additional Embed Code Parameters

You can render the search form with the beneficiary and goal pre-selected for an existing fundraiser, feature a suggested nonprofit, or allow multiple nonprofits by adding additional attributes to the embed code.

Organization Search Reference Learn how to customize your organization search form.

Messages

When a user interacts with the search widget, it triggers events (via postMessage) that your application can consume. The two main events are updateEvent and removeEvent. The format for the postMessage payload is a stringified JSON object specifying the action and associated data.

postMessage data format

{
  "action": "actionName", // All actions have an action key
  "data": {               // Select actions have a data key and structure
    "key": "value"
  }
}

updateEvent

This action has a data structure which specifies the beneficiary type and ID, and the goal set.

updateEvent sample payload with single organization

{
  "action": "updateEvent",
  "data": {
    "beneficiary_type": "Organization",
    "beneficiary_uuid": "ec0b21fc-2671-431e-8a81-783b7a9626c9",
    "goal": null
  }
}

updateEvent sample payload with multiple organizations

{
  "action": "updateEvent",
  "data": {
    "goal": null,
    "organization_ids": [
      "3685b542-61d5-45da-9580-162dca725966",
      "ec0b21fc-2671-431e-8a81-783b7a9626c9"
    ]
  }
}

removeEvent

This action has no data structure attached.

removeEvent payload

{
  "action": "removeEvent"
}

Consuming messages

In order to make use of the postMessage format, parse the string into a JSON object and then process it according to the action and associated data.

Note

In the sandbox environment, validate against https://staging.pledge.to instead of https://www.pledge.to.

Example code consuming postMessage format

const updateEvent = data => {
  // Do something with the data
}

const removeEvent = () => {
  // Do what is necessary to remove the event
}

const handleMessage = e => {
  if (e.origin != 'https://www.pledge.to') return

  const message = JSON.parse(e.data)

  switch (message.action) {
    case 'updateEvent':
      return updateEvent(message.data)
    case 'removeEvent':
      return removeEvent()
  }
}

addEventListener('message', handleMessage)