Overview #

Note: All interactions with The Groundwork API require a valid account and API Key. If you would like to try out the API or learn more about The Groundwork platform, sign up now for free.

The Groundwork API follows REST principles. The API uses HTTP status codes to describe errors and supports CORS to allow access from client-side web applications.

Schema #

All API access is over HTTPS, and accessed from the api.thegroundwork.com domain. All requests and responses use JSON.

Parameters #

Many API methods take optional parameters. For GET requests, use query strings for any parameters not specified in the path.

Pagination #

Requests that return a list will be paginated to 10 items by default. You can specify further pages with the page parameter. For some resources, you can also set a custom page size up to 100 with the perPage parameter. Note that for technical reasons not all endpoints respect the perPage parameter.

Versions #

You may target a specific version of the API by including a Gw-API-Version header in your request, e.g. Gw-API-Version: 2016-03-22. Omit the header to use the default version.

Version History #
Version Default Description
2016-03-22 All API endpoints and functionality
2016-08-04 Introduced the /collections/supporters endpoint for Supporter data capture.

CORS #

The API supports Cross Origin Resource Sharing (CORS) for AJAX requests from any origin.

HTTP Verbs #

Where possible, the API uses appropriate HTTP verbs for each action.

Verb Description
GET Used for retrieving resources.
POST Used for creating resources.
PUT Used for updating resources.
PATCH Used for updating resources.
DELETE Used for deleting resources.

Errors #

The API uses HTTP response codes to describe the success or failure of a request. Codes in the 2xx range are successful. Codes in the 4xx are unsuccessful. Codes in the 5xx range indicate an error with the API.

The API uses the following error codes:

Error Code Description
400 Bad Request - Missing or bad parameter.
401 Unauthorized - Missing or bad API key in most cases.
402 Unsuccessful - The request was valid but was ultimately unsuccessful (e.g. unsuccessful payment due to declined card).
403 Forbidden - The data requested requires more or different permissions.
404 Not Found - The specified data could not be found.
405 Method Not Allowed - Attempted to access data with an invalid HTTP method.
406 Not Acceptable - Requested a format that isn’t JSON.
410 Gone - The data requested has been removed.
429 Too Many Requests - Too many requests have been made.
500 Internal Server Error - The API is having trouble.
503 Service Unavailable - The API or individual service is offline or disabled.

Authentication #

Overview #

To make a request to The Groundwork, you must first obtain an authentication token, and pass it in an Authorization HTTP header with every request. Many public requests on The Groundwork can be completed with a Basic token, as described below. When a user creates a profile and authenticates on your site, they will create a Bearer token for use in their session, giving them slightly escalated permissions. For maximum permissions, you will need a client credential token. Client credential tokens are useful for building integrations and batch operations on data, amongst other things. To get a client credential token for your account, reach out to support@timshel.com

Authentication #

https://api.thegroundwork.com/oauth/token

Requests to this endpoint must use HTTP Basic Authentication. All requests must have a header Content-Type: application/json.

Public client authentication #

Public clients are those, like a client-side web application or native application, that cannot protect the confidentiality of a client secret.

Public clients submit an Authorization header with only their base64 encoded client_id (api key) and a “:”. To make this Authorization header, you must first base64 encode your client_id + a : (like so: base64(client_id:)).

Authorization: Basic base64({client_id} + ":")

For example, if a client_id is “client_id”, the Authorization header would be:

Authorization: Basic Y2xpZW50X2lkOg==

To authenticate, a user must also have an email and password. These are created by creating a profile, as described below.

Note - Admin accounts are separate from profiles. Admin accounts are intended for use in admin only, and are different from the profiles your end users will create in order to interact with your site (and use for authentication).

Request body parameters #
Parameter Required Type Description
email string The email address for the authenticating user.
password string The password for the authenticating user.
Response body parameters #
Parameter Type Description
expiresIn integer The time-to-live of the token in seconds. A null value indicates that the token does not expire.
tokenType string The type of the token returned. Always “Bearer”.
accessToken string The access token, for use in authenticated requests.
gwid string The gwid of the user associated with this token, or null if there is no gwid (as is the case with client-credential-grants).
Example request #
curl -X POST -H "Content-Type: application/json" -H "Authorization: Basic {base64(client_id:)}" -d '{
  "email":"email@email.com",
  "password":"Password1"
}' "https://api.thegroundwork.com/oauth/token"
Example response #
{
  "expiresIn": null,
  "tokenType": "Bearer",
  "accessToken": "{oauth-access-token}",
  "gwid": "f238fafe-7f0f-454c-910b-9bedbc86d06b"
}

Facebook authentication #

The Groundwork supports Facebook authentication as a specific grant_type. Groundwork accepts a Facebook access token and uses it to look up a Profile. When authenticating with Facebook, there are three possible outcomes:

  • If there is already a Profile associated with the Facebook user, The Groundwork will return a Bearer access token for that Profile.
  • If there is not a Profile associated with the Facebook user, The Groundwork will attempt to create a new Profile, and return a Bearer access token for that Profile.
  • If there is already a profile with a matching email address, The Groundwork will connect the Facebook account to that Profile, and return a Bearer access token.
Request body parameters #
Parameter Required Type Description
grant_type string The grant_type of the Authentication request. Must be facebook to authenticate via Facebook.
access_token string The Facebook access token.
Response body parameters #
Parameter Type Description
expiresIn integer The time-to-live of the token in seconds. A null value indicates that the token does not expire.
tokenType string The type of the token returned. Always “Bearer”.
accessToken string The access token, for use in authenticated requests.
gwid string The gwid of the user associated with this token, or null if there is no gwid (as is the case with client-credential-grants).
Example request #
curl -X POST -H "Content-Type: application/json" -H "Authorization: Basic {base64(client_id:)}" -d '{
  "grant_type":"facebook",
  "access_token":"{facebook-access-token}"
}' "https://api.thegroundwork.com/oauth/token"
Example response #
{
  "expiresIn": null,
  "tokenType": "Bearer",
  "accessToken": "{oauth-access-token}",
  "gwid": "f238fafe-7f0f-454c-910b-9bedbc86d06b"
}

Using a token #

In all requests made to the Groundwork after obtaining an accessToken, you must include the word Bearer, followed by the token, as the value of the Authorization header. This is true for all requests made as an authenticated user. If a request is made with just an Authorization header of base64(client_id:), it must be preceded by the word Basic, as in the public authentication example above.

Authorization: Bearer {oauth-access-token}

Supporters #

Version information #

This section documents Supporter functionality as of version 2016-08-04. View complete version history

Overview #

The Supporter service can be used to store a wide variety of data about about your users. Supporters are typically used for appeals, signups, petitions, and other webforms. Its flexibility allows for capturing nearly any data that may be relevant for your organization.

Supporter records are created in a data container called a Collection and validated by a Schema that is associated with that Collection. The Collection name is, appropriately, supporters and is included in the endpoint path as shown below. The Schema is referred to using a schemaId that is specific to your organization and is incuded in the request body as shown below.

Supporter #

Create a Supporter #

https://api.thegroundwork.com/collections/supporters/records

Create a new Supporter.

Request body parameters #
Parameter Required Type Description
schemaId string The id of the Schema used to validate the Supporter record. See below for the query used to list your available schemaIds.
data object A JSON object with the data used to populate the Supporter record. Data object parameters are listed below.
data.email string The Supporter’s RFC-5322-compliant email address.
data.givenName string The Supporter’s given (first) name.
data.familyName string The Supporter’s family (last) name.
data.phone string The Supporter’s phone number.
data.address1 string The first line of Supporter’s street address.
data.address2 string The second line of Supporter’s street address.
data.addressCity string The city of Supporter’s address.
data.addressCounty string The county of Supporter’s address.
data.addressStateProvince string The state of Supporter’s address.
data.addressPostalCode string The postal code of Supporter’s address.
data.addressCountry string The country of Supporter’s address.
data.socialHandle string The Supporter’s social (e.g. Twitter) handle. Used for contact information, not authentication. See Profiles for information on social media authentication.
data.comments string Free text entered by Supporter, e.g. on a webform.
data.utmSource string The source of the supporter’s visit, e.g. “newsletter”. We recommend that you pass this parameter from a hidden form field and use utm_source when available.
data.utmMedium string The medium over which the supporter’s visit was driven, e.g. “email”. We recommend that you pass this parameter from a hidden form field.
data.utmCampaign string The specific campaign name to associate the supporter’s visit, e.g. “Spring 2016 Appeal”. We recommend that you pass this parameter from a hidden form field.
data.utmContent string The content variant displayed to the supporter, generally for multivariate testing, e.g. “CTA-top”. We recommend that you pass this parameter from a hidden form field.
data.utmTerm string The user’s search term, generally used for paid search. We recommend that you pass this parameter from a hidden form field
data.emailTemplate string Used to to specify the template (omitting the file extension, e.g. specify “welcome” to use a template file named “welcome.html”) for a post-submission email. See Note below.
data.externalId string Used to hold a reference to another record within or outside The Groundwork.
data.metadata object A JSON object used to hold arbitrary additional data you would like to associate with this supporter record.

Note - When a Supporter record is created, the system sends a confirmation email to the address specified by email, using the email template specified by emailTemplate. Pass "emailTemplate": "welcome" to use a generic email template or "emailTemplate": "" if you do not wish to send any confirmation email.

Contact support@timshel.com to set up your email templates.

Response body parameters #
Parameter Type Description
id string A unique identifier for the Supporter record.
created string A ISO-8601 formatted creation time of the record, in UTC.
modified string A ISO-8601 formatted last modification time for the record, in UTC.
schemaId string The id of the Schema used to validate the record.
data object A JSON object with the data payload used to populate the record. Data object parameters are listed below.
data.email string The Supporter’s RFC-5322-compliant email address.
data.givenName string The Supporter’s given (first) name.
data.familyName string The Supporter’s family (last) name.
data.phone string The Supporter’s phone number.
data.address1 string The first line of Supporter’s street address.
data.address2 string The second line of Supporter’s street address.
data.addressCity string The city of Supporter’s address.
data.addressCounty string The county of Supporter’s address.
data.addressStateProvince string The state of Supporter’s address.
data.addressPostalCode string The postal code of Supporter’s address.
data.addressCountry string The country of Supporter’s address.
data.socialHandle string The Supporter’s social (e.g. Twitter) handle. Used for contact information, not authentication. See Profiles for information on social media authentication.
data.comments string Free text entered by Supporter, e.g. on a webform.
data.utmSource string The source of the supporter’s visit, e.g. “newsletter”. We recommend that you use the value from utm_source when available.
data.utmMedium string The medium over which the supporter’s visit was driven, e.g. “email”. We recommend that you use the value from utm_medium when available.
data.utmCampaign string The specific campaign name to associate the supporter’s visit, e.g. “spring-2016-appeal”. We recommend that you use the value from utm_campaign when available.
data.utmContent string The content variant displayed to the supporter, generally for multivariate testing, e.g. “CTA-top”. We recommend that you use the value from utm_content when available.
data.utmTerm string The paid keywords used to drive the supporter’s visit, e.g. “supporter-microsite”. We recommend that you use the value from utm_term when available.
data.emailTemplate string Used to to specify the template to be used when sending a post-submission email.
data.externalId string Used to hold a reference to another record within or outside The Groundwork.
data.metadata object A JSON object used to hold arbitrary additional data you would like to associate with this supporter record.
Example request #
curl -X POST -H "Content-Type: application/json" -H "Authorization: Basic {client-id}" -d '{
    "schemaId": "abf3e913-29f4-4d71-9729-9c3d57b361e2",
    "data": {
        "email": "marina@galileo.edu",
        "givenName": "Marina",
        "familyName": "Gamba",
        "phone": "4155551212",
        "address1": "101 Main St",
        "address2": "Suite 600",
        "addressCity": "SF",
        "addressStateProvince": "CA",
        "addressCounty": "San Francisco",
        "addressPostalCode": "94111",
        "addressCountry": "USA",
        "socialHandle": "@marina",
        "comments": "Harder problems than this have already been solved.",
        "utmSource": "August-Member-Newsletter",
        "utmMedium": "email",
        "utmCampaign": "Summer-2016",
        "utmContent": "multivariate-b",
        "utmTerm": "Pinniped-Love",
        "emailTemplate": "welcome",
        "externalId": "987654321",
        "metadata": {"beverage":"coffee"}
    }
}  ' "https://api.thegroundwork.com/collections/supporters"
Example response #
{
  "id": "4c9fb861-c860-4c15-8fc9-cb48d21ef66b",
  "created": "2016-09-26T17:43:02.739334Z",
  "modified": "2016-09-26T17:43:02.739377Z",
  "data": {
    "givenName": "Marina",
    "email": "marina@galileo.edu",
    "campaign": "Summer 2016 - Clean the Pacific Gyre",
    "addressPostalCode": "94111",
    "metadata": {
      "beverage": "coffee"
    },
    "addressCity": "SF",
    "familyName": "Gamba",
    "addressCounty": "San Francisco",
    "addressStateProvince": "CA",
    "externalId": "987654321",
    "address2": "Suite 600",
    "socialHandle": "@marina",
    "addressCountry": "USA",
    "utmSource": "August-Member-Newsletter",
    "utmMedium": "email",
    "utmCampaign": "Summer-2016",
    "utmContent": "multivariate-b",
    "utmTerm": "Pinniped-Love",
    "comments": "Harder problems than this have already been solved.",
    "phone": "4155551212",
    "address1": "101 Main St"
  },
  "schemaId": "abf3e913-29f4-4d71-9729-9c3d57b361e2"
}

List all Supporter Schemas #

Returns a JSON Schema definition of the Supporters Schema. Multiple Supporter Schemas may be defined and if so, all will be returned.

https://api.thegroundwork.com/collections/supporters/schemas
Response body parameters #
Parameter Type Description
id string A unique identifier for the Schema. Referenced when creating a new Supporter record.
created string A ISO-8601 formatted creation time of the Schema, in UTC.
schema object The Supporters Schema as JSON Schema.

Get a Supporter Schema #

Returns a JSON Schema definition of the Supporters Schema.

https://api.thegroundwork.com/collections/supporters/schemas/{schema-id}

Get a specific Schema by its {id}

Path parameters #
Parameter Description
schema-id The unique identifier of the Schema.
Response body parameters #
Parameter Type Description
id string A unique identifier for the Schema. Referenced when creating a new Supporter record.
created string A ISO-8601 formatted creation time of the Schema, in UTC.
schema object The Supporters Schema as JSON Schema.

Payments #

Overview #

Payments enables partners to process one time transactions (Donations), create recurring transaction profiles (Subscriptions), securely save a user’s credit card information for reuse (QuickCard), and process single-click donations against saved cards.

Permissions #

Donations and Subscriptions can be made anonymously, as an authenticated user, or by an administrator. QuickCards must be associated with an authenticated user.

To create a Donation, Subscription, or QuickCard as an authenticated user, include the gwid in the request body, and send an Authorization header with Bearer {oauth-access-token}, as per the authentication documentation.

To create an anonymous Donation or Subscription, omit the gwid and send an Authorization header with Basic base64({client-ID} + ":"), just like the authentication request.

Note - Any GET requests for Donations, Subscriptions, or QuickCards must have request parameters (gwid or email) corresponding to the authorized user making the request, or the response will 404 for security reasons. Administrators can manipulate any Donation, Subscription, or QuickCard.

Compliance #

The Groundwork is not responsible for enforcing transaction compliance for partner organizations. Use your discretion when enforcing data requirements, and verify that you are implementing Donations, Subscriptions, and QuickCards in a way that is compliant with any federal and local laws where in use.

Payment processors #

Payments is built to integrate with, and operate on top of, commonly used payment processors. Stripe and CyberSource are currently supported, and Stripe is heavily recommended.

Note - Payments will 503 until you have provided your access key for the payment processor.

The Groundwork supports failover switching between payment processors, and it is available with certain licenses.

For assistance credentialing your payment processor in Payments, and for inquiries about failover processors, contact us at support@timshel.com.

Testing #

To make test requests in Payments, use test data from whichever payment processor you are integrated with. For example, here is Stripe’s test data.

Messaging #

The Groundwork supports sending messages for each transaction. Partners can build email templates and specify which template is used for each specific Donation via the emailTemplate param.

Tags #

tags are JSON metadata attached to Donation, Subscription, and QuickCard objects. If a child object is created, all tags data will be copied from the parent to the child. Subscriptions and QuickCards can each pass tags to child Donations.

While there is no limit on the number of tags an object may have, the total size of the tags field must be less than 1,000 characters, including quote and separator characters.

Tokens #

The Groundwork supports the use of one-time and multi-use tokens for one-click functionality, such as click-to-donate links in emails. Contact us at support@timshel.com for more information.

Data #

The user data in each Payments object represents the data that was submitted when the object was created, and may be different than a user’s Profile information.

Donations #

Donation objects represent successful transactions. Each Donation is one of three types: one-time, subscription-based, or a result of a Quick Donate action. The type of each Donation can be determined by looking at the included identifier fields. If a subscription is present, the Donation is the result of a Subscription. If quickCard is present, the Donation is the result of a Quick Donation. If neither subscription nor quickCard are present, the Donation is a one-time Donation. A Donation may have a corresponding Subscription or QuickCard, but not both.

Create a Donation #

https://api.thegroundwork.com/payments/donations

Create a new Donation.

Donations can be anonymous, created by an administrator, or created by an authorized user, as per the Payments permissions.

Request body parameters #
Parameter Required Type Description
gwid string The gwid of the user making the Donation.
amount integer The amount of the Donation, in cents (e.g. $8.00 = “800”). Must be greater than 100, or the request will return a 400.
cartId string Unique identifier for the cart this Donation fulfills.
fundraising object A JSON object used to associate this Donation with a P2P Fundraiser. fundraiserId is required if this object is provided. comment and anonymous are optional.
currency string The 3-letter ISO-4217 formatted currency code. Default is “USD”.
givenName string The given (first) name of the user.
familyName string The family (last) name of the user.
address1 string The first line of the user’s billing street address.
address2 string The second line of the user’s billing street address.
city string The city of the user’s billing address.
state string The state of the user’s billing address.
zip string The 5-digit zip code of the user’s billing address.
country string The country of the user’s billing address.
email string The user’s email address. An email receipt of the Donation will be sent here if successful and sendEmail is “true”.
phone string The user’s phone number.
employer string The user’s employer.
occupation string The user’s occupation.
ccNum string The credit card number for the Donation, as a string and with no separators.
ccExpMonth integer The month of the credit card expiration date, as a 2-digit number (e.g. March = 03).
ccExpYear integer The year of the credit card expiration date, as a 4-digit number.
ccCvc string The CVC for the credit card.
paymentMethod string The payment method. If paymentMethod is included, it must be “card”. It will default to “card” if left out of the request.
tags JSON A JSON object for storing any additional parameters for the Donation (e.g. additional survey responses).
agreeToTerms boolean A boolean indicating whether or not the user agreed to the legal terms around donating.
source string The source of the Donation, for analytics purposes (e.g. “home page donate form”).
submittingUrl string The URL of the page submitting the Donation.
emailTemplate string The name of the email template used to generate the email receipt.
sendEmail boolean A boolean indicating whether an email should be sent upon successful Donation. If not provided, the default value is “true”.

Note - If a Donation is made from an authorized user, be sure to pass through that user’s gwid as a parameter.

Response body parameters #
Parameter Type Description
id string The unique identifier for the Donation.
created timestamp The unix timestamp of when the Donation was created.
deleted timestamp The unix timestamp of when the Donation was deleted. If null, then the Donation has not been deleted.
amount integer The amount of the Donation, in cents (e.g. $8.00 = “800”).
currency string The 3-letter ISO-4217 formatted currency code.
gwid string The gwid of the user making the Donation.
subscription string The unique identifier of the Subscription the Donation belongs to, if it is from a Subscription.
quickCard string The unique identifier of the QuickCard the Donation belongs to, if it is from a QuickCard.
givenName string The given (first) name of the user.
familyName string The family (last) name of the user.
address1 string The first line of the user’s billing street address.
address2 string The second line of the user’s billing street address.
city string The city of user’s billing address.
state string The state of the user’s billing address.
zip string The 5-digit zip code of the user’s billing address.
country string The country of the user’s billing address.
email string The user’s email address used for the Donation.
phone string The user’s phone number used for the Donation.
employer string The user’s employer.
occupation string The user’s occupation.
tags JSON A JSON object for storing any additional parameters for the Donation.
processor string This string indicates which payment processor was used to charge this card.
processorPaymentData JSON A JSON object of data saved from the payment processor’s response.
Example request #
curl -X POST -H "Content-Type: application/json" -H "Authorization: Bearer {oauth-access-token}" -d '{
  "amount": "800",
  "cartid": "",
  "fundraising": {
      "fundraiserId": "21f2ef39-9ff7-4426-908a-1e02ebb645f5",
      "anonymous": false,
      "comment": "Keep up the good work, Jane!"
  },
  "givenName": "James",
  "familyName": "Jameson",
  "address1": "123 Elm Street",
  "address2": "",
  "city": "New York",
  "state": "NY",
  "zip": "10010",
  "country": "US",
  "email": "example@email.com",
  "phone": "1234567890",
  "employer": "Job Place, Inc.",
  "occupation": "Guy",
  "ccNum": "4242424242424242",
  "ccExpMonth": "03",
  "ccExpYear": "2018",
  "ccCvc": "666",
  "tags": {
      "event_id": "4665"
  },
  "agreeToTerms": "True",
  "source": "",
  "submittingUrl": "",
  "paymentMethod": "card",
  "gwid": "f238fafe-7f0f-454c-910b-9bedbc86d06b"
}' "https://api.thegroundwork.com/payments/donations"
Example response #
{
  "donation": {
    "currency": "USD",
    "id": "59f623d6c1074a14836552651cba37e6",
    "occupation": "test",
    "city": "New York",
    "quickCard": "",
    "zip": "10010",
    "processorPaymentData": {
      "chargeId": "ch_181iRGGqCW8jAjllFTkVnJNR",
      "cardId": "card_181iRGGqCW8jAjlletkxzsj1"
    },
    "employer": "acme",
    "state": "NY",
    "paymentMethod": "card",
    "email": "example@email.com",
    "tags": {
      "event_id": "4665"
    },
    "deleted": null,
    "address1": "123 Elm Street",
    "address2": "4th floor",
    "familyName": "Jameson",
    "phone": "2125555555",
    "subscription": "",
    "created": 1461009223,
    "country": "US",
    "gwid": "f238fafe-7f0f-454c-910b-9bedbc86d06b",
    "amount": 800,
    "givenName": "James",
    "processor": "stripeinc"
  }
}

Get a Donation #

https://api.thegroundwork.com/payments/donations/{donation-id}

Get a specific Donation by its id.

Path parameters #
Parameter Description
donation-id The unique identifier of the Donation.
Response body parameters #
Parameter Type Description
id string The unique identifier for the Donation.
created timestamp The unix timestamp of when the Donation was created.
deleted timestamp The unix timestamp of when the Donation was deleted. If null, then the Donation has not been deleted.
amount integer The amount of the Donation, in cents (e.g. $8.00 = “800”).
currency string The 3-letter ISO-4217 formatted currency code.
gwid string The gwid of the user making the Donation.
subscription string The unique identifier of the Subscription the Donation belongs to, if it is from a Subscription.
quickCard string The unique identifier of the QuickCard the Donation belongs to, if it is from a QuickCard.
givenName string The given (first) name of the user.
familyName string The family (last) name of the user.
address1 string The first line of the user’s billing street address.
address2 string The second line of the user’s billing street address.
city string The city of user’s billing address.
state string The state of the user’s billing address.
zip string The 5-digit zip code of the user’s billing address.
country string The country of the user’s billing address.
email string The user’s email address used for the Donation.
phone string The user’s phone number used for the Donation.
employer string The user’s employer.
occupation string The user’s occupation.
tags JSON A JSON object for any additional Donation parameters.
processor string This string indicates which payment processor was used to charge this card.
processorPaymentData JSON A JSON object of data saved from the payment processor’s response.
Example request #
curl -X GET -H "Content-Type: application/json" -H "Authorization: Bearer {oauth-access-token}" "https://api.thegroundwork.com/payments/donations/5595e20a90014f8db2783d354f55880e"
Example response #
{
  "donation": {
    "currency": "USD",
    "id": "5595e20a90014f8db2783d354f55880e",
    "occupation": "test",
    "city": "New York",
    "quickCard": "",
    "zip": "10010",
    "processorPaymentData": {
      "chargeId": "ch_181iihGqCW8jAjllhvxj9rcC",
      "cardId": "card_181iihGqCW8jAjll7pxLp81A"
    },
    "employer": "acme",
    "state": "NY",
    "paymentMethod": "card",
    "email": "example@email.com",
    "tags": {
      "event_id": "4665"
    },
    "deleted": null,
    "address1": "123 Elm Street",
    "address2": "4th floor",
    "familyName": "Jameson",
    "phone": "2125555555",
    "subscription": "",
    "created": 1461010304,
    "country": "US",
    "gwid": "f238fafe-7f0f-454c-910b-9bedbc86d06b",
    "amount": 800,
    "givenName": "James",
    "processor": "stripeinc"
  }
}

