# Persons
## GET /api/v1/persons
> \
> The persons you are able to fetch might be filtered, based upon your service account's organization scope, if applicable. Besides those filters, you can apply additional filters by supplying query parameters to the url.\
> \
> The collection you are paginating is sorted by creation datetime, descending. This means that the first page contains the most recently created persons.
```json
{"openapi":"3.0.0","info":{"title":"TapRaise API","version":"v1"},"security":[{"bearer":[]}],"components":{"securitySchemes":{"bearer":{"scheme":"bearer","bearerFormat":"jwt","type":"http"}},"schemas":{"PersonPaginationConnection":{"type":"object","properties":{"edges":{"type":"array","items":{"$ref":"#/components/schemas/PersonEdgeDto"}},"pageInfo":{"$ref":"#/components/schemas/PageInfo"}},"required":["edges","pageInfo"]},"PersonEdgeDto":{"type":"object","properties":{"node":{"$ref":"#/components/schemas/PersonDto"},"cursor":{"type":"string","description":"Cursor used in 'before' and 'after' pagination connection arguments"}},"required":["node","cursor"]},"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"]},"OrganizationDto":{"type":"object","properties":{"uuid":{"type":"string","format":"uuid","description":"UUID (v4)"},"name":{"type":"string","description":"Name of organization"}},"required":["uuid","name"]},"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"]},"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/persons":{"get":{"operationId":"PersonOverviewRestController_getPersons","summary":"","description":"\nThe persons you are able to fetch might be filtered, based upon your service account's organization scope, if applicable. Besides those filters, you can apply additional filters by supplying query parameters to the url.\n\nThe collection you are paginating is sorted by creation datetime, descending. This means that the first page contains the most recently created persons.\n","parameters":[{"name":"owningOrganizationUuids","required":false,"in":"query","description":"Filter persons by owning organization uuids (version 4). If not supplied, the owning organization scope of the service account, if applicable, will be used.","schema":{"type":"array","items":{"type":"string"}}},{"name":"createdAfter","required":false,"in":"query","description":"ISO8601 compatible datetime string","schema":{"format":"date-time","type":"string"}},{"name":"iban","required":false,"in":"query","description":"Filter persons by IBAN","schema":{"type":"string"}},{"name":"before","required":false,"in":"query","description":"Person 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":"Person 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/PersonPaginationConnection"}}}},"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/PersonPaginationConnection"}}}}},"tags":["persons"]}}}}
```
## Create a person
> \
> This endpoint allows you to create a person, if your service account allows you to. \
> \
> The 'owningOrganizationUuid' and 'recruitingOrganizationUuid' might also be bound to limitations depending on your service account's organization scope and permissions.\
> \
> We advice you to provide your own 'uuid' value, as you can use this as a mechanism to ensure the person is only created once. When accidentally the person is posted twice, the uuid will ensure it is only saved the first time, and a 409 CONFLICT status will be returned when posted a second time with the same uuid. When you don't supply a uuid, the system will generate one for you, which will be returned in the response body.\
> \
> This endpoint will return the person created with the data in your request body.
```json
{"openapi":"3.0.0","info":{"title":"TapRaise API","version":"v1"},"security":[{"bearer":[]}],"components":{"securitySchemes":{"bearer":{"scheme":"bearer","bearerFormat":"jwt","type":"http"}},"schemas":{"CreatePersonInput":{"type":"object","properties":{"uuid":{"type":"string","format":"uuid","description":"UUID (v4). The person's globally unique identifier in the system. If not provided, a new UUID will be generated."},"owningOrganizationUuid":{"type":"string","format":"uuid","description":"UUID (v4) of the organization that owns this person"},"recruitingOrganizationUuid":{"type":"string","format":"uuid","description":"UUID (v4) of the organization that recruited this person"},"academicTitle":{"type":"string"},"name":{"$ref":"#/components/schemas/NameInput"},"dateOfBirth":{"type":"string","description":"Date of birth, formatted as ISO8601 date string"},"socialSecurityNumber":{"type":"string","description":"Social security number as string without any separators."},"gender":{"type":"string","enum":["male","female","other"]},"phoneNumber":{"type":"string","description":"International phone number"},"mobilePhoneNumber":{"type":"string","description":"International phone number"},"email":{"type":"string","description":"valid email address"},"address":{"$ref":"#/components/schemas/AddressInput"},"language":{"type":"string","description":"ISO6391 language code"},"iban":{"type":"string","description":"Valid iBAN"},"optIns":{"$ref":"#/components/schemas/OptInsInput"},"mandate":{"$ref":"#/components/schemas/MandateInput"}},"required":["owningOrganizationUuid","recruitingOrganizationUuid"]},"NameInput":{"type":"object","properties":{"initials":{"type":"string","nullable":true},"firstName":{"type":"string","nullable":true},"lastNamePrefix":{"type":"string","nullable":true},"lastName":{"type":"string","nullable":false}},"required":["initials","firstName","lastNamePrefix","lastName"]},"AddressInput":{"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":"ISO31661 Alpha2 country code"}},"required":["street","houseNumber","houseNumberExtension","zipCode","city","country"]},"OptInsInput":{"type":"object","properties":{"email":{"type":"boolean","nullable":true},"mail":{"type":"boolean","nullable":true},"phone":{"type":"boolean","nullable":true},"sms":{"type":"boolean","nullable":true}},"required":["email","mail","phone","sms"]},"MandateInput":{"type":"object","properties":{"id":{"type":"string","nullable":false,"description":"Globally unique mandate identifier"},"createdAt":{"type":"string","nullable":false,"description":"ISO8601 date string representing the datetime the mandate was created"}},"required":["id","createdAt"]},"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"]},"OrganizationDto":{"type":"object","properties":{"uuid":{"type":"string","format":"uuid","description":"UUID (v4)"},"name":{"type":"string","description":"Name of organization"}},"required":["uuid","name"]},"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"]}}},"paths":{"/api/v1/persons":{"post":{"operationId":"CreatePersonRestController_create","summary":"Create a person","description":"\nThis endpoint allows you to create a person, if your service account allows you to. \n\nThe 'owningOrganizationUuid' and 'recruitingOrganizationUuid' might also be bound to limitations depending on your service account's organization scope and permissions.\n\nWe advice you to provide your own 'uuid' value, as you can use this as a mechanism to ensure the person is only created once. When accidentally the person is posted twice, the uuid will ensure it is only saved the first time, and a 409 CONFLICT status will be returned when posted a second time with the same uuid. When you don't supply a uuid, the system will generate one for you, which will be returned in the response body.\n\nThis endpoint will return the person created with the data in your request body.\n","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreatePersonInput"}}}},"responses":{"201":{"description":"Person was created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PersonDto"}}}},"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":"Person already exists"}},"tags":["persons"]}}}}
```
## GET /api/v1/persons/{uuid}
> Fetches the details of a single person.
```json
{"openapi":"3.0.0","info":{"title":"TapRaise API","version":"v1"},"security":[{"bearer":[]}],"components":{"securitySchemes":{"bearer":{"scheme":"bearer","bearerFormat":"jwt","type":"http"}},"schemas":{"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"]},"OrganizationDto":{"type":"object","properties":{"uuid":{"type":"string","format":"uuid","description":"UUID (v4)"},"name":{"type":"string","description":"Name of organization"}},"required":["uuid","name"]},"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"]}}},"paths":{"/api/v1/persons/{uuid}":{"get":{"operationId":"PersonDetailsRestController_getDetails","summary":"","description":"Fetches the details of a single person.","parameters":[{"name":"uuid","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PersonDto"}}}},"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/PersonDto"}}}}},"tags":["persons"]}}}}
```
## Update a person's data
> \
> This endpoint allows you to update a person. \
> \
> You only have to provide the fields you want to update. Any fields that you set to \`null\`, will be cleared. Any fields that you don't supply will not be updated.\
> \
> Whether you are allowed to execute this request, depends on your service account's permissions and organization scope.\
> \
> This endpoint will return the updated person.
```json
{"openapi":"3.0.0","info":{"title":"TapRaise API","version":"v1"},"security":[{"bearer":[]}],"components":{"securitySchemes":{"bearer":{"scheme":"bearer","bearerFormat":"jwt","type":"http"}},"schemas":{"UpdatePersonInput":{"type":"object","properties":{"academicTitle":{"type":"string","nullable":true},"name":{"nullable":true,"allOf":[{"$ref":"#/components/schemas/NameInput"}]},"dateOfBirth":{"type":"string","description":"Date of birth, formatted as ISO8601 date string","nullable":true},"socialSecurityNumber":{"type":"string","nullable":true,"description":"Social security number as string without any separators."},"gender":{"type":"string","enum":["male","female","other"],"nullable":true},"phoneNumber":{"type":"string","description":"International phone number","nullable":true},"mobilePhoneNumber":{"type":"string","description":"International phone number","nullable":true},"email":{"type":"string","description":"valid email address","nullable":true},"address":{"nullable":true,"allOf":[{"$ref":"#/components/schemas/AddressInput"}]},"language":{"type":"string","description":"ISO6391 language code","nullable":true},"iban":{"type":"string","description":"Valid iBAN","nullable":true},"optIns":{"nullable":false,"allOf":[{"$ref":"#/components/schemas/OptInsInput"}]},"mandate":{"nullable":true,"allOf":[{"$ref":"#/components/schemas/MandateInput"}]}}},"NameInput":{"type":"object","properties":{"initials":{"type":"string","nullable":true},"firstName":{"type":"string","nullable":true},"lastNamePrefix":{"type":"string","nullable":true},"lastName":{"type":"string","nullable":false}},"required":["initials","firstName","lastNamePrefix","lastName"]},"AddressInput":{"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":"ISO31661 Alpha2 country code"}},"required":["street","houseNumber","houseNumberExtension","zipCode","city","country"]},"OptInsInput":{"type":"object","properties":{"email":{"type":"boolean","nullable":true},"mail":{"type":"boolean","nullable":true},"phone":{"type":"boolean","nullable":true},"sms":{"type":"boolean","nullable":true}},"required":["email","mail","phone","sms"]},"MandateInput":{"type":"object","properties":{"id":{"type":"string","nullable":false,"description":"Globally unique mandate identifier"},"createdAt":{"type":"string","nullable":false,"description":"ISO8601 date string representing the datetime the mandate was created"}},"required":["id","createdAt"]},"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"]},"OrganizationDto":{"type":"object","properties":{"uuid":{"type":"string","format":"uuid","description":"UUID (v4)"},"name":{"type":"string","description":"Name of organization"}},"required":["uuid","name"]},"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"]}}},"paths":{"/api/v1/persons/{uuid}/actions/update":{"put":{"operationId":"UpdatePersonRestController_update","summary":"Update a person's data","description":"\nThis endpoint allows you to update a person. \n\nYou only have to provide the fields you want to update. Any fields that you set to `null`, will be cleared. Any fields that you don't supply will not be updated.\n\nWhether you are allowed to execute this request, depends on your service account's permissions and organization scope.\n\nThis endpoint will return the updated person.\n","parameters":[{"name":"uuid","required":true,"in":"path","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdatePersonInput"}}}},"responses":{"200":{"description":"Person was updated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PersonDto"}}}},"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":"Person with this Uuid not found"}},"tags":["persons"]}}}}
```
---
# 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/persons.md?ask=
```
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.