# Calls

## GET /api/v1/calls

> \
> 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 \<code>externalApplicationName\</code> and \<code>externalReferenceId\</code> filters together.\
> When you want to retrieve calls that have no external reference id and external application name you can filter on \<code>externalApplicationName=null\</code> and \<code>externalReferenceId=null\</code> together.\
> \
> \## Fetching newly requested calls periodically\
> \
> When you are retrieving recently requested calls using the \<code>requestedAfter\</code>-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 \<code>requestedAfter\</code>-filter value, instead of the last cursor.\
> \
> \<details>\
> \<summary>Example of recommended use, fetching requested calls every day\</summary>\
> \
> 1\. \*\*First day:\*\*\
> &#x20; 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>requestedAfter\</code>-value for tomorrow.\
> \
> &#x20;   \* first page: \<code>/api/v1/calls?requestedAfter=\[initial]\&first=50\</code>\
> &#x20;   \* second page: \<code>/api/v1/calls?requestedAfter=\[initial]\&first=10\&after=41222ef7-a861-4bbd-ae93-2f645336b85d\</code>\
> &#x20;   \* ...\
> &#x20;   \* last page: \<code>/api/v1/calls?requestedAfter=\[initial]\&first=10\&after=10d303b1-4eca-4db4-9ae7-7cd65f98a5b5\</code>\
> \
> 2\. \*\*Second day:\*\*\
> &#x20;  retrieve all requested 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 call you received.\
> \
> &#x20;   \* first page: \<code>/api/v1/calls?requestedAfter=\[previousDay]\&first=50\</code>\
> &#x20;   \* second page: \<code>/api/v1/calls?requestedAfter=\[previousDay]\&first=10\&after=bd82f150-a797-4d9f-af09-c3ea06964e9d\</code>\
> &#x20;   \* ...\
> &#x20;   \* last page: \<code>/api/v1/calls?requestedAfter=\[previousDay]\&first=10\&after=3c53b11a-adef-4dc1-90d7-c23dc0108492\</code>\
> &#x20;   \*\
> 3\. etc.\
> \</details>\
> \
> \## 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 \<code>updatedAfter\</code>-filter. This filters on the call's last updated datetime, which is updated whenever a call status changes (e.g. from \<code>requested\</code> to \<code>completed\</code>, \<code>cancelled\</code>, or \<code>expired\</code>).\
> \
> Note: Changes to a call do not update the related pledge case's \<code>updatedAt\</code> field. If you are polling for pledge case changes via \<code>GET /api/v1/pledges?updatedAfter=...\</code>, you should also poll this endpoint with \<code>updatedAfter\</code> to detect call status changes. You can correlate call updates back to their pledge case via the \<code>relatedCaseUuid\</code> field on the call.<br>

```json
{"openapi":"3.0.0","info":{"title":"TapRaise API","version":"v1"},"security":[{"bearer":[]}],"components":{"securitySchemes":{"bearer":{"scheme":"bearer","bearerFormat":"jwt","type":"http"}},"schemas":{"CallPaginationConnection":{"type":"object","properties":{"edges":{"type":"array","items":{"$ref":"#/components/schemas/CallEdgeDto"}},"pageInfo":{"$ref":"#/components/schemas/PageInfo"}},"required":["edges","pageInfo"]},"CallEdgeDto":{"type":"object","properties":{"node":{"$ref":"#/components/schemas/CallDto"},"cursor":{"type":"string","description":"Cursor used in 'before' and 'after' pagination connection arguments"}},"required":["node","cursor"]},"CallDto":{"type":"object","properties":{"uuid":{"type":"string","format":"uuid","description":"UUID (v4)","nullable":false},"status":{"type":"string","enum":["completed","requested","cancelled","expired"],"description":"\nThe current status of the call:\n* `requested` → a call is requested and should be made. Initial status.\n* `completed` → a call is done and completed. End status.\n* `cancelled` → a call was requested but is cancelled and thus never called. End status.\n* `expired` → a call was expired since the person was not reached within a specified number of attempts. End status.","nullable":false},"requestedAt":{"format":"date-time","type":"string","description":"ISO8601 compatible datetime string","nullable":false},"externalMetadata":{"nullable":true,"allOf":[{"$ref":"#/components/schemas/CallExternalMetadataDto"}]},"attempts":{"nullable":false,"description":"Contains a collection of attempts that were made to complete the call","type":"array","items":{"$ref":"#/components/schemas/CallAttemptDto"}},"attemptsCount":{"type":"number","description":"The number of call attempts","nullable":false},"result":{"description":"The result of a completed call","nullable":true,"allOf":[{"$ref":"#/components/schemas/CallResultDto"}]},"lastUpdatedAt":{"format":"date-time","type":"string","description":"ISO8601 compatible datetime string","nullable":false},"cancelledAt":{"format":"date-time","type":"string","description":"ISO8601 compatible datetime string","nullable":true},"completedAt":{"format":"date-time","type":"string","description":"ISO8601 compatible datetime string","nullable":true},"expiredAt":{"format":"date-time","type":"string","description":"ISO8601 compatible datetime string","nullable":true},"notes":{"type":"string","description":"The notes of the call","nullable":true},"personUuid":{"type":"string","format":"uuid","description":"UUID (v4) of the person that is being called.","nullable":false},"relatedCaseUuid":{"type":"string","format":"uuid","description":"UUID (v4) of any of the person's pledge cases that is related to this call.","nullable":true},"callingOrganizationUuid":{"type":"string","format":"uuid","description":"UUID (v4) of the organization that will perform this call.","nullable":true},"type":{"type":"string","enum":["verification","happy_call","winback"],"description":"\nThe current type of the call:\n* `verification` → used for verifying the personal details when a donor was newly recruited.\n* `happy_call` → used for existing donors to keep them engaged.\n* `winback` → used for donors to get them resubscribed.","nullable":false},"pledgeCase":{"description":"Related pledge case.\n\nNote: Only included when explicitly requested via the `include` query parameter via the GET calls endpoint.","nullable":true,"allOf":[{"$ref":"#/components/schemas/PledgeCaseDto"}]},"person":{"description":"Related person.\n\nNote: Only included when explicitly requested via the `include` query parameter via the GET calls endpoint.","nullable":true,"allOf":[{"$ref":"#/components/schemas/PersonDto"}]},"transactions":{"description":"Related transactions.\n\nNote: Only included when explicitly requested via the `include` query parameter via the GET calls endpoint.","nullable":true,"type":"array","items":{"$ref":"#/components/schemas/TransactionDto"}},"recordingDuration":{"type":"number","description":"The duration of the call recording, in seconds","nullable":true}},"required":["uuid","status","requestedAt","externalMetadata","attempts","attemptsCount","result","lastUpdatedAt","cancelledAt","completedAt","expiredAt","notes","personUuid","relatedCaseUuid","callingOrganizationUuid","type","pledgeCase","person","transactions","recordingDuration"]},"CallExternalMetadataDto":{"type":"object","properties":{"applicationName":{"type":"string","description":"The name of the application that created the call","nullable":false},"referenceId":{"type":"string","description":"The reference id of the call in the external system","nullable":false},"agentReferenceId":{"type":"string","description":"The reference id of the agent in the external system","nullable":true},"statusCode":{"type":"string","description":"The status code of the call in the external system","nullable":true},"statusDescription":{"type":"string","description":"The status description of the call in the external system","nullable":true},"additionalProperties":{"type":"object","description":"Additional properties provided by/about the external system.","nullable":true}},"required":["applicationName","referenceId","agentReferenceId","statusCode","statusDescription","additionalProperties"]},"CallAttemptDto":{"type":"object","properties":{"userUuid":{"type":"string","format":"uuid","description":"UUID (v4) of the user that attempted a call.","nullable":true},"attemptAt":{"type":"string","format":"date-time","description":"Timestamp when a call was attempted, formatted as ISO8601 date string.","nullable":true},"createdAt":{"type":"string","format":"date-time","description":"Timestamp when the call attempt was created, formatted as ISO8601 date string.","nullable":true}},"required":["userUuid","attemptAt","createdAt"]},"CallResultDto":{"type":"object","properties":{"resultCode":{"type":"string","enum":["confirmed","downgraded","converted","dropped","other"],"description":"\nThe current status of the call result:\n* `confirmed` → a call has been made and pledge agreements are confirmed and data may be updated before confirming.\n* `downgraded` → a call has been made and the pledge amount has been downgraded to a lower value.\n* `converted` → a call has been made and the pledge was converted. For example: change of donation period.\n* `dropped` → a call has been made and the pledge was dropped. For example due to: a regret, complaint or missing IBAN.\n* `other` → a call has been made. This status is applied when other statuses do not apply.","nullable":false},"completedAt":{"format":"date-time","type":"string","description":"ISO8601 compatible datetime string","nullable":false},"notes":{"type":"string","nullable":true},"duration":{"type":"number","description":"The duration of the call result recording, in seconds. This field is deprecated and will be removed in the future. Use `call.recordingDuration` instead.","nullable":true,"deprecated":true},"donorRetentionRating":{"type":"number","description":"The donor retention rating is available when status of the call is completed. The donor retention rating values can be between 1 and 10.","nullable":true,"enum":[0,1,2,3,4,5,6,7,8,9,10]}},"required":["resultCode","completedAt","notes","duration","donorRetentionRating"]},"PledgeCaseDto":{"type":"object","properties":{"uuid":{"type":"string","format":"uuid","description":"UUID (v4)"},"status":{"type":"string","enum":["lead","active","dropped","cancelled","fulfilled"],"description":"\nThe current status of the pledge:\n* `lead` → lead pledge, to be collected. Initial status.\n* `active` → active pledge, being collected.\n* `dropped` → dropped before it was ever collected or released.\n* `cancelled` → cancelled after it was collected or released.\n* `fulfilled` → ended after reaching its end date."},"startsAt":{"format":"date-time","type":"string","description":"ISO8601 compatible datetime string"},"endsAt":{"format":"date-time","type":"string","nullable":true,"description":"ISO8601 compatible datetime string"},"createdAt":{"format":"date-time","type":"string","description":"ISO8601 compatible datetime string"},"updatedAt":{"format":"date-time","type":"string","description":"ISO8601 compatible datetime string describing when the pledge was last updated"},"releasedAt":{"format":"date-time","type":"string","nullable":true,"description":"ISO8601 compatible datetime string"},"owningOrganizationUuid":{"type":"string","format":"uuid","description":"UUID (v4)","deprecated":true},"owningOrganization":{"description":"Organization recruited for","allOf":[{"$ref":"#/components/schemas/OrganizationDto"}]},"recruitingOrganizationUuid":{"type":"string","format":"uuid","description":"UUID (v4)","deprecated":true},"recruitingOrganization":{"description":"Recruiting organization","allOf":[{"$ref":"#/components/schemas/OrganizationDto"}]},"recruitingLocationLabel":{"type":"string","nullable":true,"description":"The label of the location where the pledge was recruited."},"initialDonationAmount":{"type":"number","description":"The donation amount at the moment the pledge was submitted."},"donationAmount":{"type":"number","description":"The current donation amount"},"initialDonationInterval":{"type":"string","enum":["once","monthly","halfYearly","quarterly","yearly"],"description":"The donation interval at the moment the pledge was submitted."},"donationInterval":{"type":"string","enum":["once","monthly","halfYearly","quarterly","yearly"],"description":"The current donation interval"},"preferredPaymentDay":{"type":"number","description":"The preferred payment day of the month (options: 1 - 28). Default value, when not supplied or user has no preference, is: <code>null</code>"},"person":{"description":"Related person.\n\nNote: 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.","nullable":true,"allOf":[{"$ref":"#/components/schemas/PersonDto"}]},"recruitmentType":{"type":"string","enum":["d2d","street"],"nullable":true},"recruiterUserUuid":{"type":"string","format":"uuid","description":"UUID (v4)","deprecated":true},"recruiterUser":{"description":"User that recruited the pledge","allOf":[{"$ref":"#/components/schemas/RecruiterUserDto"}]},"signatureSignedUrl":{"type":"string","nullable":true,"description":"Temporary URL to signature file, valid for 1 hour"},"transactions":{"description":"Transactions that were created for this pledge case.\n\nNote: Only included when explicitly requested via the `include` query parameter via the GET pledges endpoint.","nullable":true,"type":"array","items":{"$ref":"#/components/schemas/TransactionDto"}},"calls":{"description":"Calls that were created for this pledge case.\n\nNote: Only included when explicitly requested via the `include` query parameter via the GET pledges endpoint.","nullable":true,"type":"array","items":{"$ref":"#/components/schemas/CallDto"}},"focusAreas":{"default":[],"type":"array","items":{"$ref":"#/components/schemas/FocusAreaDto"}},"externalSource":{"nullable":true,"description":"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.","allOf":[{"$ref":"#/components/schemas/ExternalSourceDto"}]},"externalMetadata":{"type":"object","nullable":true,"description":"Additional properties provided by/about the external system."},"campaignCode":{"type":"string","nullable":true,"description":"Campaign code defined by the organization"},"collectionDate":{"format":"date-time","type":"string","nullable":true,"description":"Collection date of the pledge case defined by the organization. ISO8601 compatible datetime string."}},"required":["uuid","status","startsAt","endsAt","createdAt","updatedAt","owningOrganizationUuid","owningOrganization","recruitingOrganizationUuid","recruitingOrganization","recruitingLocationLabel","initialDonationAmount","donationAmount","initialDonationInterval","donationInterval","preferredPaymentDay","person","recruitmentType","recruiterUserUuid","recruiterUser","signatureSignedUrl","transactions","calls","focusAreas","externalSource","externalMetadata","campaignCode","collectionDate"]},"OrganizationDto":{"type":"object","properties":{"uuid":{"type":"string","format":"uuid","description":"UUID (v4)"},"name":{"type":"string","description":"Name of organization"}},"required":["uuid","name"]},"PersonDto":{"type":"object","properties":{"uuid":{"type":"string","format":"uuid","description":"UUID (v4)"},"personUuid":{"type":"string","format":"uuid","description":"UUID (v4). Deprecated: use the 'uuid' property instead.","deprecated":true},"academicTitle":{"type":"string","nullable":true},"initials":{"type":"string","nullable":true},"firstName":{"type":"string","nullable":true},"lastNamePrefix":{"type":"string","nullable":true},"lastName":{"type":"string","nullable":true},"dateOfBirth":{"type":"string","nullable":true,"description":"Local date of birth for user, formatted as YYYY-MM-DD"},"socialSecurityNumber":{"type":"string","nullable":true,"description":"Social security number as string without any separators."},"iban":{"type":"string","nullable":true},"address":{"nullable":true,"allOf":[{"$ref":"#/components/schemas/AddressDto"}]},"phoneNumber":{"type":"string","nullable":true},"mobilePhoneNumber":{"type":"string","nullable":true},"email":{"type":"string","nullable":true},"gender":{"type":"string","enum":["male","female","other"],"nullable":true},"optInEmail":{"type":"boolean","nullable":true},"optInPhone":{"type":"boolean","nullable":true},"optInMail":{"type":"boolean","nullable":true},"optInSms":{"type":"boolean","nullable":true},"language":{"type":"string","nullable":true,"description":"ISO-639-1 language code"},"mandate":{"nullable":true,"allOf":[{"$ref":"#/components/schemas/MandateDto"}]},"createdAt":{"format":"date-time","type":"string","description":"ISO8601 compatible datetime string"},"owningOrganization":{"description":"Organization recruited for","allOf":[{"$ref":"#/components/schemas/OrganizationDto"}]},"qualityResult":{"nullable":true,"description":"The generated quality result of the person. This is only included when requested via the 'include' parameter in the request, if available for the endpoint you're calling. If the value is `null` it means that the quality result is not yet generated.","allOf":[{"$ref":"#/components/schemas/QualityResultDto"}]}},"required":["uuid","personUuid","academicTitle","initials","firstName","lastNamePrefix","lastName","dateOfBirth","iban","address","phoneNumber","mobilePhoneNumber","email","gender","optInEmail","optInPhone","optInMail","optInSms","language","mandate","createdAt","owningOrganization","qualityResult"]},"AddressDto":{"type":"object","properties":{"street":{"type":"string","nullable":true},"houseNumber":{"type":"string","nullable":true},"houseNumberExtension":{"type":"string","nullable":true},"zipCode":{"type":"string","nullable":true},"city":{"type":"string","nullable":true},"country":{"type":"string","nullable":true,"description":"Country code in ISO 3166-1 alpha-2"}}},"MandateDto":{"type":"object","properties":{"createdAt":{"format":"date-time","type":"string","description":"ISO8601 compatible datetime string"}},"required":["createdAt"]},"QualityResultDto":{"type":"object","properties":{"score":{"type":"number","description":"The combined score of the quality gates","nullable":false},"maxScore":{"type":"number","description":"The combined max score that could be reached with the applied the quality gates","nullable":false},"percentage":{"type":"number","description":"The percentage of the score compared to the max score","nullable":false},"createdAt":{"format":"date-time","type":"string","description":"ISO8601 compatible datetime string","nullable":false},"gateResults":{"description":"The results from the quality gates that are part of this quality result","nullable":false,"type":"array","items":{"$ref":"#/components/schemas/QualityGateResultDto"}}},"required":["score","maxScore","percentage","createdAt","gateResults"]},"QualityGateResultDto":{"type":"object","properties":{"identifier":{"type":"string","description":"The identifier of the quality gate","nullable":false,"enum":["addressIsAvailable","addressIsComplete","addressIsValid","addressDoesNotMatchRecruiterUsersAddress","ibanDoesNotMatchAnotherPersonsIban","ibanDoesNotMatchRecruiterUsersIban","ibanIsAvailable","ibanIsValid","phoneNumberDoesNotMatchRecruiterUsersPhoneNumber","phoneNumberIsNotASequence","phoneNumberIsAvailable","phoneNumberMatchesPattern","phoneNumberDoesNotMatchAnotherPersonsPhoneNumber","emailIsAvailable","emailMatchesEmailPattern","emailIsDeliverable"]},"category":{"type":"string","description":"The category of the quality gate","nullable":false,"enum":["addressQuality","recruiterFraud","uniqueness","ibanQuality","emailQuality","phoneNumberQuality"]},"score":{"type":"number","description":"The score for this quality gate","nullable":false},"maxScore":{"type":"number","description":"The maximum score that could be reached with this quality gate","nullable":false},"percentage":{"type":"number","description":"The percentage of the score compared to the max score","nullable":false},"explanation":{"type":"string","description":"The explanation of the score","nullable":false,"enum":["ok","ibanMatchesPersonIban","ibanMatchesRecruiterIban","ibanIsMissing","ibanIsInvalid","ibanMayBeInvalid","addressIsMissing","addressIsIncomplete","addressIsInvalid","addressIsNotValidated","addressMatchesRecruiterAddress","phoneNumberIsASequence","mobilePhoneNumberIsASequence","phoneNumberMatchesRecruiterPhoneNumber","phoneNumberMatchesAnotherPersonsPhoneNumber","mobilePhoneNumberMatchesRecruiterPhoneNumber","phoneNumberIsMissing","phoneNumberDoesNotMatchPattern","mobilePhoneNumberDoesNotMatchPattern","emailIsMissing","emailDoesNotMatchEmailPattern","emailNotDeliverable","emailValidationUnknown"]},"metadata":{"type":"object","description":"Additional metadata for this quality gate result","nullable":true}},"required":["identifier","category","score","maxScore","percentage","explanation","metadata"]},"RecruiterUserDto":{"type":"object","properties":{"uuid":{"type":"string","format":"uuid","description":"UUID (v4)"},"identifier":{"type":"string","description":"Recruiter user identifier"},"name":{"type":"string","description":"Recruiter user name. Only returned if you have permission to view it.","nullable":true}},"required":["uuid","identifier","name"]},"TransactionDto":{"type":"object","properties":{"uuid":{"type":"string","format":"uuid","description":"UUID (v4)"},"personUuid":{"type":"string","format":"uuid","description":"UUID (v4)"},"origin":{"description":"This field requires you to connect the transaction to an origin, for example pledge case.","allOf":[{"$ref":"#/components/schemas/TransactionOriginDto"}]},"amount":{"type":"number","description":"Transaction amount. Only supporting Euros at this point."},"name":{"type":"string","description":"Name of the person that made this transaction at the moment in time. Might also be used for the name of the bank account holder.","nullable":true},"iban":{"type":"string","description":"IBAN of the bank account that made this transaction.","nullable":true},"description":{"type":"string","description":"Description of the transaction, usually provided by the payment initiator."},"provider":{"type":"string","enum":["cm","mollie"],"description":"Identifier of the payment provider used for this transaction.","nullable":true},"method":{"type":"string","enum":["idealqr","direct_debit"],"description":"Payment method used for this transaction.","nullable":true},"referenceId":{"type":"string","description":"Reference id provided by the payment initiator.","nullable":true},"transactionId":{"type":"string","description":"Transaction id provided by the payment provider.","nullable":true},"providerMetadata":{"type":"object","description":"Meta data provided by/about the payment provider.","nullable":true},"createdAt":{"format":"date-time","type":"string","description":"Date of transaction creation, formatted as ISO8601 date string."},"updatedAt":{"format":"date-time","type":"string","description":"Date of transaction last update, formatted as ISO8601 date string."},"status":{"type":"string","enum":["open","paid","failed","cancelled","reversed"],"description":"\nThe current status of the transaction:\n* `open` → open transaction, to be paid.\n* `paid` → paid transaction.\n* `failed` → failed transaction before it was paid.\n* `cancelled` → cancelled transaction before it was paid.\n* `reversed` → reversed transaction or chargeback."}},"required":["uuid","personUuid","origin","amount","description","createdAt","updatedAt","status"]},"TransactionOriginDto":{"type":"object","properties":{"name":{"type":"string","enum":["pledgeCase"]},"identifier":{"type":"string","format":"uuid","description":"UUID (v4)"}},"required":["name","identifier"]},"FocusAreaDto":{"type":"object","properties":{"uuid":{"type":"string","format":"uuid","description":"UUID (v4)"},"name":{"type":"string","description":"Name of the focus area"},"externalSource":{"description":"External source of the focus area","nullable":true,"allOf":[{"$ref":"#/components/schemas/ExternalSourceDto"}]}},"required":["uuid","name","externalSource"]},"ExternalSourceDto":{"type":"object","properties":{"name":{"type":"string","description":"Name of the external source"},"identifier":{"type":"string","description":"Identifier of this entity in the external source"}},"required":["name","identifier"]},"PageInfo":{"type":"object","properties":{"startCursor":{"type":"string","nullable":true,"description":"The first cursor of this slice"},"endCursor":{"type":"string","nullable":true,"description":"The last cursor of this slice"},"hasPreviousPage":{"type":"boolean"},"hasNextPage":{"type":"boolean"}},"required":["startCursor","endCursor","hasPreviousPage","hasNextPage"]}}},"paths":{"/api/v1/calls":{"get":{"operationId":"CallOverviewRestController_getCalls","summary":"","description":"\nThe calls you are able to fetch might be filtered by your service account's permissions, and the organization you represent.\n\nThe collection you are paginating is sorted by requested at datetime, descending. This means that the first page contains the most recently requested calls.\n\nWhen you are retrieving a call by the reference id, you have to use the <code>externalApplicationName</code> and <code>externalReferenceId</code> filters together.\nWhen you want to retrieve calls that have no external reference id and external application name you can filter on <code>externalApplicationName=null</code> and <code>externalReferenceId=null</code> together.\n\n## Fetching newly requested calls periodically\n\nWhen you are retrieving recently requested calls using the <code>requestedAfter</code>-filter, one thing to keep in mind is not to store the last cursor as the starting point for retrieving tomorrow's results.\n\nWe recommend storing the date and time you last fetched, and use that next time as the <code>requestedAfter</code>-filter value, instead of the last cursor.\n\n<details>\n<summary>Example of recommended use, fetching requested calls every day</summary>\n\n1. **First day:**\n  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>requestedAfter</code>-value for tomorrow.\n\n    * first page: <code>/api/v1/calls?requestedAfter=[initial]&first=50</code>\n    * second page: <code>/api/v1/calls?requestedAfter=[initial]&first=10&after=41222ef7-a861-4bbd-ae93-2f645336b85d</code>\n    * ...\n    * last page: <code>/api/v1/calls?requestedAfter=[initial]&first=10&after=10d303b1-4eca-4db4-9ae7-7cd65f98a5b5</code>\n\n2. **Second day:**\n   retrieve all requested 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 call you received.\n\n    * first page: <code>/api/v1/calls?requestedAfter=[previousDay]&first=50</code>\n    * second page: <code>/api/v1/calls?requestedAfter=[previousDay]&first=10&after=bd82f150-a797-4d9f-af09-c3ea06964e9d</code>\n    * ...\n    * last page: <code>/api/v1/calls?requestedAfter=[previousDay]&first=10&after=3c53b11a-adef-4dc1-90d7-c23dc0108492</code>\n    *\n3. etc.\n</details>\n\n## Fetching calls with status changes since a given date\n\nWhen you want to detect calls whose status (or any other property) has changed since a given date, use the <code>updatedAfter</code>-filter. This filters on the call's last updated datetime, which is updated whenever a call status changes (e.g. from <code>requested</code> to <code>completed</code>, <code>cancelled</code>, or <code>expired</code>).\n\nNote: Changes to a call do not update the related pledge case's <code>updatedAt</code> field. If you are polling for pledge case changes via <code>GET /api/v1/pledges?updatedAfter=...</code>, you should also poll this endpoint with <code>updatedAfter</code> to detect call status changes. You can correlate call updates back to their pledge case via the <code>relatedCaseUuid</code> field on the call.\n","parameters":[{"name":"owningOrganizationUuid","required":false,"in":"query","description":"UUID of the organization that owns the person the call is for.","schema":{"type":"string"}},{"name":"externalStatusCode","required":false,"in":"query","description":"Status code of the call provided by the external system","schema":{"type":"string"}},{"name":"externalReferenceId","required":false,"in":"query","description":"Reference id of the call provided by the external system","schema":{"type":"string"}},{"name":"externalApplicationName","required":false,"in":"query","description":"Name of the application that handles the call. Values can be: 4dmc,basicall,kalff,twilio,tapraise","schema":{"type":"string"}},{"name":"requestedUntil","required":false,"in":"query","description":"ISO8601 compatible datetime string to filter on calls until a given datetime (must be used with requestedFrom)","schema":{"format":"date-time","type":"string"}},{"name":"requestedFrom","required":false,"in":"query","description":"ISO8601 compatible datetime string to filter on calls from a given datetime (must be used with requestedUntil)","schema":{"format":"date-time","type":"string"}},{"name":"updatedAfter","required":false,"in":"query","description":"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.","schema":{"format":"date-time","type":"string"}},{"name":"requestedAfter","required":false,"in":"query","description":"ISO8601 compatible datetime string","schema":{"format":"date-time","type":"string"}},{"name":"include","required":false,"in":"query","description":"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.","schema":{"type":"string"}},{"name":"before","required":false,"in":"query","description":"Call cursor to fetch results before","schema":{"type":"string"}},{"name":"last","required":false,"in":"query","description":"The amount of results to fetch before the 'before' cursor","schema":{"type":"number"}},{"name":"after","required":false,"in":"query","description":"Call cursor to fetch results after","schema":{"type":"string"}},{"name":"first","required":false,"in":"query","description":"The amount of results to fetch after the 'after' cursor","schema":{"type":"number"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CallPaginationConnection"}}}},"400":{"description":"Bad request. Response body shows what the problem is."},"401":{"description":"Service account not properly authenticated"},"403":{"description":"Service account forbids executing this action"},"default":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CallPaginationConnection"}}}}},"tags":["calls"]}}}}
```