List all Donations #

https://api.thegroundwork.com/payments/donations

Lists all Donations, and filter by request parameters.

Query string parameters #
Parameter Type Description
gwid string Return Donations from the user with the corresponding gwid.
subscription string Return Donations with the corresponding Subscription id.
quickCard string Return Donations with the corresponding QuickCard id.
email string Return Donations with the corresponding email address.
page integer A metadata parameter for specifying a page of results to return, with a default of 1.
perPage integer A metadata parameter for specifying number of results per page, with a default of 10 and a maximum of 50.

Note - Every query string must supply one, and only one, of the four filtering criteria (gwid, subscription, quickCard, email). If more than one of the filtering criteria is passed, the parameters will be given the following order of precedence: gwid, subscription, quickCard, and email.

Response body parameters #
Parameter Type Description
id string The unique identifier for the Donation.
created timestamp The unix timestamp of when the Donation was created.
deleted timestamp The unix timestamp of when the Donation was deleted. If null, then the Donation has not been deleted.
amount integer The amount of the Donation, in cents (e.g. $8.00 = “800”).
currency string The 3-letter ISO-4217 formatted currency code.
gwid string The gwid of the user making the Donation.
subscription string The unique identifier of the Subscription the Donation belongs to, if it is from a Subscription.
quickCard string The unique identifier of the QuickCard the Donation belongs to, if it is from a QuickCard.
givenName string The given (first) name of the user.
familyName string The family (last) name of the user.
address1 string The first line of the user’s billing street address.
address2 string The second line of the user’s billing street address.
city string The city of user’s billing address.
state string The state of the user’s billing address.
zip string The 5-digit zip code of the user’s billing address.
country string The country of the user’s billing address.
email string The user’s email address used for the Donation.
phone string The user’s phone number used for the Donation.
employer string The user’s employer.
occupation string The user’s occupation.
tags JSON A JSON object for any additional Donation parameters.
processor string This string indicates which payment processor was used to charge this card.
processorPaymentData JSON A JSON object of data saved from the payment processor’s response.
Example request #
curl -X GET -H "Content-Type: application/json" -H "Authorization: Bearer {oauth-access-token}" "https://api.thegroundwork.com/payments/donations?email=example@email.com&perPage=2"
Example response #
{
  "meta": {
    "count": 2,
    "totalPages": 7,
    "params": {
      "perPage": 2,
      "page": 1,
      "email": "example@email.com"
    }
  },
  "donations": [
    {
      "currency": "USD",
      "id": "5595e20a90014f8db2783d354f55880e",
      "occupation": "test",
      "city": "New York",
      "quickCard": "",
      "zip": "10010",
      "processorPaymentData": {
        "chargeId": "ch_181iihGqCW8jAjllhvxj9rcC",
        "cardId": "card_181iihGqCW8jAjll7pxLp81A"
      },
      "employer": "acme",
      "state": "NY",
      "paymentMethod": "card",
      "email": "example@email.com",
      "tags": {
        "event_id": "4665"
      },
      "deleted": null,
      "address1": "123 Elm Street",
      "address2": "4th floor",
      "familyName": "Jameson",
      "phone": "2125555555",
      "subscription": "",
      "created": 1461010304,
      "country": "US",
      "gwid": "f238fafe-7f0f-454c-910b-9bedbc86d06b",
      "amount": 800,
      "givenName": "James",
      "processor": "stripeinc"
    },
    {
      "currency": "USD",
      "id": "f71b66caf0c74e08a8de6e8caec046a5",
      "occupation": "test",
      "city": "New York",
      "quickCard": "",
      "zip": "10010",
      "processorPaymentData": {
        "chargeId": "ch_181igyGqCW8jAjllzJ1zHQq9",
        "cardId": "card_181igyGqCW8jAjlle5prlCUa"
      },
      "employer": "acme",
      "state": "NY",
      "paymentMethod": "card",
      "email": "example@email.com",
      "tags": {
        "event_id": "4665"
      },
      "deleted": null,
      "address1": "123 Elm Street",
      "address2": "4th floor",
      "familyName": "Jameson",
      "phone": "2125555555",
      "subscription": "",
      "created": 1461010196,
      "country": "US",
      "gwid": "",
      "amount": 800,
      "givenName": "James",
      "processor": "stripeinc"
    }
  ]
}

Subscriptions #

Subscription objects allow supporters to create recurring transactions. Subscriptions cause Donations in monthly or weekly intervals. Users can have multiple Subscriptions.

Create a Subscription #

https://api.thegroundwork.com/payments/subscriptions

Create a Subscription.

Request body parameters #
Parameter Required Type Description
gwid string The gwid of the user making the Subscription.
amount integer The amount of the Donation, in cents (e.g. $8.00 = “800”).
currency string The 3-letter ISO-4217 formatted currency code. Default is “USD”.
interval string The interval at which the Subscription is charged. Defaults to “monthly”. Valid values are “monthly” or “weekly”.
givenName string The given (first) name of the user.
familyName string The family (last) name of the user.
address1 string The first line of the user’s billing street address.
address2 string The second line of the user’s billing street address.
city string The city of the user’s billing address.
state string The state of the user’s billing address.
zip string The 5-digit zip code of the user’s billing address.
country string The country of the user’s billing address.
email string The user’s email address. An email receipt of the Subscription will be sent here each time a Donation occurs successfully and sendEmail is “true”.
phone string The user’s phone number.
employer string The user’s employer.
occupation string The user’s occupation.
ccNum string The credit card number for the Subscription, as a string and with no separators.
ccExpMonth integer The month of the credit card expiration date, as a 2-digit number (e.g. March = 03).
ccExpYear integer The year of the credit card expiration date, as a 4-digit number.
ccCvc string The CVC for the credit card.
tags JSON A JSON object for storing any additional parameters for the Subscription (e.g. additional survey responses).
agreeToTerms boolean A boolean indicating whether or not the user agreed to the legal terms around donating.
source string The source of the Subscription, for analytics purposes (e.g. “home page donate form”).
submittingUrl string The URL of the page submitting the donation.
emailTemplate string The name of the email template used to generate the email receipt.
sendEmail boolean A boolean indicating whether an email should be sent upon Subscription creation, notifying the user of their recurring payment. If not provided, the default value is “true”.

Note - Creating a Subscription without a gwid, and with a Basic Authorization header, will make it anonymous. Partners will only be able to cancel anonymous Subscriptions as an administrator, as the user will not be able to find or manage this recurring Donation. Utilize this feature at your discretion and ensure that you are in compliance with any fundraising requirements.

Response body parameters #
Parameter Type Description
id string The unique identifier for the Subscription.
created timestamp The unix timestamp of when the Subscription was created.
cancelled timestamp The unix timestamp of when the Subscription was cancelled. If this is null, the Subscription is still active.
amount integer The amount of the Subscription, in cents (e.g. $8.00 = “800”).
currency string The 3-letter ISO-4217 formatted currency code.
interval string The interval at which the Subscription is charged. Defaults to “monthly”. Valid values are “monthly” or “weekly”.
currentPeriodStart timestamp The unix timestamp of when the current Subscription period began.
currentPeriodEnd timestamp The unix timestamp of when the current Subscription period ends. At this date the user will be charged and the Subscription period will roll over as specified by the interval.
gwid string The gwid of the user making the Subscription.
givenName string The given (first) name of the user.
familyName string The family (last) name of the user.
address1 string The first line of the user’s billing street address.
address2 string The second line of the user’s billing street address.
city string The city of user’s billing address.
state string The state of user’s billing address.
zip string The 5-digit zip code of user’s billing address.
country string The country of the user’s billing address.
email string The user’s email address used for this Subscription.
phone string The user’s phone number used for this Subscription.
employer string The user’s employer.
occupation string The user’s occupation.
ccNumLast4 string The last 4 digits of the card used for the Subscription.
ccExpMonth integer The month of the credit card’s expiration date, as a 2-digit number (e.g. March = 03).
ccExpYear integer The year of the credit card’s expiration date, as a 4-digit number.
ccType string The type of the credit card. Valid values are: “Visa”, “American Express”, “MasterCard”, “Discover”, “JCB”, “Diners Club” or “Unknown”.
processor string This string indicates which payment processor was used to charge this card.
processorPaymentData JSON A JSON of data needed to charge the card. The structure varies per payment processor.
tags JSON A JSON object for storing any additional Subscription parameters.
Example request #
curl -X POST -H "Content-Type: application/json" -H "Authorization: Bearer {oauth-access-token}" -d '{
  "amount": "800",
  "givenName": "First",
  "familyName": "Last",
  "address1": "123 Elmston Street",
  "address2": "4",
  "city": "Newt York",
  "state": "NYC",
  "zip": "10010",
  "country": "US",
  "gwid": "f238fafe-7f0f-454c-910b-9bedbc86d06b",
  "email": "example@email.com",
  "phone": "1235896839",
  "employer": "acme",
  "occupation": "test",
  "ccNum": "4242424242424242",
  "ccExpMonth": "08",
  "ccExpYear": "2016",
  "ccCvc": "667",
  "agreeToTerms": "True",
  "source": "",
  "submittingUrl": ""
}' "https://api.thegroundwork.com/payments/subscriptions"
Example response #
{
  "subscription": {
    "ccNumLast4": "4242",
    "ccExpMonth": 8,
    "currentPeriodStart": 1461017411,
    "currency": "USD",
    "id": "6fcfa88e02c84eaab6bdd6f3524f1545",
    "occupation": "test",
    "city": "Newt York",
    "zip": "10010",
    "processorPaymentData": {
      "customer": "cus_8ILFb21SewEDLh"
    },
    "employer": "acme",
    "state": "NYC",
    "currentPeriodEnd": 1463609411,
    "email": "example@email.com",
    "tags": {},
    "address1": "123 Elmston Street",
    "address2": "4",
    "familyName": "Last",
    "phone": "1235896839",
    "created": 1461017410,
    "country": "US",
    "interval": "monthly",
    "ccType": "Visa",
    "gwid": "f238fafe-7f0f-454c-910b-9bedbc86d06b",
    "amount": 800,
    "ccExpYear": 2016,
    "cancelled": null,
    "givenName": "First",
    "processor": "stripeinc"
  }
}

Get a Subscription #

https://api.thegroundwork.com/payments/subscriptions/{subscription-id}

Get a specific Subscription by its id.

Path parameters #
Parameter Description
subscription-id The unique identifier of the Subscription.
Response body parameters #
Parameter Type Description
id string The unique identifier for the Subscription.
created timestamp The unix timestamp of when the Subscription was created.
cancelled timestamp The unix timestamp of when the Subscription was cancelled. If this is null, the Subscription is still active.
amount integer The amount of the Subscription, in cents (e.g. $8.00 = “800”).
currency string The 3-letter ISO-4217 formatted currency code.
interval string The interval at which the Subscription is charged. Defaults to “monthly”. Valid values are “monthly” or “weekly”.
currentPeriodStart timestamp The unix timestamp of when the current Subscription period began.
currentPeriodEnd timestamp The unix timestamp of when the current Subscription period ends. At this date the user will be charged and the Subscription period will roll over as specified by the interval.
gwid string The gwid of the user making the Subscription.
givenName string The given (first) name of the user.
familyName string The family (last) name of the user.
address1 string The first line of the user’s billing street address.
address2 string The second line of the user’s billing street address.
city string The city of user’s billing address.
state string The state of user’s billing address.
zip string The 5-digit zip code of user’s billing address.
country string The country of the user’s billing address.
email string The user’s email address used for this Subscription.
phone string The user’s phone number used for this Subscription.
employer string The user’s employer.
occupation string The user’s occupation.
ccNumLast4 string The last 4 digits of the card used for the Subscription.
ccExpMonth integer The month of the credit card’s expiration date, as a 2-digit number (e.g. March = 03).
ccExpYear integer The year of the credit card’s expiration date, as a 4-digit number.
ccType string The type of the credit card. Valid values are: “Visa”, “American Express”, “MasterCard”, “Discover”, “JCB”, “Diners Club” or “Unknown”.
processor string This string indicates which payment processor was used to charge this card.
processorPaymentData JSON A JSON of data needed to charge the card. The structure varies per payment processor.
tags JSON A JSON object for storing any additional Subscription parameters.
Example request #
curl -X GET -H "Content-Type: application/json" -H "Authorization: Bearer {oauth-access-token}" "https://api.thegroundwork.com/payments/subscriptions/6fcfa88e02c84eaab6bdd6f3524f1545"
Example response #
{
  "subscription": {
    "ccNumLast4": "4242",
    "ccExpMonth": 8,
    "currentPeriodStart": 1461017411,
    "currency": "USD",
    "id": "6fcfa88e02c84eaab6bdd6f3524f1545",
    "occupation": "job",
    "city": "New York",
    "zip": "10010",
    "processorPaymentData": {
      "customer": "cus_8ILFb21SewEDLh"
    },
    "employer": "acme",
    "state": "NYC",
    "currentPeriodEnd": 1463609411,
    "email": "example@email.com",
    "tags": {},
    "address1": "123 Elmston Street",
    "address2": "4",
    "familyName": "Last",
    "phone": "1235896839",
    "created": 1461017410,
    "country": "US",
    "interval": "monthly",
    "ccType": "Visa",
    "gwid": "f238fafe-7f0f-454c-910b-9bedbc86d06b",
    "amount": 800,
    "ccExpYear": 2016,
    "cancelled": null,
    "givenName": "First",
    "processor": "stripeinc"
  }
}

Modify a Subscription #

https://api.thegroundwork.com/payments/subscriptions/{subscription-id}

Update an existing Subscription by its id, updating only parameters passed in the request body. Unpassed parameters will not be overwritten as blank. Subscriptions can be updated to change the recurring Donation amount, or to cancel the Subscription altogether.

Request body parameters #
Parameter Required Type Description
cancelled timestamp The unix timestamp of when the Subscription was cancelled. If this is null, the Subscription is still active.
amount integer The updated amount of the Subscription, in cents (e.g. $8.00 = “800”).
Response body parameters #
Parameter Type Description
id string The unique identifier for the Subscription.
created timestamp The unix timestamp of when the Subscription was created.
cancelled timestamp The unix timestamp of when the Subscription was cancelled. If this is null, the Subscription is still active.
amount integer The amount of the Subscription, in cents (e.g. $8.00 = “800”).
currency string The 3-letter ISO-4217 formatted currency code.
interval string The interval at which the Subscription is charged. Defaults to “monthly”. Valid values are “monthly” or “weekly”.
currentPeriodStart timestamp The unix timestamp of when the current Subscription period began.
currentPeriodEnd timestamp The unix timestamp of when the current Subscription period ends. At this date the user will be charged and the Subscription period will roll over as specified by the interval.
gwid string The gwid of the user making the Subscription.
givenName string The given (first) name of the user.
familyName string The family (last) name of the user.
address1 string The first line of the user’s billing street address.
address2 string The second line of the user’s billing street address.
city string The city of user’s billing address.
state string The state of user’s billing address.
zip string The 5-digit zip code of user’s billing address.
country string The country of the user’s billing address.
email string The user’s email address used for this Subscription.
phone string The user’s phone number used for this Subscription.
employer string The user’s employer.
occupation string The user’s occupation.
ccNumLast4 string The last 4 digits of the card used for the Subscription.
ccExpMonth integer The month of the credit card’s expiration date, as a 2-digit number (e.g. March = 03).
ccExpYear integer The year of the credit card’s expiration date, as a 4-digit number.
ccType string The type of the credit card. Valid values are: “Visa”, “American Express”, “MasterCard”, “Discover”, “JCB”, “Diners Club” or “Unknown”.
processor string This string indicates which payment processor was used to charge this card.
processorPaymentData JSON A JSON of data needed to charge the card. The structure varies per payment processor.
tags JSON JSON object for storing any additional Subscription parameters.
Example request #
curl -X PUT -H "Content-Type: application/json" -H "Authorization: Bearer {oauth-access-token}" -d '{
    "cancelled": 1460059
}' "https://api.thegroundwork.com/payments/subscriptions/35c280c41d994abcbffa2787a3d04e2e"
Example response #
{
  "subscription": {
    "ccNumLast4": "4242",
    "ccExpMonth": 8,
    "currentPeriodStart": 1460059147,
    "currency": "USD",
    "id": "35c280c41d994abcbffa2787a3d04e2e",
    "occupation": "test",
    "city": "Newt York",
    "zip": "10010",
    "processorPaymentData": {
      "customer": "cus_8EBeEYP2zLly1T"
    },
    "employer": "acme",
    "state": "NYC",
    "currentPeriodEnd": 1462651147,
    "email": "example@email.com",
    "tags": {},
    "address1": "123 Elmston Street",
    "address2": "4",
    "familyName": "Last",
    "phone": "1235896839",
    "created": 1460059146,
    "country": "US",
    "interval": "monthly",
    "ccType": "Visa",
    "gwid": "f238fafe-7f0f-454c-910b-9bedbc86d06b",
    "amount": 12490385930283,
    "ccExpYear": 2016,
    "cancelled": 1460059,
    "givenName": "First",
    "processor": "stripeinc"
  }
}

List all Subscriptions #

https://api.thegroundwork.com/payments/subscriptions

List all Subscriptions, and filter by request parameters.

Query string parameters #
Parameter Type Description
gwid string Return Subscriptions from the user with the corresponding gwid.
email string Return Subscriptions with the corresponding email address.
page integer A metadata parameter for specifying a page of results to return, with a default of 1.
perPage integer A metadata parameter for specifying number of results per page, with a default of 10 and a maximum of 50.

Note - Requests must include either gwid or email. If both are included, the query will filter based off of email.

Response body parameters #
Parameter Type Description
id string The unique identifier for the Subscription.
created timestamp The unix timestamp of when the Subscription was created.
cancelled timestamp The unix timestamp of when the Subscription was cancelled. If this is null, the Subscription is still active.
amount integer The amount of the Subscription, in cents (e.g. $8.00 = “800”).
currency string The 3-letter ISO-4217 formatted currency code.
interval string The interval at which the Subscription is charged. Defaults to “monthly”. Valid values are “monthly” or “weekly”.
currentPeriodStart timestamp The unix timestamp of when the current Subscription period began.
currentPeriodEnd timestamp The unix timestamp of when the current Subscription period ends. At this date the user will be charged and the Subscription period will roll over as specified by the interval.
gwid string The gwid of the user making the Subscription.
givenName string The given (first) name of the user.
familyName string The family (last) name of the user.
address1 string The first line of the user’s billing street address.
address2 string The second line of the user’s billing street address.
city string The city of user’s billing address.
state string The state of user’s billing address.
zip string The 5-digit zip code of user’s billing address.
country string The country of the user’s billing address.
email string The user’s email address used for this Subscription.
phone string The user’s phone number used for this Subscription.
employer string The user’s employer.
occupation string The user’s occupation.
ccNumLast4 string The last 4 digits of the card used for the Subscription.
ccExpMonth integer The month of the credit card’s expiration date, as a 2-digit number (e.g. March = 03).
ccExpYear integer The year of the credit card’s expiration date, as a 4-digit number.
ccType string The type of the credit card. Valid values are: “Visa”, “American Express”, “MasterCard”, “Discover”, “JCB”, “Diners Club” or “Unknown”.
processor string This string indicates which payment processor was used to charge this card.
processorPaymentData JSON A JSON of data needed to charge the card. The structure varies per payment processor.
tags JSON JSON object for storing any additional Subscription parameters.
Example request #
curl -X GET -H "Content-Type: application/json" -H "Authorization: Bearer {oauth-access-token}" "https://api.thegroundwork.com/payments/subscriptions?email=example@email.com&perPage=2"
Example response #
{
  "meta": {
    "count": 2,
    "totalPages": 5,
    "params": {
      "perPage": 2,
      "page": 1,
      "email": "example@email.com"
    }
  },
  "subscriptions": [
    {
      "ccNumLast4": "4242",
      "ccExpMonth": 8,
      "currentPeriodStart": 1461020479,
      "currency": "USD",
      "id": "0289c8914cf94e6bb664214d60b25508",
      "occupation": "test",
      "city": "Newt York",
      "zip": "10010",
      "processorPaymentData": {
        "customer": "cus_8IM4pN5r4qR5tk"
      },
      "employer": "acme",
      "state": "NYC",
      "currentPeriodEnd": 1461625279,
      "email": "example@email.com",
      "tags": {},
      "address1": "123 Elmston Street",
      "address2": "4",
      "familyName": "Last",
      "phone": "1235896839",
      "created": 1461020478,
      "country": "US",
      "interval": "weekly",
      "ccType": "Visa",
      "gwid": "f238fafe-7f0f-454c-910b-9bedbc86d06b",
      "amount": 800,
      "ccExpYear": 2016,
      "cancelled": null,
      "givenName": "First",
      "processor": "stripeinc"
    },
    {
      "ccNumLast4": "4242",
      "ccExpMonth": 8,
      "currentPeriodStart": 1461020206,
      "currency": "USD",
      "id": "c8ecb77e767b4b81859920eace1ace04",
      "occupation": "test",
      "city": "Newt York",
      "zip": "10010",
      "processorPaymentData": {
        "customer": "cus_8IM0np6eUXG6AM"
      },
      "employer": "acme",
      "state": "NYC",
      "currentPeriodEnd": 1463612206,
      "email": "example@email.com",
      "tags": {},
      "address1": "123 Elmston Street",
      "address2": "4",
      "familyName": "Last",
      "phone": "1235896839",
      "created": 1461020205,
      "country": "US",
      "interval": "monthly",
      "ccType": "Visa",
      "gwid": "f238fafe-7f0f-454c-910b-9bedbc86d06b",
      "amount": 800,
      "ccExpYear": 2016,
      "cancelled": null,
      "givenName": "First",
      "processor": "stripeinc"
    }
  ]
}

QuickCards #

A QuickCard represents a credit card the user has saved to quickly and easily use again. The card details are not stored within the Groundwork database, but instead at the payment processor. A user can have any number of QuickCards, and QuickCards can not be made anonymously.

Create a QuickCard #

https://api.thegroundwork.com/payments/quickcards

Create a QuickCard.

