search

Pledges

get

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.

hashtag
Fetching newly released pledges periodically

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.

chevron-rightExample of recommended use, fetching newly released pledges every dayhashtag

  1. 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.

    • first page: /api/v1/pledges?releasedAfter=[initial]&first=50

    • second page: /api/v1/pledges?releasedAfter=[initial]&first=10&after=41222ef7-a861-4bbd-ae93-2f645336b85d

    • ...

    • last page: /api/v1/pledges?releasedAfter=[initial]&first=10&after=10d303b1-4eca-4db4-9ae7-7cd65f98a5b5

  2. 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.

    • first page: /api/v1/pledges?releasedAfter=[previousDay]&first=50

    • second page: /api/v1/pledges?releasedAfter=[previousDay]&first=10&after=bd82f150-a797-4d9f-af09-c3ea06964e9d

    • ...

    • last page: /api/v1/pledges?releasedAfter=[previousDay]&first=10&after=3c53b11a-adef-4dc1-90d7-c23dc0108492

  3. etc.

Authorizations
AuthorizationstringRequired
Bearer authentication header of the form Bearer <token>.
Query parameters
includestring · enumOptional

Include additional data in the response

Example: transactionsPossible values:
beforestringOptional

Pledge cursor to fetch results before

Example: a3c2a57e-2797-4159-8700-8ad55bf8150e
lastnumberOptional

The amount of results to fetch before the 'before' cursor

Example: 10
afterstringOptional

Pledge cursor to fetch results after

Example: a3c2a57e-2797-4159-8700-8ad55bf8150e
firstnumberOptional

The amount of results to fetch after the 'after' cursor

Example: 10
personUuidstringOptional

Filter by person uuid. This will be a v4 UUID

Example: a3c2a57e-2797-4159-8700-8ad55bf8150e
withIdealQrbooleanOptional

Filter by pledges that have an iDEAL QR transaction

Example: false
statusstring · enumOptional

Pledge case status

Example: leadPossible values:
updatedAfterstring · date-timeOptional

ISO8601 compatible datetime string. If applied only pledges will be returned that have been updated after the supplied datetime. Note: changes to related calls do not update the pledge case's updated datetime. To detect call status changes, use the GET /api/v1/calls?updatedAfter=... endpoint.

Example: 2017-07-21T17:32:28Z
releasedAfterstring · date-timeOptional

ISO8601 compatible datetime string

Example: 2017-07-21T17:32:28Z
Responses
chevron-right
200Success
application/json
get
/api/v1/pledges

hashtag
Create a pledge

post

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.

hashtag
Determining where the pledge will be managed

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.

Authorizations
AuthorizationstringRequired
Bearer authentication header of the form Bearer <token>.
Body
uuidstring · uuidOptional

UUID (v4). The pledge's globally unique identifier in the system. If not provided, a new UUID will be generated.

Example: 82b431f0-f401-4afd-b6db-9d1d751232d9
personUuidstring · uuidRequired

UUID (v4) of the person that made this pledge.

Example: adb97226-a7d7-4a39-8564-765131d5643b
statusstring · enumOptional

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.

Example: activePossible values:
createdAtstringRequired

Date of pledge creation, formatted as ISO8601 date string.

Example: 2023-05-01T00:00:00.000Z
owningOrganizationUuidstring · uuidRequired

UUID (v4) of the organization that owns this pledge.

Example: 82b431f0-f401-4afd-b6db-9d1d751232d9
recruitingOrganizationUuidstring · uuidRequired

UUID (v4) of the organization that recruited this pledge

Example: 82b431f0-f401-4afd-b6db-9d1d751232d9
recruitingLocationLabelstringOptional

The label of the location where the pledge was recruited.

Example: Utrecht
donationIntervalstring · enumOptional

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.

Example: monthlyPossible values:
donationAmountnumberOptional

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..

Example: 7.5
initialDonationIntervalstring · enumRequired

The 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.

Example: oncePossible values:
initialDonationAmountnumberRequired

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.