## Create a call

> \
> 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.\
> \
> \## 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.<br>

```json
{"openapi":"3.0.0","info":{"title":"TapRaise API","version":"v1"},"security":[{"bearer":[]}],"components":{"securitySchemes":{"bearer":{"scheme":"bearer","bearerFormat":"jwt","type":"http"}},"schemas":{"CreateCallInput":{"type":"object","properties":{"uuid":{"type":"string","format":"uuid","description":"UUID (v4). The call's globally unique identifier in the system. If not provided, a new UUID will be generated."},"status":{"type":"string","enum":["completed","requested","cancelled","expired"],"description":"\nThe current status of the call:\n* `requested` → a call is requested and should be made. Initial status.\n* `completed` → a call is done and completed. End status.\n* `cancelled` → a call was requested but is cancelled and thus never called. End status.\n* `expired` → a call was expired since the person was not reached within a specified number of attempts. End status.\n\nStatus 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.\n"},"requestedAt":{"type":"string","format":"date-time","description":"ISO8601 compatible datetime string"},"externalMetadata":{"default":null,"description":"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.","allOf":[{"$ref":"#/components/schemas/CallExternalMetadataInput"}]},"externalSource":{"default":null,"description":"When provided the call 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.","allOf":[{"$ref":"#/components/schemas/ExternalSourceInput"}]},"attempts":{"description":"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.","type":"array","items":{"$ref":"#/components/schemas/CallAttemptInput"}},"result":{"description":"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.","allOf":[{"$ref":"#/components/schemas/CallResultInput"}]},"requestedByUserUuid":{"type":"string","format":"uuid","description":"UUID (v4) of the user that requested this call."},"cancelledAt":{"type":"string","description":"Date when call got cancelled, formatted as ISO8601 date string."},"completedAt":{"type":"string","description":"Date when call got completed, formatted as ISO8601 date string."},"notes":{"type":"string","description":"The notes of the call"},"personUuid":{"type":"string","format":"uuid","description":"UUID (v4) of the person that is being called."},"relatedCaseUuid":{"type":"string","format":"uuid","description":"UUID (v4) of any of the person's pledge cases that is related to this call."},"callingOrganizationUuid":{"type":"string","format":"uuid","description":"UUID (v4) of the organization that will perform this call."},"type":{"type":"string","enum":["verification","happy_call","winback"],"description":"\nThe type of call:\n* `verification` → used for verifying the personal details when a donor was newly recruited.\n* `happy_call` → used for existing donors to keep them engaged.\n* `winback` → used for donors to get them resubscribed.\n\nCall 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. \n        "}},"required":["requestedAt","personUuid","type"]},"CallExternalMetadataInput":{"type":"object","properties":{"applicationName":{"type":"string","description":"The name of the application that created the call"},"referenceId":{"type":"string","description":"The reference id of the call in the external system"},"agentReferenceId":{"type":"string","description":"The reference id of the agent in the external system"},"statusCode":{"type":"string","description":"The status code of the call in the external system"},"statusDescription":{"type":"string","description":"The status description of the call in the external system"},"additionalProperties":{"type":"string","description":"A JSON encoded array with mixed additional properties"}},"required":["applicationName","referenceId","agentReferenceId","statusCode","statusDescription","additionalProperties"]},"ExternalSourceInput":{"type":"object","properties":{"name":{"type":"string","description":"The description of the external source"},"identifier":{"type":"string","description":"The unique identifier of the pledge in the external source"}},"required":["name","identifier"]},"CallAttemptInput":{"type":"object","properties":{"createdAt":{"type":"string","format":"date-time","description":"ISO8601 compatible datetime string"},"userUuid":{"type":"string","format":"uuid","description":"UUID (v4) of the user that attempted a call."}}},"CallResultInput":{"type":"object","properties":{"resultCode":{"type":"string","enum":["confirmed","downgraded","converted","dropped","other"],"description":"\nThe current status of the call result:\n* `confirmed` → a call has been made and pledge agreements are confirmed and data may be updated before confirming.\n* `downgraded` → a call has been made and the pledge amount has been downgraded to a lower value.\n* `converted` → a call has been made and the pledge was converted. For example: change of donation period.\n* `dropped` → a call has been made and the pledge was dropped. For example due to: a regret, complaint or missing IBAN.\n* `other` → a call has been made. This status is applied when other statuses do not apply."},"completedAt":{"type":"string","description":"Timestamp when a call was completed, formatted as ISO8601 date string."},"notes":{"type":"string","description":"The notes of the call result"},"donorRetentionRating":{"type":"number","nullable":true,"description":"The donor retention rating is available when status of the call is completed. The donor retention rating values can be between 1 and 10.","enum":[0,1,2,3,4,5,6,7,8,9,10]}},"required":["resultCode","completedAt","notes","donorRetentionRating"]},"CallDto":{"type":"object","properties":{"uuid":{"type":"string","format":"uuid","description":"UUID (v4)","nullable":false},"status":{"type":"string","enum":["completed","requested","cancelled","expired"],"description":"\nThe current status of the call:\n* `requested` → a call is requested and should be made. Initial status.\n* `completed` → a call is done and completed. End status.\n* `cancelled` → a call was requested but is cancelled and thus never called. End status.\n* `expired` → a call was expired since the person was not reached within a specified number of attempts. End status.","nullable":false},"requestedAt":{"format":"date-time","type":"string","description":"ISO8601 compatible datetime string","nullable":false},"externalMetadata":{"nullable":true,"allOf":[{"$ref":"#/components/schemas/CallExternalMetadataDto"}]},"attempts":{"nullable":false,"description":"Contains a collection of attempts that were made to complete the call","type":"array","items":{"$ref":"#/components/schemas/CallAttemptDto"}},"attemptsCount":{"type":"number","description":"The number of call attempts","nullable":false},"result":{"description":"The result of a completed call","nullable":true,"allOf":[{"$ref":"#/components/schemas/CallResultDto"}]},"lastUpdatedAt":{"format":"date-time","type":"string","description":"ISO8601 compatible datetime string","nullable":false},"cancelledAt":{"format":"date-time","type":"string","description":"ISO8601 compatible datetime string","nullable":true},"completedAt":{"format":"date-time","type":"string","description":"ISO8601 compatible datetime string","nullable":true},"expiredAt":{"format":"date-time","type":"string","description":"ISO8601 compatible datetime string","nullable":true},"notes":{"type":"string","description":"The notes of the call","nullable":true},"personUuid":{"type":"string","format":"uuid","description":"UUID (v4) of the person that is being called.","nullable":false},"relatedCaseUuid":{"type":"string","format":"uuid","description":"UUID (v4) of any of the person's pledge cases that is related to this call.","nullable":true},"callingOrganizationUuid":{"type":"string","format":"uuid","description":"UUID (v4) of the organization that will perform this call.","nullable":true},"type":{"type":"string","enum":["verification","happy_call","winback"],"description":"\nThe current type of the call:\n* `verification` → used for verifying the personal details when a donor was newly recruited.\n* `happy_call` → used for existing donors to keep them engaged.\n* `winback` → used for donors to get them resubscribed.","nullable":false},"pledgeCase":{"description":"Related pledge case.\n\nNote: Only included when explicitly requested via the `include` query parameter via the GET calls endpoint.","nullable":true,"allOf":[{"$ref":"#/components/schemas/PledgeCaseDto"}]},"person":{"description":"Related person.\n\nNote: Only included when explicitly requested via the `include` query parameter via the GET calls endpoint.","nullable":true,"allOf":[{"$ref":"#/components/schemas/PersonDto"}]},"transactions":{"description":"Related transactions.\n\nNote: Only included when explicitly requested via the `include` query parameter via the GET calls endpoint.","nullable":true,"type":"array","items":{"$ref":"#/components/schemas/TransactionDto"}},"recordingDuration":{"type":"number","description":"The duration of the call recording, in seconds","nullable":true}},"required":["uuid","status","requestedAt","externalMetadata","attempts","attemptsCount","result","lastUpdatedAt","cancelledAt","completedAt","expiredAt","notes","personUuid","relatedCaseUuid","callingOrganizationUuid","type","pledgeCase","person","transactions","recordingDuration"]},"CallExternalMetadataDto":{"type":"object","properties":{"applicationName":{"type":"string","description":"The name of the application that created the call","nullable":false},"referenceId":{"type":"string","description":"The reference id of the call in the external system","nullable":false},"agentReferenceId":{"type":"string","description":"The reference id of the agent in the external system","nullable":true},"statusCode":{"type":"string","description":"The status code of the call in the external system","nullable":true},"statusDescription":{"type":"string","description":"The status description of the call in the external system","nullable":true},"additionalProperties":{"type":"object","description":"Additional properties provided by/about the external system.","nullable":true}},"required":["applicationName","referenceId","agentReferenceId","statusCode","statusDescription","additionalProperties"]},"CallAttemptDto":{"type":"object","properties":{"userUuid":{"type":"string","format":"uuid","description":"UUID (v4) of the user that attempted a call.","nullable":true},"attemptAt":{"type":"string","format":"date-time","description":"Timestamp when a call was attempted, formatted as ISO8601 date string.","nullable":true},"createdAt":{"type":"string","format":"date-time","description":"Timestamp when the call attempt was created, formatted as ISO8601 date string.","nullable":true}},"required":["userUuid","attemptAt","createdAt"]},"CallResultDto":{"type":"object","properties":{"resultCode":{"type":"string","enum":["confirmed","downgraded","converted","dropped","other"],"description":"\nThe current status of the call result:\n* `confirmed` → a call has been made and pledge agreements are confirmed and data may be updated before confirming.\n* `downgraded` → a call has been made and the pledge amount has been downgraded to a lower value.\n* `converted` → a call has been made and the pledge was converted. For example: change of donation period.\n* `dropped` → a call has been made and the pledge was dropped. For example due to: a regret, complaint or missing IBAN.\n* `other` → a call has been made. This status is applied when other statuses do not apply.","nullable":false},"completedAt":{"format":"date-time","type":"string","description":"ISO8601 compatible datetime string","nullable":false},"notes":{"type":"string","nullable":true},"duration":{"type":"number","description":"The duration of the call result recording, in seconds. This field is deprecated and will be removed in the future. Use `call.recordingDuration` instead.","nullable":true,"deprecated":true},"donorRetentionRating":{"type":"number","description":"The donor retention rating is available when status of the call is completed. The donor retention rating values can be between 1 and 10.","nullable":true,"enum":[0,1,2,3,4,5,6,7,8,9,10]}},"required":["resultCode","completedAt","notes","duration","donorRetentionRating"]},"PledgeCaseDto":{"type":"object","properties":{"uuid":{"type":"string","format":"uuid","description":"UUID (v4)"},"status":{"type":"string","enum":["lead","active","dropped","cancelled","fulfilled"],"description":"\nThe current status of the pledge:\n* `lead` → lead pledge, to be collected. Initial status.\n* `active` → active pledge, being collected.\n* `dropped` → dropped before it was ever collected or released.\n* `cancelled` → cancelled after it was collected or released.\n* `fulfilled` → ended after reaching its end date."},"startsAt":{"format":"date-time","type":"string","description":"ISO8601 compatible datetime string"},"endsAt":{"format":"date-time","type":"string","nullable":true,"description":"ISO8601 compatible datetime string"},"createdAt":{"format":"date-time","type":"string","description":"ISO8601 compatible datetime string"},"updatedAt":{"format":"date-time","type":"string","description":"ISO8601 compatible datetime string describing when the pledge was last updated"},"releasedAt":{"format":"date-time","type":"string","nullable":true,"description":"ISO8601 compatible datetime string"},"owningOrganizationUuid":{"type":"string","format":"uuid","description":"UUID (v4)","deprecated":true},"owningOrganization":{"description":"Organization recruited for","allOf":[{"$ref":"#/components/schemas/OrganizationDto"}]},"recruitingOrganizationUuid":{"type":"string","format":"uuid","description":"UUID (v4)","deprecated":true},"recruitingOrganization":{"description":"Recruiting organization","allOf":[{"$ref":"#/components/schemas/OrganizationDto"}]},"recruitingLocationLabel":{"type":"string","nullable":true,"description":"The label of the location where the pledge was recruited."},"initialDonationAmount":{"type":"number","description":"The donation amount at the moment the pledge was submitted."},"donationAmount":{"type":"number","description":"The current donation amount"},"initialDonationInterval":{"type":"string","enum":["once","monthly","halfYearly","quarterly","yearly"],"description":"The donation interval at the moment the pledge was submitted."},"donationInterval":{"type":"string","enum":["once","monthly","halfYearly","quarterly","yearly"],"description":"The current donation interval"},"preferredPaymentDay":{"type":"number","description":"The preferred payment day of the month (options: 1 - 28). Default value, when not supplied or user has no preference, is: <code>null</code>"},"person":{"description":"Related person.\n\nNote: 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.","nullable":true,"allOf":[{"$ref":"#/components/schemas/PersonDto"}]},"recruitmentType":{"type":"string","enum":["d2d","street"],"nullable":true},"recruiterUserUuid":{"type":"string","format":"uuid","description":"UUID (v4)","deprecated":true},"recruiterUser":{"description":"User that recruited the pledge","allOf":[{"$ref":"#/components/schemas/RecruiterUserDto"}]},"signatureSignedUrl":{"type":"string","nullable":true,"description":"Temporary URL to signature file, valid for 1 hour"},"transactions":{"description":"Transactions that were created for this pledge case.\n\nNote: Only included when explicitly requested via the `include` query parameter via the GET pledges endpoint.","nullable":true,"type":"array","items":{"$ref":"#/components/schemas/TransactionDto"}},"calls":{"description":"Calls that were created for this pledge case.\n\nNote: Only included when explicitly requested via the `include` query parameter via the GET pledges endpoint.","nullable":true,"type":"array","items":{"$ref":"#/components/schemas/CallDto"}},"focusAreas":{"default":[],"type":"array","items":{"$ref":"#/components/schemas/FocusAreaDto"}},"externalSource":{"nullable":true,"description":"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.","allOf":[{"$ref":"#/components/schemas/ExternalSourceDto"}]},"externalMetadata":{"type":"object","nullable":true,"description":"Additional properties provided by/about the external system."},"campaignCode":{"type":"string","nullable":true,"description":"Campaign code defined by the organization"},"collectionDate":{"format":"date-time","type":"string","nullable":true,"description":"Collection date of the pledge case defined by the organization. ISO8601 compatible datetime string."}},"required":["uuid","status","startsAt","endsAt","createdAt","updatedAt","owningOrganizationUuid","owningOrganization","recruitingOrganizationUuid","recruitingOrganization","recruitingLocationLabel","initialDonationAmount","donationAmount","initialDonationInterval","donationInterval","preferredPaymentDay","person","recruitmentType","recruiterUserUuid","recruiterUser","signatureSignedUrl","transactions","calls","focusAreas","externalSource","externalMetadata","campaignCode","collectionDate"]},"OrganizationDto":{"type":"object","properties":{"uuid":{"type":"string","format":"uuid","description":"UUID (v4)"},"name":{"type":"string","description":"Name of organization"}},"required":["uuid","name"]},"PersonDto":{"type":"object","properties":{"uuid":{"type":"string","format":"uuid","description":"UUID (v4)"},"personUuid":{"type":"string","format":"uuid","description":"UUID (v4). Deprecated: use the 'uuid' property instead.","deprecated":true},"academicTitle":{"type":"string","nullable":true},"initials":{"type":"string","nullable":true},"firstName":{"type":"string","nullable":true},"lastNamePrefix":{"type":"string","nullable":true},"lastName":{"type":"string","nullable":true},"dateOfBirth":{"type":"string","nullable":true,"description":"Local date of birth for user, formatted as YYYY-MM-DD"},"socialSecurityNumber":{"type":"string","nullable":true,"description":"Social security number as string without any separators."},"iban":{"type":"string","nullable":true},"address":{"nullable":true,"allOf":[{"$ref":"#/components/schemas/AddressDto"}]},"phoneNumber":{"type":"string","nullable":true},"mobilePhoneNumber":{"type":"string","nullable":true},"email":{"type":"string","nullable":true},"gender":{"type":"string","enum":["male","female","other"],"nullable":true},"optInEmail":{"type":"boolean","nullable":true},"optInPhone":{"type":"boolean","nullable":true},"optInMail":{"type":"boolean","nullable":true},"optInSms":{"type":"boolean","nullable":true},"language":{"type":"string","nullable":true,"description":"ISO-639-1 language code"},"mandate":{"nullable":true,"allOf":[{"$ref":"#/components/schemas/MandateDto"}]},"createdAt":{"format":"date-time","type":"string","description":"ISO8601 compatible datetime string"},"owningOrganization":{"description":"Organization recruited for","allOf":[{"$ref":"#/components/schemas/OrganizationDto"}]},"qualityResult":{"nullable":true,"description":"The generated quality result of the person. This is only included when requested via the 'include' parameter in the request, if available for the endpoint you're calling. If the value is `null` it means that the quality result is not yet generated.","allOf":[{"$ref":"#/components/schemas/QualityResultDto"}]}},"required":["uuid","personUuid","academicTitle","initials","firstName","lastNamePrefix","lastName","dateOfBirth","iban","address","phoneNumber","mobilePhoneNumber","email","gender","optInEmail","optInPhone","optInMail","optInSms","language","mandate","createdAt","owningOrganization","qualityResult"]},"AddressDto":{"type":"object","properties":{"street":{"type":"string","nullable":true},"houseNumber":{"type":"string","nullable":true},"houseNumberExtension":{"type":"string","nullable":true},"zipCode":{"type":"string","nullable":true},"city":{"type":"string","nullable":true},"country":{"type":"string","nullable":true,"description":"Country code in ISO 3166-1 alpha-2"}}},"MandateDto":{"type":"object","properties":{"createdAt":{"format":"date-time","type":"string","description":"ISO8601 compatible datetime string"}},"required":["createdAt"]},"QualityResultDto":{"type":"object","properties":{"score":{"type":"number","description":"The combined score of the quality gates","nullable":false},"maxScore":{"type":"number","description":"The combined max score that could be reached with the applied the quality gates","nullable":false},"percentage":{"type":"number","description":"The percentage of the score compared to the max score","nullable":false},"createdAt":{"format":"date-time","type":"string","description":"ISO8601 compatible datetime string","nullable":false},"gateResults":{"description":"The results from the quality gates that are part of this quality result","nullable":false,"type":"array","items":{"$ref":"#/components/schemas/QualityGateResultDto"}}},"required":["score","maxScore","percentage","createdAt","gateResults"]},"QualityGateResultDto":{"type":"object","properties":{"identifier":{"type":"string","description":"The identifier of the quality gate","nullable":false,"enum":["addressIsAvailable","addressIsComplete","addressIsValid","addressDoesNotMatchRecruiterUsersAddress","ibanDoesNotMatchAnotherPersonsIban","ibanDoesNotMatchRecruiterUsersIban","ibanIsAvailable","ibanIsValid","phoneNumberDoesNotMatchRecruiterUsersPhoneNumber","phoneNumberIsNotASequence","phoneNumberIsAvailable","phoneNumberMatchesPattern","phoneNumberDoesNotMatchAnotherPersonsPhoneNumber","emailIsAvailable","emailMatchesEmailPattern","emailIsDeliverable"]},"category":{"type":"string","description":"The category of the quality gate","nullable":false,"enum":["addressQuality","recruiterFraud","uniqueness","ibanQuality","emailQuality","phoneNumberQuality"]},"score":{"type":"number","description":"The score for this quality gate","nullable":false},"maxScore":{"type":"number","description":"The maximum score that could be reached with this quality gate","nullable":false},"percentage":{"type":"number","description":"The percentage of the score compared to the max score","nullable":false},"explanation":{"type":"string","description":"The explanation of the score","nullable":false,"enum":["ok","ibanMatchesPersonIban","ibanMatchesRecruiterIban","ibanIsMissing","ibanIsInvalid","ibanMayBeInvalid","addressIsMissing","addressIsIncomplete","addressIsInvalid","addressIsNotValidated","addressMatchesRecruiterAddress","phoneNumberIsASequence","mobilePhoneNumberIsASequence","phoneNumberMatchesRecruiterPhoneNumber","phoneNumberMatchesAnotherPersonsPhoneNumber","mobilePhoneNumberMatchesRecruiterPhoneNumber","phoneNumberIsMissing","phoneNumberDoesNotMatchPattern","mobilePhoneNumberDoesNotMatchPattern","emailIsMissing","emailDoesNotMatchEmailPattern","emailNotDeliverable","emailValidationUnknown"]},"metadata":{"type":"object","description":"Additional metadata for this quality gate result","nullable":true}},"required":["identifier","category","score","maxScore","percentage","explanation","metadata"]},"RecruiterUserDto":{"type":"object","properties":{"uuid":{"type":"string","format":"uuid","description":"UUID (v4)"},"identifier":{"type":"string","description":"Recruiter user identifier"},"name":{"type":"string","description":"Recruiter user name. Only returned if you have permission to view it.","nullable":true}},"required":["uuid","identifier","name"]},"TransactionDto":{"type":"object","properties":{"uuid":{"type":"string","format":"uuid","description":"UUID (v4)"},"personUuid":{"type":"string","format":"uuid","description":"UUID (v4)"},"origin":{"description":"This field requires you to connect the transaction to an origin, for example pledge case.","allOf":[{"$ref":"#/components/schemas/TransactionOriginDto"}]},"amount":{"type":"number","description":"Transaction amount. Only supporting Euros at this point."},"name":{"type":"string","description":"Name of the person that made this transaction at the moment in time. Might also be used for the name of the bank account holder.","nullable":true},"iban":{"type":"string","description":"IBAN of the bank account that made this transaction.","nullable":true},"description":{"type":"string","description":"Description of the transaction, usually provided by the payment initiator."},"provider":{"type":"string","enum":["cm","mollie"],"description":"Identifier of the payment provider used for this transaction.","nullable":true},"method":{"type":"string","enum":["idealqr","direct_debit"],"description":"Payment method used for this transaction.","nullable":true},"referenceId":{"type":"string","description":"Reference id provided by the payment initiator.","nullable":true},"transactionId":{"type":"string","description":"Transaction id provided by the payment provider.","nullable":true},"providerMetadata":{"type":"object","description":"Meta data provided by/about the payment provider.","nullable":true},"createdAt":{"format":"date-time","type":"string","description":"Date of transaction creation, formatted as ISO8601 date string."},"updatedAt":{"format":"date-time","type":"string","description":"Date of transaction last update, formatted as ISO8601 date string."},"status":{"type":"string","enum":["open","paid","failed","cancelled","reversed"],"description":"\nThe current status of the transaction:\n* `open` → open transaction, to be paid.\n* `paid` → paid transaction.\n* `failed` → failed transaction before it was paid.\n* `cancelled` → cancelled transaction before it was paid.\n* `reversed` → reversed transaction or chargeback."}},"required":["uuid","personUuid","origin","amount","description","createdAt","updatedAt","status"]},"TransactionOriginDto":{"type":"object","properties":{"name":{"type":"string","enum":["pledgeCase"]},"identifier":{"type":"string","format":"uuid","description":"UUID (v4)"}},"required":["name","identifier"]},"FocusAreaDto":{"type":"object","properties":{"uuid":{"type":"string","format":"uuid","description":"UUID (v4)"},"name":{"type":"string","description":"Name of the focus area"},"externalSource":{"description":"External source of the focus area","nullable":true,"allOf":[{"$ref":"#/components/schemas/ExternalSourceDto"}]}},"required":["uuid","name","externalSource"]},"ExternalSourceDto":{"type":"object","properties":{"name":{"type":"string","description":"Name of the external source"},"identifier":{"type":"string","description":"Identifier of this entity in the external source"}},"required":["name","identifier"]}}},"paths":{"/api/v1/calls":{"post":{"operationId":"CreateCallRestController_create","summary":"Create a call","description":"\nThis endpoint creates a call for a person (and pledge case), if your service account allows you to.\n\nThe person you are allowed to create a call for is also limited by your service account.\n\nWe 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.\n\nThis endpoint will return the created call in the response body.\n\n## Determining where the call will be managed\n\nWhen 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. \n\nWhen 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. \n\nWhen 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.\n\nBe sure to check the descriptions for fields in the request body to see which fields are required, optional or forbidden for each scenario.\n","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateCallInput"}}}},"responses":{"201":{"description":"Call was created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CallDto"}}}},"400":{"description":"Bad request. Response body shows what the problem is."},"401":{"description":"Service account not properly authenticated"},"403":{"description":"Service account forbids executing this action"},"409":{"description":"Call already exists"}},"tags":["calls"]}}}}
```