Request body parameters #
Parameter Required Type Description
gwid string The gwid of the user who is creating the QuickCard.
givenName string The given (first) name of the user.
familyName string The family (last) name of the user.
address1 string The first line of the user’s billing street address.
address2 string The second line of the user’s billing street address.
city string The city of the user’s billing address.
state string The state of the user’s billing address.
zip string The 5-digit zip code of the user’s billing address.
country string The country of the user’s billing address.
email string The user’s email address.
phone string The user’s phone number.
employer string The user’s employer.
occupation string The user’s occupation.
ccNum string The credit card number for the QuickCard, as a string and with no separators.
ccExpMonth integer The month of the credit card expiration date, as a 2-digit number (e.g. March = 03).
ccExpYear integer The year of the credit card expiration date, as a 4-digit number.
ccCvc string The CVC for the credit card.
tags JSON A JSON object for storing any additional QuickCard parameters.
agreeToTerms boolean A boolean indicating whether or not the user agreed to the legal terms around donating.
source string The source of the QuickCard, for analytics purposes (e.g. “home page donate form”).
submittingUrl string The URL of the page submitting the donation.
emailTemplate string The name of the email template used to generate the email receipt.
sendEmail boolean A boolean indicating whether an email should be sent upon successful QuickCard creation, notifying the user of a saved card. If not provided, the default value is “true”.
Response body parameters #
Parameter Type Description
gwid string The gwid of the user associated with the QuickCard.
id string The unique identifier for the QuickCard.
created timestamp The unix timestamp of when the QuickCard was created.
deleted timestamp The unix timestamp of when the QuickCard was deleted. If this is null, the QuickCard is still active.
givenName string The given (first) name of the user.
familyName string The family (last) name of the user.
address1 string The first line of the user’s billing street address.
address2 string The second line of the user’s billing street address.
city string The city of the user’s billing address.
state string The state of the user’s billing address.
zip string The 5-digit zip code of the user’s billing address.
country string The country of the user’s billing address.
email string The user’s email address.
phone string The user’s phone number.
employer string The user’s employer.
occupation string The user’s occupation.
ccNumLast4 string The last 4 numbers of the credit card on the QuickCard.
ccExpMonth integer The month of the credit card expiration date, as a 2-digit number (e.g. March = 03).
ccExpyear integer The year of the credit card expiration date, as a 4-digit number.
ccType string The type of the credit card. Valid values are: “Visa”, “American Express”, “MasterCard”, “Discover”, “JCB”, “Diners Club” or “Unknown”.
processor string This string indicates which payment processor was used to charge this card.
processorPaymentData JSON A JSON of data needed to charge the card. The structure varies per payment processor.
tags JSON A JSON object for storing any additional QuickCard parameters.
Example request #
curl -X POST -H "Content-Type: application/json" -H "Authorization: Bearer {oauth-access-token}" -d '{
  "amount": 2000,
  "givenName": "John",
  "familyName": "Doe",
  "address1": "123 Main St",
  "city": "New York City",
  "state": "NY",
  "zip": "11201",
  "country": "US",
  "gwid": "f238fafe-7f0f-454c-910b-9bedbc86d06b",
  "email": "example@email.com",
  "phone": "1231231234",
  "employer": "Acme",
  "occupation": "Coyote",
  "ccNum": "4242424242424242",
  "ccExpMonth": 12,
  "ccExpYear": 2020,
  "ccCvc": "123",
  "agreeToTerms": true
}' "https://api.thegroundwork.com/payments/quickcards"
Example response #
{
  "quickCard": {
    "ccNumLast4": "4242",
    "ccExpMonth": 12,
    "id": "fc2b9dd2c1ec4a6386f6f5966417d24a",
    "occupation": "Coyote",
    "city": "New York City",
    "zip": "11201",
    "employer": "Acme",
    "paymentData": null,
    "state": "NY",
    "email": "example@email.com",
    "tags": {},
    "deleted": null,
    "address1": "123 Main St",
    "address2": "",
    "familyName": "Doe",
    "phone": "1231231234",
    "created": 1461031211,
    "country": "US",
    "ccType": "Visa",
    "gwid": "f238fafe-7f0f-454c-910b-9bedbc86d06b",
    "processorPaymentData": {
      "customer": "cus_8IOxVNdyyYF8F7"
    },
    "ccExpYear": 2020,
    "givenName": "John",
    "processor": "stripeinc"
  }
}

Get a QuickCard #

https://api.thegroundwork.com/payments/quickcards/{quickcard-id}

Get a specific QuickCard by its id.

Path parameters #
Parameter Description
quickcard-id The unique identifier of the QuickCard.
Response body parameters #
Parameter Type Description
gwid string The gwid of the user associated with the QuickCard.
id string The unique identifier for the QuickCard.
created timestamp The unix timestamp of when the QuickCard was created.
deleted timestamp The unix timestamp of when the QuickCard was deleted. If this is null, the QuickCard is still active.
givenName string The given (first) name of the user.
familyName string The family (last) name of the user.
address1 string The first line of the user’s billing street address.
address2 string The second line of the user’s billing street address.
city string The city of the user’s billing address.
state string The state of the user’s billing address.
zip string The 5-digit zip code of the user’s billing address.
country string The country of the user’s billing address.
email string The user’s email address.
phone string The user’s phone number.
employer string The user’s employer.
occupation string The user’s occupation.
ccNumLast4 string The last 4 numbers of the credit card on the QuickCard.
ccExpMonth integer The month of the credit card expiration date, as a 2-digit number (e.g. March = 03).
ccExpYear integer The year of the credit card expiration date, as a 4-digit number.
ccType string The type of the credit card. Valid values are: “Visa”, “American Express”, “MasterCard”, “Discover”, “JCB”, “Diners Club” or “Unknown”.
processor string This string indicates which payment processor was used to charge this card.
processorPaymentData JSON A JSON of data needed to charge the card. The structure varies per payment processor.
tags JSON A JSON object for storing any additional QuickCard parameters.
Example request #
curl -X GET -H "Content-Type: application/json" -H "Authorization: Bearer {oauth-access-token}" "https://api.thegroundwork.com/payments/quickcards/fc2b9dd2c1ec4a6386f6f5966417d24a"
Example response #
{
  "quickCard": {
    "ccNumLast4": "4242",
    "ccExpMonth": 12,
    "id": "fc2b9dd2c1ec4a6386f6f5966417d24a",
    "occupation": "Coyote",
    "city": "New York City",
    "zip": "11201",
    "employer": "Acme",
    "paymentData": null,
    "state": "NY",
    "email": "example@email.com",
    "tags": {},
    "deleted": null,
    "address1": "123 Main St",
    "address2": "",
    "familyName": "Doe",
    "phone": "1231231234",
    "created": 1461031211,
    "country": "US",
    "ccType": "Visa",
    "gwid": "f238fafe-7f0f-454c-910b-9bedbc86d06b",
    "processorPaymentData": {
      "customer": "cus_8IOxVNdyyYF8F7"
    },
    "ccExpYear": 2020,
    "givenName": "John",
    "processor": "stripeinc"
  }
}

Delete a QuickCard #

https://api.thegroundwork.com/payments/quickcards/{quickcard-id}

Delete a QuickCard by its id. Set the deleted field to a Unix epoch timestamp. Only the deleted field will be updated.

Path parameters #
Parameter Description
quickcard-id The unique identifier of the QuickCard.
Request body parameters #
Parameter Required Type Description
deleted timestamp The unix timestamp of when the QuickCard was deleted.
Response body parameters #
Parameter Type Description
gwid string The gwid of the user associated with the QuickCard.
id string The unique identifier for the QuickCard.
created timestamp The unix timestamp of when the QuickCard was created.
deleted timestamp The unix timestamp of when the QuickCard was deleted. If this is null, the QuickCard is still active.
givenName string The given (first) name of the user.
familyName string The family (last) name of the user.
address1 string The first line of the user’s billing street address.
address2 string The second line of the user’s billing street address.
city string The city of the user’s billing address.
state string The state of the user’s billing address.
zip string The 5-digit zip code of the user’s billing address.
country string The country of the user’s billing address.
email string The user’s email address.
phone string The user’s phone number.
employer string The user’s employer.
occupation string The user’s occupation.
ccNumLast4 string The last 4 numbers of the credit card on the QuickCard.
ccExpMonth integer The month of the credit card expiration date, as a 2-digit number (e.g. March = 03).
ccExpYear integer The year of the credit card expiration date, as a 4-digit number.
ccType string The type of the credit card. Valid values are: “Visa”, “American Express”, “MasterCard”, “Discover”, “JCB”, “Diners Club” or “Unknown”.
processor string This string indicates which payment processor was used to charge this card.
processorPaymentData JSON A JSON of data needed to charge the card. The structure varies per payment processor.
tags JSON A JSON object for storing any additional QuickCard parameters.
Example request #
curl -X PUT -H "Content-Type: application/json" -H "Authorization: Bearer {oauth-access-token}" -d '{
  "deleted": 1441155636
}' "https://api.thegroundwork.com/payments/quickcards/1b9c17490cd2494699ca163d52f6c92e"
Example response #
{
  "quickCard": {
    "ccNumLast4": "4242",
    "ccExpMonth": 12,
    "id": "1b9c17490cd2494699ca163d52f6c92e",
    "occupation": "Coyote",
    "city": "New York City",
    "zip": "11201",
    "employer": "Acme",
    "paymentData": null,
    "state": "NY",
    "email": "example@email.com",
    "tags": {},
    "deleted": 1441155636,
    "address1": "123 Main St",
    "address2": "",
    "familyName": "Doe",
    "phone": "1231231234",
    "created": 1460062819,
    "country": "US",
    "ccType": "Visa",
    "gwid": "f238fafe-7f0f-454c-910b-9bedbc86d06b",
    "processorPaymentData": {
      "customer": "cus_8ECdq57rkDw9jA"
    },
    "ccExpYear": 2020,
    "givenName": "John",
    "processor": "stripeinc"
  }
}

Make a Quick Donation #

https://api.thegroundwork.com/payments/quickcards/{quickcard-id}/donations

Create a Quick Donation using a stored and active QuickCard (the QuickCard must have a deleted value of null).

Path parameters #
Parameter Description
quickcard-id The unique identifier of the QuickCard.
Request body parameters #
Parameter Required Type Description
amount integer The amount of the Donation, in cents (e.g. $8.00 = “800”).
cartId string Unique identifier for the cart this Donation fulfills.
gwid string The gwid of the user associated with the QuickCard.
submittingUrl string The URL of the page submitting the donation.
tags JSON A JSON object for storing any additional Quick Donation parameters.
emailTemplate string The name of the email template used to generate the email receipt.
sendEmail boolean A boolean indicating whether an email should be sent upon successful Quick Donation. If not provided, the default value is “true”.
Response body parameters #
Parameter Type Description
gwid string The gwid of the user associated with the QuickCard.
id string The unique identifier of the Quick Donation.
quickCard string The unique identifier of the QuickCard.
subscription string The unique identifier of the Subscription the Quick Donation belongs to, if it is from a Subscription.
amount integer The amount of the Subscription, in cents (e.g. $8.00 = “800”).
currency string The 3-letter ISO-4217 formatted currency code.
created timestamp The unix timestamp of when the QuickCard was created.
deleted timestamp The unix timestamp of when the QuickCard was deleted. If this is null, the QuickCard is still active.
givenName string The given (first) name of the user.
familyName string The family (last) name of the user.
address1 string The first line of the user’s billing street address.
address2 string The second line of the user’s billing street address.
city string The city of the user’s billing address.
state string The state of the user’s billing address.
zip string The 5-digit zip code of the user’s billing address.
country string The country of the user’s billing address.
email string The user’s email address.
phone string The user’s phone number.
employer string The user’s employer.
occupation string The user’s occupation.
processor string This string indicates which payment processor was used to charge this card.
processorPaymentData JSON A JSON of data needed to charge the card. The structure varies per payment processor.
tags JSON A JSON object for storing any additional Quick Donation parameters.
Example request #
curl -X POST -H "Content-Type: application/json" -H "Authorization: Bearer {oauth-access-token}" -d '{
  "amount": 2000,
  "cartId": "",
  "gwid": "f238fafe-7f0f-454c-910b-9bedbc86d06b"
}' "https://api.thegroundwork.com/payments/quickcards/fc2b9dd2c1ec4a6386f6f5966417d24a/donations"
Example response #
{
  "donation": {
    "currency": "USD",
    "id": "9ce7aad21f8e419ea40b152d0a637e66",
    "occupation": "Coyote",
    "city": "New York City",
    "quickCard": "fc2b9dd2c1ec4a6386f6f5966417d24a",
    "zip": "11201",
    "processorPaymentData": {
      "chargeId": "ch_181opnGqCW8jAjllT58PARYP",
      "cardId": "card_181o9vGqCW8jAjll4cFnvqQJ"
    },
    "employer": "Acme",
    "state": "NY",
    "paymentMethod": "card",
    "email": "example@email.com",
    "tags": {},
    "deleted": null,
    "address1": "123 Main St",
    "address2": "",
    "familyName": "Doe",
    "phone": "1231231234",
    "subscription": "",
    "created": 1461033808,
    "country": "US",
    "gwid": "f238fafe-7f0f-454c-910b-9bedbc86d06b",
    "amount": 2000,
    "givenName": "John",
    "processor": "stripeinc"
  }
}

List all QuickCards #

https://api.thegroundwork.com/payments/quickcards

List all QuickCards, and filter by request parameters. Only QuickCard objects with params corresponding to the Bearer token will be returned.

Query string parameters #
Parameter Type Description
gwid string Return QuickCards from the user with the corresponding gwid.
email string Return QuickCards with the corresponding email address.
page integer A metadata parameter for specifying a page of results to return, with a default of 1.
perPage integer A metadata parameter for specifying number of results per page, with a default of 10 and a maximum of 50.

Note - Requests must include either gwid or email. If both are included, the query will filter based off of email.

Response body parameters #
Parameter Type Description
gwid string The gwid of the user associated with the QuickCard.
id string The unique identifier of the Quick Donation.
quickCard string The unique identifier of the QuickCard.
subscription string The unique identifier of the Subscription the Quick Donation belongs to, if it is from a Subscription.
amount integer The amount of the Subscription, in cents (e.g. $8.00 = “800”).
currency string The 3-letter ISO-4217 formatted currency code.
created timestamp The unix timestamp of when the QuickCard was created.
deleted timestamp The unix timestamp of when the QuickCard was deleted. If this is null, the QuickCard is still active.
givenName string The given (first) name of the user.
familyName string The family (last) name of the user.
address1 string The first line of the user’s billing street address.
address2 string The second line of the user’s billing street address.
city string The city of the user’s billing address.
state string The state of the user’s billing address.
zip string The 5-digit zip code of the user’s billing address.
country string The country of the user’s billing address.
email string The user’s email address.
phone string The user’s phone number.
employer string The user’s employer.
occupation string The user’s occupation.
processor string This string indicates which payment processor was used to charge this card.
processorPaymentData JSON A JSON of data needed to charge the card. The structure varies per payment processor.
tags JSON A JSON object for storing any additional Quick Donation parameters.
Example request #
curl -X GET -H "Content-Type: application/json" -H "Authorization: Bearer {oauth-access-token}" "https://api.thegroundwork.com/payments/quickcards?gwid=f238fafe-7f0f-454c-910b-9bedbc86d06b&perPage=2"
Example response #
{
  "quickCards": [
    {
      "ccNumLast4": "4242",
      "ccExpMonth": 12,
      "id": "f463967db42c40afa486d0ad3cc56395",
      "occupation": "Coyote",
      "city": "New York City",
      "zip": "11201",
      "employer": "Acme",
      "paymentData": null,
      "state": "NY",
      "email": "example@email.com",
      "tags": {},
      "deleted": null,
      "address1": "123 Main St",
      "address2": "",
      "familyName": "Doe",
      "phone": "1231231234",
      "created": 1461034478,
      "country": "US",
      "ccType": "Visa",
      "gwid": "f238fafe-7f0f-454c-910b-9bedbc86d06b",
      "processorPaymentData": {
        "customer": "cus_8IPqmUOo6kkMSi"
      },
      "ccExpYear": 2020,
      "givenName": "John",
      "processor": "stripeinc"
    },
    {
      "ccNumLast4": "4242",
      "ccExpMonth": 12,
      "id": "9e6429dc4f2040a2844fbff7a33c9192",
      "occupation": "Coyote",
      "city": "New York City",
      "zip": "11201",
      "employer": "Acme",
      "paymentData": null,
      "state": "NY",
      "email": "example@email.com",
      "tags": {},
      "deleted": null,
      "address1": "123 Main St",
      "address2": "",
      "familyName": "Doe",
      "phone": "1231231234",
      "created": 1461034077,
      "country": "US",
      "ccType": "Visa",
      "gwid": "f238fafe-7f0f-454c-910b-9bedbc86d06b",
      "processorPaymentData": {
        "customer": "cus_8IPj1faIekrk9u"
      },
      "ccExpYear": 2020,
      "givenName": "John",
      "processor": "stripeinc"
    }
  ],
  "meta": {
    "count": 2,
    "totalPages": 5,
    "params": {
      "perPage": 2,
      "page": 1,
      "gwid": "f238fafe-7f0f-454c-910b-9bedbc86d06b"
    }
  }
}

Service health #

The service health requests return a JSON object containing information about the status of the Groundwork Payments service as well as availability of specific functionality. Although uncommon, if repeated failed calls occurs please contact support@timshel.com.

Check Payments health #

https://api.thegroundwork.com/payments/health

Get version number and service status only.

Response body parameters #
Parameter Type Description
version string The version number of the Groundwork Payments service in use.
credit_card_transactions boolean A boolean indicating whether or not credit card payments are currently operational.
ach_transactions boolean A boolean indicating whether or not ACH payments are currently operational. ACH transactions are only available on certain Enterprise licenses.

Note - ACH transactions are only available upon request with certain Groundwork licenses. Please contact support@timshel.com if you would like to support ACH and currently do not.

Example request #
curl -X GET -H "Content-Type: application/json" -H "Authorization: Bearer {oauth-access-token}" "https://api.thegroundwork.com/payments/health"
Example response #
{
  "ach_transactions": true,
  "version": "1.2.1",
  "credit_card_transactions": true
}

Check Payments health and available methods #

https://api.thegroundwork.com/payments/health/features

Get version number, service status, and available HTTP methods.

Response body parameters #
Parameter Type Description
version string The version number of the Groundwork Payments service in use.
features JSON A JSON containing information on which Payment methods are currently operational.
allowed_methods JSON A JSON containing information on which HTTP methods are allowed on Subscriptions, QuickCards, and Donations.
Example request #
curl -X GET -H "Content-Type: application/json" -H "Authorization: Bearer {oauth-access-token}" "https://api.thegroundwork.com/payments/health/features"
Example response #
{
  "version": "1.2.1",
  "allowed_methods": {
    "quickcards": [
      "GET",
      "POST",
      "PUT"
    ],
    "donations": [
      "GET",
      "POST",
      "PUT"
    ],
    "subscriptions": [
      "GET",
      "POST",
      "PUT"
    ]
  },
  "features": {
    "ach_transactions": true,
    "credit_card_transactions": true
  }
}

Peer-to-Peer Fundraising #

Overview #

Using Groundwork Peer-to-Peer Fundraising (P2P), members of your community can create public Fundraiser pages and solicit donations on your organization’s behalf. Donations made through Fundraiser pages flow directly to your organization and are attributed to the Fundraiser for reporting purposes.

The feature consists of three main objects, Campaign, Fundraiser and Donation. A Campaign represents a particular fundraising effort by your organization (e.g “2016 Walkathon”). A Fundraiser represents a web page created by a member of the public to raise money for one Campaign. A Donation represents the money donated by one person to one Fundraiser at one point in time.

Campaigns #

Campaigns are created and managed by administrators via Admin. GET requests, for example to list Campaigns on your organization’s website, may be made using public client authentication.

List all Campaigns #

https://api.thegroundwork.com/p2p/campaigns

List all visible Campaigns, and filter by request parameters.

Query string parameters #
Parameter Type Description
startsBefore string Return Campaigns starting before this ISO-8601 datetime.
startsAfter string Return Campaigns starting after this ISO-8601 datetime.
endsBefore string Return Campaigns ending before this ISO-8601 datetime.
endsAfter string Return Campaigns ending after this ISO-8601 datetime.
page integer A metadata parameter for specifying a page of results to return.
perPage integer A metadata parameter for specifying number of results per page.
Response body parameters #
Parameter Type Description
amountRaised integer The current sum of all donations attributed to this Campaign, given in the least-significant unit of the currency, e.g. cents.
created string The ISO-8601 formatted creation time of the Campaign, given in UTC.
currency string The ISO-4217 currency code for all the Campaign’s donations.
description string The Campaign description.
fundraiserGoalSuggestion integer The monetary amount to recommend for new Fundraisers in this Campaign, given in the least-significant unit of the currency, e.g. cents.
goal integer The monetary target for the Campaign, given in the least-significant unit of the currency, e.g. cents.
id string The unique identifier for the Campaign.
imageUrl string A URL for an image file to display for the Campaign.
initiativeId string The Groundwork Initiative to which the Campaign belongs.
timeEnd string The ISO-8601 formatted end time of the Campaign, given in UTC.
timeStart string The ISO-8601 formatted start time of the Campaign, given in UTC.
title string The Campaign title.
visible boolean A flag indicating whether the Campaign is publicly visible. Only Admin users may view a Campaign where visible is false.
Example request #
curl -X GET -H "Content-Type: application/json" -H "Authorization: Basic {client-id}" "https://api.thegroundwork.com/p2p/campaigns"
Example response #
{
    "meta": {
        "count": 2,
        "params": {
            "page": 1,
            "perPage": 10
        },
        "total": 2,
        "totalPages": 1
    },
    "results": [
        {
            "amountRaised": 0,
            "created": "2016-09-23T22:15:35Z",
            "currency": "USD",
            "description": "Let's save some puppies!",
            "fundraiserGoalSuggestion": 20000,
            "goal": 100000,
            "id": "8873f6d3-059c-4734-af4b-cca5cb817256",
            "imageUrl": "http://example.com/img.jpg",
            "initiativeId": "gw.test",
            "timeEnd": "2017-04-20T00:00:00Z",
            "timeStart": "2016-12-12T00:00:00Z",
            "title": "Puppies are great!",
            "visible": true
        },
        {
            "amountRaised": 50000,
            "created": "2016-09-23T22:01:12Z",
            "currency": "USD",
            "description": "Help us build a new science lab!",
            "fundraiserGoalSuggestion": 40000,
            "goal": 100000,
            "id": "5212fe10-fa3f-4cb6-b02c-4eb633630ec8",
            "imageUrl": "http://example.com/img.jpg",
            "initiativeId": "gw.test",
            "timeEnd": "2017-04-20T00:00:00Z",
            "timeStart": "2016-12-12T00:00:00Z",
            "title": "Washington Elementary Science Lab",
            "visible": true
        }
    ]
}

Get a Campaign #

https://api.thegroundwork.com/p2p/campaigns/{campaign-id}

Get a specific Campaign by its id.

Path parameters #
Parameter Description
campaign-id The unique identifier of the Campaign.
Response body parameters #
Parameter Type Description
amountRaised integer The current sum of all donations attributed to this Campaign, given in the least-significant unit of the currency, e.g. cents.
created string The ISO-8601 formatted creation time of the Campaign, given in UTC.
currency string The ISO-4217 currency code for all the Campaign’s donations.
description string The Campaign description.
fundraiserGoalSuggestion integer The monetary amount to recommend for new Fundraisers in this Campaign, given in the least-significant unit of the currency, e.g. cents.
goal integer The monetary target for the Campaign, given in the least-significant unit of the currency, e.g. cents.
id string The unique identifier for the Campaign.
imageUrl string A URL for an image file to display for the Campaign.
initiativeId string The Groundwork Initiative to which the Campaign belongs.
timeEnd string The ISO-8601 formatted end time of the Campaign, given in UTC.
timeStart string The ISO-8601 formatted start time of the Campaign, given in UTC.
title string The Campaign title.
visible boolean A flag indicating whether the Campaign is publicly visible. Only Admin users may view a Campaign where visible is false.
Example request #
curl -X GET -H "Content-Type: application/json" -H "Authorization: Basic {client-id}" "https://api.thegroundwork.com/p2p/campaigns/5212fe10-fa3f-4cb6-b02c-4eb633630ec8"
Example response #
{
  "amountRaised": 50000,
  "created": "2016-09-23T22:01:12Z",
  "currency": "USD",
  "description": "Help us build a new science lab!",
  "fundraiserGoalSuggestion": 40000,
  "goal": 100000,
  "id": "5212fe10-fa3f-4cb6-b02c-4eb633630ec8",
  "imageUrl": "http://example.com/img.jpg",
  "initiativeId": "gw.test",
  "timeEnd": "2017-04-20T00:00:00Z",
  "timeStart": "2016-12-12T00:00:00Z",
  "title": "Washington Elementary Science Lab",
  "visible": true
}

Fundraisers #

Fundraisers are created by members of the community via a public-facing page hosted by your organization. To create or update a fundraiser, a user must have a Groundwork Profile and be logged in. In the case of updates, the logged-in user must be the Fundraiser’s owner (typically the user who created it). A given Profile may only own one Fundraiser per Campaign.

