Overview

The Goodworld API is organized around REST and provides a stateless interface for interacting with your Goodworld account. The Goodworld API supports JSON, and all requests return and require a valid JSON object.

What you can do with the API

Contacts:

Retrieve a contact
List all contacts
Create a contact
Update a contact
Delete a contact

Donations:

Retrieve a donation
List all donations
Create a donation
Update a donation
Delete a donation

Recurring Plans:

Retrieve a recurring plan
List all recurring plans
Create a recurring plan
Update a recurring plan
Cancel a recurring plan
Delete a recurring plan

Campaigns:

Retrieve a campaign
Create a campaign
List all campaigns
Update a campaign
Archive a campaign

Companies:

List all companies
Create a company
Update a company
Delete a company

Tags:

Retrieve a tag
Return a list of tags
Create a new tag
Update a tag
Tag/Untag contact

Webhooks

By setting up webhooks, your server will be notified of Goodworld events as they happen. For example, if a user creates a new post, we would send a request to your server to let you know.

You can set up webhooks for your account in the Webhooks section of the Platform Settings.

Events:

donation.created — Occurs when a new donation is created.
donation.deleted — Occurs when a donation is deleted.
donation.refunded — Occurs when a donation is refunded.
contact.created — Occurs when a new contact is created.
contact.deleted — Occurs when a contact is deleted.
campaign.created — Occurs when a new campaign is created.
campaign.disabled — Occurs when a campaign is disabled.

Errors

The Goodworld API uses the standard HTTP status response codes:

Code	Description
400	Bad Request: The request could not be understood by the server due to malformed syntax.
401	Unauthorized: The request requires user authentication. The API access token may be missing or invalid.
403	Forbidden: The server understood the request, but is refusing to fulfill it. The API user does not have correct permissions.
404	Not Found: The resource requested does not exist or was not found.
405	Method Not Allowed: The method / verb specified in the request is not allowed for the resource.
500	Internal Server Error: The request was valid, but something failed on the server.

Authentication

The Goodworld API uses API Keys to authenticate and perform requests. Provide your API key as the basic auth username value. You do not need to provide a password.

Authorization: Basic base64(“{{ your_api_key }}:”)

All API requests must be made over HTTPS. Unencrypted calls over HTTP are not supported and will fail. API requests without authentication will also fail.

Campaigns

Campaigns, also often referred to as fundraisers, are where donation activity occurs. There are several different types of campaigns, the differences of which can be found on our website.

The Campaign Object

Attribute	Description
id	The campaign ID.
title	The title of the campaign.
description	The HTML content displayed as the description of the campaign.
slug	The slug to be used for this campaign. Must be unique across the Goodworld platform
goal	The campaign goal.
raised	The amount of money raised for this campaign.
number of donors	The number of donors who gave to this campaign.
end_at	A UTC datetime string indicating when the campaign ends.
start_at	A UTC datetime string indicating when the campaign starts.
url	The full URL of this campaign.
image	An object representing the main image / banner of this campaign.
created_at	A UTC datetime string indicating when the campaign was created.
updated_at	A UTC datetime string indicating when the campaign was last updated.
Managers	A list of users who manage this campaign

Users

The User Object

Attribute	Description
id	The User ID.
first_name	The User's first name.
last_name	The User's last name.
email	The User's email address.
phone	The User's phone number.
picture	A URL to the User's profile picture.
donated	The amount of money given by this User.
raised	The amount of money raised by this User.
url	The full URL to the User's profile page.
campaigns	A list of all campaigns/fundraisers that this User is managing

Transactions

Every donation or ticket purchase made on your campaigns are called Transactions. Every Transaction is made up of several Line Items that represent the contents of that transaction.

The Transaction Object

Attribute	Description
id	The ID of the transaction.
campaign_id	The ID of the campaign this transaction is credited to.
plan_id	The ID of a recurring plan this transaction is made under.
team_id	The ID of the team this transaction is credited to.
User_id	The ID of the User this transaction is credited to.
first_name	The supporter's first name.
last_name	The supporter's last name.
email	The supporter's email address.
phone	The supporter's phone number.
address	An object representing the supporter's billing address.
status	The status of the transaction. Possible values: succeeded, authorized, failed, canceled.
method	The method this transaction was paid with. Possible values: card, check, cash
amount	The amount the transaction was for.
fee	The full fee charged.
fee_covered	The portion of the fee the supporter covered.
donated	The final amount donated to the campaign after fees.
payout	The amount Goodworld will payout to your account after fees. Note for offline donations this will be 0.
currency	The currency the donation was made in.
created_at	A UTC datetime string indicating when the transaction was created.
captured	A boolean value letting you know if the transaction has been captured.
captured_at	A UTC datetime string indicating when the transaction was captured. For non-pledge transactions this will be the same as created_at.
refunded	A boolean value letting you know if the transaction was refunded.
refunded_at	A UTC datetime string indicating when the transaction was refunded.
line_items	An array containing the Line Items associated with this transaction.
giving_space	An object representing the Giving Space for this transaction.
utm	An object containing UTM tracking data.

Plans

Plans are recurring donations that a supporter has agreed to make.

Attribute	Description
id	The Plan ID.
first_name	The supporter's first name.
last_name	The supporter's last name.
email	The supporter's email address.
phone	The supporter's phone number.
frequency	How often the donation is made. Can be monthly, quarterly or yearly
status	The status of the plan. Can be active, canceled ,ended,past_dueorpaused
method	The payment method used for this plan.
amount	The amount of the recurring donation.
fee_covered	The portion of the fee the supporter covered.
created_at	A UTC datetime string indicating when the plan was created.
start_at	A UTC datetime string indicating when the plan was started.
next_bill_date	A UTC datetime string indicating when the plan will bill next.