## Add a call attempt

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

```json
{"openapi":"3.0.0","info":{"title":"TapRaise API","version":"v1"},"security":[{"bearer":[]}],"components":{"securitySchemes":{"bearer":{"scheme":"bearer","bearerFormat":"jwt","type":"http"}},"schemas":{"AddCallAttemptInput":{"type":"object","properties":{"userUuid":{"type":"string","format":"uuid","description":"UUID (v4) of the user that attempted the call."},"attemptAt":{"type":"string","description":"Timestamp when a call was attempted, formatted as ISO8601 date string."}}},"CallDto":{"type":"object","properties":{"uuid":{"type":"string","format":"uuid","description":"UUID (v4)","nullable":false},"status":{"type":"string","enum":["completed","requested","cancelled","expired"],"description":"\nThe current status of the call:\n* `requested` → a call is requested and should be made. Initial status.\n* `completed` → a call is done and completed. End status.\n* `cancelled` → a call was requested but is cancelled and thus never called. End status.\n* `expired` → a call was expired since the person was not reached within a specified number of attempts. End status.","nullable":false},"requestedAt":{"format":"date-time","type":"string","description":"ISO8601 compatible datetime string","nullable":false},"externalMetadata":{"nullable":true,"allOf":[{"$ref":"#/components/schemas/CallExternalMetadataDto"}]},"attempts":{"nullable":false,"description":"Contains a collection of attempts that were made to complete the call","type":"array","items":{"$ref":"#/components/schemas/CallAttemptDto"}},"attemptsCount":{"type":"number","description":"The number of call attempts","nullable":false},"result":{"description":"The result of a completed call","nullable":true,"allOf":[{"$ref":"#/components/schemas/CallResultDto"}]},"lastUpdatedAt":{"format":"date-time","type":"string","description":"ISO8601 compatible datetime string","nullable":false},"cancelledAt":{"format":"date-time","type":"string","description":"ISO8601 compatible datetime string","nullable":true},"completedAt":{"format":"date-time","type":"string","description":"ISO8601 compatible datetime string","nullable":true},"expiredAt":{"format":"date-time","type":"string","description":"ISO8601 compatible datetime string","nullable":true},"notes":{"type":"string","description":"The notes of the call","nullable":true},"personUuid":{"type":"string","format":"uuid","description":"UUID (v4) of the person that is being called.","nullable":false},"relatedCaseUuid":{"type":"string","format":"uuid","description":"UUID (v4) of any of the person's pledge cases that is related to this call.","nullable":true},"callingOrganizationUuid":{"type":"string","format":"uuid","description":"UUID (v4) of the organization that will perform this call.","nullable":true},"type":{"type":"string","enum":["verification","happy_call","winback"],"description":"\nThe current type of the call:\n* `verification` → used for verifying the personal details when a donor was newly recruited.\n* `happy_call` → used for existing donors to keep them engaged.\n* `winback` → used for donors to get them resubscribed.","nullable":false},"pledgeCase":{"description":"Related pledge case.\n\nNote: Only included when explicitly requested via the `include` query parameter via the GET calls endpoint.","nullable":true,"allOf":[{"$ref":"#/components/schemas/PledgeCaseDto"}]},"person":{"description":"Related person.\n\nNote: Only included when explicitly requested via the `include` query parameter via the GET calls endpoint.","nullable":true,"allOf":[{"$ref":"#/components/schemas/PersonDto"}]},"transactions":{"description":"Related transactions.\n\nNote: Only included when explicitly requested via the `include` query parameter via the GET calls endpoint.","nullable":true,"type":"array","items":{"$ref":"#/components/schemas/TransactionDto"}},"recordingDuration":{"type":"number","description":"The duration of the call recording, in seconds","nullable":true}},"required":["uuid","status","requestedAt","externalMetadata","attempts","attemptsCount","result","lastUpdatedAt","cancelledAt","completedAt","expiredAt","notes","personUuid","relatedCaseUuid","callingOrganizationUuid","type","pledgeCase","person","transactions","recordingDuration"]},"CallExternalMetadataDto":{"type":"object","properties":{"applicationName":{"type":"string","description":"The name of the application that created the call","nullable":false},"referenceId":{"type":"string","description":"The reference id of the call in the external system","nullable":false},"agentReferenceId":{"type":"string","description":"The reference id of the agent in the external system","nullable":true},"statusCode":{"type":"string","description":"The status code of the call in the external system","nullable":true},"statusDescription":{"type":"string","description":"The status description of the call in the external system","nullable":true},"additionalProperties":{"type":"object","description":"Additional properties provided by/about the external system.","nullable":true}},"required":["applicationName","referenceId","agentReferenceId","statusCode","statusDescription","additionalProperties"]},"CallAttemptDto":{"type":"object","properties":{"userUuid":{"type":"string","format":"uuid","description":"UUID (v4) of the user that attempted a call.","nullable":true},"attemptAt":{"type":"string","format":"date-time","description":"Timestamp when a call was attempted, formatted as ISO8601 date string.","nullable":true},"createdAt":{"type":"string","format":"date-time","description":"Timestamp when the call attempt was created, formatted as ISO8601 date string.","nullable":true}},"required":["userUuid","attemptAt","createdAt"]},"CallResultDto":{"type":"object","properties":{"resultCode":{"type":"string","enum":["confirmed","downgraded","converted","dropped","other"],"description":"\nThe current status of the call result:\n* `confirmed` → a call has been made and pledge agreements are confirmed and data may be updated before confirming.\n* `downgraded` → a call has been made and the pledge amount has been downgraded to a lower value.\n* `converted` → a call has been made and the pledge was converted. For example: change of donation period.\n* `dropped` → a call has been made and the pledge was dropped. For example due to: a regret, complaint or missing IBAN.\n* `other` → a call has been made. This status is applied when other statuses do not apply.","nullable":false},"completedAt":{"format":"date-time","type":"string","description":"ISO8601 compatible datetime string","nullable":false},"notes":{"type":"string","nullable":true},"duration":{"type":"number","description":"The duration of the call result recording, in seconds. This field is deprecated and will be removed in the future. Use `call.recordingDuration` instead.","nullable":true,"deprecated":true},"donorRetentionRating":{"type":"number","description":"The donor retention rating is available when status of the call is completed. The donor retention rating values can be between 1 and 10.","nullable":true,"enum":[0,1,2,3,4,5,6,7,8,9,10]}},"required":["resultCode","completedAt","notes","duration","donorRetentionRating"]},"PledgeCaseDto":{"type":"object","properties":{"uuid":{"type":"string","format":"uuid","description":"UUID (v4)"},"status":{"type":"string","enum":["lead","active","dropped","cancelled","fulfilled"],"description":"\nThe current status of the pledge:\n* `lead` → lead pledge, to be collected. Initial status.\n* `active` → active pledge, being collected.\n* `dropped` → dropped before it was ever collected or released.\n* `cancelled` → cancelled after it was collected or released.\n* `fulfilled` → ended after reaching its end date."},"startsAt":{"format":"date-time","type":"string","description":"ISO8601 compatible datetime string"},"endsAt":{"format":"date-time","type":"string","nullable":true,"description":"ISO8601 compatible datetime string"},"createdAt":{"format":"date-time","type":"string","description":"ISO8601 compatible datetime string"},"updatedAt":{"format":"date-time","type":"string","description":"ISO8601 compatible datetime string describing when the pledge was last updated"},"releasedAt":{"format":"date-time","type":"string","nullable":true,"description":"ISO8601 compatible datetime string"},"owningOrganizationUuid":{"type":"string","format":"uuid","description":"UUID (v4)","deprecated":true},"owningOrganization":{"description":"Organization recruited for","allOf":[{"$ref":"#/components/schemas/OrganizationDto"}]},"recruitingOrganizationUuid":{"type":"string","format":"uuid","description":"UUID (v4)","deprecated":true},"recruitingOrganization":{"description":"Recruiting organization","allOf":[{"$ref":"#/components/schemas/OrganizationDto"}]},"recruitingLocationLabel":{"type":"string","nullable":true,"description":"The label of the location where the pledge was recruited."},"initialDonationAmount":{"type":"number","description":"The donation amount at the moment the pledge was submitted."},"donationAmount":{"type":"number","description":"The current donation amount"},"initialDonationInterval":{"type":"string","enum":["once","monthly","halfYearly","quarterly","yearly"],"description":"The donation interval at the moment the pledge was submitted."},"donationInterval":{"type":"string","enum":["once","monthly","halfYearly","quarterly","yearly"],"description":"The current donation interval"},"preferredPaymentDay":{"type":"number","description":"The preferred payment day of the month (options: 1 - 28). Default value, when not supplied or user has no preference, is: <code>null</code>"},"person":{"description":"Related person.\n\nNote: 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.","nullable":true,"allOf":[{"$ref":"#/components/schemas/PersonDto"}]},"recruitmentType":{"type":"string","enum":["d2d","street"],"nullable":true},"recruiterUserUuid":{"type":"string","format":"uuid","description":"UUID (v4)","deprecated":true},"recruiterUser":{"description":"User that recruited the pledge","allOf":[{"$ref":"#/components/schemas/RecruiterUserDto"}]},"signatureSignedUrl":{"type":"string","nullable":true,"description":"Temporary URL to signature file, valid for 1 hour"},"transactions":{"description":"Transactions that were created for this pledge case.\n\nNote: Only included when explicitly requested via the `include` query parameter via the GET pledges endpoint.","nullable":true,"type":"array","items":{"$ref":"#/components/schemas/TransactionDto"}},"calls":{"description":"Calls that were created for this pledge case.\n\nNote: Only included when explicitly requested via the `include` query parameter via the GET pledges endpoint.","nullable":true,"type":"array","items":{"$ref":"#/components/schemas/CallDto"}},"focusAreas":{"default":[],"type":"array","items":{"$ref":"#/components/schemas/FocusAreaDto"}},"externalSource":{"nullable":true,"description":"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.","allOf":[{"$ref":"#/components/schemas/ExternalSourceDto"}]},"externalMetadata":{"type":"object","nullable":true,"description":"Additional properties provided by/about the external system."},"campaignCode":{"type":"string","nullable":true,"description":"Campaign code defined by the organization"},"collectionDate":{"format":"date-time","type":"string","nullable":true,"description":"Collection date of the pledge case defined by the organization. ISO8601 compatible datetime string."}},"required":["uuid","status","startsAt","endsAt","createdAt","updatedAt","owningOrganizationUuid","owningOrganization","recruitingOrganizationUuid","recruitingOrganization","recruitingLocationLabel","initialDonationAmount","donationAmount","initialDonationInterval","donationInterval","preferredPaymentDay","person","recruitmentType","recruiterUserUuid","recruiterUser","signatureSignedUrl","transactions","calls","focusAreas","externalSource","externalMetadata","campaignCode","collectionDate"]},"OrganizationDto":{"type":"object","properties":{"uuid":{"type":"string","format":"uuid","description":"UUID (v4)"},"name":{"type":"string","description":"Name of organization"}},"required":["uuid","name"]},"PersonDto":{"type":"object","properties":{"uuid":{"type":"string","format":"uuid","description":"UUID (v4)"},"personUuid":{"type":"string","format":"uuid","description":"UUID (v4). Deprecated: use the 'uuid' property instead.","deprecated":true},"academicTitle":{"type":"string","nullable":true},"initials":{"type":"string","nullable":true},"firstName":{"type":"string","nullable":true},"lastNamePrefix":{"type":"string","nullable":true},"lastName":{"type":"string","nullable":true},"dateOfBirth":{"type":"string","nullable":true,"description":"Local date of birth for user, formatted as YYYY-MM-DD"},"socialSecurityNumber":{"type":"string","nullable":true,"description":"Social security number as string without any separators."},"iban":{"type":"string","nullable":true},"address":{"nullable":true,"allOf":[{"$ref":"#/components/schemas/AddressDto"}]},"phoneNumber":{"type":"string","nullable":true},"mobilePhoneNumber":{"type":"string","nullable":true},"email":{"type":"string","nullable":true},"gender":{"type":"string","enum":["male","female","other"],"nullable":true},"optInEmail":{"type":"boolean","nullable":true},"optInPhone":{"type":"boolean","nullable":true},"optInMail":{"type":"boolean","nullable":true},"optInSms":{"type":"boolean","nullable":true},"language":{"type":"string","nullable":true,"description":"ISO-639-1 language code"},"mandate":{"nullable":true,"allOf":[{"$ref":"#/components/schemas/MandateDto"}]},"createdAt":{"format":"date-time","type":"string","description":"ISO8601 compatible datetime string"},"owningOrganization":{"description":"Organization recruited for","allOf":[{"$ref":"#/components/schemas/OrganizationDto"}]},"qualityResult":{"nullable":true,"description":"The generated quality result of the person. This is only included when requested via the 'include' parameter in the request, if available for the endpoint you're calling. If the value is `null` it means that the quality result is not yet generated.","allOf":[{"$ref":"#/components/schemas/QualityResultDto"}]}},"required":["uuid","personUuid","academicTitle","initials","firstName","lastNamePrefix","lastName","dateOfBirth","iban","address","phoneNumber","mobilePhoneNumber","email","gender","optInEmail","optInPhone","optInMail","optInSms","language","mandate","createdAt","owningOrganization","qualityResult"]},"AddressDto":{"type":"object","properties":{"street":{"type":"string","nullable":true},"houseNumber":{"type":"string","nullable":true},"houseNumberExtension":{"type":"string","nullable":true},"zipCode":{"type":"string","nullable":true},"city":{"type":"string","nullable":true},"country":{"type":"string","nullable":true,"description":"Country code in ISO 3166-1 alpha-2"}}},"MandateDto":{"type":"object","properties":{"createdAt":{"format":"date-time","type":"string","description":"ISO8601 compatible datetime string"}},"required":["createdAt"]},"QualityResultDto":{"type":"object","properties":{"score":{"type":"number","description":"The combined score of the quality gates","nullable":false},"maxScore":{"type":"number","description":"The combined max score that could be reached with the applied the quality gates","nullable":false},"percentage":{"type":"number","description":"The percentage of the score compared to the max score","nullable":false},"createdAt":{"format":"date-time","type":"string","description":"ISO8601 compatible datetime string","nullable":false},"gateResults":{"description":"The results from the quality gates that are part of this quality result","nullable":false,"type":"array","items":{"$ref":"#/components/schemas/QualityGateResultDto"}}},"required":["score","maxScore","percentage","createdAt","gateResults"]},"QualityGateResultDto":{"type":"object","properties":{"identifier":{"type":"string","description":"The identifier of the quality gate","nullable":false,"enum":["addressIsAvailable","addressIsComplete","addressIsValid","addressDoesNotMatchRecruiterUsersAddress","ibanDoesNotMatchAnotherPersonsIban","ibanDoesNotMatchRecruiterUsersIban","ibanIsAvailable","ibanIsValid","phoneNumberDoesNotMatchRecruiterUsersPhoneNumber","phoneNumberIsNotASequence","phoneNumberIsAvailable","phoneNumberMatchesPattern","phoneNumberDoesNotMatchAnotherPersonsPhoneNumber","emailIsAvailable","emailMatchesEmailPattern","emailIsDeliverable"]},"category":{"type":"string","description":"The category of the quality gate","nullable":false,"enum":["addressQuality","recruiterFraud","uniqueness","ibanQuality","emailQuality","phoneNumberQuality"]},"score":{"type":"number","description":"The score for this quality gate","nullable":false},"maxScore":{"type":"number","description":"The maximum score that could be reached with this quality gate","nullable":false},"percentage":{"type":"number","description":"The percentage of the score compared to the max score","nullable":false},"explanation":{"type":"string","description":"The explanation of the score","nullable":false,"enum":["ok","ibanMatchesPersonIban","ibanMatchesRecruiterIban","ibanIsMissing","ibanIsInvalid","ibanMayBeInvalid","addressIsMissing","addressIsIncomplete","addressIsInvalid","addressIsNotValidated","addressMatchesRecruiterAddress","phoneNumberIsASequence","mobilePhoneNumberIsASequence","phoneNumberMatchesRecruiterPhoneNumber","phoneNumberMatchesAnotherPersonsPhoneNumber","mobilePhoneNumberMatchesRecruiterPhoneNumber","phoneNumberIsMissing","phoneNumberDoesNotMatchPattern","mobilePhoneNumberDoesNotMatchPattern","emailIsMissing","emailDoesNotMatchEmailPattern","emailNotDeliverable","emailValidationUnknown"]},"metadata":{"type":"object","description":"Additional metadata for this quality gate result","nullable":true}},"required":["identifier","category","score","maxScore","percentage","explanation","metadata"]},"RecruiterUserDto":{"type":"object","properties":{"uuid":{"type":"string","format":"uuid","description":"UUID (v4)"},"identifier":{"type":"string","description":"Recruiter user identifier"},"name":{"type":"string","description":"Recruiter user name. Only returned if you have permission to view it.","nullable":true}},"required":["uuid","identifier","name"]},"TransactionDto":{"type":"object","properties":{"uuid":{"type":"string","format":"uuid","description":"UUID (v4)"},"personUuid":{"type":"string","format":"uuid","description":"UUID (v4)"},"origin":{"description":"This field requires you to connect the transaction to an origin, for example pledge case.","allOf":[{"$ref":"#/components/schemas/TransactionOriginDto"}]},"amount":{"type":"number","description":"Transaction amount. Only supporting Euros at this point."},"name":{"type":"string","description":"Name of the person that made this transaction at the moment in time. Might also be used for the name of the bank account holder.","nullable":true},"iban":{"type":"string","description":"IBAN of the bank account that made this transaction.","nullable":true},"description":{"type":"string","description":"Description of the transaction, usually provided by the payment initiator."},"provider":{"type":"string","enum":["cm","mollie"],"description":"Identifier of the payment provider used for this transaction.","nullable":true},"method":{"type":"string","enum":["idealqr","direct_debit"],"description":"Payment method used for this transaction.","nullable":true},"referenceId":{"type":"string","description":"Reference id provided by the payment initiator.","nullable":true},"transactionId":{"type":"string","description":"Transaction id provided by the payment provider.","nullable":true},"providerMetadata":{"type":"object","description":"Meta data provided by/about the payment provider.","nullable":true},"createdAt":{"format":"date-time","type":"string","description":"Date of transaction creation, formatted as ISO8601 date string."},"updatedAt":{"format":"date-time","type":"string","description":"Date of transaction last update, formatted as ISO8601 date string."},"status":{"type":"string","enum":["open","paid","failed","cancelled","reversed"],"description":"\nThe current status of the transaction:\n* `open` → open transaction, to be paid.\n* `paid` → paid transaction.\n* `failed` → failed transaction before it was paid.\n* `cancelled` → cancelled transaction before it was paid.\n* `reversed` → reversed transaction or chargeback."}},"required":["uuid","personUuid","origin","amount","description","createdAt","updatedAt","status"]},"TransactionOriginDto":{"type":"object","properties":{"name":{"type":"string","enum":["pledgeCase"]},"identifier":{"type":"string","format":"uuid","description":"UUID (v4)"}},"required":["name","identifier"]},"FocusAreaDto":{"type":"object","properties":{"uuid":{"type":"string","format":"uuid","description":"UUID (v4)"},"name":{"type":"string","description":"Name of the focus area"},"externalSource":{"description":"External source of the focus area","nullable":true,"allOf":[{"$ref":"#/components/schemas/ExternalSourceDto"}]}},"required":["uuid","name","externalSource"]},"ExternalSourceDto":{"type":"object","properties":{"name":{"type":"string","description":"Name of the external source"},"identifier":{"type":"string","description":"Identifier of this entity in the external source"}},"required":["name","identifier"]}}},"paths":{"/api/v1/calls/{uuid}/actions/add-attempt":{"put":{"operationId":"AddCallAttemptRestController_addAttempt","summary":"Add a call attempt","description":"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.","parameters":[{"name":"uuid","required":true,"in":"path","description":"The uuid of the call","schema":{"format":"uuid","type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AddCallAttemptInput"}}}},"responses":{"200":{"description":"Call attempt was added","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CallDto"}}}},"400":{"description":"Bad request. Response body shows what the problem is."},"401":{"description":"Service account not properly authenticated"},"403":{"description":"Service account forbids executing this action"},"404":{"description":"Call is not found"}},"tags":["calls"]}}}}
```