All Fundraiser requests except GET require an oauth access token as described here. GET requests can be made using public client authentication as described here.

Create a Fundraiser #

https://api.thegroundwork.com/p2p/campaigns/{campaign-id}/fundraisers

Create a new Fundraiser.

Path parameters #
Parameter Description
campaign-id The unique identifier of the Campaign.
Request body parameters #
Parameter Required Type Description
description string The Fundraiser description.
goal integer The monetary target for the Fundraiser, given in the least-significant unit of the currency, e.g. cents. This field is required.
imageUrl string A URL for an image file to display for the Fundraiser.
timeEnd string A ISO-8601 formatted end time of the Fundraiser, given in UTC.
timeStart string A ISO-8601 formatted start time of the Fundraiser, given in UTC.
title string The title of the Fundraiser.
visible boolean A flag indicating whether the Fundraiser is publicly visible. Only Admin users and the Fundraiser’s owner may view a Fundraiser where visible is false.
Response body parameters #
Parameter Type Description
amountRaised integer The current sum of all donations attributed to this Fundraiser, given in the least-significant unit of the currency, e.g. cents.
campaignId string The unique identifier for the Fundraiser’s Campaign.
created string An ISO-8601 formatted creation time of the Fundraiser, given in UTC.
currency string The ISO-4217 currency code set on the Fundraiser’s Campaign.
Description string The Fundraiser description.
goal integer The monetary target for the Fundraiser, given in the least-significant unit of the currency, e.g. cents.
id string The unique identifier for the Fundraiser.
imageUrl string A URL for an image file to display for the Fundraiser.
initiativeId string The Groundwork Initiative to which the Fundraiser belongs.
ownerGwid string The gwid of the user who created the Fundraiser.
ownerProfile object An object containing the owner’s givenName and familyName, as strings.
timeEnd string An ISO-8601 formatted end time of the Fundraiser, given in UTC.
timeStart string An ISO-8601 formatted start time of the Fundraiser, given in UTC.
title string The Fundraiser title.
visible boolean A flag indicating whether the Fundraiser is publicly visible. Only Admin users and the Fundraiser’s owner may view a Fundraiser where visible is false.
Example request #
curl -X POST -H "Content-Type: application/json" -H "Authorization: Bearer {oauth-access-token}" -d '{
  "description": "We can help together",
  "goal": 500000,
  "imageUrl": "http://example.com/img.jpg",
  "timeEnd": "2017-04-20T00:00:00Z",
  "timeStart": "2016-12-12T00:00:00Z",
  "title": "My Fundraiser",
  "visible": true
}' "https://api.thegroundwork.com/p2p/campaigns/8873f6d3-059c-4734-af4b-cca5cb817256/fundraisers"
Example response #
{
    "amountRaised": 0,
    "campaignId": "8873f6d3-059c-4734-af4b-cca5cb817256",
    "created": "2016-10-13T17:33:38Z",
    "currency": "USD",
    "description": "We can help together",
    "goal": 500000,
    "id": "21f2ef39-9ff7-4426-908a-1e02ebb645f5",
    "imageUrl": "http://example.com/img.jpg",
    "initiativeId": "gw.test",
    "ownerGwid": "f121d988-a3ab-4646-a1a6-0c8f0d18442e",
    "ownerProfile": {
        "familyName": "Smith",
        "givenName": "Jane"
    },
    "timeEnd": "2017-04-20T00:00:00Z",
    "timeStart": "2016-12-12T00:00:00Z",
    "title": "My Fundraiser",
    "visible": true
}

Get a Fundraiser #

https://api.thegroundwork.com/p2p/campaigns/{campaign-id}/fundraisers/{fundraiser-id}

Get a specific Fundraiser by its id.

Path parameters #
Parameter Description
campaign-id The unique identifier of the Fundraiser’s Campaign.
fundraiser-id The unique identifier of the Fundraiser.
Response body parameters #
Parameter Type Description
amountRaised integer The current sum of all donations attributed to this Fundraiser, given in the least-significant unit of the currency, e.g. cents.
campaignId string The unique identifier for the Fundraiser’s Campaign.
created string An ISO-8601 formatted creation time of the Fundraiser, given in UTC.
currency string The ISO-4217 currency code set on the Fundraiser’s Campaign.
Description string The Fundraiser description.
goal integer The monetary target for the Fundraiser, given in the least-significant unit of the currency, e.g. cents.
id string The unique identifier for the Fundraiser.
imageUrl string A URL for an image file to display for the Fundraiser.
initiativeId string The Groundwork Initiative to which the Fundraiser belongs.
ownerGwid string The gwid of the user who created the Fundraiser.
ownerProfile object An object containing the owner’s givenName and familyName, as strings.
timeEnd string An ISO-8601 formatted end time of the Fundraiser, given in UTC.
timeStart string An ISO-8601 formatted start time of the Fundraiser, given in UTC.
title string The Fundraiser title.
visible boolean A flag indicating whether the Fundraiser is publicly visible. Only Admin users and the Fundraiser’s owner may view a Fundraiser where visible is false.
Example request #
curl -X GET -H "Content-Type: application/json" -H "Authorization: Basic {client-id}" "https://api.thegroundwork.com/p2p/campaigns/8873f6d3-059c-4734-af4b-cca5cb817256/fundraisers/21f2ef39-9ff7-4426-908a-1e02ebb645f5"
Example response #
{
    "amountRaised": 0,
    "campaignId": "8873f6d3-059c-4734-af4b-cca5cb817256",
    "created": "2016-10-13T17:33:38Z",
    "currency": "USD",
    "description": "We can help together",
    "goal": 500000,
    "id": "21f2ef39-9ff7-4426-908a-1e02ebb645f5",
    "imageUrl": "http://example.com/img.jpg",
    "initiativeId": "gw.test",
    "ownerGwid": "f121d988-a3ab-4646-a1a6-0c8f0d18442e",
    "ownerProfile": {
        "familyName": "Smith",
        "givenName": "Jane"
    },
    "timeEnd": "2017-04-20T00:00:00Z",
    "timeStart": "2016-12-12T00:00:00Z",
    "title": "My Fundraiser",
    "visible": true
}

Update a Fundraiser (PATCH) #

https://api.thegroundwork.com/p2p/campaigns/{campaign-id}/fundraisers/{fundraiser-id}

Update a Fundraiser, by id

Path parameters #
Parameter Description
campaign-id The unique identifier of the Fundraiser’s Campaign.
fundraiser-id The unique identifier of the Fundraiser.
Request body parameters #

Any of:

Parameter Type Description
description string The Fundraiser description.
goal integer The monetary target for the Fundraiser, given in the least-significant unit of the currency, e.g. cents. This field is required.
imageUrl string A URL for an image file to display for the Fundraiser.
timeEnd string A ISO-8601 formatted end time of the Fundraiser, given in UTC.
timeStart string A ISO-8601 formatted start time of the Fundraiser, given in UTC.
title string The title of the Fundraiser.
visible boolean A flag indicating whether the Fundraiser is publicly visible. Only Admin users and the Fundraiser’s owner may view a Fundraiser where visible is false.

Note - Only the Fundraiser’s owner may update a Fundraiser.

Response body parameters #
Parameter Type Description
amountRaised integer The current sum of all donations attributed to this Fundraiser, given in the least-significant unit of the currency, e.g. cents.
campaignId string The unique identifier for the Fundraiser’s Campaign.
created string An ISO-8601 formatted creation time of the Fundraiser, given in UTC.
currency string The ISO-4217 currency code set on the Fundraiser’s Campaign.
Description string The Fundraiser description.
goal integer The monetary target for the Fundraiser, given in the least-significant unit of the currency, e.g. cents.
id string The unique identifier for the Fundraiser.
imageUrl string A URL for an image file to display for the Fundraiser.
initiativeId string The Groundwork Initiative to which the Fundraiser belongs.
ownerGwid string The gwid of the user who created the Fundraiser.
ownerProfile object An object containing the owner’s givenName and familyName, as strings.
timeEnd string An ISO-8601 formatted end time of the Fundraiser, given in UTC.
timeStart string An ISO-8601 formatted start time of the Fundraiser, given in UTC.
title string The Fundraiser title.
visible boolean A flag indicating whether the Fundraiser is publicly visible. Only Admin users and the Fundraiser’s owner may view a Fundraiser where visible is false.
Example request #
curl -X PATCH -H "Content-Type: application/json" -H "Authorization: Bearer {oauth-access-token}" -d '{
  "goal": 1000000
}' "https://api.thegroundwork.com/p2p/campaigns/8873f6d3-059c-4734-af4b-cca5cb817256/fundraisers/21f2ef39-9ff7-4426-908a-1e02ebb645f5"
Example response #
{
    "amountRaised": 0,
    "campaignId": "8873f6d3-059c-4734-af4b-cca5cb817256",
    "created": "2016-10-13T17:33:38Z",
    "currency": "USD",
    "description": "We can help together",
    "goal": 1000000,
    "id": "21f2ef39-9ff7-4426-908a-1e02ebb645f5",
    "imageUrl": "http://example.com/img.jpg",
    "initiativeId": "gw.test",
    "ownerGwid": "f121d988-a3ab-4646-a1a6-0c8f0d18442e",
    "ownerProfile": {
        "familyName": "Smith",
        "givenName": "Jane"
    },
    "timeEnd": "2017-04-20T00:00:00Z",
    "timeStart": "2016-12-12T00:00:00Z",
    "title": "My Fundraiser",
    "visible": true
}

Update a Fundraiser (PUT) #

https://api.thegroundwork.com/p2p/campaigns/{campaign-id}/fundraisers/{fundraiser-id}

Update a Fundraiser, by id. All fields are updated. If an optional field is not provided, it will be overwritten as blank.

Path parameters #
Parameter Description
campaign-id The unique identifier of the Fundraiser’s Fundraiser.
fundraiser-id The unique identifier of the Fundraiser.
Request body parameters #
Parameter Required Type Description
description string The Fundraiser description.
goal integer The monetary target for the Fundraiser, given in the least-significant unit of the currency, e.g. cents. This field is required.
imageUrl string A URL for an image file to display for the Fundraiser.
timeEnd string A ISO-8601 formatted end time of the Fundraiser, given in UTC.
timeStart string A ISO-8601 formatted start time of the Fundraiser, given in UTC.
title string The title of the Fundraiser.
visible boolean A flag indicating whether the Fundraiser is publicly visible. Only Admin users and the Fundraiser’s owner may view a Fundraiser where visible is false.

Note - Only the Fundraiser’s owner may update a Fundraiser.

Response body parameters #
Parameter Type Description
amountRaised integer The current sum of all donations attributed to this Fundraiser, given in the least-significant unit of the currency, e.g. cents.
campaignId string The unique identifier for the Fundraiser’s Campaign.
created string An ISO-8601 formatted creation time of the Fundraiser, given in UTC.
currency string The ISO-4217 currency code set on the Fundraiser’s Campaign.
Description string The Fundraiser description.
goal integer The monetary target for the Fundraiser, given in the least-significant unit of the currency, e.g. cents.
id string The unique identifier for the Fundraiser.
imageUrl string A URL for an image file to display for the Fundraiser.
initiativeId string The Groundwork Initiative to which the Fundraiser belongs.
ownerGwid string The gwid of the user who created the Fundraiser.
ownerProfile object An object containing the owner’s givenName and familyName, as strings.
timeEnd string An ISO-8601 formatted end time of the Fundraiser, given in UTC.
timeStart string An ISO-8601 formatted start time of the Fundraiser, given in UTC.
title string The Fundraiser title.
visible boolean A flag indicating whether the Fundraiser is publicly visible. Only Admin users and the Fundraiser’s owner may view a Fundraiser where visible is false.
Example request #
curl -X PUT -H "Content-Type: application/json" -H "Authorization: Bearer {oauth-access-token}" -d '{
  "goal": 2000000,
  "imageUrl": "http://example.com/img.jpg",
  "timeEnd": "2016-05-01T00:00:00Z",
  "timeStart": "2016-12-12T00:00:00Z",
  "title": "My Updated Fundraiser",
  "visible": true
}' "https://api.thegroundwork.com/p2p/campaigns/8873f6d3-059c-4734-af4b-cca5cb817256/fundraisers/21f2ef39-9ff7-4426-908a-1e02ebb645f5"
Example response #
{
    "amountRaised": 0,
    "campaignId": "8873f6d3-059c-4734-af4b-cca5cb817256",
    "created": "2016-10-13T17:33:38Z",
    "currency": "USD",
    "description": "",
    "goal": 20000000,
    "id": "21f2ef39-9ff7-4426-908a-1e02ebb645f5",
    "imageUrl": "http://example.com/img.jpg",
    "initiativeId": "gw.test",
    "ownerGwid": "f121d988-a3ab-4646-a1a6-0c8f0d18442e",
    "ownerProfile": {
        "familyName": "Smith",
        "givenName": "Jane"
    },
    "timeEnd": "2017-05-01T00:00:00Z",
    "timeStart": "2016-12-12T00:00:00Z",
    "title": "My Fundraiser",
    "visible": true
}

List all Fundraisers #

https://api.thegroundwork.com/p2p/campaigns/{campaign-id}/fundraisers

List all visible Fundraisers for one Campaign, and filter by request parameters.

Query string parameters #
Parameter Type Description
startsBefore string Return Fundraisers starting before this ISO-8601 datetime.
startsAfter string Return Fundraisers starting after this ISO-8601 datetime.
endsBefore string Return Fundraisers ending before this ISO-8601 datetime.
endsAfter string Return Fundraisers ending after this ISO-8601 datetime.
ownerGwid string Return Fundraiser owned by the user with this gwid.
page integer A metadata parameter for specifying a page of results to return.
perPage integer A metadata parameter for specifying number of results per page.
Response body parameters #
Parameter Type Description
amountRaised integer The current sum of all donations attributed to this Fundraiser, given in the least-significant unit of the currency, e.g. cents.
campaignId string The unique identifier for the Fundraiser’s Campaign.
created string An ISO-8601 formatted creation time of the Fundraiser, given in UTC.
currency string The ISO-4217 currency code set on the Fundraiser’s Campaign.
Description string The Fundraiser description.
goal integer The monetary target for the Fundraiser, given in the least-significant unit of the currency, e.g. cents.
id string The unique identifier for the Fundraiser.
imageUrl string A URL for an image file to display for the Fundraiser.
initiativeId string The Groundwork Initiative to which the Fundraiser belongs.
ownerGwid string The gwid of the user who created the Fundraiser.
ownerProfile object An object containing the owner’s givenName and familyName, as strings.
timeEnd string An ISO-8601 formatted end time of the Fundraiser, given in UTC.
timeStart string An ISO-8601 formatted start time of the Fundraiser, given in UTC.
title string The Fundraiser title.
visible boolean A flag indicating whether the Fundraiser is publicly visible. Only Admin users and the Fundraiser’s owner may view a Fundraiser where visible is false.
Example request #
curl -X GET -H "Content-Type: application/json" -H "Authorization: Basic {client-id}" "https://api.thegroundwork.com/p2p/campaigns/8873f6d3-059c-4734-af4b-cca5cb817256/fundraisers/"
Example response #
{
    "meta": {
        "count": 2,
        "params": {
            "page": 1,
            "perPage": 10
        },
        "total": 2,
        "totalPages": 1
    },
    "results": [
        {
            "amountRaised": 1,
            "campaignId": "8873f6d3-059c-4734-af4b-cca5cb817256",
            "created": "2016-10-13T17:33:38Z",
            "currency": "USD",
            "description": "We can help together",
            "goal": 500000,
            "id": "21f2ef39-9ff7-4426-908a-1e02ebb645f5",
            "imageUrl": "http://example.com/img.jpg",
            "initiativeId": "gw.test",
            "ownerGwid": "f121d988-a3ab-4646-a1a6-0c8f0d18442e",
            "ownerProfile": {
                "familyName": "Smith",
                "givenName": "Jane"
            },
            "timeEnd": "2017-05-01T00:00:00Z",
            "timeStart": "2016-12-12T00:00:00Z",
            "title": "My Fundraiser",
            "visible": true
        },
        {
            "amountRaised": 1,
            "campaignId": "8873f6d3-059c-4734-af4b-cca5cb817256",
            "created": "2016-10-20T10:20:20Z",
            "currency": "USD",
            "description": "Help me save the stray puppers.",
            "goal": 100000,
            "id": "ef3db26bd39e41f5b10efdb4adbef670",
            "imageUrl": "http://example.com/img.jpg",
            "initiativeId": "gw.test",
            "ownerGwid": "d088ec91-a664-4aa1-bb8f-1944962bca33",
            "ownerProfile": {
                "familyName": "Stiles",
                "givenName": "Harry"
            },
            "timeEnd": "2017-05-01T00:00:00Z",
            "timeStart": "2017-01-02T00:00:00Z",
            "title": "Harry's Hopeful Hounds",
            "visible": true
        }
    ]
}

P2P Donations #

A Donation represents a contribution to one individual Fundraiser. To create a P2P Donation, pass a fundraising object while creating a generic Donation as described in Payments. The system automatically creates a P2P Donation when a generic Donation transaction containing a fundraising object succeeds.

GET requests, for example to list Donations on a Fundraiser page, may be made using public client authentication.

List all Donations #

https://api.thegroundwork.com/p2p/campaigns/{campaign-id}/fundraisers/{fundraiser-id}/donations

List all Donations for one Fundraiser, and filter by request parameters.

Query string parameters #
Parameter Type Description
createdAfter string Return Donations made after this ISO-8601 datetime.
createdBefore string Return Donations made before this ISO-8601 datetime.
page integer A metadata parameter for specifying a page of results to return.
perPage integer A metadata parameter for specifying number of results per page.
Response body parameters #
Parameter Type Description
amount integer The amount donated, given in the least-significant unit of the currency, e.g. cents.
anonymous boolean A flag indicating whether the donor chose to remain anonymous to the public when making the Donation. If true, the givenName, and familyName will be “” for users who aren’t Admins or the Fundraiser owner.
campaignId string The unique identifier of the Campaign to which the Donation belongs.
comment string A comment set by the donor when making the Donation.
created string The ISO-8601 formatted creation time of the Campaign, given in UTC.
currency string The ISO-4217 currency code the set on the Donations’s Campaign.
email string The email address of the donor. This field is only populated if the request comes from the Fundraiser’s owner.
familyName string The donor’s family name.
fundraiserId string The unique identifier of the Donation’s Fundraiser.
givenName string The donor’s given name.
id string The unique identifier of the P2P Donation.
initiativeId string The Groundwork Initiative to which the Donation belongs.
paymentId string The unique identifier of the Payment that generated this P2P Donation.
Example request #
curl -X GET -H "Content-Type: application/json" -H "Authorization: Basic {client-id}" "https://api.thegroundwork.com/p2p/campaigns/8873f6d3-059c-4734-af4b-cca5cb817256/fundraisers/21f2ef39-9ff7-4426-908a-1e02ebb645f5/donations"
Example response #
{
    "meta": {
        "count": 2,
        "params": {
            "page": 1,
            "perPage": 10
        },
        "total": 2,
        "totalPages": 1
    },
    "results": [
        "results": [
        {
          "amount": 5000,
          "anonymous": false,
          "campaignId": "8873f6d3-059c-4734-af4b-cca5cb817256",
          "comment": "Great job!",
          "created": "2016-11-21T19:04:24Z",
          "currency": "USD",
          "email": "john@example.com",
          "familyName": "Smith",
          "fundraiserId": "21f2ef39-9ff7-4426-908a-1e02ebb645f5",
          "givenName": "John",
          "id": "c98668d5-1b9e-48b5-9ba2-2ab8ca1cb4d2",
          "initiativeId": "gw.test",
          "paymentId": "855bb8540ca44331bd7dfb99a4711243"
        },
        {
          "amount": 1000,
          "anonymous": true,
          "campaignId": "8873f6d3-059c-4734-af4b-cca5cb817256",
          "comment": "Happy to help!",
          "created": "2016-11-29T10:20:15Z",
          "currency": "USD",
          "email": "jane@example.com",
          "familyName": "Doe",
          "fundraiserId": "21f2ef39-9ff7-4426-908a-1e02ebb645f5",
          "givenName": "Jane",
          "id": "a3e97698676a44abba53c45de0578c6d",
          "initiativeId": "gw.test",
          "paymentId": "9836efcc85414c6fa78b6e7360ff1e41"
        }
    ]
    ]
}

Get a Donation #

https://api.thegroundwork.com/p2p/campaigns/{campaign-id}

Get a specific Donation by its id.

Response body parameters #
Parameter Type Description
amountRaised integer The current sum of all donations attributed to this Campaign, given in the least-significant unit of the currency, e.g. cents.
created string The ISO-8601 formatted creation time of the Campaign, given in UTC.
currency string The ISO-4217 currency code for all the Campaign’s donations.
description string The Campaign description.
fundraiserGoalSuggestion integer The monetary amount to recommend for new Fundraisers in this Campaign, given in the least-significant unit of the currency, e.g. cents.
goal integer The monetary target for the Campaign, given in the least-significant unit of the currency, e.g. cents.
id string The unique identifier for the Campaign.
imageUrl string A URL for an image file to display for the Campaign.
initiativeId string The Groundwork Initiative to which the Campaign belongs.
timeEnd string The ISO-8601 formatted end time of the Campaign, given in UTC.
timeStart string The ISO-8601 formatted start time of the Campaign, given in UTC.
title string The Campaign title.
visible boolean A flag indicating whether the Campaign is publicly visible. Only Admin users may view a Campaign where visible is false.
Example request #
curl -X GET -H "Content-Type: application/json" -H "Authorization: Basic {client-id}" "https://api.thegroundwork.com/p2p/campaigns/8873f6d3-059c-4734-af4b-cca5cb817256/fundraisers/21f2ef39-9ff7-4426-908a-1e02ebb645f5/donations/c98668d5-1b9e-48b5-9ba2-2ab8ca1cb4d2"
Example response #
{
   "amount": 5000,
   "anonymous": false,
   "campaignId": "8873f6d3-059c-4734-af4b-cca5cb817256",
   "comment": "Great job!",
   "created": "2016-11-21T19:04:24Z",
   "currency": "USD",
   "email": "john@example.com",
   "familyName": "Smith",
   "fundraiserId": "21f2ef39-9ff7-4426-908a-1e02ebb645f5",
   "givenName": "John",
   "id": "c98668d5-1b9e-48b5-9ba2-2ab8ca1cb4d2",
   "initiativeId": "gw.test",
   "paymentId": "855bb8540ca44331bd7dfb99a4711243"
}

Profiles #

Overview #

Profiles allow for creating and managing user accounts. Creating a profile for a user results in that user being assigned a gwid. Profile email and passwords enable authentication. Anytime a user with a Profile takes an action while authenticated, that action is associated to their Profile via the user’s gwid. Profiles allow for a rich history of users’ actions across services. Groundwork Profiles supports profile creation, access, modification, email confirmation, and password management.

Authentication #

The Groundwork supports Profile creation through Facebook authentication and email address.

Password requirements #

All Profile passwords must:

  • be at least 8 characters long.
  • be less than 100 characters long.
  • contain an uppercase character.
  • contain a lowercase character.
  • contain a numeric character.

Gender parameter options #

The gender parameter must be an integer, of the following options:

  • 0 for “Male”.
  • 1 for “Female”.
  • 2 for “Other”.
  • 3 for “Choose not to answer”.

Profiles #

Create a Profile #

https://api.thegroundwork.com/the-claw/profiles

Create a new user Profile.

Note - Profiles can be created using an Authorization header of Basic base64({client-id} + ":"). The basic header enables unauthenticated account creation.