Example: 12.5
recruitmentTypestring · enumOptional

Describes how this pledge was recruited. Currently supported values are:

  • d2d → Door-to-door recruitment
  • street → Street recruitment
Example: streetPossible values:
recruiterUserUuidstring · uuidRequired

UUID (v4) of the recruiter that recruited the pledge.

Example: 82b431f0-f401-4afd-b6db-9d1d751232d9
startsAtstringRequired

Date of pledge start, formatted as ISO8601 date string

Example: 2023-05-01T00:00:00.000Z
focusAreaUuidsstring · uuid[]Optional

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.

Default: []Example: ['4bb765d0-3d5f-48ab-ac7e-59da84d5f297']
cancelledAtstringOptional

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.

Example: 2023-05-01T00:00:00.000Z
preferredPaymentDaynumberOptional

The preferred day of the month the pledge is to be collected on. Should be an integer between 1 and 28.

Default: nullExample: 8
droppedAtstringOptional

Date 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.

Example: 2023-05-01T00:00:00.000Z
releasedAtstringOptional

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.

Example: 2023-05-01T00:00:00.000Z
endsAtstringOptional

Date the pledge ends, formatted as ISO8601 date string. Leave empty if unknown.

Example: 2023-05-01T00:00:00.000Z
externalMetadataobjectOptional

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.

Responses
post
/api/v1/pledges

hashtag
Update a pledge case

put

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.

Authorizations
AuthorizationstringRequired
Bearer authentication header of the form Bearer <token>.
Path parameters
uuidstring · uuidRequired

The uuid of the pledge case

Body
recruitingLocationLabelstringOptional

The label of the location where the pledge was recruited.

Example: Utrecht
donationIntervalstring · enumOptional

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.

Example: monthlyPossible values:
donationAmountnumberOptional

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..

Example: 7.5
recruiterUserUuidstring · uuidOptional

UUID (v4) of the recruiter that recruited the pledge.

Example: 82b431f0-f401-4afd-b6db-9d1d751232d9
startsAtstringOptional

Date of pledge start, formatted as ISO8601 date string

Example: 2023-05-01T00:00:00.000Z
endsAtstringOptional

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.

Example: 2023-05-01T00:00:00.000Z
externalMetadataobjectOptional

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.

Responses
chevron-right
200

Pledge case was updated

application/json
uuidstring · uuidRequired

UUID (v4)

Example: 5cf67f69-34d0-46fe-b904-20d56248a844
statusstring · enumRequired

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.
Example: leadPossible values:
startsAtstring · date-timeRequired

ISO8601 compatible datetime string

Example: 2017-07-21T17:32:28Z
endsAtstring · date-time · nullableRequired

ISO8601 compatible datetime string

Example: 2017-07-21T17:32:28Z
createdAtstring · date-timeRequired

ISO8601 compatible datetime string

Example: 2017-07-21T17:32:28Z
updatedAtstring · date-timeRequired

ISO8601 compatible datetime string describing when the pledge was last updated

Example: 2017-07-21T17:32:28Z
releasedAtstring · date-time · nullableOptional

ISO8601 compatible datetime string

Example: 2017-07-21T17:32:28Z
owningOrganizationUuidstring · uuidRequiredDeprecated

UUID (v4)

Example: 95dc688a-b757-4bf6-a0fb-47dda3f0dbf5
recruitingOrganizationUuidstring · uuidRequiredDeprecated

UUID (v4)

Example: 6fbfd835-9e94-4034-b6d4-6a6cef450913
recruitingLocationLabelstring · nullableRequired

The label of the location where the pledge was recruited.

Example: Utrecht
initialDonationAmountnumberRequired

The donation amount at the moment the pledge was submitted.

Example: 7.5
donationAmountnumberRequired

The current donation amount

Example: 7.5
initialDonationIntervalstring · enumRequired

The donation interval at the moment the pledge was submitted.

Example: monthlyPossible values:
donationIntervalstring · enumRequired