## Mark a call as completed

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

```json
{"openapi":"3.0.0","info":{"title":"TapRaise API","version":"v1"},"security":[{"bearer":[]}],"components":{"securitySchemes":{"bearer":{"scheme":"bearer","bearerFormat":"jwt","type":"http"}},"schemas":{"CompleteCallInput":{"type":"object","properties":{"userUuid":{"type":"string","format":"uuid","description":"UUID (v4) of the user that completes the call."},"result":{"description":"The result of a completed call.","allOf":[{"$ref":"#/components/schemas/CompleteCallResultInput"}]}},"required":["result"]},"CompleteCallResultInput":{"type":"object","properties":{"completedAt":{"type":"string","description":"Timestamp when a call was completed, formatted as ISO8601 date string."},"notes":{"type":"string","description":"The notes of the call result"},"donorRetentionRating":{"type":"number","description":"The donor retention rating is available when status of the call is completed. The donor retention rating values can be between 1 and 10.","enum":[0,1,2,3,4,5,6,7,8,9,10]},"resultCode":{"type":"string","description":"The result code of the call.","enum":["confirmed","downgraded","converted","dropped","other"]}},"required":["completedAt","resultCode"]},"CallDto":{"type":"object","properties":{"uuid":{"type":"string","format":"uuid","description":"UUID (v4)","nullable":false},"status":{"type":"string","enum":["completed","requested","cancelled","expired"],"description":"\nThe current status of the call:\n* `requested` → a call is requested and should be made. Initial status.\n* `completed` → a call is done and completed. End status.\n* `cancelled` → a call was requested but is cancelled and thus never called. End status.\n* `expired` → a call was expired since the person was not reached within a specified number of attempts. End status.","nullable":false},"requestedAt":{"format":"date-time","type":"string","description":"ISO8601 compatible datetime string","nullable":false},"externalMetadata":{"nullable":true,"allOf":[{"$ref":"#/components/schemas/CallExternalMetadataDto"}]},"attempts":{"nullable":false,"description":"Contains a collection of attempts that were made to complete the call","type":"array","items":{"$ref":"#/components/schemas/CallAttemptDto"}},"attemptsCount":{"type":"number","description":"The number of call attempts","nullable":false},"result":{"description":"The result of a completed call","nullable":true,"allOf":[{"$ref":"#/components/schemas/CallResultDto"}]},"lastUpdatedAt":{"format":"date-time","type":"string","description":"ISO8601 compatible datetime string","nullable":false},"cancelledAt":{"format":"date-time","type":"string","description":"ISO8601 compatible datetime string","nullable":true},"completedAt":{"format":"date-time","type":"string","description":"ISO8601 compatible datetime string","nullable":true},"expiredAt":{"format":"date-time","type":"string","description":"ISO8601 compatible datetime string","nullable":true},"notes":{"type":"string","description":"The notes of the call","nullable":true},"personUuid":{"type":"string","format":"uuid","description":"UUID (v4) of the person that is being called.","nullable":false},"relatedCaseUuid":{"type":"string","format":"uuid","description":"UUID (v4) of any of the person's pledge cases that is related to this call.","nullable":true},"callingOrganizationUuid":{"type":"string","format":"uuid","description":"UUID (v4) of the organization that will perform this call.","nullable":true},"type":{"type":"string","enum":["verification","happy_call","winback"],"description":"\nThe current type of the call:\n* `verification` → used for verifying the personal details when a donor was newly recruited.\n* `happy_call` → used for existing donors to keep them engaged.\n* `winback` → used for donors to get them resubscribed.","nullable":false},"pledgeCase":{"description":"Related pledge case.\n\nNote: Only included when explicitly requested via the `include` query parameter via the GET calls endpoint.","nullable":true,"allOf":[{"$ref":"#/components/schemas/PledgeCaseDto"}]},"person":{"description":"Related person.\n\nNote: Only included when explicitly requested via the `include` query parameter via the GET calls endpoint.","nullable":true,"allOf":[{"$ref":"#/components/schemas/PersonDto"}]},"transactions":{"description":"Related transactions.\n\nNote: Only included when explicitly requested via the `include` query parameter via the GET calls endpoint.","nullable":true,"type":"array","items":{"$ref":"#/components/schemas/TransactionDto"}},"recordingDuration":{"type":"number","description":"The duration of the call recording, in seconds","nullable":true}},"required":["uuid","status","requestedAt","externalMetadata","attempts","attemptsCount","result","lastUpdatedAt","cancelledAt","completedAt","expiredAt","notes","personUuid","relatedCaseUuid","callingOrganizationUuid","type","pledgeCase","person","transactions","recordingDuration"]},"CallExternalMetadataDto":{"type":"object","properties":{"applicationName":{"type":"string","description":"The name of the application that created the call","nullable":false},"referenceId":{"type":"string","description":"The reference id of the call in the external system","nullable":false},"agentReferenceId":{"type":"string","description":"The reference id of the agent in the external system","nullable":true},"statusCode":{"type":"string","description":"The status code of the call in the external system","nullable":true},"statusDescription":{"type":"string","description":"The status description of the call in the external system","nullable":true},"additionalProperties":{"type":"object","description":"Additional properties provided by/about the external system.","nullable":true}},"required":["applicationName","referenceId","agentReferenceId","statusCode","statusDescription","additionalProperties"]},"CallAttemptDto":{"type":"object","properties":{"userUuid":{"type":"string","format":"uuid","description":"UUID (v4) of the user that attempted a call.","nullable":true},"attemptAt":{"type":"string","format":"date-time","description":"Timestamp when a call was attempted, formatted as ISO8601 date string.","nullable":true},"createdAt":{"type":"string","format":"date-time","description":"Timestamp when the call attempt was created, formatted as ISO8601 date string.","nullable":true}},"required":["userUuid","attemptAt","createdAt"]},"CallResultDto":{"type":"object","properties":{"resultCode":{"type":"string","enum":["confirmed","downgraded","converted","dropped","other"],"description":"\nThe current status of the call result:\n* `confirmed` → a call has been made and pledge agreements are confirmed and data may be updated before confirming.\n* `downgraded` → a call has been made and the pledge amount has been downgraded to a lower value.\n* `converted` → a call has been made and the pledge was converted. For example: change of donation period.\n* `dropped` → a call has been made and the pledge was dropped. For example due to: a regret, complaint or missing IBAN.\n* `other` → a call has been made. This status is applied when other statuses do not apply.","nullable":false},"completedAt":{"format":"date-time","type":"string","description":"ISO8601 compatible datetime string","nullable":false},"notes":{"type":"string","nullable":true},"duration":{"type":"number","description":"The duration of the call result recording, in seconds. This field is deprecated and will be removed in the future. Use `call.recordingDuration` instead.","nullable":true,"deprecated":true},"donorRetentionRating":{"type":"number","description":"The donor retention rating is available when status of the call is completed. The donor retention rating values can be between 1 and 10.","nullable":true,"enum":[0,1,2,3,4,5,6,7,8,9,10]}},"required":["resultCode","completedAt","notes","duration","donorRetentionRating"]},"PledgeCaseDto":{"type":"object","properties":{"uuid":{"type":"string","format":"uuid","description":"UUID (v4)"},"status":{"type":"string","enum":["lead","active","dropped","cancelled","fulfilled"],"description":"\nThe current status of the pledge:\n* `lead` → lead pledge, to be collected. Initial status.\n* `active` → active pledge, being collected.\n* `dropped` → dropped before it was ever collected or released.\n* `cancelled` → cancelled after it was collected or released.\n* `fulfilled` → ended after reaching its end date."},"startsAt":{"format":"date-time","type":"string","description":"ISO8601 compatible datetime string"},"endsAt":{"format":"date-time","type":"string","nullable":true,"description":"ISO8601 compatible datetime string"},"createdAt":{"format":"date-time","type":"string","description":"ISO8601 compatible datetime string"},"updatedAt":{"format":"date-time","type":"string","description":"ISO8601 compatible datetime string describing when the pledge was last updated"},"releasedAt":{"format":"date-time","type":"string","nullable":true,"description":"ISO8601 compatible datetime string"},"owningOrganizationUuid":{"type":"string","format":"uuid","description":"UUID (v4)","deprecated":true},"owningOrganization":{"description":"Organization recruited for","allOf":[{"$ref":"#/components/schemas/OrganizationDto"}]},"recruitingOrganizationUuid":{"type":"string","format":"uuid","description":"UUID (v4)","deprecated":true},"recruitingOrganization":{"description":"Recruiting organization","allOf":[{"$ref":"#/components/schemas/OrganizationDto"}]},"recruitingLocationLabel":{"type":"string","nullable":true,"description":"The label of the location where the pledge was recruited."},"initialDonationAmount":{"type":"number","description":"The donation amount at the moment the pledge was submitted."},"donationAmount":{"type":"number","description":"The current donation amount"},"initialDonationInterval":{"type":"string","enum":["once","monthly","halfYearly","quarterly","yearly"],"description":"The donation interval at the moment the pledge was submitted."},"donationInterval":{"type":"string","enum":["once","monthly","halfYearly","quarterly","yearly"],"description":"The current donation interval"},"preferredPaymentDay":{"type":"number","description":"The preferred payment day of the month (options: 1 - 28). Default value, when not supplied or user has no preference, is: <code>null</code>"},"person":{"description":"Related person.\n\nNote: 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.","nullable":true,"allOf":[{"$ref":"#/components/schemas/PersonDto"}]},"recruitmentType":{"type":"string","enum":["d2d","street"],"nullable":true},"recruiterUserUuid":{"type":"string","format":"uuid","description":"UUID (v4)","deprecated":true},"recruiterUser":{"description":"User that recruited the pledge","allOf":[{"$ref":"#/components/schemas/RecruiterUserDto"}]},"signatureSignedUrl":{"type":"string","nullable":true,"description":"Temporary URL to signature file, valid for 1 hour"},"transactions":{"description":"Transactions that were created for this pledge case.\n\nNote: Only included when explicitly requested via the `include` query parameter via the GET pledges endpoint.","nullable":true,"type":"array","items":{"$ref":"#/components/schemas/TransactionDto"}},"calls":{"description":"Calls that were created for this pledge case.\n\nNote: Only included when explicitly requested via the `include` query parameter via the GET pledges endpoint.","nullable":true,"type":"array","items":{"$ref":"#/components/schemas/CallDto"}},"focusAreas":{"default":[],"type":"array","items":{"$ref":"#/components/schemas/FocusAreaDto"}},"externalSource":{"nullable":true,"description":"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.","allOf":[{"$ref":"#/components/schemas/ExternalSourceDto"}]},"externalMetadata":{"type":"object","nullable":true,"description":"Additional properties provided by/about the external system."},"campaignCode":{"type":"string","nullable":true,"description":"Campaign code defined by the organization"},"collectionDate":{"format":"date-time","type":"string","nullable":true,"description":"Collection date of the pledge case defined by the organization. ISO8601 compatible datetime string."}},"required":["uuid","status","startsAt","endsAt","createdAt","updatedAt","owningOrganizationUuid","owningOrganization","recruitingOrganizationUuid","recruitingOrganization","recruitingLocationLabel","initialDonationAmount","donationAmount","initialDonationInterval","donationInterval","preferredPaymentDay","person","recruitmentType","recruiterUserUuid","recruiterUser","signatureSignedUrl","transactions","calls","focusAreas","externalSource","externalMetadata","campaignCode","collectionDate"]},"OrganizationDto":{"type":"object","properties":{"uuid":{"type":"string","format":"uuid","description":"UUID (v4)"},"name":{"type":"string","description":"Name of organization"}},"required":["uuid","name"]},"PersonDto":{"type":"object","properties":{"uuid":{"type":"string","format":"uuid","description":"UUID (v4)"},"personUuid":{"type":"string","format":"uuid","description":"UUID (v4). Deprecated: use the 'uuid' property instead.","deprecated":true},"academicTitle":{"type":"string","nullable":true},"initials":{"type":"string","nullable":true},"firstName":{"type":"string","nullable":true},"lastNamePrefix":{"type":"string","nullable":true},"lastName":{"type":"string","nullable":true},"dateOfBirth":{"type":"string","nullable":true,"description":"Local date of birth for user, formatted as YYYY-MM-DD"},"socialSecurityNumber":{"type":"string","nullable":true,"description":"Social security number as string without any separators."},"iban":{"type":"string","nullable":true},"address":{"nullable":true,"allOf":[{"$ref":"#/components/schemas/AddressDto"}]},"phoneNumber":{"type":"string","nullable":true},"mobilePhoneNumber":{"type":"string","nullable":true},"email":{"type":"string","nullable":true},"gender":{"type":"string","enum":["male","female","other"],"nullable":true},"optInEmail":{"type":"boolean","nullable":true},"optInPhone":{"type":"boolean","nullable":true},"optInMail":{"type":"boolean","nullable":true},"optInSms":{"type":"boolean","nullable":true},"language":{"type":"string","nullable":true,"description":"ISO-639-1 language code"},"mandate":{"nullable":true,"allOf":[{"$ref":"#/components/schemas/MandateDto"}]},"createdAt":{"format":"date-time","type":"string","description":"ISO8601 compatible datetime string"},"owningOrganization":{"description":"Organization recruited for","allOf":[{"$ref":"#/components/schemas/OrganizationDto"}]},"qualityResult":{"nullable":true,"description":"The generated quality result of the person. This is only included when requested via the 'include' parameter in the request, if available for the endpoint you're calling. If the value is `null` it means that the quality result is not yet generated.","allOf":[{"$ref":"#/components/schemas/QualityResultDto"}]}},"required":["uuid","personUuid","academicTitle","initials","firstName","lastNamePrefix","lastName","dateOfBirth","iban","address","phoneNumber","mobilePhoneNumber","email","gender","optInEmail","optInPhone","optInMail","optInSms","language","mandate","createdAt","owningOrganization","qualityResult"]},"AddressDto":{"type":"object","properties":{"street":{"type":"string","nullable":true},"houseNumber":{"type":"string","nullable":true},"houseNumberExtension":{"type":"string","nullable":true},"zipCode":{"type":"string","nullable":true},"city":{"type":"string","nullable":true},"country":{"type":"string","nullable":true,"description":"Country code in ISO 3166-1 alpha-2"}}},"MandateDto":{"type":"object","properties":{"createdAt":{"format":"date-time","type":"string","description":"ISO8601 compatible datetime string"}},"required":["createdAt"]},"QualityResultDto":{"type":"object","properties":{"score":{"type":"number","description":"The combined score of the quality gates","nullable":false},"maxScore":{"type":"number","description":"The combined max score that could be reached with the applied the quality gates","nullable":false},"percentage":{"type":"number","description":"The percentage of the score compared to the max score","nullable":false},"createdAt":{"format":"date-time","type":"string","description":"ISO8601 compatible datetime string","nullable":false},"gateResults":{"description":"The results from the quality gates that are part of this quality result","nullable":false,"type":"array","items":{"$ref":"#/components/schemas/QualityGateResultDto"}}},"required":["score","maxScore","percentage","createdAt","gateResults"]},"QualityGateResultDto":{"type":"object","properties":{"identifier":{"type":"string","description":"The identifier of the quality gate","nullable":false,"enum":["addressIsAvailable","addressIsComplete","addressIsValid","addressDoesNotMatchRecruiterUsersAddress","ibanDoesNotMatchAnotherPersonsIban","ibanDoesNotMatchRecruiterUsersIban","ibanIsAvailable","ibanIsValid","phoneNumberDoesNotMatchRecruiterUsersPhoneNumber","phoneNumberIsNotASequence","phoneNumberIsAvailable","phoneNumberMatchesPattern","phoneNumberDoesNotMatchAnotherPersonsPhoneNumber","emailIsAvailable","emailMatchesEmailPattern","emailIsDeliverable"]},"category":{"type":"string","description":"The category of the quality gate","nullable":false,"enum":["addressQuality","recruiterFraud","uniqueness","ibanQuality","emailQuality","phoneNumberQuality"]},"score":{"type":"number","description":"The score for this quality gate","nullable":false},"maxScore":{"type":"number","description":"The maximum score that could be reached with this quality gate","nullable":false},"percentage":{"type":"number","description":"The percentage of the score compared to the max score","nullable":false},"explanation":{"type":"string","description":"The explanation of the score","nullable":false,"enum":["ok","ibanMatchesPersonIban","ibanMatchesRecruiterIban","ibanIsMissing","ibanIsInvalid","ibanMayBeInvalid","addressIsMissing","addressIsIncomplete","addressIsInvalid","addressIsNotValidated","addressMatchesRecruiterAddress","phoneNumberIsASequence","mobilePhoneNumberIsASequence","phoneNumberMatchesRecruiterPhoneNumber","phoneNumberMatchesAnotherPersonsPhoneNumber","mobilePhoneNumberMatchesRecruiterPhoneNumber","phoneNumberIsMissing","phoneNumberDoesNotMatchPattern","mobilePhoneNumberDoesNotMatchPattern","emailIsMissing","emailDoesNotMatchEmailPattern","emailNotDeliverable","emailValidationUnknown"]},"metadata":{"type":"object","description":"Additional metadata for this quality gate result","nullable":true}},"required":["identifier","category","score","maxScore","percentage","explanation","metadata"]},"RecruiterUserDto":{"type":"object","properties":{"uuid":{"type":"string","format":"uuid","description":"UUID (v4)"},"identifier":{"type":"string","description":"Recruiter user identifier"},"name":{"type":"string","description":"Recruiter user name. Only returned if you have permission to view it.","nullable":true}},"required":["uuid","identifier","name"]},"TransactionDto":{"type":"object","properties":{"uuid":{"type":"string","format":"uuid","description":"UUID (v4)"},"personUuid":{"type":"string","format":"uuid","description":"UUID (v4)"},"origin":{"description":"This field requires you to connect the transaction to an origin, for example pledge case.","allOf":[{"$ref":"#/components/schemas/TransactionOriginDto"}]},"amount":{"type":"number","description":"Transaction amount. Only supporting Euros at this point."},"name":{"type":"string","description":"Name of the person that made this transaction at the moment in time. Might also be used for the name of the bank account holder.","nullable":true},"iban":{"type":"string","description":"IBAN of the bank account that made this transaction.","nullable":true},"description":{"type":"string","description":"Description of the transaction, usually provided by the payment initiator."},"provider":{"type":"string","enum":["cm","mollie"],"description":"Identifier of the payment provider used for this transaction.","nullable":true},"method":{"type":"string","enum":["idealqr","direct_debit"],"description":"Payment method used for this transaction.","nullable":true},"referenceId":{"type":"string","description":"Reference id provided by the payment initiator.","nullable":true},"transactionId":{"type":"string","description":"Transaction id provided by the payment provider.","nullable":true},"providerMetadata":{"type":"object","description":"Meta data provided by/about the payment provider.","nullable":true},"createdAt":{"format":"date-time","type":"string","description":"Date of transaction creation, formatted as ISO8601 date string."},"updatedAt":{"format":"date-time","type":"string","description":"Date of transaction last update, formatted as ISO8601 date string."},"status":{"type":"string","enum":["open","paid","failed","cancelled","reversed"],"description":"\nThe current status of the transaction:\n* `open` → open transaction, to be paid.\n* `paid` → paid transaction.\n* `failed` → failed transaction before it was paid.\n* `cancelled` → cancelled transaction before it was paid.\n* `reversed` → reversed transaction or chargeback."}},"required":["uuid","personUuid","origin","amount","description","createdAt","updatedAt","status"]},"TransactionOriginDto":{"type":"object","properties":{"name":{"type":"string","enum":["pledgeCase"]},"identifier":{"type":"string","format":"uuid","description":"UUID (v4)"}},"required":["name","identifier"]},"FocusAreaDto":{"type":"object","properties":{"uuid":{"type":"string","format":"uuid","description":"UUID (v4)"},"name":{"type":"string","description":"Name of the focus area"},"externalSource":{"description":"External source of the focus area","nullable":true,"allOf":[{"$ref":"#/components/schemas/ExternalSourceDto"}]}},"required":["uuid","name","externalSource"]},"ExternalSourceDto":{"type":"object","properties":{"name":{"type":"string","description":"Name of the external source"},"identifier":{"type":"string","description":"Identifier of this entity in the external source"}},"required":["name","identifier"]}}},"paths":{"/api/v1/calls/{uuid}/actions/complete":{"put":{"operationId":"CompleteCallRestController_completeCall","summary":"Mark a call as completed","description":"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.","parameters":[{"name":"uuid","required":true,"in":"path","description":"The uuid of the call","schema":{"format":"uuid","type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CompleteCallInput"}}}},"responses":{"200":{"description":"Call that was marked as completed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CallDto"}}}},"400":{"description":"Bad request. Response body shows what the problem is."},"401":{"description":"Service account not properly authenticated"},"403":{"description":"Service account forbids executing this action"},"404":{"description":"Call is not found"}},"tags":["calls"]}}}}
```