Request body parameters #
Parameter Required Type Description
gwid string The gwid of the user.
email string The user’s email address.
password string The user’s Profile password. See password requirements.
givenName string The given (first) name of the user.
familyName string The family (last) name of the user.
honorificPrefix string An honorific prefix like “Dr”, “Ms”, etc.
honorificSuffix string An honorific suffix like “Jr.”, “Ph.D”, etc.
dateOfBirth string The birth date of when the user was born. Formatted as YYYY-MM-DD.
gender integer An integer indicating the user’s gender. See the gender section for values.
genderIdentity string A string representing the user’s gender identity, in case they don’t identify with gender options.
address1 string The first line of the user’s street address.
address2 string The second line of the user’s street address.
locality string The city of the user’s address.
state string The 2-letter US state code of the user’s address.
zipCode string The 5-digit zip code of the user’s address.
phoneNumber string The user’s phone number.
employer string The user’s employer.
occupation string The user’s occupation.
Response body parameters #
Parameter Type Description
gwid string The gwid of the user.
email string The user’s email address.
givenName string The given (first) name of the user.
familyName string The family (last) name of the user.
honorificPrefix string An honorific prefix like “Dr”, “Ms”, etc.
honorificSuffix string An honorific suffix like “Jr.”, “Ph.D”, etc.
dateOfBirth string The birth date of when the user was born. Formatted as YYYY-MM-DD.
gender integer An integer indicating the user’s gender. See the gender section for values.
genderIdentity string A string representing the user’s gender identity, in case they don’t identify with gender options.
address1 string The first line of the user’s street address.
address2 string The second line of the user’s street address.
locality string The city of the user’s address.
state string The 2-letter US state code of the user’s address.
zipCode string The 5-digit zip code of the user’s address.
phoneNumber string The user’s phone number.
employer string The user’s employer.
occupation string The user’s occupation.
dateJoined timestamp The read-only ISO8601 formatted timestamp of when the Profile was created.
dateModified timestamp The read-only ISO8601 formatted timestamp of when the user last modified their Profile.
isConfirmed boolean Designates whether or not the user has confirmed their Profile. Assigned via the email confirmation endpoint.
confirmedAt timestamp The read-only ISO8601 formatted timestamp of when the user confirmed their email address. Assigned at the same time as isConfirmed.
socialaccounts array A read-only array of JSON objects specifying the network and remote_id of each social media authorization for the Profile.
authMethods array A read-only array of strings specifying the authorization methods supported for this Profile. Current values include facebook and password.
Example request #
curl -X POST -H "Content-Type: application/json" -H "Authorization: Basic {client-id}" -d '{
    "email": "email@email.com",
    "employer": "Timshel",
    "gender": 0,
    "confirmedAt": "2016-04-22T01:43:13.582178Z",
    "address": "123 Street",
    "zipCode": "12345"
}' "https://api.thegroundwork.com/the-claw/profiles"
Example response #
{
  "profile": {
    "gwid": "61b9fa74-d7d4-493a-8032-c38d901049d0",
    "email": "email@email.com",
    "isConfirmed": false,
    "confirmedAt": "2016-04-22T01:43:13.582178Z",
    "dateJoined": "2016-04-22T01:45:46.527320Z",
    "dateModified": "2016-04-22T01:45:46.527788Z",
    "dateOfBirth": null,
    "givenName": "",
    "familyName": "",
    "honorificPrefix": "",
    "honorificSuffix": "",
    "gender": 0,
    "genderIdentity": "",
    "employer": "Timshel",
    "occupation": "",
    "phoneNumber": "",
    "address1": "",
    "address2": "",
    "locality": "",
    "state": "",
    "zipCode": "12345",
    "socialaccounts": [],
    "authMethods": []
  }
}

Get a Profile #

https://api.thegroundwork.com/the-claw/profiles/{gwid}

Get a specific Profile by its gwid. Authorized users can only view the Profile associated with their gwid, while administrators can see any.

Path parameters #
Parameter Description
gwid The gwid of the user.
Response body parameters #
Parameter Type Description
gwid string The gwid of the user.
email string The user’s email address.
givenName string The given (first) name of the user.
familyName string The family (last) name of the user.
honorificPrefix string An honorific prefix like “Dr”, “Ms”, etc.
honorificSuffix string An honorific suffix like “Jr.”, “Ph.D”, etc.
dateOfBirth string The birth date of when the user was born. Formatted as YYYY-MM-DD.
gender integer An integer indicating the user’s gender. See the gender section for values.
genderIdentity string A string representing the user’s gender identity, in case they don’t identify with gender options.
address1 string The first line of the user’s street address.
address2 string The second line of the user’s street address.
locality string The city of the user’s address.
state string The 2-letter US state code of the user’s address.
zipCode string The 5-digit zip code of the user’s address.
phoneNumber string The user’s phone number.
employer string The user’s employer.
occupation string The user’s occupation.
dateJoined timestamp The read-only ISO8601 formatted timestamp of when the Profile was created.
dateModified timestamp The read-only ISO8601 formatted timestamp of when the user last modified their Profile.
isConfirmed boolean Designates whether or not the user has confirmed their Profile. Assigned via the email confirmation endpoint.
confirmedAt timestamp The read-only ISO8601 formatted timestamp of when the user confirmed their email address. Assigned at the same time as isConfirmed.
socialaccounts array A read-only array of JSON objects specifying the network and remote_id of each social media authorization for the Profile.
authMethods array A read-only array of strings specifying the authorization methods supported for this Profile. Current values include facebook and password.
Example request #
curl -X GET -H "Content-Type: application/json" -H "Authorization: Bearer {oauth-access-token}" "https://api.thegroundwork.com/the-claw/profiles/db834462-c089-41c2-87d0-57dfb54557e7"
Example response #
{
  "profile": {
    "gwid": "db834462-c089-41c2-87d0-57dfb54557e7",
    "email": "test8@gmail.com",
    "isConfirmed": false,
    "confirmedAt": null,
    "dateJoined": "2016-04-22T02:10:37.997640Z",
    "dateModified": "2016-04-22T02:10:37.998112Z",
    "dateOfBirth": null,
    "givenName": "",
    "familyName": "",
    "honorificPrefix": "",
    "honorificSuffix": "",
    "gender": 0,
    "genderIdentity": "",
    "employer": "Timshel",
    "occupation": "",
    "phoneNumber": "",
    "address1": "",
    "address2": "",
    "locality": "",
    "state": "",
    "zipCode": "",
    "socialaccounts": [],
    "authMethods": []
  }
}

Modify a Profile #

https://api.thegroundwork.com/the-claw/profiles/{gwid}

Update an existing Profile by its gwid, updating only the parameters that are passed. Authorized supporters can only update the Profile associated with their gwid, while administrators can update any.

Request body parameters #
Parameter Required Type Description
email string The user’s email address.
password string The user’s Profile password. See password requirements.
givenName string The given (first) name of the user.
familyName string The family (last) name of the user.
honorificPrefix string An honorific prefix like “Dr”, “Ms”, etc.
honorificSuffix string An honorific suffix like “Jr.”, “Ph.D”, etc.
dateOfBirth string The birth date of when the user was born. Formatted as YYYY-MM-DD.
gender integer An integer indicating the user’s gender. See the gender section for values.
genderIdentity string A string representing the user’s gender identity, in case they don’t identify with gender options.
address1 string The first line of the user’s street address.
address2 string The second line of the user’s street address.
locality string The city of the user’s address.
state string The 2-letter US state code of the user’s address.
zipCode string The 5-digit zip code of the user’s address.
phoneNumber string The user’s phone number.
employer string The user’s employer.
occupation string The user’s occupation.
Response body parameters #
Parameter Type Description
gwid string The gwid of the user.
email string The user’s email address.
givenName string The given (first) name of the user.
familyName string The family (last) name of the user.
honorificPrefix string An honorific prefix like “Dr”, “Ms”, etc.
honorificSuffix string An honorific suffix like “Jr.”, “Ph.D”, etc.
dateOfBirth string The birth date of when the user was born. Formatted as YYYY-MM-DD.
gender integer An integer indicating the user’s gender. See the gender section for values.
genderIdentity string A string representing the user’s gender identity, in case they don’t identify with gender options.
address1 string The first line of the user’s street address.
address2 string The second line of the user’s street address.
locality string The city of the user’s address.
state string The 2-letter US state code of the user’s address.
zipCode string The 5-digit zip code of the user’s address.
phoneNumber string The user’s phone number.
employer string The user’s employer.
occupation string The user’s occupation.
dateJoined timestamp The read-only ISO8601 formatted timestamp of when the Profile was created.
dateModified timestamp The read-only ISO8601 formatted timestamp of when the user last modified their Profile.
isConfirmed boolean Designates whether or not the user has confirmed their Profile. Assigned via the email confirmation endpoint.
confirmedAt timestamp The read-only ISO8601 formatted timestamp of when the user confirmed their email address. Assigned at the same time as isConfirmed.
socialaccounts array A read-only array of JSON objects specifying the network and remote_id of each social media authorization for the Profile.
authMethods array A read-only array of strings specifying the authorization methods supported for this Profile. Current values include facebook and password.
Example request #
curl -X PUT -H "Content-Type: application/json" -H "Authorization: Bearer {oauth-access-token}" -d '{
    "email": "test8@gmail.com",
    "employer": "Job LLC",
    "gender": 2
}' "https://api.thegroundwork.com/the-claw/profiles/db834462-c089-41c2-87d0-57dfb54557e7"
Example response #
{
  "profile": {
    "gwid": "db834462-c089-41c2-87d0-57dfb54557e7",
    "email": "test8@gmail.com",
    "isConfirmed": false,
    "confirmedAt": null,
    "dateJoined": "2016-04-22T02:10:37.997640Z",
    "dateModified": "2016-04-22T02:24:23.609056Z",
    "dateOfBirth": null,
    "givenName": "",
    "familyName": "",
    "honorificPrefix": "",
    "honorificSuffix": "",
    "gender": 2,
    "genderIdentity": "",
    "employer": "Job LLC",
    "occupation": "",
    "phoneNumber": "",
    "address1": "",
    "address2": "",
    "locality": "",
    "state": "",
    "zipCode": "",
    "socialaccounts": [],
    "authMethods": []
  }
}

List all Profiles #

https://api.thegroundwork.com/the-claw/profiles

Lists all Profiles, and filter by request parameters. Only Administrators can use this endpoint.

Query string parameters #
Parameter Required Type Description
email string Return Profiles with the corresponding email address.
email_contains string Return Profiles with a partially corresponding email address.
socialaccount__network string Return Profiles with the corresponding connected social network.
socialaccount__remote_id string Return Profiles with the corresponding user’s social network unique identifier.
page string A metadata parameter for specifying a page of results to return, with a default of 1.
perPage string A metadata parameter for specifying number of results per page, with a default of 10 and a maximum of 50.
Response body parameters #
Parameter Type Description
gwid string The gwid of the user.
email string The user’s email address.
givenName string The given (first) name of the user.
familyName string The family (last) name of the user.
honorificPrefix string An honorific prefix like “Dr”, “Ms”, etc.
honorificSuffix string An honorific suffix like “Jr.”, “Ph.D”, etc.
dateOfBirth string The birth date of when the user was born. Formatted as YYYY-MM-DD.
gender integer An integer indicating the user’s gender. See the gender section for values.
genderIdentity string A string representing the user’s gender identity, in case they don’t identify with gender options.
address1 string The first line of the user’s street address.
address2 string The second line of the user’s street address.
locality string The city of the user’s address.
state string The 2-letter US state code of the user’s address.
zipCode string The 5-digit zip code of the user’s address.
phoneNumber string The user’s phone number.
employer string The user’s employer.
occupation string The user’s occupation.
dateJoined timestamp The read-only ISO8601 timestamp of when the Profile was created.
dateModified timestamp The read-only ISO8601 timestamp of when the user last modified their Profile.
isConfirmed boolean Designates whether or not the user has confirmed their Profile. Assigned via the email confirmation endpoint.
confirmedAt timestamp The read-only ISO8601 formatted timestamp of when the user confirmed their email address. Assigned at the same time as isConfirmed.
socialaccounts array A read-only array of JSON objects specifying the network and remote_id of each social media authorization for the Profile.
authMethods array A read-only array of strings specifying the authorization methods supported for this Profile. Current values include facebook and password.
Example request #
curl -X GET -H "Content-Type: application/json" -H "Authorization: Bearer {oauth-access-token}" "https://api.thegroundwork.com/the-claw/profiles?email=email@email.com"
Example response #
{
  "meta": {
    "count": 1,
    "totalPages": 1,
    "total": 1,
    "params": {
      "perPage": 10,
      "page": 1
    }
  },
  "profiles": [
    {
      "gwid": "f238fafe-7f0f-454c-910b-9bedbc86d06b",
      "email": "email@email.com",
      "isConfirmed": false,
      "confirmedAt": null,
      "dateJoined": "2016-04-01T18:42:38.432625Z",
      "dateModified": "2016-04-18T18:44:05.786530Z",
      "dateOfBirth": null,
      "givenName": "Example",
      "familyName": "Name",
      "honorificPrefix": "",
      "honorificSuffix": "",
      "gender": null,
      "genderIdentity": "",
      "employer": "",
      "occupation": "",
      "phoneNumber": "",
      "address1": "",
      "address2": "",
      "locality": "",
      "state": "",
      "zipCode": "",
      "socialaccounts": [],
      "authMethods": [
        "password"
      ]
    }
  ]
}

Confirm a Profile email #

Upon Profile creation, the user is sent a templated confirmation email with a URL containing a confirmation key. This confirmation key can then be used to get the Profile information of the user and display a confirmation message to them at the URL destination contained in the email. This feature can be enabled or disabled upon request.

A successful email confirmation sets the is_confirmed and confirmed_at fields on the Profile.

https://api.thegroundwork.com/the-claw/email_confirmations/{confirmation-key}
Request path parameters #
Parameter Description
confirmation-key The email address of the authorized user requesting a password reset.
Response body parameters #
Parameter Type Description
gwid string The gwid of the user.
email string The user’s email address.
givenName string The given (first) name of the user.
familyName string The family (last) name of the user.
honorificPrefix string An honorific prefix like “Dr”, “Ms”, etc.
honorificSuffix string An honorific suffix like “Jr.”, “Ph.D”, etc.
dateOfBirth string The birth date of when the user was born. Formatted as YYYY-MM-DD.
gender integer An integer indicating the user’s gender. See the gender section for values.
genderIdentity string A string representing the user’s gender identity, in case they don’t identify with gender options.
address1 string The first line of the user’s street address.
address2 string The second line of the user’s street address.
locality string The city of the user’s address.
state string The 2-letter US state code of the user’s address.
zipCode string The 5-digit zip code of the user’s address.
phoneNumber string The user’s phone number.
employer string The user’s employer.
occupation string The user’s occupation.
dateJoined timestamp The read-only ISO8601 timestamp of when the Profile was created.
dateModified timestamp The read-only ISO8601 timestamp of when the user last modified their Profile.
isConfirmed boolean Designates whether or not the user has confirmed their Profile. Assigned via the email confirmation endpoint.
confirmedAt timestamp The read-only ISO8601 formatted timestamp of when the user confirmed their email address. Assigned at the same time as isConfirmed.
socialaccounts array A read-only array of JSON objects specifying the network and remote_id of each social media authorization for the Profile.
authMethods array A read-only array of strings specifying the authorization methods supported for this Profile. Current values include facebook and password.
Example request #
curl -X GET -H "Content-Type: application/json" -H "Authorization: Bearer {oauth-access-token}" "https://api.thegroundwork.com/the-claw/email_confirmations/TbOm9JiFeB8E"
Example response #
{
  "profile": {
    "gwid": "b72f820b-9c3f-485d-a381-cadb8786ffe9",
    "email": "email@email.com",
    "isConfirmed": true,
    "confirmedAt": "2016-04-05T21:52:38.712693Z",
    "dateJoined": "2016-04-05T21:52:38.712693Z",
    "dateModified": "2016-04-22T05:57:54.989658Z",
    "dateOfBirth": null,
    "givenName": "",
    "familyName": "",
    "honorificPrefix": "",
    "honorificSuffix": "",
    "gender": null,
    "genderIdentity": "",
    "employer": "",
    "occupation": "",
    "phoneNumber": "",
    "address1": "",
    "address2": "",
    "locality": "",
    "state": "",
    "zipCode": "",
    "socialaccounts": [],
    "authMethods": [
      "password"
    ]
  }
}

Manage a Profile password #

Password resets are managed via a Profile’s email address. Creating a request for a password reset results in the delivery of a templated email, which contains a 24-hour, single-use token, passed in a URL. The user may click this URL, and that token must be provided to update a password.

Create a password reset token #

https://api.thegroundwork.com/the-claw/password_resets

Trigger a password reset for the provided email address.

Request body parameters #
Parameter Required Type Description
email string The email address for the Profile requesting a password reset.
Response body parameters #
Parameter Type Description
passwordReset boolean Indicates whether or not the token was successfully emailed to the email address provided in the request body.
Example request #
curl -X POST -H "Content-Type: application/json" -H "Authorization: Bearer {oauth-access-token}" -d '{
    "email": "email@email.com"
}' "https://api.thegroundwork.com/the-claw/password_resets"
Example response #
{
  "passwordReset": true
}

Retrieve a Profile from token #

https://api.thegroundwork.com/the-claw/password_resets/{password-token}

Get the Profile of the user who is resetting their password, using the password reset token. This request is useful for personalizing messaging on a password reset page, based on the token provided.

Path parameters #
Parameter Description
password-token The token generated for resetting the password, obtained by creating a password token.
Response body parameters #
Parameter Type Description
gwid string The gwid of the user.
email string The user’s email address.
givenName string The given (first) name of the user.
familyName string The family (last) name of the user.
honorificPrefix string An honorific prefix like “Dr”, “Ms”, etc.
honorificSuffix string An honorific suffix like “Jr.”, “Ph.D”, etc.
dateOfBirth string The birth date of when the user was born. Formatted as YYYY-MM-DD.
gender integer An integer indicating the user’s gender. See the gender section for values.
genderIdentity string A string representing the user’s gender identity, in case they don’t identify with gender options.
address1 string The first line of the user’s street address.
address2 string The second line of the user’s street address.
locality string The city of the user’s address.
state string The 2-letter US state code of the user’s address.
zipCode string The 5-digit zip code of the user’s address.
phoneNumber string The user’s phone number.
employer string The user’s employer.
occupation string The user’s occupation.
dateJoined timestamp The read-only ISO8601 formatted timestamp of when the Profile was created.
dateModified timestamp The read-only ISO8601 formatted timestamp of when the user last modified their Profile.
isConfirmed boolean Designates whether or not the user has confirmed their Profile. Assigned via the email confirmation endpoint.
confirmedAt timestamp The read-only ISO8601 formatted timestamp of when the user confirmed their email address. Assigned at the same time as isConfirmed.
socialaccounts array A read-only array of JSON objects specifying the network and remote_id of each social media authorization for the Profile.
authMethods array A read-only array of strings specifying the authorization methods supported for this Profile. Current values include facebook and password.
Example request #
curl -X GET -H "Content-Type: application/json" -H "Authorization: Bearer {oauth-access-token}" "https://api.thegroundwork.com/the-claw/password_resets/TbOm9JiFeB8E"
Example response #
{
  "profile": {
    "gwid": "b72f820b-9c3f-485d-a381-cadb8786ffe9",
    "email": "email@email.com",
    "isConfirmed": false,
    "confirmedAt": null,
    "dateJoined": "2016-04-05T21:52:38.712693Z",
    "dateModified": "2016-04-22T05:57:54.989658Z",
    "dateOfBirth": null,
    "givenName": "",
    "familyName": "",
    "honorificPrefix": "",
    "honorificSuffix": "",
    "gender": null,
    "genderIdentity": "",
    "employer": "",
    "occupation": "",
    "phoneNumber": "",
    "address1": "",
    "address2": "",
    "locality": "",
    "state": "",
    "zipCode": "",
    "socialaccounts": [],
    "authMethods": [
      "password"
    ]
  }
}

Update a password #

https://api.thegroundwork.com/the-claw/password_resets/{password-token}

Create a new password for the user.

Path parameters #
Parameter Description
password-token The token generated for resetting the password, obtained by creating a password token.
Request body parameters #
Parameter Required Type Description
token string The password reset token.
password string The new password for the user. It must comply with the password requirements.
Response body parameters #
Parameter Type Description
gwid string The gwid of the user.
email string The user’s email address.
givenName string The given (first) name of the user.
familyName string The family (last) name of the user.
honorificPrefix string An honorific prefix like “Dr”, “Ms”, etc.
honorificSuffix string An honorific suffix like “Jr.”, “Ph.D”, etc.
dateOfBirth string The birth date of when the user was born. Formatted as YYYY-MM-DD.
gender integer An integer indicating the user’s gender. See the gender section for values.
genderIdentity string A string representing the user’s gender identity, in case they don’t identify with gender options.
address1 string The first line of the user’s street address.
address2 string The second line of the user’s street address.
locality string The city of the user’s address.
state string The 2-letter US state code of the user’s address.
zipCode string The 5-digit zip code of the user’s address.
phoneNumber string The user’s phone number.
employer string The user’s employer.
occupation string The user’s occupation.
dateJoined timestamp The read-only ISO8601 formatted timestamp of when the Profile was created.
dateModified timestamp The read-only ISO8601 formatted timestamp of when the user last modified their Profile.
isConfirmed boolean Designates whether or not the user has confirmed their Profile. Assigned via the email confirmation endpoint.
confirmedAt timestamp The read-only ISO8601 formatted timestamp of when the user confirmed their email address. Assigned at the same time as isConfirmed.
socialaccounts array A read-only array of JSON objects specifying the network and remote_id of each social media authorization for the Profile.
authMethods array A read-only array of strings specifying the authorization methods supported for this Profile. Current values include facebook and password.
Example request #
curl -X PUT -H "Content-Type: application/json" -H "Authorization: Bearer {oauth-access-token}" -d '{
    "token": "TbOm9JiFeB8E",
    "password": "Password1"
}' "https://api.thegroundwork.com/the-claw/password_resets/TbOm9JiFeB8E"
Example response #
{
  "profile": {
    "gwid": "b72f820b-9c3f-485d-a381-cadb8786ffe9",
    "email": "email@email.com",
    "isConfirmed": false,
    "confirmedAt": null,
    "dateJoined": "2016-04-05T21:52:38.712693Z",
    "dateModified": "2016-04-22T06:25:41.247435Z",
    "dateOfBirth": null,
    "givenName": "",
    "familyName": "",
    "honorificPrefix": "",
    "honorificSuffix": "",
    "gender": null,
    "genderIdentity": "",
    "employer": "",
    "occupation": "",
    "phoneNumber": "",
    "address1": "",
    "address2": "",
    "locality": "",
    "state": "",
    "zipCode": "",
    "socialaccounts": [],
    "authMethods": [
      "password"
    ]
  }
}

Events #

Overview #

A Groundwork Event is a representation of a real-word event occurring at a defined place during a defined time window, and is attended by those who have obtained Tickets to that Event. The Groundwork allows organization administrators, or authenticated users, to create and manage Events, Invitations, Messages, ticketing, and Ticket redemption.

Invitations #

An authenticated user or an administrator can create an Event, and may send Invitation emails for that Event via The Groundwork. Each invitation email is represented by an Invitation object, which may be referenced when creating a Ticket, thereby attributing the Ticket to the Invitation.

Categories, Tickets and Orders #

A Category represents a class of Ticket, defined by price, timeframe, and available quantity. A Ticket is obtained by creating an Order and, if a Ticket’s Category has a price > 0, by also creating a Donation referencing that Order’s cart.

An individual who obtains a Ticket is considered its purchaser. The person for whom a Ticket is obtained is considered the attendee, and may or may not be the same person as its purchaser.

Ticket redemption #

On the day of the Event, ticketholders “check in” and their Ticket is considered redeemed. Walk-up attendees can also obtain Tickets and redeem them at the Event.

Messaging #

Two types of user-generated emails are supported, each having its own endpoint: Invitations and generic Messages. Invitations are sent to an arbitrary set of email addresses (invitees) and a Ticket may reference an Invitation (when an invitee accepts an Invitation). Generic Messages may be sent to defined subsets of invitees or ticketholders and serve as informational messages only. Each email references an email template stored in an organization’s email template repository.

The system also automatically sends a confirmation email to the purchaser for each ticket purchased.

Permissions #

Events can be created by an organization’s administrators, or authenticated users. Event details can be viewed by anyone, without user authentication, but they may only be edited and deleted by the user that created them, or by an administrator.

It is not necessary for invitees or attendees to authenticate to The Groundwork in order to receive Invitations or obtain Tickets, though the recommended flow is to authenticate users whenever possible.

