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 |
|
2016-12-12 | ✔ | Introduced the /p2p/* endpoints for Peer-to-peer fundraising |
Note - API keys are pinned to the current default version. For example, if you created an API key on 2016-10-10
it would not have access to the P2P endpoints added in version 2016-12-12
. You will need to create a new key and update your apps.
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 [email protected]
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 |
---|---|---|---|
✔ | 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 protected]",
"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 schemaId s. |
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 [email protected] 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": "[email protected]",
"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": "[email protected]",
"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 [email protected].
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 [email protected] 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. | |
✔ | 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. |
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": "[email protected]",
"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": "[email protected]",
"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. |
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": "[email protected]",
"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. |
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. |
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/[email protected]&perPage;=2"
Example response #
{
"meta": {
"count": 2,
"totalPages": 7,
"params": {
"perPage": 2,
"page": 1,
"email": "[email protected]"
}
},
"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": "[email protected]",
"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": "[email protected]",
"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. | |
✔ | 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. |
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": "[email protected]",
"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": "[email protected]",
"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. |
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": "[email protected]",
"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. |
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": "[email protected]",
"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 . |
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. |
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/[email protected]&perPage;=2"
Example response #
{
"meta": {
"count": 2,
"totalPages": 5,
"params": {
"perPage": 2,
"page": 1,
"email": "[email protected]"
}
},
"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": "[email protected]",
"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": "[email protected]",
"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. | |
✔ | 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. |
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": "[email protected]",
"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": "[email protected]",
"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. |
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": "[email protected]",
"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. |
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": "[email protected]",
"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. |
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": "[email protected]",
"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 . |
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. |
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": "[email protected]",
"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": "[email protected]",
"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 [email protected].
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 [email protected] 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. |
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": "[email protected]",
"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": "[email protected]",
"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": "[email protected]",
"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. |
|
✔ | 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. |
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 protected]",
"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 protected]",
"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. |
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": "[email protected]",
"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 |
---|---|---|---|
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. |
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": "[email protected]",
"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": "[email protected]",
"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 |
---|---|---|---|
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. |
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 protected]"
Example response #
{
"meta": {
"count": 1,
"totalPages": 1,
"total": 1,
"params": {
"perPage": 10,
"page": 1
}
},
"profiles": [
{
"gwid": "f238fafe-7f0f-454c-910b-9bedbc86d06b",
"email": "[email protected]",
"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. |
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 protected]",
"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 |
---|---|---|---|
✔ | 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 protected]"
}' "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. |
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 protected]",
"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. |
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 protected]",
"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:
- Front end creates a new Order.
- System:
- decrements
quantityRemaining
for the Categories specified in the new Order. - responds with Order object, including
cartId
.
- decrements
- Front end creates a new Donation, passing in the Order’s
cartId
. - 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 |
---|---|---|---|---|
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": "[email protected]",
"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": "[email protected]",
"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": "[email protected]",
"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": "[email protected]",
"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": "[email protected]",
"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": "[email protected]",
"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": "[email protected]",
"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": "[email protected]",
"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": "[email protected]",
"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": "[email protected]",
"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": "[email protected]",
"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": "[email protected]",
"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": "[email protected]",
"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": "[email protected]",
"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": "[email protected]",
"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": "[email protected]",
"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": "[email protected]",
"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": "[email protected]",
"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": "[email protected]",
"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 |
---|---|---|---|
✔ | 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 |
---|---|---|
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": "[email protected]",
"familyName": "Doe",
"givenName": "John",
"message": "I hope you come to my event",
"subject": "You're invited!"
},
{
"email": "[email protected]",
"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": "[email protected]",
"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": "[email protected]",
"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 |
---|---|---|
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": "[email protected]",
"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 |
---|---|---|
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": "[email protected]",
"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 |
---|---|---|
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": "[email protected]",
"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": "[email protected]",
"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 whoseattendeeGwid
is on a Ticket that has been redeemed (redeemedUtc
has a value).attendees_not_redeemed
- Invividuals whoseattendeeGwid
is on a Ticket that has not yet been redeemted (redeemedUtc
is empty).invitees_pending
- Individuals whoseemail
is on an Invitation for whichstatus
is “pending”.invitees_declined
- Individuals whoseemail
is on an Invitation for whichstatus
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. |
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": "[email protected]",
"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. |
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": "[email protected]",
"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 |
---|---|---|---|
✔ | 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 |
---|---|---|
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 protected]",
"invitationId": "9763ea38-c48b-460a-9228-273624d8c321"
}' "https://api.thegroundwork.com/events/host-unsubscribe"
Example response #
{
"email": "[email protected]",
"id": "ffbc51b6-89b4-40dd-9d61-72d6e1c3f2be"
}