## Cancel a 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.<br>

```json
{"openapi":"3.0.0","info":{"title":"TapRaise API","version":"v1"},"security":[{"bearer":[]}],"components":{"securitySchemes":{"bearer":{"scheme":"bearer","bearerFormat":"jwt","type":"http"}},"schemas":{"CancelCallInput":{"type":"object","properties":{"cancelledAt":{"type":"string","description":"Timestamp when a call was cancelled, formatted as ISO8601 date string."}}},"CallDto":{"type":"object","properties":{"uuid":{"type":"string","format":"uuid","description":"UUID (v4)","nullable":false},"status":{"type":"string","enum":["completed","requested","cancelled","expired"],"description":"\nThe current status of the call:\n* `requested` → a call is requested and should be made. Initial status.\n* `completed` → a call is done and completed. End status.\n* `cancelled` → a call was requested but is cancelled and thus never called. End status.\n* `expired` → a call was expired since the person was not reached within a specified number of attempts. End status.","nullable":false},"requestedAt":{"format":"date-time","type":"string","description":"ISO8601 compatible datetime string","nullable":false},"externalMetadata":{"nullable":true,"allOf":[{"$ref":"#/components/schemas/CallExternalMetadataDto"}]},"attempts":{"nullable":false,"description":"Contains a collection of attempts that were made to complete the call","type":"array","items":{"$ref":"#/components/schemas/CallAttemptDto"}},"attemptsCount":{"type":"number","description":"The number of call attempts","nullable":false},"result":{"description":"The result of a completed call","nullable":true,"allOf":[{"$ref":"#/components/schemas/CallResultDto"}]},"lastUpdatedAt":{"format":"date-time","type":"string","description":"ISO8601 compatible datetime string","nullable":false},"cancelledAt":{"format":"date-time","type":"string","description":"ISO8601 compatible datetime string","nullable":true},"completedAt":{"format":"date-time","type":"string","description":"ISO8601 compatible datetime string","nullable":true},"expiredAt":{"format":"date-time","type":"string","description":"ISO8601 compatible datetime string","nullable":true},"notes":{"type":"string","description":"The notes of the call","nullable":true},"personUuid":{"type":"string","format":"uuid","description":"UUID (v4) of the person that is being called.","nullable":false},"relatedCaseUuid":{"type":"string","format":"uuid","description":"UUID (v4) of any of the person's pledge cases that is related to this call.","nullable":true},"callingOrganizationUuid":{"type":"string","format":"uuid","description":"UUID (v4) of the organization that will perform this call.","nullable":true},"type":{"type":"string","enum":["verification","happy_call","winback"],"description":"\nThe current type of the call:\n* `verification` → used for verifying the personal details when a donor was newly recruited.\n* `happy_call` → used for existing donors to keep them engaged.\n* `winback` → used for donors to get them resubscribed.","nullable":false},"pledgeCase":{"description":"Related pledge case.\n\nNote: Only included when explicitly requested via the `include` query parameter via the GET calls endpoint.","nullable":true,"allOf":[{"$ref":"#/components/schemas/PledgeCaseDto"}]},"person":{"description":"Related person.\n\nNote: Only included when explicitly requested via the `include` query parameter via the GET calls endpoint.","nullable":true,"allOf":[{"$ref":"#/components/schemas/PersonDto"}]},"transactions":{"description":"Related transactions.\n\nNote: Only included when explicitly requested via the `include` query parameter via the GET calls endpoint.","nullable":true,"type":"array","items":{"$ref":"#/components/schemas/TransactionDto"}},"recordingDuration":{"type":"number","description":"The duration of the call recording, in seconds","nullable":true}},"required":["uuid","status","requestedAt","externalMetadata","attempts","attemptsCount","result","lastUpdatedAt","cancelledAt","completedAt","expiredAt","notes","personUuid","relatedCaseUuid","callingOrganizationUuid","type","pledgeCase","person","transactions","recordingDuration"]},"CallExternalMetadataDto":{"type":"object","properties":{"applicationName":{"type":"string","description":"The name of the application that created the call","nullable":false},"referenceId":{"type":"string","description":"The reference id of the call in the external system","nullable":false},"agentReferenceId":{"type":"string","description":"The reference id of the agent in the external system","nullable":true},"statusCode":{"type":"string","description":"The status code of the call in the external system","nullable":true},"statusDescription":{"type":"string","description":"The status description of the call in the external system","nullable":true},"additionalProperties":{"type":"object","description":"Additional properties provided by/about the external system.","nullable":true}},"required":["applicationName","referenceId","agentReferenceId","statusCode","statusDescription","additionalProperties"]},"CallAttemptDto":{"type":"object","properties":{"userUuid":{"type":"string","format":"uuid","description":"UUID (v4) of the user that attempted a call.","nullable":true},"attemptAt":{"type":"string","format":"date-time","description":"Timestamp when a call was attempted, formatted as ISO8601 date string.","nullable":true},"createdAt":{"type":"string","format":"date-time","description":"Timestamp when the call attempt was created, formatted as ISO8601 date string.","nullable":true}},"required":["userUuid","attemptAt","createdAt"]},"CallResultDto":{"type":"object","properties":{"resultCode":{"type":"string","enum":["confirmed","downgraded","converted","dropped","other"],"description":"\nThe current status of the call result:\n* `confirmed` → a call has been made and pledge agreements are confirmed and data may be updated before confirming.\n* `downgraded` → a call has been made and the pledge amount has been downgraded to a lower value.\n* `converted` → a call has been made and the pledge was converted. For example: change of donation period.\n* `dropped` → a call has been made and the pledge was dropped. For example due to: a regret, complaint or missing IBAN.\n* `other` → a call has been made. This status is applied when other statuses do not apply.","nullable":false},"completedAt":{"format":"date-time","type":"string","description":"ISO8601 compatible datetime string","nullable":false},"notes":{"type":"string","nullable":true},"duration":{"type":"number","description":"The duration of the call result recording, in seconds. This field is deprecated and will be removed in the future. Use `call.recordingDuration` instead.","nullable":true,"deprecated":true},"donorRetentionRating":{"type":"number","description":"The donor retention rating is available when status of the call is completed. The donor retention rating values can be between 1 and 10.","nullable":true,"enum":[0,1,2,3,4,5,6,7,8,9,10]}},"required":["resultCode","completedAt","notes","duration","donorRetentionRating"]},"PledgeCaseDto":{"type":"object","properties":{"uuid":{"type":"string","format":"uuid","description":"UUID (v4)"},"status":{"type":"string","enum":["lead","active","dropped","cancelled","fulfilled"],"description":"\nThe current status of the pledge:\n* `lead` → lead pledge, to be collected. Initial status.\n* `active` → active pledge, being collected.\n* `dropped` → dropped before it was ever collected or released.\n* `cancelled` → cancelled after it was collected or released.\n* `fulfilled` → ended after reaching its end date."},"startsAt":{"format":"date-time","type":"string","description":"ISO8601 compatible datetime string"},"endsAt":{"format":"date-time","type":"string","nullable":true,"description":"ISO8601 compatible datetime string"},"createdAt":{"format":"date-time","type":"string","description":"ISO8601 compatible datetime string"},"updatedAt":{"format":"date-time","type":"string","description":"ISO8601 compatible datetime string describing when the pledge was last updated"},"releasedAt":{"format":"date-time","type":"string","nullable":true,"description":"ISO8601 compatible datetime string"},"owningOrganizationUuid":{"type":"string","format":"uuid","description":"UUID (v4)","deprecated":true},"owningOrganization":{"description":"Organization recruited for","allOf":[{"$ref":"#/components/schemas/OrganizationDto"}]},"recruitingOrganizationUuid":{"type":"string","format":"uuid","description":"UUID (v4)","deprecated":true},"recruitingOrganization":{"description":"Recruiting organization","allOf":[{"$ref":"#/components/schemas/OrganizationDto"}]},"recruitingLocationLabel":{"type":"string","nullable":true,"description":"The label of the location where the pledge was recruited."},"initialDonationAmount":{"type":"number","description":"The donation amount at the moment the pledge was submitted."},"donationAmount":{"type":"number","description":"The current donation amount"},"initialDonationInterval":{"type":"string","enum":["once","monthly","halfYearly","quarterly","yearly"],"description":"The donation interval at the moment the pledge was submitted."},"donationInterval":{"type":"string","enum":["once","monthly","halfYearly","quarterly","yearly"],"description":"The current donation interval"},"preferredPaymentDay":{"type":"number","description":"The preferred payment day of the month (options: 1 - 28). Default value, when not supplied or user has no preference, is: <code>null</code>"},"person":{"description":"Related person.\n\nNote: 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.","nullable":true,"allOf":[{"$ref":"#/components/schemas/PersonDto"}]},"recruitmentType":{"type":"string","enum":["d2d","street"],"nullable":true},"recruiterUserUuid":{"type":"string","format":"uuid","description":"UUID (v4)","deprecated":true},"recruiterUser":{"description":"User that recruited the pledge","allOf":[{"$ref":"#/components/schemas/RecruiterUserDto"}]},"signatureSignedUrl":{"type":"string","nullable":true,"description":"Temporary URL to signature file, valid for 1 hour"},"transactions":{"description":"Transactions that were created for this pledge case.\n\nNote: Only included when explicitly requested via the `include` query parameter via the GET pledges endpoint.","nullable":true,"type":"array","items":{"$ref":"#/components/schemas/TransactionDto"}},"calls":{"description":"Calls that were created for this pledge case.\n\nNote: Only included when explicitly requested via the `include` query parameter via the GET pledges endpoint.","nullable":true,"type":"array","items":{"$ref":"#/components/schemas/CallDto"}},"focusAreas":{"default":[],"type":"array","items":{"$ref":"#/components/schemas/FocusAreaDto"}},"externalSource":{"nullable":true,"description":"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.","allOf":[{"$ref":"#/components/schemas/ExternalSourceDto"}]},"externalMetadata":{"type":"object","nullable":true,"description":"Additional properties provided by/about the external system."},"campaignCode":{"type":"string","nullable":true,"description":"Campaign code defined by the organization"},"collectionDate":{"format":"date-time","type":"string","nullable":true,"description":"Collection date of the pledge case defined by the organization. ISO8601 compatible datetime string."}},"required":["uuid","status","startsAt","endsAt","createdAt","updatedAt","owningOrganizationUuid","owningOrganization","recruitingOrganizationUuid","recruitingOrganization","recruitingLocationLabel","initialDonationAmount","donationAmount","initialDonationInterval","donationInterval","preferredPaymentDay","person","recruitmentType","recruiterUserUuid","recruiterUser","signatureSignedUrl","transactions","calls","focusAreas","externalSource","externalMetadata","campaignCode","collectionDate"]},"OrganizationDto":{"type":"object","properties":{"uuid":{"type":"string","format":"uuid","description":"UUID (v4)"},"name":{"type":"string","description":"Name of organization"}},"required":["uuid","name"]},"PersonDto":{"type":"object","properties":{"uuid":{"type":"string","format":"uuid","description":"UUID (v4)"},"personUuid":{"type":"string","format":"uuid","description":"UUID (v4). Deprecated: use the 'uuid' property instead.","deprecated":true},"academicTitle":{"type":"string","nullable":true},"initials":{"type":"string","nullable":true},"firstName":{"type":"string","nullable":true},"lastNamePrefix":{"type":"string","nullable":true},"lastName":{"type":"string","nullable":true},"dateOfBirth":{"type":"string","nullable":true,"description":"Local date of birth for user, formatted as YYYY-MM-DD"},"socialSecurityNumber":{"type":"string","nullable":true,"description":"Social security number as string without any separators."},"iban":{"type":"string","nullable":true},"address":{"nullable":true,"allOf":[{"$ref":"#/components/schemas/AddressDto"}]},"phoneNumber":{"type":"string","nullable":true},"mobilePhoneNumber":{"type":"string","nullable":true},"email":{"type":"string","nullable":true},"gender":{"type":"string","enum":["male","female","other"],"nullable":true},"optInEmail":{"type":"boolean","nullable":true},"optInPhone":{"type":"boolean","nullable":true},"optInMail":{"type":"boolean","nullable":true},"optInSms":{"type":"boolean","nullable":true},"language":{"type":"string","nullable":true,"description":"ISO-639-1 language code"},"mandate":{"nullable":true,"allOf":[{"$ref":"#/components/schemas/MandateDto"}]},"createdAt":{"format":"date-time","type":"string","description":"ISO8601 compatible datetime string"},"owningOrganization":{"description":"Organization recruited for","allOf":[{"$ref":"#/components/schemas/OrganizationDto"}]},"qualityResult":{"nullable":true,"description":"The generated quality result of the person. This is only included when requested via the 'include' parameter in the request, if available for the endpoint you're calling. If the value is `null` it means that the quality result is not yet generated.","allOf":[{"$ref":"#/components/schemas/QualityResultDto"}]}},"required":["uuid","personUuid","academicTitle","initials","firstName","lastNamePrefix","lastName","dateOfBirth","iban","address","phoneNumber","mobilePhoneNumber","email","gender","optInEmail","optInPhone","optInMail","optInSms","language","mandate","createdAt","owningOrganization","qualityResult"]},"AddressDto":{"type":"object","properties":{"street":{"type":"string","nullable":true},"houseNumber":{"type":"string","nullable":true},"houseNumberExtension":{"type":"string","nullable":true},"zipCode":{"type":"string","nullable":true},"city":{"type":"string","nullable":true},"country":{"type":"string","nullable":true,"description":"Country code in ISO 3166-1 alpha-2"}}},"MandateDto":{"type":"object","properties":{"createdAt":{"format":"date-time","type":"string","description":"ISO8601 compatible datetime string"}},"required":["createdAt"]},"QualityResultDto":{"type":"object","properties":{"score":{"type":"number","description":"The combined score of the quality gates","nullable":false},"maxScore":{"type":"number","description":"The combined max score that could be reached with the applied the quality gates","nullable":false},"percentage":{"type":"number","description":"The percentage of the score compared to the max score","nullable":false},"createdAt":{"format":"date-time","type":"string","description":"ISO8601 compatible datetime string","nullable":false},"gateResults":{"description":"The results from the quality gates that are part of this quality result","nullable":false,"type":"array","items":{"$ref":"#/components/schemas/QualityGateResultDto"}}},"required":["score","maxScore","percentage","createdAt","gateResults"]},"QualityGateResultDto":{"type":"object","properties":{"identifier":{"type":"string","description":"The identifier of the quality gate","nullable":false,"enum":["addressIsAvailable","addressIsComplete","addressIsValid","addressDoesNotMatchRecruiterUsersAddress","ibanDoesNotMatchAnotherPersonsIban","ibanDoesNotMatchRecruiterUsersIban","ibanIsAvailable","ibanIsValid","phoneNumberDoesNotMatchRecruiterUsersPhoneNumber","phoneNumberIsNotASequence","phoneNumberIsAvailable","phoneNumberMatchesPattern","phoneNumberDoesNotMatchAnotherPersonsPhoneNumber","emailIsAvailable","emailMatchesEmailPattern","emailIsDeliverable"]},"category":{"type":"string","description":"The category of the quality gate","nullable":false,"enum":["addressQuality","recruiterFraud","uniqueness","ibanQuality","emailQuality","phoneNumberQuality"]},"score":{"type":"number","description":"The score for this quality gate","nullable":false},"maxScore":{"type":"number","description":"The maximum score that could be reached with this quality gate","nullable":false},"percentage":{"type":"number","description":"The percentage of the score compared to the max score","nullable":false},"explanation":{"type":"string","description":"The explanation of the score","nullable":false,"enum":["ok","ibanMatchesPersonIban","ibanMatchesRecruiterIban","ibanIsMissing","ibanIsInvalid","ibanMayBeInvalid","addressIsMissing","addressIsIncomplete","addressIsInvalid","addressIsNotValidated","addressMatchesRecruiterAddress","phoneNumberIsASequence","mobilePhoneNumberIsASequence","phoneNumberMatchesRecruiterPhoneNumber","phoneNumberMatchesAnotherPersonsPhoneNumber","mobilePhoneNumberMatchesRecruiterPhoneNumber","phoneNumberIsMissing","phoneNumberDoesNotMatchPattern","mobilePhoneNumberDoesNotMatchPattern","emailIsMissing","emailDoesNotMatchEmailPattern","emailNotDeliverable","emailValidationUnknown"]},"metadata":{"type":"object","description":"Additional metadata for this quality gate result","nullable":true}},"required":["identifier","category","score","maxScore","percentage","explanation","metadata"]},"RecruiterUserDto":{"type":"object","properties":{"uuid":{"type":"string","format":"uuid","description":"UUID (v4)"},"identifier":{"type":"string","description":"Recruiter user identifier"},"name":{"type":"string","description":"Recruiter user name. Only returned if you have permission to view it.","nullable":true}},"required":["uuid","identifier","name"]},"TransactionDto":{"type":"object","properties":{"uuid":{"type":"string","format":"uuid","description":"UUID (v4)"},"personUuid":{"type":"string","format":"uuid","description":"UUID (v4)"},"origin":{"description":"This field requires you to connect the transaction to an origin, for example pledge case.","allOf":[{"$ref":"#/components/schemas/TransactionOriginDto"}]},"amount":{"type":"number","description":"Transaction amount. Only supporting Euros at this point."},"name":{"type":"string","description":"Name of the person that made this transaction at the moment in time. Might also be used for the name of the bank account holder.","nullable":true},"iban":{"type":"string","description":"IBAN of the bank account that made this transaction.","nullable":true},"description":{"type":"string","description":"Description of the transaction, usually provided by the payment initiator."},"provider":{"type":"string","enum":["cm","mollie"],"description":"Identifier of the payment provider used for this transaction.","nullable":true},"method":{"type":"string","enum":["idealqr","direct_debit"],"description":"Payment method used for this transaction.","nullable":true},"referenceId":{"type":"string","description":"Reference id provided by the payment initiator.","nullable":true},"transactionId":{"type":"string","description":"Transaction id provided by the payment provider.","nullable":true},"providerMetadata":{"type":"object","description":"Meta data provided by/about the payment provider.","nullable":true},"createdAt":{"format":"date-time","type":"string","description":"Date of transaction creation, formatted as ISO8601 date string."},"updatedAt":{"format":"date-time","type":"string","description":"Date of transaction last update, formatted as ISO8601 date string."},"status":{"type":"string","enum":["open","paid","failed","cancelled","reversed"],"description":"\nThe current status of the transaction:\n* `open` → open transaction, to be paid.\n* `paid` → paid transaction.\n* `failed` → failed transaction before it was paid.\n* `cancelled` → cancelled transaction before it was paid.\n* `reversed` → reversed transaction or chargeback."}},"required":["uuid","personUuid","origin","amount","description","createdAt","updatedAt","status"]},"TransactionOriginDto":{"type":"object","properties":{"name":{"type":"string","enum":["pledgeCase"]},"identifier":{"type":"string","format":"uuid","description":"UUID (v4)"}},"required":["name","identifier"]},"FocusAreaDto":{"type":"object","properties":{"uuid":{"type":"string","format":"uuid","description":"UUID (v4)"},"name":{"type":"string","description":"Name of the focus area"},"externalSource":{"description":"External source of the focus area","nullable":true,"allOf":[{"$ref":"#/components/schemas/ExternalSourceDto"}]}},"required":["uuid","name","externalSource"]},"ExternalSourceDto":{"type":"object","properties":{"name":{"type":"string","description":"Name of the external source"},"identifier":{"type":"string","description":"Identifier of this entity in the external source"}},"required":["name","identifier"]}}},"paths":{"/api/v1/calls/{uuid}/actions/cancel":{"put":{"operationId":"CancelCallRestController_cancelCall","summary":"Cancel a call","description":"\nThis endpoint cancells a call. \n\nThe person who is allowed to cancel a call is limited by your service account.\n\nThis endpoint will return the cancelled call in the response body.\n","parameters":[{"name":"uuid","required":true,"in":"path","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CancelCallInput"}}}},"responses":{"200":{"description":"Call was cancelled","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CallDto"}}}},"400":{"description":"Bad request. Response body shows what the problem is."},"401":{"description":"Service account not properly authenticated"},"403":{"description":"Service account forbids executing this action"},"404":{"description":"Call is not found"},"409":{"description":"Call already cancelled"}},"tags":["calls"]}}}}
```