Events #

Event objects represent the Event itself, including location information and details about the Event. Each Event must have one host and belong to one Initiative.

Create an Event #

https://api.thegroundwork.com/events/events

Create a new Event.

Request body parameters #
Parameter Required Type Max Length Description
address1 string 128 The first address line of the Event location.
address2 string 128 The second address line of the Event location.
addressCity string 128 The city of the Event location.
addressCountry string 3 The ISO-3166-1 Alpha 3 formatted country of the Event.
addressCounty string 128 The county of the Event location.
addressDistrict string 128 The district of the Event location.
addressPostalCode string 32 The postal code of the Event location.
addressStateOrProvince string 128 The state or province of the Event location.
description string An arbitrary string describing the Event.
hostGwid string The gwid of the user hosting the Event. This field is required if the request comes from an admin (i.e. uses a client credential grant). If the Event is being created by an authed user, hostGwid is not required and is set to the authed user’s gwid
locationName string 256 The name of the location.
timeEnd string The end time of the Event, in the timezone of the Event location. Formatted in ISO-8601, without a timezone designator.
timeStart string The start time of the Event, in the timezone of the Event location. Formatted in ISO-8601, without a timezone designator.
title string 256 The title of the Event.

Note - The provided address will be geocoded. If a rooftop-level level location cannot be inferred from the provided address, the request will 400 with the response No geocoding results, and the Event will not be created.

Addresses are not normalized when geocoding, and Events will assign latitude and longitude based on the best-guess of the intended address. So results may be unexpected if the system receives address information that is incorrect yet can be geocoded. For example if you pass addressStateOrProvince of Illinois but the rest of the address looks like it is in Ohio, the geocoded coordinates might place your event in Ohio but your addressStateOrProvince will retain the value of Illinois. The same applies if you pass an address field value that doesn’t resolve to any real-world location. The system does not modify the provided address values based on the calculated geocode coordinates.

For this reason, and for an optimal user experience, it is highly recommended that you implement front-end data validation for address selection. Consider using Google Maps API for place lookup, and auto-suggesting places as a means of validating all address parameters.

Response body parameters #
Parameter Type Description
address1 string The first address line of the Event location.
address2 string The second address line of the Event location.
addressCity string The city of the Event location.
addressCountry string The ISO-3166-1 Alpha 3 formatted country of the Event.
addressCounty string The county of the Event location.
addressDistrict string The district of the Event location.
addressLatitude decimal The latitude coordinate of the Event location.
addressLongitude decimal The longitude coordinate of the Event location.
addressPostalCode string The postal code of the Event location.
addressStateOrProvince string The state or province of the Event location.
createdUtc string A ISO-8601 formatted creation time of the Event, given in UTC.
description string An arbitrary string describing the Event.
hostGwid string The gwid of the user hosting the Event.
id string A unique identifier for the Event.
initiativeId string The Groundwork Initiative to which the object belongs.
locationName string The name of the location.
timeEndUtc string A ISO-8601 formatted end time of the Event, given in UTC.
timeStartUtc string A ISO-8601 formatted start time of the Event, given in UTC.
timeZoneId string The ID of the timezone in which the Event is taking place.
title string The title of the Event.
Example request #
curl -X POST -H "Content-Type: application/json" -H "Authorization: Bearer {oauth-access-token}" -d '{
  "address1": "641 Walnut St.",
  "addressCity": "Cincinnati",
  "addressCountry": "USA",
  "addressPostalCode": "45202",
  "addressStateOrProvince": "Ohio",
  "description": "Come out to our winter fundraiser!",
  "locationName": "The Righteous Room",
  "timeEnd": "2016-09-26T15:00:00",
  "timeStart": "2016-09-26T12:00:00",
  "title": "Winter Fundraiser 2015"
}' "https://api.thegroundwork.com/events/events/"
Example response #
{
  "address1": "641 Walnut St.",
  "address2": "",
  "addressCity": "Cincinnati",
  "addressCountry": "USA",
  "addressCounty": "",
  "addressDistrict": "",
  "addressLatitude": 39.103652,
  "addressLongitude": -84.512228,
  "addressPostalCode": "45202",
  "addressStateOrProvince": "Ohio",
  "createdUtc": "2015-06-20T16:11:44Z",
  "description": "Come out to our winter fundraiser!",
  "hostGwid": "03d6b6c1-bf15-4401-a850-a0e6dd2be6de",
  "id": "5bc753e4-a94e-4463-a8e9-83de9c6819df",
  "initiativeId": "my_organization.my_initiative",
  "locationName": "The Righteous Room",
  "timeEndUtc": "2016-09-26T20:00:00Z",
  "timeStartUtc": "2016-09-26T17:00:00Z",
  "timeZoneId": "America/New_York",
  "title": "Winter Fundraiser 2015"
}

Get an Event #

https://api.thegroundwork.com/events/events/{event-id}

Get a specific Event by its id.

Path parameters #
Parameter Description
event-id The unique identifier of the Event.
Response body parameters #
Parameter Type Description
address1 string The first address line of the Event location.
address2 string The second address line of the Event location.
addressCity string The city of the Event location.
addressCountry string The ISO-3166-1 Alpha 3 formatted country of the Event.
addressCounty string The county of the Event location.
addressDistrict string The district of the Event location.
addressLatitude decimal The latitude coordinate of the Event location.
addressLongitude decimal The longitude coordinate of the Event location.
addressPostalCode string The postal code of the Event location.
addressStateOrProvince string The state or province of the Event location.
createdUtc string A ISO-8601 formatted creation time of the Event, given in UTC.
description string An arbitrary string describing the Event.
hostGwid string The gwid of the user hosting the Event.
id string A UUID unique identifier for the Event.
initiativeId string The Groundwork Initiative to which the object belongs.
locationName string The name of the location.
timeEndUtc string A ISO-8601 formatted end time of the Event, given in UTC.
timeStartUtc string A ISO-8601 formatted start time of the Event, given in UTC.
timeZoneId string The ID of the timezone in which the Event is taking place.
title string The title of the Event.
Example request #
curl -X GET -H "Content-Type: application/json" -H "Authorization: Basic {client-id}" "https://api.thegroundwork.com/events/events/5bc753e4-a94e-4463-a8e9-83de9c6819df"
Example response #
{
  "address1": "641 Walnut St.",
  "address2": "",
  "addressCity": "Cincinnati",
  "addressCountry": "USA",
  "addressCounty": "",
  "addressDistrict": "",
  "addressLatitude": 39.103652,
  "addressLongitude": -84.512228,
  "addressPostalCode": "45202",
  "addressStateOrProvince": "Ohio",
  "createdUtc": "2015-06-20T16:11:44Z",
  "description": "Come out to our winter fundraiser!",
  "hostGwid": "03d6b6c1-bf15-4401-a850-a0e6dd2be6de",
  "id": "5bc753e4-a94e-4463-a8e9-83de9c6819df",
  "initiativeId": "my_organization.my_initiative",
  "locationName": "The Righteous Room",
  "timeEndUtc": "2016-09-26T20:00:00Z",
  "timeStartUtc": "2016-09-26T17:00:00Z",
  "timeZoneId": "America/New_York",
  "title": "Winter Fundraiser 2015"
}

Update an Event #

https://api.thegroundwork.com/events/events/{event-id}

Update an existing Event by its id, modifying only the parameters that are passed. No request body parameters are required.

https://api.thegroundwork.com/events/events/{event-id}

Update an existing Event by its id, updating all parameters. Unpassed parameters will be overwritten as blank.

Path parameters #
Parameter Description
event-id The unique identifier of the Event.
Request body parameters #
Parameter Required Type Max Length Description
address1 string 128 The first address line of the Event location.
address2 string 128 The second address line of the Event location.
addressCity string 128 The city of the Event location.
addressCountry string 3 The ISO-3166-1 Alpha 3 formatted country of the Event.
addressCounty string 128 The county of the Event location.
addressDistrict string 128 The district of the Event location.
addressPostalCode string 32 The postal code of the Event location.
addressStateOrProvince string 128 The state or province of the Event location.
description string An arbitrary string describing the Event.
hostGwid string The gwid of the user hosting the Event. This field is required if the request comes from an admin (i.e. uses a client credential grant). If the Event is being created by an authed user, hostGwid is not required and is set to the authed user’s gwid
locationName string 256 The name of the location.
timeEnd string The end time of the Event, in the timezone of the Event location. Formatted in ISO-8601, without a timezone designator.
timeStart string The start time of the Event, in the timezone of the Event location. Formatted in ISO-8601, without a timezone designator.
title string 256 The title of the Event.

Note - The provided address will be geocoded. If a rooftop-level level location cannot be inferred from the provided address, the request will 400 with the response No geocoding results, and the Event will not be created.

Response body parameters #
Parameter Type Description
address1 string The first address line of the Event location.
address2 string The second address line of the Event location.
addressCity string The city of the Event location.
addressCountry string The ISO-3166-1 Alpha 3 formatted country of the Event.
addressCounty string The county of the Event location.
addressDistrict string The district of the Event location.
addressLatitude decimal The latitude coordinate of the Event location.
addressLongitude decimal The longitude coordinate of the Event location.
addressPostalCode string The postal code of the Event location.
addressStateOrProvince string The state or province of the Event location.
createdUtc string A ISO-8601 formatted creation time of the Event, given in UTC.
description string An arbitrary string describing the Event.
hostGwid string The gwid of the user hosting the Event.
id string A unique identifier for the Event.
initiativeId string The Groundwork Initiative to which the object belongs.
locationName string The name of the location.
timeEndUtc string A ISO-8601 formatted end time of the Event, given in UTC.
timeStartUtc string A ISO-8601 formatted start time of the Event, given in UTC.
timeZoneId string The ID of the timezone in which the Event is taking place.
title string The title of the Event.
Example request #
curl -X PUT -H "Content-Type: application/json" -H "Authorization: Bearer {oauth-access-token}" -d '{
  "address1": "641 Walnut St.",
  "addressCity": "Cincinnati",
  "addressCountry": "USA",
  "addressPostalCode": "45202",
  "addressStateOrProvince": "Ohio",
  "description": "Come out to our winter fundraiser!",
  "locationName": "The Righteous Room",
  "timeEnd": "2016-09-26T15:00:00",
  "timeStart": "2016-09-26T12:00:00",
  "title": "Winter Fundraiser 2015"
}' "https://api.thegroundwork.com/events/events/5bc753e4-a94e-4463-a8e9-83de9c6819df"
Example response #
{
  "address1": "641 Walnut St.",
  "address2": "",
  "addressCity": "Cincinnati",
  "addressCountry": "USA",
  "addressCounty": "",
  "addressDistrict": "",
  "addressLatitude": 39.103652,
  "addressLongitude": -84.512228,
  "addressPostalCode": "45202",
  "addressStateOrProvince": "Ohio",
  "createdUtc": "2015-06-20T16:11:44Z",
  "description": "Come out to our winter fundraiser!",
  "hostGwid": "03d6b6c1-bf15-4401-a850-a0e6dd2be6de",
  "id": "5bc753e4-a94e-4463-a8e9-83de9c6819df",
  "initiativeId": "my_organization.my_initiative",
  "locationName": "The Righteous Room",
  "timeEndUtc": "2016-09-26T20:00:00Z",
  "timeStartUtc": "2016-09-26T17:00:00Z",
  "timeZoneId": "America/New_York",
  "title": "Winter Fundraiser 2015"
}

Delete an Event #

https://api.thegroundwork.com/events/events/{event-id}

Delete a specific Event, by id

Path parameters #
Parameter Description
event-id The unique identifier of the Event.
Example request #
curl -X DELETE -H "Content-Type: application/json" -H "Authorization: Bearer {oauth-access-token}" "https://api.thegroundwork.com/events/events/5bc753e4-a94e-4463-a8e9-83de9c6819df"
Example response #
204 No Content

List all Events #

https://api.thegroundwork.com/events/events

List all Events, and filter by request parameters.

Query string parameters #
Parameter Type Description
hostGwid string Return Events hosted by a user with a matching gwid. Pass multiple hostGwid= parameters to include multiple hosts in your request.
isDeleted Boolean Return only Events that have/have not been deleted. Defaults to “False”. This paramater is only available if the request comes from an admin (i.e. uses a client credential grant).
latitude float A latitudinal coordinate. Required for geographic queries.
longitude float A longitudinal coordinate. Required for geographic queries.
radius float Return Events within radius, in kilometers, centered around latitude and longitude. Required for geographic queries.
search string Return Events whose title matches all or part of this value
startsBefore string Return Events starting before this ISO-8601 datetime.
startsAfter string Return Events starting after this ISO-8601 datetime.
endsBefore string Return Events ending before this ISO-8601 datetime.
endsAfter string Return Events ending after this ISO-8601 datetime.
page integer A metadata parameter for specifying a page of results to return.
perPage integer A metadata parameter for specifying number of results per page.

Note - A query string with geographic params must include latitude, longitude, and radius.

Response body parameters #
Parameter Type Description
address1 string The first address line of the Event location.
address2 string The second address line of the Event location.
addressCity string The city of the Event location.
addressCountry string The ISO-3166-1 Alpha 3 formatted country of the Event.
addressCounty string The county of the Event location.
addressDistrict string The district of the Event location.
addressLatitude decimal The latitude coordinate of the Event location.
addressLongitude decimal The longitude coordinate of the Event location.
addressPostalCode string The postal code of the Event location.
addressStateOrProvince string The state or province of the Event location.
createdUtc string A ISO-8601 formatted creation time of the Event, given in UTC.
description string An arbitrary string describing the Event.
hostGwid string The gwid of the user hosting the Event.
id string A unique identifier for the Event.
initiativeId string The Groundwork Initiative to which the object belongs.
locationName string The name of the location.
timeEndUtc string A ISO-8601 formatted end time of the Event, given in UTC.
timeStartUtc string A ISO-8601 formatted start time of the Event, given in UTC.
timeZoneId string The ID of the timezone in which the Event is taking place.
title string The title of the Event.
Example request #
curl -X GET -H "Content-Type: application/json" -H "Authorization: Basic {client-id}" "https://api.thegroundwork.com/events/events/?hostGwid=9ba6e2cb-c3b2-4aca-8953-9ec58115badb"
Example response #
{
  "meta": {
    "count": 2,
    "params": {
      "page": 1,
      "perPage": 10,
      "hostGwid": "9ba6e2cb-c3b2-4aca-8953-9ec58115badb"
    },
    "total": 2,
    "totalPages": 1
  },
  "results": [
    {
      "address1": "641 Walnut St.",
      "address2": "",
      "addressCity": "Cincinnati",
      "addressCountry": "USA",
      "addressCounty": "",
      "addressDistrict": "",
      "addressLatitude": 39.103652,
      "addressLongitude": -84.512228,
      "addressPostalCode": "45202",
      "addressStateOrProvince": "Ohio",
      "createdUtc": "2015-06-20T16:11:44Z",
      "description": "Come out to our winter fundraiser!",
      "hostGwid": "9ba6e2cb-c3b2-4aca-8953-9ec58115badb",
      "id": "5bc753e4-a94e-4463-a8e9-83de9c6819df",
      "initiativeId": "my_organization.my_initiative",
      "locationName": "The Righteous Room",
      "timeEndUtc": "2016-09-26T20:00:00Z",
      "timeStartUtc": "2016-09-26T17:00:00Z",
      "timeZoneId": "America/New_York",
      "title": "Winter Fundraiser 2015"
    },
    {
      "address1": "500 Main St.",
      "address2": "",
      "addressCity": "Cincinnati",
      "addressCountry": "USA",
      "addressCounty": "",
      "addressDistrict": "",
      "addressLatitude": 39.23652,
      "addressLongitude": -84.012228,
      "addressPostalCode": "45202",
      "addressStateOrProvince": "Ohio",
      "createdUtc": "2015-06-20T16:11:44Z",
      "description": "Come have coffee with some of the people that help with our programs!",
      "hostGwid": "9ba6e2cb-c3b2-4aca-8953-9ec58115badb",
      "id": "480c307a-41bf-429c-a5d6-95aa4034d862",
      "initiativeId": "my_organization.my_initiative",
      "locationName": "",
      "timeEndUtc": "2016-09-29T14:00:00Z",
      "timeStartUtc": "2016-09-29T12:00:00Z",
      "timeZoneId": "America/New_York",
      "title": "Coffee with Volunteers"
    }
  ]
}

Categories #

Events must have at least one Category, each of which may have zero to many Tickets. Categories are used to differentiate between Ticket types, primarily price and time.

Create a Category #

https://api.thegroundwork.com/events/events/{event-id}/categories

Create a Category.

Path parameters #
Parameter Description
event-id The unique identifier of the Event.
Request body parameters #
Parameter Required Type Max Length Description
currency conditional string An ISO-4217 currency code. Required if price is present and >0
description string An arbitrary string describing the Category.
price integer The cost of a Ticket in the Category, given in the least-significant unit of the currency, e.g. cents.
quantityTotal integer The total number of Tickets for the Category.
timeEnd string The end time of the Category, in the timezone of the Event location. Formatted in ISO-8601, without a timezone designator.
timeStart string The start time of the Category, in the timezone of the Event location. Formatted in ISO-8601, without a timezone designator.
title string 256 The title of the Category.
Response body parameters #
Parameter Type Description
currency string An ISO-4217 currency code.
description string An arbitrary string describing the Category.
createdUtc string A ISO-8601 formatted creation time of the Category, given in UTC.
eventId string A unique identifier for the Event associated with the Category.
id string A unique identifier for the Category.
initiativeId string The Groundwork Initiative to which the object belongs.
price integer The cost of a Ticket in the Category, given in the least-significant unit of the currency, e.g. cents.
quantityRemaining integer The number of remaining Tickets for the Category.
quantityTotal integer The total number of Tickets for the Category.
timeEndUtc string A ISO-8601 formatted end time of the Category, given in UTC.
timeStartUtc string A ISO-8601 formatted start time of the Category, given in UTC.
timeZoneId string The ID of the timezone in which the Event is taking place.
title string The title of the Category.
Example request #
curl -X POST -H "Content-Type: application/json" -H "Authorization: Bearer {oauth-access-token}" -d '{
  "currency": "USD",
  "title": "VIP",
  "description": "Reserved for our most active supporters",
  "price": 1000,
  "quantityTotal": 100,
  "timeEnd": "2016-09-26T14:00:00",
  "timeStart": "2016-09-26T12:00:00"
}' "https://api.thegroundwork.com/events/events/9df9edaa-6519-4a89-b758-47f884a9d27f/categories"
Example response #
{
  "currency": "USD",
  "createdUtc": "2015-06-20T16:11:44Z",
  "description": "Reserved for our most active supporters",
  "eventId": "9df9edaa-6519-4a89-b758-47f884a9d27f",
  "id": "3487eff5-04af-460b-b461-b5c8e29fdcc0",
  "initiativeId": "my_organization.my_initiative",
  "price": 1000,
  "quantityRemaining": 100,
  "quantityTotal": 100,
  "timeEndUtc": "2016-09-26T18:00:00Z",
  "timeStartUtc": "2016-09-26T16:00:00Z",
  "timeZoneId": "America/New_York",
  "title": "VIP"
}

Get a Category #

https://api.thegroundwork.com/events/events/{event-id}/categories/{category-id}

Get a specific Category by its id.

Path parameters #
Parameter Description
event-id The unique identifier of the Event.
category-id The unique identifier of the Category.
Response body parameters #
Parameter Type Description
currency string An ISO-4217 currency code.
description string An arbitrary string describing the Category.
createdUtc string A ISO-8601 formatted creation time of the Category, given in UTC.
eventId string A unique identifier for the Event associated with the Category.
id string A unique identifier for the Category.
initiativeId string The Groundwork Initiative to which the object belongs.
price integer The cost of a Ticket in the Category, given in the least-significant unit of the currency, e.g. cents.
quantityRemaining integer The number of remaining Tickets for the Category.
quantityTotal integer The total number of Tickets for the Category.
timeEndUtc string A ISO-8601 formatted end time of the Category, given in UTC.
timeStartUtc string A ISO-8601 formatted start time of the Category, given in UTC.
timeZoneId string The ID of the timezone in which the Event is taking place.
title string The title of the Category.
Example request #
curl -X GET -H "Content-Type: application/json" -H "Authorization: Bearer {oauth-access-token}" -H "https://api.thegroundwork.com/events/events/9df9edaa-6519-4a89-b758-47f884a9d27f/categories/d4fb557a-ba04-43d9-a28e-c3da7e093075"
Example response #
{
  "currency": "USD",
  "createdUtc": "2015-06-20T16:11:44Z",
  "description": "Reserved for our most active supporters",
  "eventId": "9df9edaa-6519-4a89-b758-47f884a9d27f",
  "id": "3487eff5-04af-460b-b461-b5c8e29fdcc0",
  "initiativeId": "my_organization.my_initiative",
  "price": 1000,
  "quantityRemaining": 100,
  "quantityTotal": 100,
  "timeEndUtc": "2016-09-26T18:00:00Z",
  "timeStartUtc": "2016-09-26T16:00:00Z",
  "timeZoneId": "America/New_York",
  "title": "VIP"
}

Update a Category #

https://api.thegroundwork.com/events/events/{event-id}/categories/{category-id}

Update an existing Category by its id, modifying only the parameters that are passed. No request body parameters are required.

https://api.thegroundwork.com/events/events/{event-id}/categories/{category-id}

Update an existing Category by its id, updating all parameters. Unpassed parameters will be overwritten as blank.

Path parameters #
Parameter Description
event-id The unique identifier of the Event.
category-id The unique identifier of the Category.
Request body parameters #
Parameter Required Type Max Length Description
currency conditional string An ISO-4217 currency code. Required if price is present and >0
description string An arbitrary string describing the Category.
price integer The cost of a Ticket in the Category, given in the least-significant unit of the currency, e.g. cents.
quantityTotal integer The total number of Tickets for the Category.
timeEnd string The end time of the Category, in the timezone of the Event location. Formatted in ISO-8601, without a timezone designator.
timeStart string The start time of the Category, in the timezone of the Event location. Formatted in ISO-8601, without a timezone designator.
title string 256 The title of the Category.
Response body parameters #
Parameter Type Description
currency string An ISO-4217 currency code.
description string An arbitrary string describing the Category.
createdUtc string A ISO-8601 formatted creation time of the Category, given in UTC.
eventId string A unique identifier for the Event associated with the Category.
id string A unique identifier for the Category.
initiativeId string The Groundwork Initiative to which the object belongs.
price integer The cost of a Ticket in the Category, given in the least-significant unit of the currency, e.g. cents.
quantityRemaining integer The number of remaining Tickets for the Category.
quantityTotal integer The total number of Tickets for the Category.
timeEndUtc string A ISO-8601 formatted end time of the Category, given in UTC.
timeStartUtc string A ISO-8601 formatted start time of the Category, given in UTC.
timeZoneId string The ID of the timezone in which the Event is taking place.
title string The title of the Category.
Example request #
curl -X PUT -H "Content-Type: application/json" -H "Authorization: Bearer {oauth-access-token}" -d '{
  "title": "Categorical",
  "description": "Reserved for our most active supporters",
  "quantityTotal": 100,
  "timeEnd": "2016-09-26T14:00:00",
  "timeStart": "2016-09-26T12:00:00"
}' "https://api.thegroundwork.com/events/events/9df9edaa-6519-4a89-b758-47f884a9d27f/categories"
Example response #
{
  "currency": "USD",
  "createdUtc": "2015-06-20T16:11:44Z",
  "description": "Reserved for our most active supporters",
  "eventId": "9df9edaa-6519-4a89-b758-47f884a9d27f",
  "id": "3487eff5-04af-460b-b461-b5c8e29fdcc0",
  "initiativeId": "my_organization.my_initiative",
  "price": 1000,
  "quantityRemaining": 100,
  "quantityTotal": 100,
  "timeEndUtc": "2016-09-26T18:00:00Z",
  "timeStartUtc": "2016-09-26T16:00:00Z",
  "timeZoneId": "America/New_York",
  "title": "VIP"
}

Delete a Category #

https://api.thegroundwork.com/events/events/{event-id}/categories/{category-id}

