Contents x
    Get a person
    • 18 Sep 2024
    • 6 Minutes to read
    • Print
    • Dark
      Light
    Contents

    Get a person

    • Updated on 18 Sep 2024
    • 6 Minutes to read
    • Print
    • Dark
      Light
    Article summary

    Get
    /api/v1/relations/persons

    Get an existing person. Either reference or externalIdentifier must have a value. If both are given, externalIdentifier will be used first for retrieving the person.

    Description

    Retrieve the information currently known in the Bloxs database about a certain Person. Either reference or externalIdentifier must have a value. Please note that if both identifiers are given, both must match; otherwise, an error message will be generated. It is recommended that the user utilizes only one identifier, with a preference for the reference. 

    A person is a standalone entity and pertains to an enhancement of organisation. This could be a contact person within an organisation. Several users utilize this to enter their own employees into the system.

    Use Case

    Through this operation the user can display a specific person and the relation information. For example the user wants to display all the information of the person to see which data points need to be adjusted.  

    FieldDescription
    referenceThe relationship number within Bloxs. This is unique (per client specific environment) for all relationships (EstateAgents, Organisations, Owners, Persons, Suppliers). The relationship number is generated by the Bloxs system.
    externalIdentifierThe unique identifier within the system of the requesting party. This identifier is not generated by the Bloxs system.

    Response fields

    The response contains the fields in the table below. For the get operation it gives a up-to-date insight in the data that is currently registered in Bloxs.

    FieldDescription
    referenceThe relationship number within Bloxs. This is unique (per client specific environment) for all relationships (EstateAgents, Organisations, Owners, Persons, Suppliers). The relationship number is generated by the Bloxs system .
    externalIdentifierThe unique identifier within the system of the requesting party. This identifier is not generated by the Bloxs system.
    phoneNumberPhone number of the relation.
    mobileNumberMobile phone number of the relation.
    cocNumberChamber of Commerce number.
    cocDescriptionAdditional information about the Chamber of Commerce number. Termed as KVK description in the Bloxs system. Extra information can be entered here regarding the Chamber of Commerce number.
    vatNumberVAT (BTW) number of the relation.
    correspondenceMethod

    The default method of correspondence. This field is an integer with 2 options:

    1 = Email

    2 = Post

    If the correspondenceMethod is set to Email, then the primaryEmailAddresses field is mandatory.

    If the CorrespondenceMethod is set to Post, then the Address field is mandatory.

    remarks
    		General comments. Please note: Avoid including sensitive information here, such as passwords or sensitive personal data.
    languageISOCode
    		ISO language code. Use the 2-letter code from the ISO 639-1 Code list.
    addressThe address of the relation.
    streetThe street of the relation.
    houseNumber
    		The house number of the relation.
    postalCode
    		The postal code of the relation.
    cityThe place of residence of the relation.
    addres.countryISOCode
    		ISO country code. Use the 2-letter code from the ISO 639-1 Code list.
    invoiceAddress
    		The billing address of the relation. In case this field is empty, the data from 'address' will be used. This is mainly relevant for certain templates.
    postalAddressThe postal address of the relation. In case this field is empty, the data from 'address' will be used. This is mainly relevant for certain templates.
    primaryEmailAddressesPrimary email address used by the relation. If other email addresses are left empty, this email address will be used for correspondence.
    invoicesEmailAddressesThe email address used to send invoices.
    paymentRemindersEmailAddressesThe email address used to send reminders regarding payments.
    indexationsEmailAddressesThe email address to which the annual rent increase (indexation) is sent.
    serviceTicketsEmailAddressesThe email address to which all maintenance notifications are sent. This may differ from the general email address. For instance, in the case of a shared office space where all communication is centralized through one central desk instead of being handled separately by individual tenants.
    purchaseOrdersEmailAddressesAll communication specifically related to procurement is conducted through this email address. This is primarily applicable to large parties where procurement processes are managed through separate email accounts.
    portalsEmailAddressesWithin Bloxs, a portal account for customers or tenants can be opened. Through this field, you can provide multiple email addresses that need to be granted access.
    otherEmailAddressesOther email addresses.
    relationTypeNameCategory of the person. The available categories are pre-defined in the system but can be configured by the user. If this data point contains a value that is not present in the available categories,  a validation error will be received. To retrieve the list of available options the following endpoint can be used: GET RelationTypes.
    communicationFormName

    Gender/Salutation. It's a standard list in the system and can be configured by the user in the Bloxs system.

    Male/Female/Unknown are the default values. These are configurable.

    Based on this value, other standard expressions are generated in the correspondence, such as the salutation. To retrieve the list of available options the following endpoint can be used: GET CommunicationForms.

    initialsThe initials of the person. The initials will be displayed in the Bloxs application and therefore in documentation as well, the exact way in which the data was entered through this property. Therefore, it is recommended to enter the initials as capital letters seperated with a '.' For example: The initials of Antonius Gerald Butler would be entered as 'A.G.' Diacritic symbols are accepted by the system in accordance with the UTF-8 standard

    firstName

    		The first name of the person. The first name will be displayed in the Bloxs application and therefore in documentation as well, the exact way in which the data was entered through this property. Therefore, it is recommended to enter the first name starting with a capital. For example: The first name of Gerald Butler would be entered as 'Gerald'. Diacritic symbols are accepted by the system in accordance with the UTF-8 standard.
    lastNameThe surname of the person. The surname will be displayed in the Bloxs application and therefore in documentation as well, the exact way in which the data was entered through this property. Therefore, it is recommended to enter the surname starting with a capital. For example: The surname of Gerald Butler would be entered as 'Butler'. Diacritic symbols are accepted by the system in accordance with the UTF-8 standard.
    lastNamePrefixThe name prefix of the person. The name prefix will be displayed in the Bloxs application and therefore in documentation as well, the exact way in which the data was entered through this property. Therefore, it is recommended to enter the name prefix as it should be shown in the application and communication. For example: The name prefix of Gerald van Butler would be entered as 'van'. Diacritic symbols are accepted by the system in accordance with the UTF-8 standard.
    dateOfBirthThe Date of birth of the person. This data needs to be entered in accordance with the ISO-8601 format. For example, somebody born on 25th of august 1980 should be entered as: 1980-08-25.
    jobTitleThe job title of the person. 
    identificationTypeItemNameType ID. This is a standard list but can be configured by the user. Default values: Passport, Driver's License & Identity Card. The string is validated against the list available in the Bloxs system.
    referenceThe relationship number within Bloxs. This is unique (per client specific environment) for all relationships (EstateAgents, Organizations, Owners, Persons, Suppliers). The relationship number is generated by the Bloxs system.
    Security
    HTTP
    Type Bearer

    Please enter a valid token

    Query parameters
    reference
    string

    The internal identifier of the model (i.e. Reference, Code, Name, depends on model).

    externalIdentifier
    string

    The external API identifier of the model.

    Responses
    200

    Success

    Expand All
    object
    externalIdentifier
    string | null
    Min length0
    Max length100
    phoneNumber
    string | null
    mobileNumber
    string | null
    cocNumber
    string | null
    Min length0
    Max length256
    cocDescription
    string | null
    vatNumber
    string | null
    Min length0
    Max length256
    correspondenceMethod
    integer (int32)

    1 = Email

    2 = Post

    Valid values[ \1\, \2\ ]
    remarks
    string | null
    languageISOCode
    string | null
    Min length0
    Max length2
    address
    object (Address)
    street
    string
    Min length0
    Max length200
    houseNumber
    string | null
    Min length0
    Max length40
    postalCode
    string
    Min length0
    Max length20
    city
    string
    Min length0
    Max length200
    countryISOCode
    string
    Min length0
    Max length2
    invoiceAddress
    object (Address)
    street
    string
    Min length0
    Max length200
    houseNumber
    string | null
    Min length0
    Max length40
    postalCode
    string
    Min length0
    Max length20
    city
    string
    Min length0
    Max length200
    countryISOCode
    string
    Min length0
    Max length2
    postalAddress
    object (Address)
    street
    string
    Min length0
    Max length200
    houseNumber
    string | null
    Min length0
    Max length40
    postalCode
    string
    Min length0
    Max length20
    city
    string
    Min length0
    Max length200
    countryISOCode
    string
    Min length0
    Max length2
    primaryEmailAddresses
    Array of string | null
    string
    invoicesEmailAddresses
    Array of string | null
    string
    paymentRemindersEmailAddresses
    Array of string | null
    string
    indexationsEmailAddresses
    Array of string | null
    string
    serviceTicketsEmailAddresses
    Array of string | null
    string
    purchaseOrdersEmailAddresses
    Array of string | null
    string
    portalsEmailAddresses
    Array of string | null
    string
    otherEmailAddresses
    Array of string | null
    string
    relationTypeName
    string
    Min length0
    Max length256
    communicationFormName
    string
    Min length0
    Max length256
    initials
    string | null
    Min length0
    Max length20
    firstName
    string | null
    Min length0
    Max length200
    lastName
    string
    Min length0
    Max length200
    lastNamePrefix
    string | null
    Min length0
    Max length112
    dateOfBirth
    string (date-time) | null
    jobTitle
    string | null
    Min length0
    Max length256
    identificationTypes
    Array of object (IdentificationType) | null
    object
    identificationTypeItemName
    string
    Min length0
    Max length256
    identificationNumber
    string
    Min length0
    Max length100
    reference
    string | null
    Min length0
    Max length100
    404

    The requested person was not found.

    What's Next