Pledges
Last updated
Was this helpful?
Last updated
Was this helpful?
The pledges you are able to fetch might be filtered by your service account's permissions, the organization you represent and the filters you have applied.
The collection you are paginating is sorted by creation datetime, descending. This means that the first page contains the most recently created pledges.
When you are retrieving recently released pledges using the <code>releasedAfter</code>-filter, one thing to keep in mind is not to store the last cursor as the starting point for retrieving tomorrow's results.
When pledges are created/submitted, they are released after a cooling down period, to allow for proper verification. However the returned collection you are paginating is sorted by creation datetime, this means that newly released pledges were previously not returned but might get added to the collection BEFORE your current cursor, which might result in you missing out on pledges.
Therefor we recommend storing the date and time you last fetched, and use that next time as the <code>releasedAfter</code>-filter value, instead of the last cursor.
<details> <summary>Example of recommended use, fetching newly released pledges every day</summary>First day: retrieve until <code>pageInfo.hasNextPage</code> is <code>false</code> in the response, and afterwards store the date and time of now, to be the <code>releasedAfter</code>-value for tomorrow.
Second day: retrieve all released after the previous datetime you fetched, retrieve until <code>pageInfo.hasNextPage</code> is <code>false</code> in the response, and afterwards store the date and time of the last pledge you received.
etc.
/api/v1/pledges
Include additional data in the response
transactionsPledge cursor to fetch results before
a3c2a57e-2797-4159-8700-8ad55bf8150eThe amount of results to fetch before the 'before' cursor
10Pledge cursor to fetch results after
a3c2a57e-2797-4159-8700-8ad55bf8150eThe amount of results to fetch after the 'after' cursor
10Filter by person uuid. This will be a v4 UUID
a3c2a57e-2797-4159-8700-8ad55bf8150ePledge case status<br><br> Note: <i>released</i> is deprecated and will be removed in the next version
leadlead, active, dropped, released, cancelled, fulfilled, allISO8601 compatible datetime string. If applied only pledges will be returned that have been updated after the supplied datetime
2017-07-21T17:32:28ZISO8601 compatible datetime string
2017-07-21T17:32:28ZThis endpoint creates a pledge for an organization, if your service account allows you to.
The 'owningOrganizationUuid' and 'recruitingOrganizationUuid' might also be bound to limitations depending on your service account's organization scope and permissions.
We advice you to provide your own 'uuid' value, as you can use this as a mechanism to ensure the pledge is only created once. When accidentally the pledge is posted twice, the uuid will ensure it is only saved the first time, and a 409 CONFLICT status will be returned when posted a second time with the same uuid. When you don't supply a uuid, the system will generate one for you, which will be returned in the response body.
This endpoint will return the pledge created with the data in your request body.
When creating a pledge through the API, you need to determine where the pledge will be managed. You can do this by supplying or not supplying an externalSource-property in the request body. Based upon the value of this property, different input validation and domain rules apply.
When you don't supply an external source, we consider the pledge to be primarily managed in TapRaise.app, and it needs to adhere to TapRaise's domain rules that are there to ensure it's validity and quality. This means it will start out as a 'lead' in our system, and cannot be created in any other status. Afterwards it can be updated in the TapRaise.app UI.
When you supply an external source, we consider the pledge to be primarily managed at that source, and do NOT apply the domain rules we apply on pledges managed in TapRaise. We consider it as external data that cannot be updated in TapRaise.app.
Be sure to check the descriptions for fields in the request body to see which fields are required, optional or forbidden for each scenario.
/api/v1/pledges
UUID (v4). The pledge's globally unique identifier in the system. If not provided, a new UUID will be generated.
82b431f0-f401-4afd-b6db-9d1d751232d9UUID (v4) of the person that made this pledge.
adb97226-a7d7-4a39-8564-765131d5643bDate of pledge creation, formatted as ISO8601 date string.
2023-05-01T00:00:00.000ZUUID (v4) of the organization that owns this pledge.
82b431f0-f401-4afd-b6db-9d1d751232d9UUID (v4) of the organization that recruited this pledge
82b431f0-f401-4afd-b6db-9d1d751232d9The label of the location where the pledge was recruited.
UtrechtThe current donated amount, in Euros. The donation amount is not allowed to be set when creating a pledge that is managed in TapRaise. Use initialDonationAmount instead. See the general description of this endpoint for more information about validation rules depending on where the pledge is managed..
7.5The initial donation amount of this pledge, in Euros. As the donation amount might change over time, this fields represents the amount at the moment the pledge was created. The donationAmount field should contain its current value.
12.5UUID (v4) of the recruiter that recruited the pledge.
82b431f0-f401-4afd-b6db-9d1d751232d9Date of pledge start, formatted as ISO8601 date string
2023-05-01T00:00:00.000ZDate of pledge cancellation, formatted as ISO8601 date string. This field is not allowed to be set when creating a pledge that is managed in TapRaise. See the general description of this endpoint for more information about validation rules depending on where the pledge is managed.
2023-05-01T00:00:00.000ZThe preferred day of the month the pledge is to be collected on. Should be an integer between 1 and 28.
8Date when the pledge was dropped, formatted as ISO8601 date string. This field is not allowed to be set when creating a pledge that is managed in TapRaise. See the general description of this endpoint for more information about validation rules depending on where the pledge is managed.
2023-05-01T00:00:00.000ZDate when the pledge was released, formatted as ISO8601 date string. This field is not allowed to be set when creating a pledge that is managed in TapRaise. See the general description of this endpoint for more information about validation rules depending on where the pledge is managed.
2023-05-01T00:00:00.000ZDate the pledge ends, formatted as ISO8601 date string. Leave empty if unknown. This field is not allowed to be set when creating a pledge that is managed in TapRaise. See the general description of this endpoint for more information about validation rules depending on where the pledge is managed.
2023-05-01T00:00:00.000ZAdditional properties provided by/about the external system. This field is allowed to be set when creating a pledge that is managed in TapRaise. See the general description of this endpoint for more information about validation rules depending on where the pledge is managed.
The current status of the pledge:
lead → lead pledge, to be collected. Initial status.active → active pledge, being collected.dropped → dropped before it was ever collected or released.cancelled → cancelled after it was collected or released.fulfilled → ended after reaching its end date.Status is not allowed to be set when creating a pledge that is managed in TapRaise. It will by default get assigned status lead after creation. Externally sourced pledges are allowed to be created with any status from the whitelist.
activelead, active, dropped, cancelled, fulfilledThe interval of the donation. The donation interval is not allowed to be set when creating a pledge that is managed in TapRaise. Use initialDonationInterval instead. See the general description of this endpoint for more information about validation rules depending on where the pledge is managed.
monthlyonce, monthly, halfYearly, quarterly, yearlyThe initial donation interval of this pledge. As the donation interval might change over time, this field represents the donation interval at the moment the pledge was created. The donationInterval field should contain its current value.
onceonce, monthly, halfYearly, quarterly, yearlyDescribes how this pledge was recruited. Currently supported values are:
d2d → Door-to-door recruitmentstreet → Street recruitmentstreetd2d, streetArray of UUIDs (v4) of the focus areas for this pledge. During recruitment the recruiter can select one or more focus areas for the pledge, that can later on for instance be used to filter pledges or supply custom news feeds to them. The supplied UUIDs should match the allowed focus areas for the owning organization.
['4bb765d0-3d5f-48ab-ac7e-59da84d5f297']When provided the pledge is considered to be managed in this external system, and the pledge is not editable in TapRaise and does not need to adhere to the TapRaise domain rules. See the general description of this endpoint for more information.
This field allows you to add metadata to the pledge concerning where it origins from, for later reference.
Signature of the person that made the pledge, that functions as a proof of consent. For now we only support signatures for internal purposes, but in the future we might support external signatures as well.
When the pledge is cancelled, this field should contain a cancellation reason. This field is not allowed to be set when creating a pledge that is managed in TapRaise. See the general description of this endpoint for more information about validation rules depending on where the pledge is managed.
This endpoint can update the following details of the pledge case: donation amount, donation interval, start day of the donation, end day of the donation and the UUID of the recruiter.
Only supply the properties you want to update. When you supply null it means: update to null. When you don't supply anything it means: don't update.
The person who is allowed to update a pledge case is limited by your service account.
This endpoint will return the updated pledge case in the response body.
/api/v1/pledges/{uuid}/actions/update
The uuid of the pledge case
The label of the location where the pledge was recruited.
UtrechtThe current donated amount, in Euros. The donation amount is only allowed to be set when updating a pledge that is managed in TapRaise. Use initialDonationAmount instead when creating a pledge. See the general description of this endpoint for more information about validation rules depending on where the pledge is managed..
7.5UUID (v4) of the recruiter that recruited the pledge.
82b431f0-f401-4afd-b6db-9d1d751232d9Date of pledge start, formatted as ISO8601 date string
2023-05-01T00:00:00.000ZDate the pledge ends, formatted as ISO8601 date string. Leave empty if unknown. This field is only allowed to be set when updating a pledge that is managed in TapRaise. See the general description of this endpoint for more information about validation rules depending on where the pledge is managed.
2023-05-01T00:00:00.000ZAdditional properties provided by/about the external system. This field is allowed to be set when updating a pledge that is managed in TapRaise. See the general description of this endpoint for more information about validation rules depending on where the pledge is managed.
The interval of the donation. The donation interval is only allowed to be set when updating a pledge that is managed in TapRaise. Use initialDonationInterval instead when creating a pledge. See the general description of this endpoint for more information about validation rules depending on where the pledge is managed.
monthlyonce, monthly, halfYearly, quarterly, yearlyThis endpoint allows you to execute actions to updates the status of a pledge, if your service account allows you to and the pledge is within your organization scope.
See the response documentation for the possible statuses and what they mean.
It returns the updated pledge case.
/api/v1/pledges/{uuid}/actions/{statusUpdateAction}
The UUID of the pledge to update the status for
The status update action
markLead, markActive, drop, cancel, markFulfilled