search

Calls

get

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 requested at datetime, descending. This means that the first page contains the most recently requested calls.

When you are retrieving a call by the reference id, you have to use the externalApplicationName and externalReferenceId filters together. When you want to retrieve calls that have no external reference id and external application name you can filter on externalApplicationName=null and externalReferenceId=null together.

hashtag
Fetching newly requested calls periodically

When you are retrieving recently requested calls using the requestedAfter-filter, one thing to keep in mind is not to store the last cursor as the starting point for retrieving tomorrow's results.

We recommend storing the date and time you last fetched, and use that next time as the requestedAfter-filter value, instead of the last cursor.

chevron-rightExample of recommended use, fetching requested calls 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 requestedAfter-value for tomorrow.

    • first page: /api/v1/calls?requestedAfter=[initial]&first=50

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

    • ...

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

  2. Second day: retrieve all requested 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 call you received.

    • first page: /api/v1/calls?requestedAfter=[previousDay]&first=50

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

    • ...

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

  3. etc.

hashtag
Fetching calls with status changes since a given date

When you want to detect calls whose status (or any other property) has changed since a given date, use the updatedAfter-filter. This filters on the call's last updated datetime, which is updated whenever a call status changes (e.g. from requested to completed, cancelled, or expired).

Note: Changes to a call do not update the related pledge case's updatedAt field. If you are polling for pledge case changes via GET /api/v1/pledges?updatedAfter=..., you should also poll this endpoint with updatedAfter to detect call status changes. You can correlate call updates back to their pledge case via the relatedCaseUuid field on the call.

Authorizations
AuthorizationstringRequired
Bearer authentication header of the form Bearer <token>.
Query parameters
owningOrganizationUuidstringOptional

UUID of the organization that owns the person the call is for.

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

Status code of the call provided by the external system

Example: 2
externalReferenceIdstringOptional

Reference id of the call provided by the external system

Example: 1039824
externalApplicationNamestringOptional

Name of the application that handles the call. Values can be: 4dmc,basicall,kalff,twilio,tapraise

Example: basicall
requestedUntilstring · date-timeOptional

ISO8601 compatible datetime string to filter on calls until a given datetime (must be used with requestedFrom)

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

ISO8601 compatible datetime string to filter on calls from a given datetime (must be used with requestedUntil)

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

ISO8601 compatible datetime string. If applied only calls will be returned that have been updated after the supplied datetime. This can be used to detect call status changes since a given date.

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

ISO8601 compatible datetime string

Example: 2017-07-21T17:32:28Z
includestringOptional

Include additional data in the response. Values should be comma separated. Allowed values are: person, personQualityResult, pledge, transactions. Note: 'recruiterFullName' is deprecated and no longer has any effect.

Example: pledge,person
beforestringOptional

Call 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

Call cursor to fetch results after

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

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

Example: 10
Responses
chevron-right
200Success
application/json
get
/api/v1/calls

hashtag
Create a call

post

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.

hashtag
Determining where the call will be managed

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.

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

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

Example: 82b431f0-f401-4afd-b6db-9d1d751232d9
statusstring · enumOptional

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.

Example: requestedPossible values:
requestedAtstring · date-timeRequired

ISO8601 compatible datetime string

requestedByUserUuidstring · uuidOptional

UUID (v4) of the user that requested this call.

Example: f5e2ba11-1786-4ba9-bd5a-0d99317f4706
cancelledAtstringOptional

Date when call got cancelled, formatted as ISO8601 date string.

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

Date when call got completed, formatted as ISO8601 date string.

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

The notes of the call

personUuidstring · uuidRequired

UUID (v4) of the person that is being called.

Example: f5e2ba11-1786-4ba9-bd5a-0d99317f4706
relatedCaseUuidstring · uuidOptional

UUID (v4) of any of the person's pledge cases that is related to this call.

Example: f5e2ba11-1786-4ba9-bd5a-0d99317f4706
callingOrganizationUuidstring · uuidOptional

UUID (v4) of the organization that will perform this call.

Example: f5e2ba11-1786-4ba9-bd5a-0d99317f4706
typestring · enumRequired

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.

Example: verificationPossible values:
Responses
post
/api/v1/calls

hashtag
Add a call attempt

put

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.

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

The uuid of the call

Body
userUuidstring · uuidOptional

UUID (v4) of the user that attempted the call.

Example: f5e2ba11-1786-4ba9-bd5a-0d99317f4706
attemptAtstringOptional

Timestamp when a call was attempted, formatted as ISO8601 date string.

Example: 2023-05-01T00:00:00.000Z
Responses
chevron-right
200

Call attempt was added

application/json
uuidstring · uuidRequired

UUID (v4)

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

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.
Example: requestedPossible values:
requestedAtstring · date-timeRequired

ISO8601 compatible datetime string

attemptsCountnumberRequired

The number of call attempts

Example: 1
lastUpdatedAtstring · date-timeRequired

ISO8601 compatible datetime string

cancelledAtstring · date-time · nullableRequired

ISO8601 compatible datetime string

completedAtstring · date-time · nullableRequired

ISO8601 compatible datetime string

expiredAtstring · date-time · nullableRequired

ISO8601 compatible datetime string

notesstring · nullableRequired

The notes of the call

personUuidstring · uuidRequired

UUID (v4) of the person that is being called.

Example: f5e2ba11-1786-4ba9-bd5a-0d99317f4706
relatedCaseUuidstring · uuid · nullableRequired

UUID (v4) of any of the person's pledge cases that is related to this call.

Example: f5e2ba11-1786-4ba9-bd5a-0d99317f4706
callingOrganizationUuidstring · uuid · nullableRequired