## Expires a call at a given date

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

```json
{"openapi":"3.0.0","info":{"title":"TapRaise API","version":"v1"},"security":[{"bearer":[]}],"components":{"securitySchemes":{"bearer":{"scheme":"bearer","bearerFormat":"jwt","type":"http"}},"schemas":{"ExpireCallInput":{"type":"object","properties":{"expiredAt":{"type":"string","description":"Expiry date of a call, formatted as ISO8601 date string."}}},"CallDto":{"type":"object","properties":{"uuid":{"type":"string","format":"uuid","description":"UUID (v4)","nullable":false},"status":{"type":"string","enum":["completed","requested","cancelled","expired"],"description":"\nThe current status of the call:\n* `requested` → a call is requested and should be made. Initial status.\n* `completed` → a call is done and completed. End status.\n* `cancelled` → a call was requested but is cancelled and thus never called. End status.\n* `expired` → a call was expired since the person was not reached within a specified number of attempts. End status.","nullable":false},"requestedAt":{"format":"date-time","type":"string","description":"ISO8601 compatible datetime string","nullable":false},"externalMetadata":{"nullable":true,"allOf":[{"$ref":"#/components/schemas/CallExternalMetadataDto"}]},"attempts":{"nullable":false,"description":"Contains a collection of attempts that were made to complete the call","type":"array","items":{"$ref":"#/components/schemas/CallAttemptDto"}},"attemptsCount":{"type":"number","description":"The number of call attempts","nullable":false},"result":{"description":"The result of a completed call","nullable":true,"allOf":[{"$ref":"#/components/schemas/CallResultDto"}]},"lastUpdatedAt":{"format":"date-time","type":"string","description":"ISO8601 compatible datetime string","nullable":false},"cancelledAt":{"format":"date-time","type":"string","description":"ISO8601 compatible datetime string","nullable":true},"completedAt":{"format":"date-time","type":"string","description":"ISO8601 compatible datetime string","nullable":true},"expiredAt":{"format":"date-time","type":"string","description":"ISO8601 compatible datetime string","nullable":true},"notes":{"type":"string","description":"The notes of the call","nullable":true},"personUuid":{"type":"string","format":"uuid","description":"UUID (v4) of the person that is being called.","nullable":false},"relatedCaseUuid":{"type":"string","format":"uuid","description":"UUID (v4) of any of the person's pledge cases that is related to this call.","nullable":true},"callingOrganizationUuid":{"type":"string","format":"uuid","description":"UUID (v4) of the organization that will perform this call.","nullable":true},"type":{"type":"string","enum":["verification","happy_call","winback"],"description":"\nThe current type of the call:\n* `verification` → used for verifying the personal details when a donor was newly recruited.\n* `happy_call` → used for existing donors to keep them engaged.\n* `winback` → used for donors to get them resubscribed.","nullable":false},"pledgeCase":{"description":"Related pledge case.\n\nNote: Only included when explicitly requested via the `include` query parameter via the GET calls endpoint.","nullable":true,"allOf":[{"$ref":"#/components/schemas/PledgeCaseDto"}]},"person":{"description":"Related person.\n\nNote: Only included when explicitly requested via the `include` query parameter via the GET calls endpoint.","nullable":true,"allOf":[{"$ref":"#/components/schemas/PersonDto"}]},"transactions":{"description":"Related transactions.\n\nNote: Only included when explicitly requested via the `include` query parameter via the GET calls endpoint.","nullable":true,"type":"array","items":{"$ref":"#/components/schemas/TransactionDto"}},"recordingDuration":{"type":"number","description":"The duration of the call recording, in seconds","nullable":true}},"required":["uuid","status","requestedAt","externalMetadata","attempts","attemptsCount","result","lastUpdatedAt","cancelledAt","completedAt","expiredAt","notes","personUuid","relatedCaseUuid","callingOrganizationUuid","type","pledgeCase","person","transactions","recordingDuration"]},"CallExternalMetadataDto":{"type":"object","properties":{"applicationName":{"type":"string","description":"The name of the application that created the call","nullable":false},"referenceId":{"type":"string","description":"The reference id of the call in the external system","nullable":false},"agentReferenceId":{"type":"string","description":"The reference id of the agent in the external system","nullable":true},"statusCode":{"type":"string","description":"The status code of the call in the external system","nullable":true},"statusDescription":{"type":"string","description":"The status description of the call in the external system","nullable":true},"additionalProperties":{"type":"object","description":"Additional properties provided by/about the external system.","nullable":true}},"required":["applicationName","referenceId","agentReferenceId","statusCode","statusDescription","additionalProperties"]},"CallAttemptDto":{"type":"object","properties":{"userUuid":{"type":"string","format":"uuid","description":"UUID (v4) of the user that attempted a call.","nullable":true},"attemptAt":{"type":"string","format":"date-time","description":"Timestamp when a call was attempted, formatted as ISO8601 date string.","nullable":true},"createdAt":{"type":"string","format":"date-time","description":"Timestamp when the call attempt was created, formatted as ISO8601 date string.","nullable":true}},"required":["userUuid","attemptAt","createdAt"]},"CallResultDto":{"type":"object","properties":{"resultCode":{"type":"string","enum":["confirmed","downgraded","converted","dropped","other"],"description":"\nThe current status of the call result:\n* `confirmed` → a call has been made and pledge agreements are confirmed and data may be updated before confirming.\n* `downgraded` → a call has been made and the pledge amount has been downgraded to a lower value.\n* `converted` → a call has been made and the pledge was converted. For example: change of donation period.\n* `dropped` → a call has been made and the pledge was dropped. For example due to: a regret, complaint or missing IBAN.\n* `other` → a call has been made. This status is applied when other statuses do not apply.","nullable":false},"completedAt":{"format":"date-time","type":"string","description":"ISO8601 compatible datetime string","nullable":false},"notes":{"type":"string","nullable":true},"duration":{"type":"number","description":"The duration of the call result recording, in seconds. This field is deprecated and will be removed in the future. Use `call.recordingDuration` instead.","nullable":true,"deprecated":true},"donorRetentionRating":{"type":"number","description":"The donor retention rating is available when status of the call is completed. The donor retention rating values can be between 1 and 10.","nullable":true,"enum":[0,1,2,3,4,5,6,7,8,9,10]}},"required":["resultCode","completedAt","notes","duration","donorRetentionRating"]},"PledgeCaseDto":{"type":"object","properties":{"uuid":{"type":"string","format":"uuid","description":"UUID (v4)"},"status":{"type":"string","enum":["lead","active","dropped","cancelled","fulfilled"],"description":"\nThe current status of the pledge:\n* `lead` → lead pledge, to be collected. Initial status.\n* `active` → active pledge, being collected.\n* `dropped` → dropped before it was ever collected or released.\n* `cancelled` → cancelled after it was collected or released.\n* `fulfilled` → ended after reaching its end date."},"startsAt":{"format":"date-time","type":"string","description":"ISO8601 compatible datetime string"},"endsAt":{"format":"date-time","type":"string","nullable":true,"description":"ISO8601 compatible datetime string"},"createdAt":{"format":"date-time","type":"string","description":"ISO8601 compatible datetime string"},"updatedAt":{"format":"date-time","type":"string","description":"ISO8601 compatible datetime string describing when the pledge was last updated"},"releasedAt":{"format":"date-time","type":"string","nullable":true,"description":"ISO8601 compatible datetime string"},"owningOrganizationUuid":{"type":"string","format":"uuid","description":"UUID (v4)","deprecated":true},"owningOrganization":{"description":"Organization recruited for","allOf":[{"$ref":"#/components/schemas/OrganizationDto"}]},"recruitingOrganizationUuid":{"type":"string","format":"uuid","description":"UUID (v4)","deprecated":true},"recruitingOrganization":{"description":"Recruiting organization","allOf":[{"$ref":"#/components/schemas/OrganizationDto"}]},"recruitingLocationLabel":{"type":"string","nullable":true,"description":"The label of the location where the pledge was recruited."},"initialDonationAmount":{"type":"number","description":"The donation amount at the moment the pledge was submitted."},"donationAmount":{"type":"number","description":"The current donation amount"},"initialDonationInterval":{"type":"string","enum":["once","monthly","halfYearly","quarterly","yearly"],"description":"The donation interval at the moment the pledge was submitted."},"donationInterval":{"type":"string","enum":["once","monthly","halfYearly","quarterly","yearly"],"description":"The current donation interval"},"preferredPaymentDay":{"type":"number","description":"The preferred payment day of the month (options: 1 - 28). Default value, when not supplied or user has no preference, is: <code>null</code>"},"person":{"description":"Related person.\n\nNote: 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.","nullable":true,"allOf":[{"$ref":"#/components/schemas/PersonDto"}]},"recruitmentType":{"type":"string","enum":["d2d","street"],"nullable":true},"recruiterUserUuid":{"type":"string","format":"uuid","description":"UUID (v4)","deprecated":true},"recruiterUser":{"description":"User that recruited the pledge","allOf":[{"$ref":"#/components/schemas/RecruiterUserDto"}]},"signatureSignedUrl":{"type":"string","nullable":true,"description":"Temporary URL to signature file, valid for 1 hour"},"transactions":{"description":"Transactions that were created for this pledge case.\n\nNote: Only included when explicitly requested via the `include` query parameter via the GET pledges endpoint.","nullable":true,"type":"array","items":{"$ref":"#/components/schemas/TransactionDto"}},"calls":{"description":"Calls that were created for this pledge case.\n\nNote: Only included when explicitly requested via the `include` query parameter via the GET pledges endpoint.","nullable":true,"type":"array","items":{"$ref":"#/components/schemas/CallDto"}},"focusAreas":{"default":[],"type":"array","items":{"$ref":"#/components/schemas/FocusAreaDto"}},"externalSource":{"nullable":true,"description":"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.","allOf":[{"$ref":"#/components/schemas/ExternalSourceDto"}]},"externalMetadata":{"type":"object","nullable":true,"description":"Additional properties provided by/about the external system."},"campaignCode":{"type":"string","nullable":true,"description":"Campaign code defined by the organization"},"collectionDate":{"format":"date-time","type":"string","nullable":true,"description":"Collection date of the pledge case defined by the organization. ISO8601 compatible datetime string."}},"required":["uuid","status","startsAt","endsAt","createdAt","updatedAt","owningOrganizationUuid","owningOrganization","recruitingOrganizationUuid","recruitingOrganization","recruitingLocationLabel","initialDonationAmount","donationAmount","initialDonationInterval","donationInterval","preferredPaymentDay","person","recruitmentType","recruiterUserUuid","recruiterUser","signatureSignedUrl","transactions","calls","focusAreas","externalSource","externalMetadata","campaignCode","collectionDate"]},"OrganizationDto":{"type":"object","properties":{"uuid":{"type":"string","format":"uuid","description":"UUID (v4)"},"name":{"type":"string","description":"Name of organization"}},"required":["uuid","name"]},"PersonDto":{"type":"object","properties":{"uuid":{"type":"string","format":"uuid","description":"UUID (v4)"},"personUuid":{"type":"string","format":"uuid","description":"UUID (v4). Deprecated: use the 'uuid' property instead.","deprecated":true},"academicTitle":{"type":"string","nullable":true},"initials":{"type":"string","nullable":true},"firstName":{"type":"string","nullable":true},"lastNamePrefix":{"type":"string","nullable":true},"lastName":{"type":"string","nullable":true},"dateOfBirth":{"type":"string","nullable":true,"description":"Local date of birth for user, formatted as YYYY-MM-DD"},"socialSecurityNumber":{"type":"string","nullable":true,"description":"Social security number as string without any separators."},"iban":{"type":"string","nullable":true},"address":{"nullable":true,"allOf":[{"$ref":"#/components/schemas/AddressDto"}]},"phoneNumber":{"type":"string","nullable":true},"mobilePhoneNumber":{"type":"string","nullable":true},"email":{"type":"string","nullable":true},"gender":{"type":"string","enum":["male","female","other"],"nullable":true},"optInEmail":{"type":"boolean","nullable":true},"optInPhone":{"type":"boolean","nullable":true},"optInMail":{"type":"boolean","nullable":true},"optInSms":{"type":"boolean","nullable":true},"language":{"type":"string","nullable":true,"description":"ISO-639-1 language code"},"mandate":{"nullable":true,"allOf":[{"$ref":"#/components/schemas/MandateDto"}]},"createdAt":{"format":"date-time","type":"string","description":"ISO8601 compatible datetime string"},"owningOrganization":{"description":"Organization recruited for","allOf":[{"$ref":"#/components/schemas/OrganizationDto"}]},"qualityResult":{"nullable":true,"description":"The generated quality result of the person. This is only included when requested via the 'include' parameter in the request, if available for the endpoint you're calling. If the value is `null` it means that the quality result is not yet generated.","allOf":[{"$ref":"#/components/schemas/QualityResultDto"}]}},"required":["uuid","personUuid","academicTitle","initials","firstName","lastNamePrefix","lastName","dateOfBirth","iban","address","phoneNumber","mobilePhoneNumber","email","gender","optInEmail","optInPhone","optInMail","optInSms","language","mandate","createdAt","owningOrganization","qualityResult"]},"AddressDto":{"type":"object","properties":{"street":{"type":"string","nullable":true},"houseNumber":{"type":"string","nullable":true},"houseNumberExtension":{"type":"string","nullable":true},"zipCode":{"type":"string","nullable":true},"city":{"type":"string","nullable":true},"country":{"type":"string","nullable":true,"description":"Country code in ISO 3166-1 alpha-2"}}},"MandateDto":{"type":"object","properties":{"createdAt":{"format":"date-time","type":"string","description":"ISO8601 compatible datetime string"}},"required":["createdAt"]},"QualityResultDto":{"type":"object","properties":{"score":{"type":"number","description":"The combined score of the quality gates","nullable":false},"maxScore":{"type":"number","description":"The combined max score that could be reached with the applied the quality gates","nullable":false},"percentage":{"type":"number","description":"The percentage of the score compared to the max score","nullable":false},"createdAt":{"format":"date-time","type":"string","description":"ISO8601 compatible datetime string","nullable":false},"gateResults":{"description":"The results from the quality gates that are part of this quality result","nullable":false,"type":"array","items":{"$ref":"#/components/schemas/QualityGateResultDto"}}},"required":["score","maxScore","percentage","createdAt","gateResults"]},"QualityGateResultDto":{"type":"object","properties":{"identifier":{"type":"string","description":"The identifier of the quality gate","nullable":false,"enum":["addressIsAvailable","addressIsComplete","addressIsValid","addressDoesNotMatchRecruiterUsersAddress","ibanDoesNotMatchAnotherPersonsIban","ibanDoesNotMatchRecruiterUsersIban","ibanIsAvailable","ibanIsValid","phoneNumberDoesNotMatchRecruiterUsersPhoneNumber","phoneNumberIsNotASequence","phoneNumberIsAvailable","phoneNumberMatchesPattern","phoneNumberDoesNotMatchAnotherPersonsPhoneNumber","emailIsAvailable","emailMatchesEmailPattern","emailIsDeliverable"]},"category":{"type":"string","description":"The category of the quality gate","nullable":false,"enum":["addressQuality","recruiterFraud","uniqueness","ibanQuality","emailQuality","phoneNumberQuality"]},"score":{"type":"number","description":"The score for this quality gate","nullable":false},"maxScore":{"type":"number","description":"The maximum score that could be reached with this quality gate","nullable":false},"percentage":{"type":"number","description":"The percentage of the score compared to the max score","nullable":false},"explanation":{"type":"string","description":"The explanation of the score","nullable":false,"enum":["ok","ibanMatchesPersonIban","ibanMatchesRecruiterIban","ibanIsMissing","ibanIsInvalid","ibanMayBeInvalid","addressIsMissing","addressIsIncomplete","addressIsInvalid","addressIsNotValidated","addressMatchesRecruiterAddress","phoneNumberIsASequence","mobilePhoneNumberIsASequence","phoneNumberMatchesRecruiterPhoneNumber","phoneNumberMatchesAnotherPersonsPhoneNumber","mobilePhoneNumberMatchesRecruiterPhoneNumber","phoneNumberIsMissing","phoneNumberDoesNotMatchPattern","mobilePhoneNumberDoesNotMatchPattern","emailIsMissing","emailDoesNotMatchEmailPattern","emailNotDeliverable","emailValidationUnknown"]},"metadata":{"type":"object","description":"Additional metadata for this quality gate result","nullable":true}},"required":["identifier","category","score","maxScore","percentage","explanation","metadata"]},"RecruiterUserDto":{"type":"object","properties":{"uuid":{"type":"string","format":"uuid","description":"UUID (v4)"},"identifier":{"type":"string","description":"Recruiter user identifier"},"name":{"type":"string","description":"Recruiter user name. Only returned if you have permission to view it.","nullable":true}},"required":["uuid","identifier","name"]},"TransactionDto":{"type":"object","properties":{"uuid":{"type":"string","format":"uuid","description":"UUID (v4)"},"personUuid":{"type":"string","format":"uuid","description":"UUID (v4)"},"origin":{"description":"This field requires you to connect the transaction to an origin, for example pledge case.","allOf":[{"$ref":"#/components/schemas/TransactionOriginDto"}]},"amount":{"type":"number","description":"Transaction amount. Only supporting Euros at this point."},"name":{"type":"string","description":"Name of the person that made this transaction at the moment in time. Might also be used for the name of the bank account holder.","nullable":true},"iban":{"type":"string","description":"IBAN of the bank account that made this transaction.","nullable":true},"description":{"type":"string","description":"Description of the transaction, usually provided by the payment initiator."},"provider":{"type":"string","enum":["cm","mollie"],"description":"Identifier of the payment provider used for this transaction.","nullable":true},"method":{"type":"string","enum":["idealqr","direct_debit"],"description":"Payment method used for this transaction.","nullable":true},"referenceId":{"type":"string","description":"Reference id provided by the payment initiator.","nullable":true},"transactionId":{"type":"string","description":"Transaction id provided by the payment provider.","nullable":true},"providerMetadata":{"type":"object","description":"Meta data provided by/about the payment provider.","nullable":true},"createdAt":{"format":"date-time","type":"string","description":"Date of transaction creation, formatted as ISO8601 date string."},"updatedAt":{"format":"date-time","type":"string","description":"Date of transaction last update, formatted as ISO8601 date string."},"status":{"type":"string","enum":["open","paid","failed","cancelled","reversed"],"description":"\nThe current status of the transaction:\n* `open` → open transaction, to be paid.\n* `paid` → paid transaction.\n* `failed` → failed transaction before it was paid.\n* `cancelled` → cancelled transaction before it was paid.\n* `reversed` → reversed transaction or chargeback."}},"required":["uuid","personUuid","origin","amount","description","createdAt","updatedAt","status"]},"TransactionOriginDto":{"type":"object","properties":{"name":{"type":"string","enum":["pledgeCase"]},"identifier":{"type":"string","format":"uuid","description":"UUID (v4)"}},"required":["name","identifier"]},"FocusAreaDto":{"type":"object","properties":{"uuid":{"type":"string","format":"uuid","description":"UUID (v4)"},"name":{"type":"string","description":"Name of the focus area"},"externalSource":{"description":"External source of the focus area","nullable":true,"allOf":[{"$ref":"#/components/schemas/ExternalSourceDto"}]}},"required":["uuid","name","externalSource"]},"ExternalSourceDto":{"type":"object","properties":{"name":{"type":"string","description":"Name of the external source"},"identifier":{"type":"string","description":"Identifier of this entity in the external source"}},"required":["name","identifier"]}}},"paths":{"/api/v1/calls/{uuid}/actions/expire":{"put":{"operationId":"ExpireCallRestController_expireCall","summary":"Expires a call at a given date","description":"\nThis 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. \n\nThe person who is allowed to add an expiry date is limited by your service account.\n\nWhether your service account is allowed to expire a call, is dependent on your service account's access scope.\n","parameters":[{"name":"uuid","required":true,"in":"path","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExpireCallInput"}}}},"responses":{"200":{"description":"Call expiry date was set","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CallDto"}}}},"400":{"description":"Bad request. Response body shows what the problem is."},"401":{"description":"Service account not properly authenticated"},"403":{"description":"Service account forbids executing this action"},"404":{"description":"Call is not found"}},"tags":["calls"]}}}}
```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://developer.tapraise.com/api/api-reference/calls.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.