Calls
Last updated
Was this helpful?
Last updated
Was this helpful?
The calls you are able to fetch might be filtered by your service account's permissions, and the organization you represent.
The collection you are paginating is sorted by creation datetime, descending. This means that the first page contains the most recently created calls.
/api/v1/calls
Call cursor to fetch results before
a3c2a57e-2797-4159-8700-8ad55bf8150e
The amount of results to fetch before the 'before' cursor
10
Call cursor to fetch results after
a3c2a57e-2797-4159-8700-8ad55bf8150e
The amount of results to fetch after the 'after' cursor
10
This endpoint creates a call for a person (and pledge case), if your service account allows you to.
The person you are allowed to create a call for is also limited by your service account.
We advice you to provide your own 'uuid' value, as you can use this as a mechanism to ensure the call is only created once. If the call is accidentally 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 created call in the response body.
When creating a call through the API, you need to determine where the call will be managed. You can do this by supplying or not supplying an externalMetadata
-property in the request body. Based upon the value of this property, different input validation and domain rules apply.
When you don't supply external metadata, we consider the call 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.
When you supply external metadata, we consider the call to be primarily managed at that source, and do NOT apply the domain rules we apply on calls 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/calls
UUID (v4). The call's globally unique identifier in the system. If not provided, a new UUID will be generated.
82b431f0-f401-4afd-b6db-9d1d751232d9
The current status of the call:
requested
→ a call is requested and should be made. Initial status.completed
→ a call is done and completed. End status.cancelled
→ a call was requested but is cancelled and thus never called. End status.expired
→ a call was expired since the person was not reached within a specified number of attempts. End status.Status is not allowed to be set when creating a call that is managed in TapRaise. It will by default get assigned status requested
after creation. Externally sourced calls are allowed to be created with any status from the whitelist.
requested
completed
, requested
, cancelled
, expired
ISO8601 compatible datetime string
When provided the call is considered to be managed in this external system, and the call 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.
Contains a collection of attempts that were made to complete the call. Not to be supplied when a call is managed in TapRaise, as then the call will be created as requested and locally will not have any attempts yet.
The result of a completed call. As we don't allow a call to be created completed, when to be managed in TapRaise.app, this field is not allowed to be set in that case.
UUID (v4) of the user that requested this call.
f5e2ba11-1786-4ba9-bd5a-0d99317f4706
Date when call got cancelled, formatted as ISO8601 date string.
2023-05-01T00:00:00.000Z
Date when call got completed, formatted as ISO8601 date string.
2023-05-01T00:00:00.000Z
The notes of the call
UUID (v4) of the person that is being called.
f5e2ba11-1786-4ba9-bd5a-0d99317f4706
UUID (v4) of any of the person's pledge cases that is related to this call.
f5e2ba11-1786-4ba9-bd5a-0d99317f4706
UUID (v4) of the organization that will perform this call.
f5e2ba11-1786-4ba9-bd5a-0d99317f4706
The type of call:
verification
→ used for verifying the personal details when a donor was newly recruited.happy_call
→ used for existing donors to keep them engaged.winback
→ used for donors to get them resubscribed.Call type is not allowed to be set when creating a call that is managed externally. It will by default get assigned type verification
after creation.
verification
verification
, happy_call
, winback
This endpoint adds a call attempt to a call, if your service account allows you to. A call attempt is a record of a call being made to a person. It is used to keep track of how many times a person has been called, and when the last call was made. It is also used to determine if a person should be called again, based on the maximum number of call attempts allowed for a person. The maximum number of call attempts is determined by the owning organization of the person. The owning organization is the organization that the person belongs to. The owning organization is determined by the person's owning organization uuid.
/api/v1/calls/{uuid}/actions/add-attempt
The uuid of the call
UUID (v4) of the user that attempted the call.
f5e2ba11-1786-4ba9-bd5a-0d99317f4706
Timestamp when a call was attempted, formatted as ISO8601 date string.
2023-05-01T00:00:00.000Z
This endpoint marks a call as completed, if your service account allows you to. A call can marked as completed when a call has been made to a person.
/api/v1/calls/{uuid}/actions/complete
The uuid of the call
UUID (v4) of the user that completes the call.
f5e2ba11-1786-4ba9-bd5a-0d99317f4706
The result of a completed call.
This endpoint cancells a call.
The person who is allowed to cancel a call is limited by your service account.
This endpoint will return the cancelled call in the response body.
/api/v1/calls/{uuid}/actions/cancel
Timestamp when a call was cancelled, formatted as ISO8601 date string.
2023-05-01T00:00:00.000Z
This endpoint marks a call as expired. If no expiry date is provided, the call will be set to have expired on the timestamp this request was processed.
The person who is allowed to add an expiry date is limited by your service account.
Whether your service account is allowed to expire a call, is dependent on your service account's access scope.
/api/v1/calls/{uuid}/actions/expire
Expiry date of a call, formatted as ISO8601 date string.
2023-05-01T00:00:00.000Z