The current donation interval

Example: monthlyPossible values:
preferredPaymentDaynumberRequired

The preferred payment day of the month (options: 1 - 28). Default value, when not supplied or user has no preference, is: null

Example: 13
recruitmentTypestring · enum · nullableRequiredExample: d2dPossible values:
recruiterUserUuidstring · uuidRequiredDeprecated

UUID (v4)

Example: 83d7638b-ad2b-4d6d-8805-9c4352352599
signatureSignedUrlstring · nullableRequired

Temporary URL to signature file, valid for 1 hour

Example: https://storage.googleapis.com/test/signature.mp3?GoogleAccessId=service-account%40test.iam.gserviceaccount.com&Expires=1659968507&Signature=
externalMetadataobject · nullableRequired

Additional properties provided by/about the external system.

campaignCodestring · nullableRequired

Campaign code defined by the organization

collectionDatestring · date-time · nullableRequired

Collection date of the pledge case defined by the organization. ISO8601 compatible datetime string.

Example: 2017-07-21T17:32:28Z
put
/api/v1/pledges/{uuid}/actions/update

hashtag
Update the status of a pledge

put

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.

Authorizations
AuthorizationstringRequired
Bearer authentication header of the form Bearer <token>.
Path parameters
uuidstring · uuidRequired

The UUID of the pledge to update the status for

statusUpdateActionstring · enumRequired

The status update action

Possible values:
Responses
chevron-right
200

Pledge was updated

application/json
uuidstring · uuidRequired

UUID (v4)

Example: 5cf67f69-34d0-46fe-b904-20d56248a844
statusstring · enumRequired

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.
Example: leadPossible values:
startsAtstring · date-timeRequired

ISO8601 compatible datetime string

Example: 2017-07-21T17:32:28Z
endsAtstring · date-time · nullableRequired

ISO8601 compatible datetime string

Example: 2017-07-21T17:32:28Z
createdAtstring · date-timeRequired

ISO8601 compatible datetime string

Example: 2017-07-21T17:32:28Z
updatedAtstring · date-timeRequired

ISO8601 compatible datetime string describing when the pledge was last updated

Example: 2017-07-21T17:32:28Z
releasedAtstring · date-time · nullableOptional

ISO8601 compatible datetime string

Example: 2017-07-21T17:32:28Z
owningOrganizationUuidstring · uuidRequiredDeprecated

UUID (v4)

Example: 95dc688a-b757-4bf6-a0fb-47dda3f0dbf5
recruitingOrganizationUuidstring · uuidRequiredDeprecated

UUID (v4)

Example: 6fbfd835-9e94-4034-b6d4-6a6cef450913
recruitingLocationLabelstring · nullableRequired

The label of the location where the pledge was recruited.

Example: Utrecht
initialDonationAmountnumberRequired

The donation amount at the moment the pledge was submitted.

Example: 7.5
donationAmountnumberRequired

The current donation amount

Example: 7.5
initialDonationIntervalstring · enumRequired

The donation interval at the moment the pledge was submitted.

Example: monthlyPossible values:
donationIntervalstring · enumRequired

The current donation interval

Example: monthlyPossible values:
preferredPaymentDaynumberRequired

The preferred payment day of the month (options: 1 - 28). Default value, when not supplied or user has no preference, is: null

Example: 13
recruitmentTypestring · enum · nullableRequiredExample: d2dPossible values:
recruiterUserUuidstring · uuidRequiredDeprecated

UUID (v4)

Example: 83d7638b-ad2b-4d6d-8805-9c4352352599
signatureSignedUrlstring · nullableRequired

Temporary URL to signature file, valid for 1 hour

Example: https://storage.googleapis.com/test/signature.mp3?GoogleAccessId=service-account%40test.iam.gserviceaccount.com&Expires=1659968507&Signature=
externalMetadataobject · nullableRequired

Additional properties provided by/about the external system.

put
/api/v1/pledges/{uuid}/actions/{statusUpdateAction}

Last updated