Delete a specific Category, by id.

Path parameters #
Parameter Description
event-id The unique identifier of the Event.
category-id The unique identifier of the Category.
Example request #
curl -X DELETE -H "Content-Type: application/json" -H "Authorization: Bearer {oauth-access-token}" -H "https://api.thegroundwork.com/events/events/9df9edaa-6519-4a89-b758-47f884a9d27f/categories/d4fb557a-ba04-43d9-a28e-c3da7e093075"
Example response #
204 No Content

List an Event’s Categories #

https://api.thegroundwork.com/events/events/{event-id}/categories

List all of an Event’s categories, and filter by request parameters.

Path parameters #
Parameter Description
event-id The unique identifier of the Event.
Query string parameters #
Parameter Type Description
startsBefore string Return Categories starting before this ISO-8601 datetime.
startsAfter string Return Categories starting after this ISO-8601 datetime.
endsBefore string Return Categories ending before this ISO-8601 datetime.
endsAfter string Return Categories ending after this ISO-8601 datetime.
page integer A metadata parameter for specifying a page of results to return.
perPage integer A metadata parameter for specifying number of results per page.
Response body parameters #
Parameter Type Description
currency string An ISO-4217 currency code.
description string An arbitrary string describing the Category.
createdUtc string A ISO-8601 formatted creation time of the Category, given in UTC.
eventId string A unique identifier for the Event associated with the Category.
id string A unique identifier for the Category.
initiativeId string The Groundwork Initiative to which the object belongs.
price integer The cost of a Ticket in the Category, given in the least-significant unit of the currency, e.g. cents.
quantityRemaining integer The number of remaining Tickets for the Category.
quantityTotal integer The total number of Tickets for the Category.
timeEndUtc string A ISO-8601 formatted end time of the Category, given in UTC.
timeStartUtc string A ISO-8601 formatted start time of the Category, given in UTC.
timeZoneId string The ID of the timezone in which the Event is taking place.
title string The title of the Category.
Example request #
curl -X GET -H "Content-Type: application/json" -H "Authorization: Bearer {oauth-access-token}" "https://api.thegroundwork.com/events/events/9df9edaa-6519-4a89-b758-47f884a9d27f/categories"
Example response #
{
  "meta": {
    "count": 2,
    "totalPages": 1,
    "total": 2,
    "params": {
      "perPage": 10,
      "page": 1,
      "startsAfter": "2016-09-26T15:00:00"
    }
  },
  "results": [
    {
      "currency": "USD",
      "createdUtc": "2015-06-20T16:11:44Z",
      "description": "Have dinner and a table during tonight's party.",
      "eventId": "9df9edaa-6519-4a89-b758-47f884a9d27f",
      "id": "d4fb557a-ba04-43d9-a28e-c3da7e093075",
      "initiativeId": "my_organization.my_initiative",
      "price": 1000,
      "quantityTotal": 1000,
      "quantityRemaining": 1000,
      "timeEndUtc": "2016-09-26T18:00:00Z",
      "timeStartUtc": "2016-09-26T16:00:00Z",
      "timeZoneId": "America/New_York",
      "title": "Table Seat"
    },
    {
      "currency": "USD",
      "createdUtc": "2015-06-20T16:11:44Z",
      "description": "A special behind the scenes experience at tonight's gala.",
      "eventId": "9df9edaa-6519-4a89-b758-47f884a9d27f",
      "id": "30d531fe-d86a-4577-9024-ba28b2572ad5",
      "initiativeId": "my_organization.my_initiative",
      "price": 5000,
      "quantityTotal": 1000,
      "quantityRemaining": 1000,
      "timeEndUtc": "2016-09-26T18:00:00Z",
      "timeStartUtc": "2016-09-26T15:00:00Z",
      "timeZoneId": "America/New_York",
      "title": "VIP"
    }
  ]
}

Orders #

An Order is a request to process the creation of one or more Tickets. If all Tickets in an Order Ticket belong to a Category whose price = 0, then that Ticket is created immediately. If any Tickets in an Order belong to a Category whose price > 0, then the Ticket is not created until a single payment for the exact amount of the order is received as part of the following workflow:

  1. Front end creates a new Order.
  2. System:
    • decrements quantityRemaining for the Categories specified in the new Order.
    • responds with Order object, including cartId.
  3. Front end creates a new Donation, passing in the Order’s cartId.
  4. System:
    • charges card and responds with Donation object.
    • changes Order status to completed.
    • creates Ticket.

If the Order is not completed within 1 hour of creation, the system automatically deletes it.

Create an Order #

https://api.thegroundwork.com/events/events/{event-id}/orders

Create an order.

Path parameters #
Parameter Description
event-id The unique identifier of the Event.
Request body parameters #
Parameter Required Type Max Length Description
email conditional string The email address of the person requesting this Order. This must be passed if the purchaser’s gwid is not known. It must not be passed otherwise. See Note below.
invitationId string The unique identifier of an Invitation with which to associate this Order’s Tickets. If provided, the system will update the Invitation status to accepted when the Tickets are created.
purchaserGwid conditional string The gwid of the user purchasing this Ticket. This must be passed if the purchaser’s gwid is known. See Note below.
ticketReservations array An Array of Tickets requested by this Order.
attendeeGwid string The unique identifier of the user attending with this Ticket, if known .
attendeeIsPurchaser boolean A flag indicating whether this Ticket’s attendeeGwid should be set by the system to match that of the purchaser. Used when creating Orders using email instead of purchaserGwid.
categoryId string The unique identifier of the Category in which to create the Ticket. Needn’t be unique in the ticketReservations array.

Note - When email is provided with an Order, the system will attempt to match it to an email in existing Profiles. If no Profile exists, the system will create a Shadow Profile for the user (one with no password set). If the email matches an existing Shadow Profile, the system will set that Profile’s gwid as the Order’s purchaserGwid. If the email matches an existing Profile (one with a password set), but the user is not authenticated, the system will respond with 403 and the front end should ask the user to authenticate.

Example request #
curl -X PUT -H "Content-Type: application/json" -H "Authorization: Bearer {oauth-access-token}" -d '{
  "invitationId": "96548627-008c-403d-87fa-4826edde5f6d",
  "email": "johnbrown@thegroundwork.com",
  "ticketReservations": [
    {
      "attendeeIsPurchaser": true,
      "categoryId": "d4fb557a-ba04-43d9-a28e-c3da7e093075"
    }
  ]
}' "https://api.thegroundwork.com/events/events/64452ae1-2c17-4ffb-920f-31e8c2926b13/orders"
Example response #
{
  "cartId": "c3f5904a4073482f92d7701dcd0211e6",
  "createdUtc": "2016-07-07T18:14:00Z",
  "currency": "USD",
  "eventId": "64452ae1-2c17-4ffb-920f-31e8c2926b13",
  "id": "cbe35c9b-4dfb-49a3-b367-04b354373536",
  "initiativeId": "my_organization.my_initiative",
  "invitationId": "96548627-008c-403d-87fa-4826edde5f6d",
  "price": 2000,
  "purchaserGwid": "4e72eb91-c0b3-46e6-84f7-09bf9900e107",
  "status": "completed",
  "tickets": [
    {
      "attendeeGwid": "752bfe79-fc8b-48e9-8f7f-67cdd1c7a67c",
      "attendeeProfile": {
        "email": "johnbrown@thegroundwork.com",
        "familyName": "",
        "givenName": ""
      },
      "categoryId": "d4fb557a-ba04-43d9-a28e-c3da7e093075",
      "createdUtc": "2015-06-20T16:11:44Z",
      "eventId": "9df9edaa-6519-4a89-b758-47f884a9d27f",
      "id": "84e1e2c4-8ac9-4f38-9bd8-b1abfb8dc3d4",
      "initiativeId": "my_organization.my_initiative",
      "invitationId": "96548627-008c-403d-87fa-4826edde5f6d",
      "orderId": "cbe35c9b-4dfb-49a3-b367-04b354373536",
      "purchaserGwid": "752bfe79-fc8b-48e9-8f7f-67cdd1c7a67c",
      "purchaserProfile": {
        "email": "johnbrown@thegroundwork.com",
        "familyName": "",
        "givenName": ""
      },
      "redeemedUtc": ""
    }
  ]
}

Get an Order #

https://api.thegroundwork.com/events/events/{event-id}/orders/{order-id}

Get a specific Order by its id.

Path parameters #
Parameter Description
event-id The unique identifier of the Event.
order-id The unique identifier of the Order.
Response body parameters #
Parameter Type Description
cartId string The unique identifier for the cart created by the Order. This value is blank if no payment was necessary.
createdUtc string A ISO-8601 formatted creation time of the Order, given in UTC.
currency string A ISO-4217 currency code for any non-free Categories in the Order.
eventId string A unique identifier for the Event associated with the Order.
id string A unique identifier for the Order.
initiativeId string The Groundwork Initiative to which the object belongs.
invitationId string The unique identifier for the Invitation associated with the Order, if any.
price integer The sum of price for all Categories referenced by the Order, given in the least-significant unit of the currency, e.g. cents.
purchaserGwid string The gwid of the user making the Order.
status string The status of the Order. It may be either pending or completed.
tickets array An Array of Tickets requested by the Order. The array is empty if the Order status is not complete
Example request #
curl -X GET -H "Content-Type: application/json" -H "Authorization: Bearer {oauth-access-token}" "https://api.thegroundwork.com/events/events/64452ae1-2c17-4ffb-920f-31e8c2926b13/orders/cbe35c9b-4dfb-49a3-b367-04b354373536"
Example response #
{
  "cartId": "c3f5904a4073482f92d7701dcd0211e6",
  "createdUtc": "2016-07-07T18:14:00Z",
  "currency": "USD",
  "eventId": "64452ae1-2c17-4ffb-920f-31e8c2926b13",
  "id": "cbe35c9b-4dfb-49a3-b367-04b354373536",
  "initiativeId": "my_organization.my_initiative",
  "invitationId": "96548627-008c-403d-87fa-4826edde5f6d",
  "price": 2000,
  "purchaserGwid": "4e72eb91-c0b3-46e6-84f7-09bf9900e107",
  "status": "completed",
  "tickets": [
    {
      "attendeeGwid": "752bfe79-fc8b-48e9-8f7f-67cdd1c7a67c",
      "attendeeProfile": {
        "email": "johnbrown@thegroundwork.com",
        "familyName": "",
        "givenName": ""
      },
      "categoryId": "d4fb557a-ba04-43d9-a28e-c3da7e093075",
      "createdUtc": "2015-06-20T16:11:44Z",
      "eventId": "9df9edaa-6519-4a89-b758-47f884a9d27f",
      "id": "84e1e2c4-8ac9-4f38-9bd8-b1abfb8dc3d4",
      "initiativeId": "my_organization.my_initiative",
      "invitationId": "96548627-008c-403d-87fa-4826edde5f6d",
      "orderId": "cbe35c9b-4dfb-49a3-b367-04b354373536",
      "purchaserGwid": "752bfe79-fc8b-48e9-8f7f-67cdd1c7a67c",
      "purchaserProfile": {
        "email": "johnbrown@thegroundwork.com",
        "familyName": "",
        "givenName": ""
      },
      "redeemedUtc": ""
    }
  ]
}

List all an Event’s Orders #

