Pledges
Last updated
Last updated
This 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.
UUID (v4). The pledge's globally unique identifier in the system. If not provided, a new UUID will be generated.
"82b431f0-f401-4afd-b6db-9d1d751232d9"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.
UUID (v4) of the person that made this pledge.
"adb97226-a7d7-4a39-8564-765131d5643b"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.
"active"Date of pledge creation, formatted as ISO8601 date string.
"2023-05-01T00:00:00.000Z"UUID (v4) of the organization that owns this pledge.
"82b431f0-f401-4afd-b6db-9d1d751232d9"UUID (v4) of the organization that recruited this pledge
"82b431f0-f401-4afd-b6db-9d1d751232d9"The label of the location where the pledge was recruited.
"Utrecht"The 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.
"monthly"The 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 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.
"once"The 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.5Describes how this pledge was recruited. Currently supported values are:
d2d → Door-to-door recruitmentstreet → Street recruitment"street"UUID (v4) of the recruiter that recruited the pledge.
"82b431f0-f401-4afd-b6db-9d1d751232d9"Date of pledge start, formatted as ISO8601 date string
"2023-05-01T00:00:00.000Z"This field allows you to add metadata to the pledge concerning where it origins from, for later reference.
Array 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']"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.
Date 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.000Z"The 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.000Z"Date 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.000Z"Date 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.000Z"Additional 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.
Pledge was created
UUID (v4)
"5cf67f69-34d0-46fe-b904-20d56248a844"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."lead"ISO8601 compatible datetime string
"2017-07-21T17:32:28Z"ISO8601 compatible datetime string
"2017-07-21T17:32:28Z"ISO8601 compatible datetime string
"2017-07-21T17:32:28Z"ISO8601 compatible datetime string describing when the pledge was last updated
"2017-07-21T17:32:28Z"ISO8601 compatible datetime string
"2017-07-21T17:32:28Z"Organization recruited for
Recruiting organization
The label of the location where the pledge was recruited.
"Utrecht"The donation amount at the moment the pledge was submitted.
7.5The current donation amount
7.5The donation interval at the moment the pledge was submitted.
"monthly"The current donation interval
"monthly"The preferred payment day of the month (options: 1 - 28). Default value, when not supplied or user has no preference, is: null
13Related person.
Note: Not included when this pledge case is requested with the include query parameter via the GET calls endpoint. In that case you can use the CallDto.person.
"d2d"User that recruited the pledge
Temporary URL to signature file, valid for 1 hour
"https://storage.googleapis.com/test/signature.mp3?GoogleAccessId=service-account%40test.iam.gserviceaccount.com&Expires=1659968507&Signature="Transactions that were created for this pledge case.
Note: Only included when explicitly requested via the include query parameter via the GET pledges endpoint.
Calls that were created for this pledge case.
Note: Only included when explicitly requested via the include query parameter via the GET pledges endpoint.
When the pledge case is imported into TapRaise, for instance from Backstage, it has an external source definition set that describes where it comes from and what its identifier in the external system is.
Additional properties provided by/about the external system.
This 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.
The UUID of the pledge to update the status for
The status update action
Pledge was updated
UUID (v4)
"5cf67f69-34d0-46fe-b904-20d56248a844"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."lead"ISO8601 compatible datetime string
"2017-07-21T17:32:28Z"ISO8601 compatible datetime string
"2017-07-21T17:32:28Z"ISO8601 compatible datetime string
"2017-07-21T17:32:28Z"ISO8601 compatible datetime string describing when the pledge was last updated
"2017-07-21T17:32:28Z"ISO8601 compatible datetime string
"2017-07-21T17:32:28Z"Organization recruited for
Recruiting organization
The label of the location where the pledge was recruited.
"Utrecht"The donation amount at the moment the pledge was submitted.
7.5The current donation amount
7.5The donation interval at the moment the pledge was submitted.
"monthly"The current donation interval
"monthly"The preferred payment day of the month (options: 1 - 28). Default value, when not supplied or user has no preference, is: null
13Related person.
Note: Not included when this pledge case is requested with the include query parameter via the GET calls endpoint. In that case you can use the CallDto.person.
"d2d"User that recruited the pledge
Temporary URL to signature file, valid for 1 hour
"https://storage.googleapis.com/test/signature.mp3?GoogleAccessId=service-account%40test.iam.gserviceaccount.com&Expires=1659968507&Signature="Transactions that were created for this pledge case.
Note: Only included when explicitly requested via the include query parameter via the GET pledges endpoint.
Calls that were created for this pledge case.
Note: Only included when explicitly requested via the include query parameter via the GET pledges endpoint.
When the pledge case is imported into TapRaise, for instance from Backstage, it has an external source definition set that describes where it comes from and what its identifier in the external system is.
Additional properties provided by/about the external system.
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 releasedAfter-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 releasedAfter-filter value, instead of the last cursor.
First day: retrieve until pageInfo.hasNextPage is false in the response, and afterwards store the date and time of now, to be the releasedAfter-value for tomorrow.
Second day: retrieve all released after the previous datetime you fetched, retrieve until pageInfo.hasNextPage is false in the response, and afterwards store the date and time of the last pledge you received.
etc.
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.
The uuid of the pledge case
The label of the location where the pledge was recruited.
"Utrecht"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.
"monthly"The 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-9d1d751232d9"Date of pledge start, formatted as ISO8601 date string
"2023-05-01T00:00:00.000Z"Date 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.000Z"Additional 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.
Pledge case was updated
UUID (v4)
"5cf67f69-34d0-46fe-b904-20d56248a844"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."lead"ISO8601 compatible datetime string
"2017-07-21T17:32:28Z"ISO8601 compatible datetime string
"2017-07-21T17:32:28Z"ISO8601 compatible datetime string
"2017-07-21T17:32:28Z"ISO8601 compatible datetime string describing when the pledge was last updated
"2017-07-21T17:32:28Z"ISO8601 compatible datetime string
"2017-07-21T17:32:28Z"Organization recruited for
Recruiting organization
The label of the location where the pledge was recruited.
"Utrecht"The donation amount at the moment the pledge was submitted.
7.5The current donation amount
7.5The donation interval at the moment the pledge was submitted.
"monthly"The current donation interval
"monthly"The preferred payment day of the month (options: 1 - 28). Default value, when not supplied or user has no preference, is: null
13Related person.
Note: Not included when this pledge case is requested with the include query parameter via the GET calls endpoint. In that case you can use the CallDto.person.
"d2d"User that recruited the pledge
Temporary URL to signature file, valid for 1 hour
"https://storage.googleapis.com/test/signature.mp3?GoogleAccessId=service-account%40test.iam.gserviceaccount.com&Expires=1659968507&Signature="Transactions that were created for this pledge case.
Note: Only included when explicitly requested via the include query parameter via the GET pledges endpoint.
Calls that were created for this pledge case.
Note: Only included when explicitly requested via the include query parameter via the GET pledges endpoint.
When the pledge case is imported into TapRaise, for instance from Backstage, it has an external source definition set that describes where it comes from and what its identifier in the external system is.
Additional properties provided by/about the external system.