UUID (v4) of the organization that will perform this call.

Example: f5e2ba11-1786-4ba9-bd5a-0d99317f4706
typestring · enumRequired

The current type of the 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.
Example: happy_callPossible values:
recordingDurationnumber · nullableRequired

The duration of the call recording, in seconds

Example: 120.23
put
/api/v1/calls/{uuid}/actions/add-attempt

hashtag
Mark a call as completed

put

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.

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

The uuid of the call

Body
userUuidstring · uuidOptional

UUID (v4) of the user that completes the call.

Example: f5e2ba11-1786-4ba9-bd5a-0d99317f4706
Responses
chevron-right
200

Call that was marked as completed

application/json
uuidstring · uuidRequired

UUID (v4)

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

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.
Example: requestedPossible values:
requestedAtstring · date-timeRequired

ISO8601 compatible datetime string

attemptsCountnumberRequired

The number of call attempts

Example: 1
lastUpdatedAtstring · date-timeRequired

ISO8601 compatible datetime string

cancelledAtstring · date-time · nullableRequired

ISO8601 compatible datetime string

completedAtstring · date-time · nullableRequired

ISO8601 compatible datetime string

expiredAtstring · date-time · nullableRequired

ISO8601 compatible datetime string

notesstring · nullableRequired

The notes of the call

personUuidstring · uuidRequired

UUID (v4) of the person that is being called.

Example: f5e2ba11-1786-4ba9-bd5a-0d99317f4706
relatedCaseUuidstring · uuid · nullableRequired

UUID (v4) of any of the person's pledge cases that is related to this call.

Example: f5e2ba11-1786-4ba9-bd5a-0d99317f4706
callingOrganizationUuidstring · uuid · nullableRequired

UUID (v4) of the organization that will perform this call.

Example: f5e2ba11-1786-4ba9-bd5a-0d99317f4706
typestring · enumRequired

The current type of the 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.
Example: happy_callPossible values:
recordingDurationnumber · nullableRequired

The duration of the call recording, in seconds

Example: 120.23
put
/api/v1/calls/{uuid}/actions/complete

hashtag
Cancel a call

put

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.

Authorizations
AuthorizationstringRequired
Bearer authentication header of the form Bearer <token>.
Path parameters
uuidstringRequired
Body
cancelledAtstringOptional

Timestamp when a call was cancelled, formatted as ISO8601 date string.

Example: 2023-05-01T00:00:00.000Z
Responses
chevron-right
200

Call was cancelled

application/json
uuidstring · uuidRequired

UUID (v4)

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

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.
Example: requestedPossible values:
requestedAtstring · date-timeRequired

ISO8601 compatible datetime string

attemptsCountnumberRequired

The number of call attempts

Example: 1
lastUpdatedAtstring · date-timeRequired

ISO8601 compatible datetime string

cancelledAtstring · date-time · nullableRequired

ISO8601 compatible datetime string

completedAtstring · date-time · nullableRequired

ISO8601 compatible datetime string

expiredAtstring · date-time · nullableRequired

ISO8601 compatible datetime string

notesstring · nullableRequired

The notes of the call

personUuidstring · uuidRequired

UUID (v4) of the person that is being called.

Example: f5e2ba11-1786-4ba9-bd5a-0d99317f4706
relatedCaseUuidstring · uuid · nullableRequired

UUID (v4) of any of the person's pledge cases that is related to this call.

Example: f5e2ba11-1786-4ba9-bd5a-0d99317f4706
callingOrganizationUuidstring · uuid · nullableRequired

UUID (v4) of the organization that will perform this call.

Example: f5e2ba11-1786-4ba9-bd5a-0d99317f4706
typestring · enumRequired

The current type of the 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.
Example: happy_callPossible values:
recordingDurationnumber · nullableRequired

The duration of the call recording, in seconds

Example: 120.23
put
/api/v1/calls/{uuid}/actions/cancel

hashtag
Expires a call at a given date

put

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.

Authorizations
AuthorizationstringRequired
Bearer authentication header of the form Bearer <token>.
Path parameters
uuidstringRequired
Body
expiredAtstringOptional

Expiry date of a call, formatted as ISO8601 date string.

Example: 2023-05-01T00:00:00.000Z
Responses
chevron-right
200

Call expiry date was set

application/json
uuidstring · uuidRequired

UUID (v4)

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

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.
Example: requestedPossible values:
requestedAtstring · date-timeRequired

ISO8601 compatible datetime string

attemptsCountnumberRequired

The number of call attempts

Example: 1
lastUpdatedAtstring · date-timeRequired

ISO8601 compatible datetime string

cancelledAtstring · date-time · nullableRequired

ISO8601 compatible datetime string

completedAtstring · date-time · nullableRequired

ISO8601 compatible datetime string

expiredAtstring · date-time · nullableRequired

ISO8601 compatible datetime string

notesstring · nullableRequired

The notes of the call

personUuidstring · uuidRequired

UUID (v4) of the person that is being called.

Example: f5e2ba11-1786-4ba9-bd5a-0d99317f4706
relatedCaseUuidstring · uuid · nullableRequired

UUID (v4) of any of the person's pledge cases that is related to this call.

Example: f5e2ba11-1786-4ba9-bd5a-0d99317f4706
callingOrganizationUuidstring · uuid · nullableRequired

UUID (v4) of the organization that will perform this call.

Example: f5e2ba11-1786-4ba9-bd5a-0d99317f4706
typestring · enumRequired

The current type of the 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.
Example: happy_callPossible values:
recordingDurationnumber · nullableRequired

The duration of the call recording, in seconds

Example: 120.23
put
/api/v1/calls/{uuid}/actions/expire

Last updated