https://api.thegroundwork.com/events/events/{event-id}/orders/
Path parameters #
Parameter Description
event-id The unique identifier of the Event.
Response body parameters #
Parameter Type Description
cartId string The unique identifier for the cart created by the Order. This value is blank if no payment was necessary.
createdUtc string A ISO-8601 formatted creation time of the Order, given in UTC.
currency string A ISO-4217 currency code for any non-free Categories in the Order.
eventId string A unique identifier for the Event associated with the Order.
id string A unique identifier for the Order.
initiativeId string The Groundwork Initiative to which the object belongs.
invitationId string The unique identifier for the Invitation associated with the Order, if any.
price integer The sum of price for all Categories referenced by the Order, given in the least-significant unit of the currency, e.g. cents.
purchaserGwid string The gwid of the user making the Order.
status string The status of the Order. It may be either pending or completed.
tickets array An Array of Tickets requested by the Order. The array is empty if the Order status is not complete
Example request #
curl -X GET -H "Content-Type: application/json" -H "Authorization: Bearer {oauth-access-token}" "https://api.thegroundwork.com/events/events/64452ae1-2c17-4ffb-920f-31e8c2926b13/orders/"
Example response #
{
  "meta": {
    "count": 2,
    "totalPages": 1,
    "total": 2,
    "params": {
      "perPage": 10,
      "page": 1,
    }
  },
  "results": [
  {
  "cartId": "c3f5904a4073482f92d7701dcd0211e6",
  "createdUtc": "2016-07-07T18:14:00Z",
  "currency": "USD",
  "eventId": "64452ae1-2c17-4ffb-920f-31e8c2926b13",
  "id": "cbe35c9b-4dfb-49a3-b367-04b354373536",
  "initiativeId": "my_organization.my_initiative",
  "invitationId": "96548627-008c-403d-87fa-4826edde5f6d",
  "price": 2000,
  "purchaserGwid": "4e72eb91-c0b3-46e6-84f7-09bf9900e107",
  "status": "completed",
  "tickets": [
    {
      "attendeeGwid": "752bfe79-fc8b-48e9-8f7f-67cdd1c7a67c",
      "attendeeProfile": {
        "email": "johnbrown@thegroundwork.com",
        "familyName": "",
        "givenName": ""
      },
      "categoryId": "d4fb557a-ba04-43d9-a28e-c3da7e093075",
      "createdUtc": "2015-06-20T16:11:44Z",
      "eventId": "9df9edaa-6519-4a89-b758-47f884a9d27f",
      "id": "84e1e2c4-8ac9-4f38-9bd8-b1abfb8dc3d4",
      "initiativeId": "my_organization.my_initiative",
      "invitationId": "96548627-008c-403d-87fa-4826edde5f6d",
      "orderId": "cbe35c9b-4dfb-49a3-b367-04b354373536",
      "purchaserGwid": "752bfe79-fc8b-48e9-8f7f-67cdd1c7a67c",
      "purchaserProfile": {
        "email": "johnbrown@thegroundwork.com",
        "familyName": "",
        "givenName": ""
      },
      "redeemedUtc": ""
    },
    {
  "cartId": "c3f5904a4073482f92d7701dcd0211e6",
  "createdUtc": "2016-07-07T18:14:00Z",
  "currency": "USD",
  "eventId": "64452ae1-2c17-4ffb-920f-31e8c2926b13",
  "id": "d9900600d335455680d38f120a5cf805",
  "initiativeId": "my_organization.my_initiative",
  "invitationId": "",
  "price": 2000,
  "purchaserGwid": "f3fed15c-7007-4f39-82d8-930db0c3c0ea",
  "status": "completed",
  "tickets": [
    {
      "attendeeGwid": "f3fed15c-7007-4f39-82d8-930db0c3c0ea",
      "attendeeProfile": {
        "email": "nat@thegroundwork.com",
        "familyName": "Turner",
        "givenName": "Nat"
      },
      "categoryId": "d4fb557a-ba04-43d9-a28e-c3da7e093075",
      "createdUtc": "2015-06-20T16:11:44Z",
      "eventId": "9df9edaa-6519-4a89-b758-47f884a9d27f",
      "id": "79f351de996b4caeb88c13b1fc731388",
      "initiativeId": "my_organization.my_initiative",
      "invitationId": "",
      "orderId": "d9900600d335455680d38f120a5cf805",
      "purchaserGwid": "f3fed15c-7007-4f39-82d8-930db0c3c0ea",
      "purchaserProfile": {
        "email": "nat@thegroundwork.com",
        "familyName": "Turner",
        "givenName": "Nat"
      },
      "redeemedUtc": ""
    }
  ]
}

Tickets #

The Ticket object represents a Ticket obtained for an Event. Tickets are created via the /orders endpoint; they may be listed, updated and deleted via the /tickets endpoint.

Get a Ticket #

https://api.thegroundwork.com/events/events/{event-id}/categories/{categories-id}/tickets/{ticket-id}

Get a specific Ticket by its id.

Path parameters #
Parameter Description
event-id The unique identifier of the Event.
category-id The unique identifier of the Category.
ticket-id The unique identifier of the Ticket.
Response body parameters #
Parameter Type Description
attendeeGwid string The gwid of the user attending the event with this Ticket.
attendeeProfile object An object containing email, givenName, and familyName from the attendee’s Profile, as strings. May be null.
categoryId string The unique identifier for the Category to which the Ticket belongs.
createdUtc string A ISO-8601 formatted creation time of the Ticket, given in UTC.
eventId string The unique identifier for the Event to which the Ticket belongs.
id string The unique identifier for this Ticket.
initiativeId string The Groundwork Initiative to which the object belongs.
invitationId string The unique identifier for the Invitation associated with this Ticket.
orderId string The Order in which the Ticket was created
purchaserGwid string The gwid of the user purchasing this Ticket.
purchaserProfile object An object containing email, givenName, and familyName from the purchaser’s Profile, as strings.
redeemedUtc string A UTC ISO-8601 formatted time at which this Ticket was redeemed.
Example request #
curl -X GET -H "Content-Type: application/json" -H "Authorization: Bearer {oauth-access-token}" "https://api.thegroundwork.com/events/events/9df9edaa-6519-4a89-b758-47f884a9d27f/categories/d4fb557a-ba04-43d9-a28e-c3da7e093075/tickets/480bf1e8-8946-45dd-8e54-e91c99487190"
Example response #
    {
      "attendeeGwid": "752bfe79-fc8b-48e9-8f7f-67cdd1c7a67c",
      "attendeeProfile": {
        "email": "johnbrown@thegroundwork.com",
        "familyName": "",
        "givenName": ""
      },
      "categoryId": "d4fb557a-ba04-43d9-a28e-c3da7e093075",
      "createdUtc": "2015-06-20T16:11:44Z",
      "eventId": "9df9edaa-6519-4a89-b758-47f884a9d27f",
      "id": "84e1e2c4-8ac9-4f38-9bd8-b1abfb8dc3d4",
      "initiativeId": "my_organization.my_initiative",
      "invitationId": "",
      "orderId": "cbe35c9b-4dfb-49a3-b367-04b354373536",
      "purchaserGwid": "752bfe79-fc8b-48e9-8f7f-67cdd1c7a67c",
      "purchaserProfile": {
        "email": "johnbrown@thegroundwork.com",
        "familyName": "",
        "givenName": ""
      },
      "redeemedUtc": "2016-08-22T12:00:00Z"
    }

Update a Ticket #

https://api.thegroundwork.com/events/events/{event-id}/categories/{categories-id}/tickets/{ticket-id}

Update an existing Ticket by its id, modifying only the parameters that are passed. No request body parameters are required.

https://api.thegroundwork.com/events/events/{event-id}/categories/{categories-id}/tickets/{ticket-id}

Update an existing Ticket by its id, updating all parameters. Unpassed parameters will be overwritten as blank.

Path parameters #
Parameter Description
event-id The unique identifier of the Event.
category-id The unique identifier of the Category.
ticket-id The unique identifier of the Ticket.
Request body parameters #
Parameter Required Type Description
attendeeGwid string The gwid of the user attending the event with this Ticket. Not necessarily equivalent to purchaserGwid.
invitationId string The unique identifier of an Invitation, if associated with this Ticket. If provided, the specified Invitation will update its status to “accepted”, when the Ticket is redeemed.
redeemedUtc string The time that the Ticket was redeemed, in UTC. Formatted in ISO-8601, with a timezone designator.
Response body parameters #
Parameter Type Description
attendeeGwid string The gwid of the user attending the event with this Ticket.
attendeeProfile object An object containing email, givenName, and familyName from the attendee’s Profile, as strings. May be null.
categoryId string The unique identifier for the Category to which the Ticket belongs.
createdUtc string A ISO-8601 formatted creation time of the Ticket, given in UTC.
eventId string The unique identifier for the Event to which the Ticket belongs.
id string The unique identifier for this Ticket.
initiativeId string The Groundwork Initiative to which the object belongs.
invitationId string The unique identifier for the Invitation associated with this Ticket.
orderId string The Order in which the Ticket was created
purchaserGwid string The gwid of the user purchasing this Ticket.
purchaserProfile object An object containing email, givenName, and familyName from the purchaser’s Profile, as strings.
redeemedUtc string A UTC ISO-8601 formatted time at which this Ticket was redeemed.
Example request #
curl -X PUT -H "Content-Type: application/json" -H "Authorization: Bearer {oauth-access-token}" -d '{
  "redeemdUtc": "2016-04-07T12:00:00Z"
}' "https://api.thegroundwork.com/events/events/9df9edaa-6519-4a89-b758-47f884a9d27f/categories/d4fb557a-ba04-43d9-a28e-c3da7e093075/tickets/480bf1e8-8946-45dd-8e54-e91c99487190"
Example response #
    {
      "attendeeGwid": "752bfe79-fc8b-48e9-8f7f-67cdd1c7a67c",
      "attendeeProfile": {
        "email": "johnbrown@thegroundwork.com",
        "familyName": "",
        "givenName": ""
      },
      "categoryId": "d4fb557a-ba04-43d9-a28e-c3da7e093075",
      "createdUtc": "2015-06-20T16:11:44Z",
      "eventId": "9df9edaa-6519-4a89-b758-47f884a9d27f",
      "id": "84e1e2c4-8ac9-4f38-9bd8-b1abfb8dc3d4",
      "initiativeId": "my_organization.my_initiative",
      "invitationId": "",
      "orderId": "cbe35c9b-4dfb-49a3-b367-04b354373536",
      "purchaserGwid": "752bfe79-fc8b-48e9-8f7f-67cdd1c7a67c",
      "purchaserProfile": {
        "email": "nat@thegroundwork.com",
        "familyName": "Turner",
        "givenName": "Nat"
      },
      "redeemedUtc": "2016-04-07T12:00:00Z"
    }

Delete a Ticket #

https://api.thegroundwork.com/events/events/{event-id}/categories/{categories-id}/tickets/{ticket-id}

Delete a specific Ticket, by id.

Path parameters #
Parameter Description
event-id The unique identifier of the Event.
category-id The unique identifier of the Category.
ticket-id The unique identifier of the Ticket.
Example request #
curl -X DELETE -H "Content-Type: application/json" -H "Authorization: Bearer {oauth-access-token}" "https://api.thegroundwork.com/events/events/607d7f74-6e72-4f86-a046-4ea85ec42629/categories/ff6a0ef7-d138-4a89-967c-8c8db6499cbc/tickets/896f49b8-f5a8-4969-8077-bd3f586be845"
Example response #
204 No Content

List a Category’s Tickets #

https://api.thegroundwork.com/events/events/{event-id}/categories/{categories-id}/tickets
Path parameters #
Parameter Description
event-id The unique identifier of the Event.
category-id The unique identifier of the Category.
Query string parameters #
Parameter Type Description
isRedeemed Boolean Whether or not a Ticket has been redeemed.
purchaserGwid string The gwid of the user who purchased a Ticket.
page integer A metadata parameter for specifying a page of results to return.
perPage integer A metadata parameter for specifying number of results per page.
Response body parameters #
Parameter Type Description
attendeeGwid string The gwid of the user attending the event with this Ticket.
attendeeProfile object An object containing email, givenName, and familyName from the attendee’s Profile, as strings. May be null.
categoryId string The unique identifier for the Category to which the Ticket belongs.
createdUtc string A ISO-8601 formatted creation time of the Ticket, given in UTC.
eventId string The unique identifier for the Event to which the Ticket belongs.
id string The unique identifier for this Ticket.
initiativeId string The Groundwork Initiative to which the object belongs.
invitationId string The unique identifier for the Invitation associated with this Ticket.
orderId string The Order in which the Ticket was created
purchaserGwid string The gwid of the user purchasing this Ticket.
purchaserProfile object An object containing email, givenName, and familyName from the purchaser’s Profile, as strings.
redeemedUtc string A ISO-8601 formatted time at which this Ticket was redeemed, given in UTC.
Example request #
curl -X GET -H "Content-Type: application/json" -H "Authorization: Bearer {oauth-access-token}" "https://api.thegroundwork.com/events/events/9df9edaa-6519-4a89-b758-47f884a9d27f/categories/d4fb557a-ba04-43d9-a28e-c3da7e093075/tickets"
Example response #
{
  "meta": {
    "count": 2,
    "params": {
      "page": 1,
      "perPage": 10
    },
    "total": 2,
    "totalPages": 1
  },
  "results": [
    {
      "attendeeGwid": "752bfe79-fc8b-48e9-8f7f-67cdd1c7a67c",
      "attendeeProfile": {
        "email": "johnbrown@thegroundwork.com",
        "familyName": "",
        "givenName": ""
      },
      "categoryId": "d4fb557a-ba04-43d9-a28e-c3da7e093075",
      "createdUtc": "2015-06-20T16:11:44Z",
      "eventId": "9df9edaa-6519-4a89-b758-47f884a9d27f",
      "id": "84e1e2c4-8ac9-4f38-9bd8-b1abfb8dc3d4",
      "initiativeId": "my_organization.my_initiative",
      "invitationId": "",
      "orderId": "cbe35c9b-4dfb-49a3-b367-04b354373536",
      "purchaserGwid": "752bfe79-fc8b-48e9-8f7f-67cdd1c7a67c",
      "purchaserProfile": {
        "email": "johnbrown@thegroundwork.com",
        "familyName": "",
        "givenName": ""
      },
      "redeemedUtc": "2016-08-22T12:00:00Z"
    },
    {
      "attendeeGwid": "",
      "attendeeProfile": null,
      "categoryId": "d4fb557a-ba04-43d9-a28e-c3da7e093075",
      "createdUtc": "2015-06-20T16:11:44Z",
      "eventId": "9df9edaa-6519-4a89-b758-47f884a9d27f",
      "id": "36a91d28-dfaf-42c3-91ea-89806254ae35",
      "initiativeId": "my_organization.my_initiative",
      "invitationId": "",
      "orderId": "b4090498-34de-431a-bd59-25dc95eeed17",
      "purchaserGwid": "f3fed15c-7007-4f39-82d8-930db0c3c0ea",
      "purchaserProfile": {
        "email": "nat@thegroundwork.com",
        "familyName": "Turner",
        "givenName": "Nat"
      },
      "redeemedUtc": ""
    }
  ]
}

List all Tickets #

https://api.thegroundwork.com/events/tickets

List all Tickets, across Events. If called by an authenticated user, it will return all Tickets with a purchaserGwid that matches the requesting user’s gwid. When called by an Admin, it will return all Tickets.

Query string parameters #
Parameter Type Description
isRedeemed Boolean Whether or not a Ticket has been redeemed.
purchaserGwid string The gwid of the user who purchased a Ticket.
page integer A metadata parameter for specifying a page of results to return.
perPage integer A metadata parameter for specifying number of results per page.
startsBefore string Return Tickets whose Categories start before this ISO-8601 datetime.
startsAfter string Return Tickets whose Categories start after this ISO-8601 datetime.
endsBefore string Return Tickets whose Categories end before this ISO-8601 datetime.
endsAfter string Return Tickets whose Categories end after this ISO-8601 datetime..
Response body parameters #
Parameter Type Description
attendeeGwid string The gwid of the user attending the event with this Ticket.
attendeeProfile object An object containing email, givenName, and familyName from the attendee’s Profile, as strings. May be null.
categoryId string The unique identifier for the Category to which the Ticket belongs.
createdUtc string A ISO-8601 formatted creation time of the Ticket, given in UTC.
eventId string The unique identifier for the Event to which the Ticket belongs.
id string The unique identifier for this Ticket.
initiativeId string The Groundwork Initiative to which the object belongs.
invitationId string The unique identifier for the Invitation associated with this Ticket.
purchaserGwid string The gwid of the user purchasing this Ticket.
purchaserProfile object An object containing email, givenName, and familyName from the purchaser’s Profile, as strings.
redeemedUtc string A UTC ISO-8601 formatted time at which this Ticket was redeemed.
Example request #
curl -X GET -H "Content-Type: application/json" -H "Authorization: Bearer {oauth-access-token}" "https://api.thegroundwork.com/events/tickets"
Example response #
{
  "meta": {
    "count": 2,
    "params": {
      "page": 1,
      "perPage": 10
    },
    "total": 2,
    "totalPages": 1
  },
  "results": [
    {
      "attendeeGwid": "752bfe79-fc8b-48e9-8f7f-67cdd1c7a67c",
      "attendeeProfile": {
        "email": "johnbrown@thegroundwork.com",
        "familyName": "",
        "givenName": ""
      },
      "categoryId": "d4fb557a-ba04-43d9-a28e-c3da7e093075",
      "createdUtc": "2015-06-20T16:11:44Z",
      "eventId": "9df9edaa-6519-4a89-b758-47f884a9d27f",
      "id": "84e1e2c4-8ac9-4f38-9bd8-b1abfb8dc3d4",
      "initiativeId": "my_organization.my_initiative",
      "invitationId": "",
      "orderId": "cbe35c9b-4dfb-49a3-b367-04b354373536",
      "purchaserGwid": "752bfe79-fc8b-48e9-8f7f-67cdd1c7a67c",
      "purchaserProfile": {
        "email": "johnbrown@thegroundwork.com",
        "familyName": "",
        "givenName": ""
      },
      "redeemedUtc": "2016-08-22T12:00:00Z"
    },
    {
      "attendeeGwid": "",
      "attendeeProfile": null,
      "categoryId": "d4fb557a-ba04-43d9-a28e-c3da7e093075",
      "createdUtc": "2015-06-20T16:11:44Z",
      "eventId": "9df9edaa-6519-4a89-b758-47f884a9d27f",
      "id": "36a91d28-dfaf-42c3-91ea-89806254ae35",
      "initiativeId": "my_organization.my_initiative",
      "invitationId": "",
      "orderId": "b4090498-34de-431a-bd59-25dc95eeed17",
      "purchaserGwid": "f3fed15c-7007-4f39-82d8-930db0c3c0ea",
      "purchaserProfile": {
        "email": "nat@thegroundwork.com",
        "familyName": "Turner",
        "givenName": "Nat"
      },
      "redeemedUtc": ""
    }
  ]
}

Invitations #

The Invitation object is used to email people about an Event. Invitations may be “accepted”, “declined”, or “pending”.

Create an Invitation #

https://api.thegroundwork.com/events/events/{event-id}/invitations
Path parameters #
Parameter Description
event-id The unique identifier of the Event.
Request body parameters #
Parameter Required Type Description
email integer The email address of the Invitation recipient.
familyName string The last name of the Invitation recipient.
givenName string The first name of the Invitation recipient.
message string The message text to include in the Invitation that is sent.
subject string The email subject to include in the Invitation that is sent

Note - When creating an Invitation, pass an array of Invitations. You can pass multiple Invitations or a single one inside the array, but the email for each Invitation must be unique for the given Event. If you POST an Invitation with an email that matches an already existing Invitation, then that Invitation will not be created and will not be included in the response. If an Invitation is for an email that has unsubscribed, then that Invitation will not be created or included in the response. In either case, the response will still be 201.

Response body parameters #
Parameter Type Description
email string The email address of the Invitation recipient.
createdUtc string A ISO-8601 formatted creation time of the Invitation, given in UTC.
eventId string The unique identifier for the Event to which the Invitation belongs.
id string The unique identifier for this Invitation.
initiativeId string The Groundwork Initiative to which the object belongs.
familyName string The last name of the Invitation recipient.
givenName string The first name of the Invitation recipient.
message string The message text included in the Invitation.
status string The current RSVP status of the Invitation. Either “accepted”, “declined”, or “pending”.
subject string The email subject included in the Invitation.
Example request #
curl -X POST -H "Content-Type: application/json" -H "Authorization: Bearer {oauth-access-token}" -d '[
  {
    "email": "an@example.com",
    "familyName": "Doe",
    "givenName": "John",
    "message": "I hope you come to my event",
    "subject": "You're invited!"
  },
  {
    "email": "this@email.com",
    "familyName": "Lastname",
    "givenName": "FirstName",
    "message": "I hope you come to my event!",
    "subject": "You're invited!"
  }
]' "https://api.thegroundwork.com/events/events/9df9edaa-6519-4a89-b758-47f884a9d27f/invitations"
Example response #
[
  {
    "createdUtc": "2015-06-20T16:11:44Z",
    "email": "an@example.com",
    "eventId": "9df9edaa-6519-4a89-b758-47f884a9d27f",
    "familyName": "Doe",
    "givenName": "John",
    "id": "25b90eeb-8ddb-410e-aeb2-495da862b033",
    "initiativeId": "my_organization.my_initiative",
    "message": "I hope you come to my event",
    "status": "pending",
    "subject": "You're invited!"
  },
  {
    "createdUtc": "2015-06-20T16:11:44Z",
    "email": "this@email.com",
    "eventId": "9df9edaa-6519-4a89-b758-47f884a9d27f",
    "familyName": "Lastname",
    "givenName": "FirstName",
    "id": "e92119f3-e743-4922-8c20-feab82289a4d",
    "initiativeId": "my_organization.my_initiative",
    "message": "I hope you come to my event!",
    "status": "pending",
    "subject": "You're invited!"
  }
]

Get an Invitation #

https://api.thegroundwork.com/events/events/{event-id}/invitations/{invitation-id}

Get a specific Invitation by its id.

Path parameters #
Parameter Description
event-id The unique identifier of the Event.
invitation-id The unique identifier of the Invitation.
Response body parameters #
Parameter Type Description
email string The email address of the Invitation recipient.
createdUtc string A ISO-8601 formatted creation time of the Invitation, given in UTC.
eventId string The unique identifier for the Event to which the Invitation belongs.
id string The unique identifier for this Invitation.
initiativeId string The Groundwork Initiative to which the object belongs.
familyName string The last name of the Invitation recipient.
givenName string The first name of the Invitation recipient.
message string The message text included in the Invitation.
status string The current RSVP status of the Invitation. Either “accepted”, “declined”, or “pending”.
subject string The email subject included in the Invitation.
Example request #
curl -X GET -H "Content-Type: application/json" -H "Authorization: Bearer {oauth-access-token}" "https://api.thegroundwork.com/events/events/9df9edaa-6519-4a89-b758-47f884a9d27f/invitations/25b90eeb-8ddb-410e-aeb2-495da862b033"
Example response #
{
  "email": "an@example.com",
  "eventId": "9df9edaa-6519-4a89-b758-47f884a9d27f",
  "familyName": "Doe",
  "givenName": "John",
  "id": "25b90eeb-8ddb-410e-aeb2-495da862b033",
  "initiativeId": "my_organization.my_initiative",
  "message": "I hope you come to my event",
  "status": "pending",
  "subject": "You're invited!"
}

Update Invitation status #

https://api.thegroundwork.com/events/events/{event-id}/invitations/{invitation-id}

Update the status of an Invitation, by its id.

Path parameters #
Parameter Description
event-id The unique identifier of the Event.
invitation-id The unique identifier of the Invitation.
Request body parameters #
Parameter Required Type Description
status string The current RSVP status of the Invitation. You may update the status to “declined” or “pending”.

Note - You cannot accept an Invitation via this method or endpoint. To accept an Invitation, you must create an Order associated with the Invitation. When the status of an Invitation is updated from accepted to declined, the system deletes any tickets associated with that Invitation id.

Response body parameters #
Parameter Type Description
email string The email address of the Invitation recipient.
createdUtc string A ISO-8601 formatted creation time of the Invitation, given in UTC.
eventId string The unique identifier for the Event to which the Invitation belongs.
id string The unique identifier for this Invitation.
initiativeId string The Groundwork Initiative to which the object belongs.
familyName string The last name of the Invitation recipient.
givenName string The first name of the Invitation recipient.
message string The message attached to the Invitation.
status string The current RSVP status of the Invitation. Either “accepted”, “declined”, or “pending”.
Example request #
curl -X PATCH -H "Content-Type: application/json" -H "Authorization: Bearer {oauth-access-token}" -d '{
  "status": "declined"
}' "https://api.thegroundwork.com/events/events/9df9edaa-6519-4a89-b758-47f884a9d27f/invitations/25b90eeb-8ddb-410e-aeb2-495da862b033"
Example response #
{
  "createdUtc": "2015-06-20T16:11:44Z",
  "email": "an@example.com",
  "eventId": "9df9edaa-6519-4a89-b758-47f884a9d27f",
  "familyName": "Doe",
  "givenName": "John",
  "id": "25b90eeb-8ddb-410e-aeb2-495da862b033",
  "initiativeId": "my_organization.my_initiative",
  "message": "I hope you come to my event",
  "status": "declined",
  "subject": "You're invited!"
}

Delete an Invitation #

Note - This method is only available if the request comes from an admin (i.e. uses a client credential grant).

https://api.thegroundwork.com/events/events/{event-id}/invitations/{invitation-id}

Delete an Invitation, by its id.

Path parameters #
Parameter Description
event-id The unique identifier of the Event.
invitation-id The unique identifier of the Invitation.
Example request #
curl -X DELETE -H "Content-Type: application/json" -H "Authorization: Bearer {oauth-access-token}" -d '' "https://api.thegroundwork.com/events/events/9df9edaa-6519-4a89-b758-47f884a9d27f/invitations/80bf768d-1339-4af7-9bd6-8d4c4a9a42a2"
Example response #
204 No Content

List an Event’s Invitations #

https://api.thegroundwork.com/events/events/{event-id}/invitations
Path parameters #
Parameter Description
event-id The unique identifier of the Event.
Query string parameters #
Parameter Type Description
email string The “email” of an Invitation recipient.
status string The current RSVP status of the Invitations to return. Either “accepted”, “declined”, or “pending”.
page integer A metadata parameter for specifying a page of results to return.
perPage integer A metadata parameter for specifying number of results per page.
Example request #
curl -X GET -H "Content-Type: application/json" -H "Authorization: Bearer {oauth-access-token}" "https://api.thegroundwork.com/events/events/9df9edaa-6519-4a89-b758-47f884a9d27f/invitations"
Example response #
{
  "meta": {
    "count": 2,
    "totalPages": 1,
    "total": 2,
    "params": {
      "perPage": 10,
      "page": 1,
      "status": "pending"
    }
  },
  "results": [
    {
      "createdUtc": "2015-06-20T16:11:44Z",
      "email": "test@example.com",
      "eventId": "9df9edaa-6519-4a89-b758-47f884a9d27f",
      "familyName": "Doe",
      "givenName": "John",
      "id": "9763ea38-c48b-460a-9228-273624d8c321",
      "initiativeId": "my_organization.my_initiative",
      "message": "I hope you come to my event",
      "status": "pending",
      "subject": "You're invited!"
    },
    {
      "createdUtc": "2015-06-20T16:11:44Z",
      "email": "test1@example.com",
      "eventId": "9df9edaa-6519-4a89-b758-47f884a9d27f",
      "familyName": "D'oh",
      "givenName": "Jonn",
      "id": "80bf768d-1339-4af7-9bd6-8d4c4a9a42a2",
      "initiativeId": "my_organization.my_initiative",
      "message": "I hope you come to my event!",
      "status": "pending",
      "subject": "You're invited!"
    }
  ]
}

Messages #

The Message object is used to send an email to invitees or ticketholders, for example to remind them about an upcoming event or thank them for attending a past event. Since a Message record represents a historical record of an email communication, they cannot be updated.

Create a Message #

https://api.thegroundwork.com/events/events/{event-id}/messages
Path parameters #
Parameter Description
event-id The unique identifier of the Event.
Request body parameters #
Parameter Required Type Description
message string The message text to include in the Message that is sent.
recipientTypes array Who should receive the Message.
subject string The email subject to include in the Message that is sent.
template string The email template name to use when sending the Message email.
title string The title headline text to include in the Message that is sent.

Note - Use one or more of the following values when populating recipientTypes:

  • attendees_redeemed - Invividuals whose attendeeGwid is on a Ticket that has been redeemed (redeemedUtc has a value).
  • attendees_not_redeemed - Invividuals whose attendeeGwid is on a Ticket that has not yet been redeemted (redeemedUtc is empty).
  • invitees_pending - Individuals whose email is on an Invitation for which status is “pending”.
  • invitees_declined - Individuals whose email is on an Invitation for which status is “declined”.

Note - If a Message is sent to an individual who has unsubscribed, then that Message will not be created or included in the response. In either case, the response will still be 201.

Response body parameters #
Parameter Type Description
createdUtc string A ISO-8601 formatted creation time of the Message, given in UTC.
email string The email address of the Message recipient, if the recipient was fetched from an Invitation record.
eventId string The unique identifier for the Event to which the Invitation belongs.
gwid string The unique identifier of the Message recipient, if the recipient was fetched from a Ticket record.
id string The unique identifier for this Invitation.
initiativeId string The Groundwork Initiative to which the object belongs.
message string The message text included in the Message.
subject string The email template name used to send the Message email.
template string The email subject included in the Message.
title string The title headline text included in the Message.
Example request #
curl -X POST -H "Content-Type: application/json" -H "Authorization: Bearer {oauth-access-token}" -d '[
{
  "message": "I'm excited to see you at my event!",
    "recipientTypes": [
      "attendees_redeemed",
      "attendees_not_redeemed",
      "invitees_pending"
  ],
  "subject": "Can't wait to see you!",
  "template": "my_template",
  "title": "1 More Day!"
}
]' "https://api.thegroundwork.com/events/events/c84c8a10-fc0d-4bbc-beb5-86d921974998/messages"
Example response #
{
  "meta": {
    "count": 2,
    "params": {
      "page": 1,
      "perPage": 10
    },
    "total": 2,
    "totalPages": 1
  },
  "results": [
    {
      "createdUtc": "2015-06-20T16:11:44Z",
      "email": "",
      "eventId": "c84c8a10-fc0d-4bbc-beb5-86d921974998",
      "gwid": "ba5defe9-4a38-4782-abf6-70e81823a53f",
      "id": "82f29c96-bd9d-4e03-9c7d-e58c6e8bc50f",
      "initiativeId": "my_organization.my_initiative",
      "message": "I'm excited to see you at my event!",
      "subject": "Can't wait to see you!",
      "template": "my_template",
      "title": "1 More Day!"
    },
    {
      "createdUtc": "2015-06-20T16:11:44Z",
      "email": "example@example.com",
      "eventId": "c84c8a10-fc0d-4bbc-beb5-86d921974998",
      "gwid": "",
      "id": "b7269c74-773e-4070-a179-038158dd83ec",
      "initiativeId": "my_organization.my_initiative",
      "message": "I'm excited to see you at my event!",
      "subject": "Can't wait to see you!",
      "template": "my_template",
      "title": "1 More Day!"
    }
  ]
}

Get a Message #

https://api.thegroundwork.com/events/events/{event-id}/messages/{message-id}

Get a specific Message by its id.

Path parameters #
Parameter Description
event-id The unique identifier of the Event.
message-id The unique identifier of the Invitation.
Response body parameters #
Parameter Type Description
createdUtc string A ISO-8601 formatted creation time of the Message, given in UTC.
email string The email address of the Message recipient, if the recipient was fetched from an Invitation record.
eventId string The unique identifier for the Event to which the Invitation belongs.
gwid string The unique identifier of the Message recipient, if the recipient was fetched from a Ticket record.
id string The unique identifier for this Invitation.
initiativeId string The Groundwork Initiative to which the object belongs.
message string The message text included in the Message.
subject string The email template name used to send the Message email.
template string The email subject included in the Message.
title string The title headline text included in the Message.
Example request #
curl -X GET -H "Content-Type: application/json" -H "Authorization: Bearer {oauth-access-token}" "https://api.thegroundwork.com/events/events/c84c8a10-fc0d-4bbc-beb5-86d921974998/messages/b7269c74-773e-4070-a179-038158dd83ec"
Example response #
{
  "createdUtc": "2015-06-20T16:11:44Z",
  "email": "",
  "eventId": "c84c8a10-fc0d-4bbc-beb5-86d921974998",
  "gwid": "ba5defe9-4a38-4782-abf6-70e81823a53f",
  "id": "82f29c96-bd9d-4e03-9c7d-e58c6e8bc50f",
  "initiativeId": "my_organization.my_initiative",
  "message": "I'm excited to see you at my event!",
  "subject": "Can't wait to see you!",
  "template": "my_template",
  "title": "1 More Day!"
}

Delete a Message #

Note - This method is only available if the request comes from an admin (i.e. uses a client credential grant).

https://api.thegroundwork.com/events/events/{event-id}/messages/{message-id}

Delete a Message, by its id.

Path parameters #
Parameter Description
event-id The unique identifier of the Event.
message-id The unique identifier of the Message.

Note - Since a Message record represents a historical record of an email communication, we do not recommend deleting them.

Example request #
curl -X DELETE -H "Content-Type: application/json" -H "Authorization: Bearer {oauth-access-token}" -d '' "https://api.thegroundwork.com/events/events/c84c8a10-fc0d-4bbc-beb5-86d921974998/messages/b7269c74-773e-4070-a179-038158dd83ec"
Example response #
204 No Content

List an Event’s Messages #

https://api.thegroundwork.com/events/events/{event-id}/messages
Path parameters #
Parameter Description
event-id The unique identifier of the Event.
Query string parameters #
Parameter Type Description
page integer A metadata parameter for specifying a page of results to return.
perPage integer A metadata parameter for specifying number of results per page.
Example request #
curl -X GET -H "Content-Type: application/json" -H "Authorization: Bearer {oauth-access-token}" "https://api.thegroundwork.com/events/events/c84c8a10-fc0d-4bbc-beb5-86d921974998/messages"
Example response #
{
  "meta": {
    "count": 2,
    "params": {
      "page": 1,
      "perPage": 10,
      "eventId": "c84c8a10-fc0d-4bbc-beb5-86d921974998"
    },
    "total": 2,
    "totalPages": 1
  },
  "results": [
    {
      "createdUtc": "2015-06-20T16:11:44Z",
      "email": "",
      "eventId": "c84c8a10-fc0d-4bbc-beb5-86d921974998",
      "gwid": "ba5defe9-4a38-4782-abf6-70e81823a53f",
      "id": "82f29c96-bd9d-4e03-9c7d-e58c6e8bc50f",
      "initiativeId": "my_organization.my_initiative",
      "message": "I'm excited to see you at my event!",
      "subject": "Can't wait to see you!",
      "template": "my_template",
      "title": "1 More Day!"
    },
    {
      "createdUtc": "2015-06-20T16:11:44Z",
      "email": "example@example.com",
      "eventId": "c84c8a10-fc0d-4bbc-beb5-86d921974998",
      "gwid": "",
      "id": "b7269c74-773e-4070-a179-038158dd83ec",
      "initiativeId": "my_organization.my_initiative",
      "message": "I'm excited to see you at my event!",
      "subject": "Can't wait to see you!",
      "template": "my_template",
      "title": "1 More Day!"
    }
  ]
}

Unsubscribe #

Unsubscribe from a Host’s emails #

https://api.thegroundwork.com/events/host-unsubscribe

Unsubscribe an email address from all communication from a specific Event host.

Note - Unsubscribing from a host will prevent that email address from receiving any future emails from that host, regardless of the Event it is in reference to. This enables opting-out of abusive or spamming hosts. It should be clearly indicated in the UI that the user is unsubscribing from all correspondence from this host, so that they do not incidentally opt-out of future Messages.

Request body parameters #
Parameter Required Type Description
email string The email address of the user that wants to unsubscribe.
invitationId string The unique identifier of the Invitation that triggered the unsubscribe request. Used to map back to the sending host.
messageId string The unique identifier of the Message that triggered the unsubscribe request. Used to map back to the sending host.

Note - Though both invitationId and messageId are listed as optional, one and only one must be present in your request.

Response body parameters #
Parameter Type Description
email string The email address of user that unsubscribed.
invitationId string The unique identifier of the unsubscribe request.
Example request #
curl -X POST -H "Content-Type: application/json" -H "Authorization: Bearer {oauth-access-token}" -d '{
    "email": "email@example.com",
    "invitationId": "9763ea38-c48b-460a-9228-273624d8c321"
}' "https://api.thegroundwork.com/events/host-unsubscribe"
Example response #
{
  "email": "email@example.com",
  "id": "ffbc51b6-89b4-40dd-9d61-72d6e1c3f2be"
}