Contents x
    Get persons filtered and paged
    • 18 Sep 2024
    • 4 Minutes to read
    • Print
    • Dark
      Light
    Contents

    Get persons filtered and paged

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

    Get
    /api/v1/relations/persons/filter

    Get a paged list of existing persons, optionally filtered to the given parameters. A param-based alternative to the '/filter' POST endpoint.

    Description

    Retrieve a paged list of existing persons, optionally filtered to the given parameters. The Bloxs relations-api offers 2 options to get persons filtered and paged. One is through the POST option, and as an alternative there is a GET operation available. The functional difference is that the POST option offers the ability to sort the results. Furthermore, the POST includes the parameters in the body whereas the GET includes them in the url.

    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

    The Bloxs user has an external App connected to Bloxs. Through this operation the user can display a paged list of persons & the related information. This operation can be used if the user wants to display multiple persons rather than just a specific one. If the user wants to display a single person  the preference is to use the GET (persons) operation.   

    Request fields

    The request contains the following fields:

    FieldDescription
    pageSizeThe maximum number of pages to be returned per request. The default number is 100 and the maximum is 1.000. If more results are returned than specified in the PageSize, the remaining pages are dropped based on the reference (number).
    pageNumberThis allows the requesting party to specify which of the pages they want to receive.
    externalIdentifierThe unique identifier within the system of the requesting party. This identifier is not generated by the Bloxs system.
    reference
    		The 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.
    relationTypeNameCategory of the person/organization. Categories are already defined in the system but can be configured by the customer. If you select a value that is not present in the list, the caller will receive a validation error.
    displayName

    DisplayName can be used as another search term for a Person. It can be a combination of the FirstName, Initials, LastName & LastNamePrefix. The below logic applies to the compilation of the DisplayName:


    Only LastName

    Example: Sanden


    FirstName + LastName

    {LastName}, {FirstName}

    Example: Sanden, John


    FirstName + LastNamePrefix + LastName

    {LastName}, {FirstName} {LastNamePrefix}

    Example: Sanden, John van


    Initials + LastName

    {LastName}, {Initials}

    Vb: Sanden, J


    Initials + LastNamePrefix + LastName

    {LastName}, {Initials} {LastNamePrefix}

    Vb: Sanden, J van


    FirstName + Intials + LastName

    {LastName}, {FirstName}

    Vb: Sanden, John


    FirstName + Intials + LastNamePrefix + LastName

    {LastName}, {FirstName} {LastNamePrefix}

    Vb: Sanden, John van


    isActive

    Boolean. A person can be archived. If the person is archived, then the status is inactive.

    True: Active

    False: Inactive

    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
    phoneNumberPhone number of the relation.
    mobileNumberMobile number of the relation.
    addressStreetThe street of the relation.
    addressPostalCode
    		The postal code of the relation.
    addressCityThe place of residence of the relation.
    emailEmail address used by the relation.
    lastModifiedTimestamp of the last modification within Bloxs (determined by Bloxs).

    Response fields

    In addition to the fields in the request, the response also contains the fields in the table below.

    FieldDescription
    columnNameThe data field based on which sorting is applied. For example, if the results are sorted based on ascending name, columnName will contain the value 'name'.
    orderBased on this value, the property defined in 'columnName' is either sorted ascending (a-z) or descending (z-a).
    Security
    HTTP
    Type Bearer

    Please enter a valid token

    Query parameters
    pageSize
    integer (int32)

    The requested page size. Defaults to 100 when not given.

    Minimum1
    Maximum1000
    pageNumber
    integer (int32)

    The requested page number. Defaults to 1 when not given.

    Minimum1
    Maximum9999
    externalIdentifier
    string

    Optional filter on the external API identifier of the person.

    reference
    string

    Optional filter on the reference of the person.

    relationTypeName
    string

    Optional filter on the relation type name of the person.

    displayName
    string

    Optional filter on the display name of the person.

    isActive
    boolean

    Optional filter on the active state of the person.

    dateOfBirth
    string (date-time)

    Optional filter on the date of birth of the person.

    phoneNumber
    string

    Optional filter on the phone number of the person.

    mobileNumber
    string

    Optional filter on the mobile number of the person.

    addressStreet
    string

    Optional filter on the street of the address of the person.

    addressPostalCode
    string

    Optional filter on the postal code of the address of the person.

    addressCity
    string

    Optional filter on the city of the address of the person.

    email
    string

    Optional filter on the e-mail address of the person.

    lastModified
    string (date-time)

    Optional filter on the last modification date of the person.

    Responses
    200

    Success

    Expand All
    object
    paging
    object (PagingInfo)
    pageSize
    integer (int32) | null
    Minimum1
    Maximum1000
    pageNumber
    integer (int32) | null
    Minimum1
    Maximum9999
    sorting
    object (SortingInfo)
    columnName
    string | null
    order
    integer (int32)

    0 = Ascending

    1 = Descending

    Valid values[ \0\, \1\ ]
    persons
    Array of object (PersonSearchResultFilter) | null
    object
    reference
    string | null
    externalIdentifier
    string | null
    relationTypeName
    string | null
    state
    integer (int32)

    1 = Active

    2 = Inactive

    Valid values[ \1\, \2\ ]
    displayName
    string | null
    dateOfBirth
    string (date-time) | null
    phoneNumber
    string | null
    mobileNumber
    string | null
    addressStreet
    string | null
    addressPostalCode
    string | null
    addressCity
    string | null
    primaryEmailAddresses
    string | null
    lastModified
    string (date-time)
    What's Next