REST - Person

REST-Interface

Zurück zur Übersicht

Get person by accountid

URL
GET <application-url>/api/person/byaccount/<accountId>

Path parameter

  • contactId

Query parameter

  • loadClients
    possible: true, false
    default: false
  • loadAddresses
    possible: true, false
    default: false
  • loadCommunicationData
    possible: true, false
    default: false
  • loadRoles
    possible: true, false
    default: false
  • loadContactImages
    possible: true, false
    default: false
  • loadBioDocumentLanguageKey
    possible: de, en, fr, it, ...
    default: null (do not load biodocument)
    Try to load the related bio document by language-key.

Produces

application/json
application/xml

com.matterial.mtr.api.object.Person

  • 200 OK
  • 400 BAD_REQUEST
  • 404 NOT_FOUND
  • 500 INTERNAL_SERVER_ERROR

Permission
Login

Sample
GET http://localhost:8080/mtr-backend/api/person/byaccount/2


Get person by contactid

URL
GET <application-url>/api/person/bycontact/<contactId>

Path parameter

  • contactId

Query parameter

  • loadClients
    possible: true, false
    default: false
  • loadAddresses
    possible: true, false
    default: false
  • loadCommunicationData
    possible: true, false
    default: false
  • loadRoles
    possible: true, false
    default: false
  • loadContactImages
    possible: true, false
    default: false
  • loadBioDocumentLanguageKey
    possible: de, en, fr, it, ...
    default: null (do not load biodocument)
    Try to load the related bio document by language-key.

Produces

application/json
application/xml

com.matterial.mtr.api.object.Person

  • 200 OK
  • 400 BAD_REQUEST
  • 404 NOT_FOUND
  • 500 INTERNAL_SERVER_ERROR

Permission
Login

Sample
GET http://localhost:8080/mtr-backend/api/person/bycontact/2


Get persons

URL
GET <application-url>/api/person

Query parameter

  • accountId
  • contactId
  • includeSystemUser
    possible: true, false
    default: false
    default is exclude system-user
  • roleId
  • accountLogin
  • instanceOwnerOnly
    possible: true, false
    default: false
    only load instanceOwners, if true
  • hideInstanceOwner
    possible: true, false
    default: false
    hide instanceOwners, if true
  • activeOnly
    possible: true, false
    default: false
    only load active persons, if true
  • hideActive
    possible: true, false
    default: false
    only load inactive persons, if true
  • followedCategoryId
    category, that person follow
  • followedAdditionalPropertyId
    additional property, that person follow
  • followedDocumentId
    document, that persons follow
  • followedLanguageId
    language, that persons follow
    does only work together with “followedCategoryId”, “followedAdditionalPropertyId”, or “followedDocumentId”
  • markedAsHelpfulDocumentId
    document, that person marked as helpful
  • markedAsHelpfulDocumentLanguageVersionId
    document-language-version, that person marked as helpful
  • markedAsHelpfulLanguageId
    language, that person marked as helpful (works only with ‘markedAsHelpfulDocumentId’)
  • responsibleForDocumentId
    load responsibles for this document-id
  • authorshipForDocumentId
    load “authors” (write-relation) for this document-id
  • authorshipForLanguageVersionId
    load “authors” (write-relation) for this document-language-version-id
  • authorshipForLanguageId
    load “authors” (write-relation) for this language-id
  • loadClients
    possible: true, false
    default: false
    load clients
  • loadAddresses
    possible: true, false
    default: false
    load addresses
  • loadCommunicationData
    possible: true, false
    default: false
    load com data
  • loadBioDocumentLanguageKey
    possible: true, false
    default: false
    load bio document
  • loadRoles
    possible: true, false
    default: false
    load roles
  • loadContactImages
    possible: true, false
    default: false
    load contact images
  • count
    possible: true, false
    default: false
    additionally loading count of persons
  • orderBy
    possible:
    id - account id
    login - account login
    createTime - account create time
    lastLogin - account last login
    lastName - contact lastname
    firstName - contact firstname
    lastWrite - used to get last author(s) of an document,
    does only work with one of these filter set:
    authorshipForDocumentId
    authorshipForLanguageVersionId
    authorshipForLanguageId
    default: lastName
    the order by
  • orderDir
    possible: asc, desc
    default: asc
    the ordering direction
  • offset
  • limit

Produces

application/json
application/xml

com.matterial.mtr.api.object.ListResult<Person>

  • 200 OK
  • 500 INTERNAL_SERVER_ERROR

Permission
Login

Sample
GET http://localhost:8080/mtr-backend/api/person


Get CSV

Get csv-export of filtered persons. This will be UTF-8 encoded.
URL
GET <application-url>/api/person/csv

Query parameter

  • accountId
  • contactId
  • includeSystemUser
    possible: true, false
    default: false
    default is exclude system-user
  • roleId
  • accountLogin
  • instanceOwnerOnly
    possible: true, false
    default: false
    only load instanceOwners, if true
  • hideInstanceOwner
    possible: true, false
    default: false
    hide instanceOwners, if true
  • activeOnly
    possible: true, false
    default: false
    only load active persons, if true
  • hideActive
    possible: true, false
    default: false
    only load inactive persons, if true
  • followedCategoryId
    category, that person follow
  • followedAdditionalPropertyId
    additional property, that person follow
  • followedDocumentId
    document, that persons follow
  • followedLanguageId
    language, that persons follow
    does only work together with “followedCategoryId”, “followedAdditionalPropertyId”, or “followedDocumentId”
  • markedAsHelpfulDocumentId
    document, that person marked as helpful
  • markedAsHelpfulDocumentLanguageVersionId
    document-language-version, that person marked as helpful
  • markedAsHelpfulLanguageId
    language, that person marked as helpful (works only with ‘markedAsHelpfulDocumentId’)
  • responsibleForDocumentId
    load responsibles for this document-id
  • authorshipForDocumentId
    load “authors” (write-relation) for this document-id
  • authorshipForLanguageVersionId
    load “authors” (write-relation) for this document-language-version-id
  • authorshipForLanguageId
    load “authors” (write-relation) for this language-id
  • orderBy
    possible:
    id - account id
    login - account login
    createTime - account create time
    lastLogin - account last login
    lastName - contact lastname
    firstName - contact firstname
    lastWrite
    • used to get last author(s) of an document,
      does only work with one of these filter set:
      • authorshipForDocumentId
      • authorshipForLanguageVersionId
      • authorshipForLanguageId
        default: lastname
        the order by
  • orderDir
    possible: asc, desc
    default: asc
    the ordering direction
  • offset
  • limit

Produces
CSV-file (.csv)

  • 200 OK
  • 204 NO_CONTENT
  • 500 INTERNAL_SERVER_ERROR

Permission
instanceOwnerRequired + ADMINISTRATE_ALL

Sample
GET http://localhost:8080/mtr-backend/api/person/csv


Get VCards

Export of filtered persons as vcards (v4.0).
According to rfc6350 “UTF-8 is now the only possible character set.”
URL
GET <application-url>/api/person/vcard

Query parameter

  • accountId
  • contactId
  • includeSystemUser
    possible: true, false
    default: false
    default is exclude system-user
  • roleId
  • accountLogin
  • instanceOwnerOnly
    possible: true, false
    default: false
    only load instanceOwners, if true
  • hideInstanceOwner
    possible: true, false
    default: false
    hide instanceOwners, if true
  • activeOnly
    possible: true, false
    default: false
    only load active persons, if true
  • hideActive
    possible: true, false
    default: false
    only load inactive persons, if true
  • followedCategoryId
    category, that person follow
  • followedAdditionalPropertyId
    additional property, that person follow
  • followedDocumentId
    document, that persons follow
  • followedLanguageId
    language, that persons follow
    does only work together with “followedCategoryId”, “followedAdditionalPropertyId”, or “followedDocumentId”
  • markedAsHelpfulDocumentId
    document, that person marked as helpful
  • markedAsHelpfulDocumentLanguageVersionId
    document-language-version, that person marked as helpful
  • markedAsHelpfulLanguageId
    language, that person marked as helpful (works only with ‘markedAsHelpfulDocumentId’)
  • responsibleForDocumentId
    load responsibles for this document-id
  • authorshipForDocumentId
    load “authors” (write-relation) for this document-id
  • authorshipForLanguageVersionId
    load “authors” (write-relation) for this document-language-version-id
  • authorshipForLanguageId
    load “authors” (write-relation) for this language-id
  • orderBy
    possible:
    id - account id
    login - account login
    createTime - account create time
    lastLogin - account last login
    lastName - contact lastname
    firstName - contact firstname
    lastWrite
    • used to get last author(s) of an document,
      does only work with one of these filter set:
      • authorshipForDocumentId
      • authorshipForLanguageVersionId
      • authorshipForLanguageId
        default: lastname
        the order by
  • orderDir
    possible: asc, desc
    default: asc
    the ordering direction
  • offset
  • limit

Produces
VCARD-file (.vcf)

  • 200 OK
  • 204 NO_CONTENT
  • 500 INTERNAL_SERVER_ERROR

Permission
instanceOwnerRequired + ADMINISTRATE_ALL

Sample
GET http://localhost:8080/mtr-backend/api/person/vcard


Get VCard by contact

Export of person by contactId as vcard (v4.0).
According to rfc6350 “UTF-8 is now the only possible character set.”
URL
GET <application-url>/api/person/bycontact/<contactId>/vcard

Path parameter

parameter mandatory possible values default description
contactId yes - - contact-id

Produces
VCARD-file (.vcf)

  • 200 OK
  • 204 NO_CONTENT
  • 500 INTERNAL_SERVER_ERROR

Permission
Login

Sample
GET http://localhost:8080/mtr-backend/api/person/bycontact/2/vcard


Create person

URL
POST <application-url>/api/person

Query parameter

parameter possible values default description
contextToken context-token for temp-file-upload (ContactImages)

Consumes

application/json
application/xml

com.matterial.mtr.api.object.Person

Produces

application/json
application/xml

com.matterial.mtr.api.object.Person

  • 201 CREATED
  • 400 BAD_REQUEST
  • 304 NOT_MODIFIED
  • 500 INTERNAL_SERVER_ERROR

Permission
EDIT_PERSON

Sample
POST http://localhost:8080/mtr-backend/api/person


Update person

URL
PUT <application-url>/api/person/byaccount/<accountId>

Path parameter

  • accountId

Query parameter

  • contextToken
    context-token for temp-file-upload (ContactImages)
  • ignoreClients
    possible: true, false
    default: false
    If true update ignores clients.
  • ignoreContactImages
    possible: true, false
    default: false
    If true update ignores contact images (also ignores activating a contact image).
  • ignoreAddreses
    possible: true, false
    default: false
    If true update ignores addresses.
  • ignoreCommuncationData
    possible: true, false
    default: false
    If true update ignores communication data.

Consumes

application/json
application/xml

com.matterial.mtr.api.object.Person

Produces

application/json
application/xml

com.matterial.mtr.api.object.Person

  • 201 CREATED
  • 400 BAD_REQUEST
  • 304 NOT_MODIFIED
  • 500 INTERNAL_SERVER_ERROR

Permission
EDIT_PERSON

Sample
PUT http://localhost:8080/mtr-backend/api/person/byaccount/8


Set instance-owner-flag

URL
PUT <application-url>/api/person/byaccount/<accountId>/instanceowner

Path parameter

parameter mandatory possible values default description
accountId yes - - account-id

Produces

text/plain

Integer - updated

  • 200 OK
  • 400 BAD_REQUEST
  • 304 NOT_MODIFIED
  • 500 INTERNAL_SERVER_ERROR

Permission
instanceOwnerRequired, EDIT_PERSON

Sample
PUT http://localhost:8080/mtr-backend/api/person/byaccount/8/instanceowner


Unset instance-owner-flag

URL
DELETE <application-url>/api/person/byaccount/<accountId>/instanceowner

Path parameter

parameter mandatory possible values default description
accountId yes - - account-id

Produces

text/plain

Integer - updated

  • 200 OK
  • 400 BAD_REQUEST
  • 304 NOT_MODIFIED
  • 500 INTERNAL_SERVER_ERROR

Permission
instanceOwnerRequired, EDIT_PERSON

Sample
DELETE http://localhost:8080/mtr-backend/api/person/byaccount/8/instanceowner


Set demo-flag

URL
PUT <application-url>/api/person/byaccount/<accountId>/demo

Path parameter

parameter mandatory possible values default description
accountId yes - - account-id

Produces

text/plain

Integer - updated

  • 200 OK
  • 400 BAD_REQUEST
  • 304 NOT_MODIFIED
  • 500 INTERNAL_SERVER_ERROR

Permission
instanceOwnerRequired, EDIT_PERSON

Sample
PUT http://localhost:8080/mtr-backend/api/person/byaccount/8/demo


Unset demo-flag

URL
DELETE <application-url>/api/person/byaccount/<accountId>/demo

Path parameter

parameter mandatory possible values default description
accountId yes - - account-id

Produces

text/plain

Integer - updated

  • 200 OK
  • 400 BAD_REQUEST
  • 304 NOT_MODIFIED
  • 500 INTERNAL_SERVER_ERROR

Permission
instanceOwnerRequired, EDIT_PERSON

Sample
DELETE http://localhost:8080/mtr-backend/api/person/byaccount/8/demo


Update personal-data

Updates data of a person for current logged-in account. Personal-data includes Addresses, CommunicationData, and ContactImages.
URL
PUT <application-url>/api/person/personaldata

Query parameter

  • contextToken
    context-token for temp-file-upload (ContactImages + bio-document)
  • languageKey
    possible: de, en, fr, it, ...
    default: the default content language
    The languageKey to use for the bio-document
  • ignoreClients
    possible: true, false
    default: false
    If true update ignores clients.
  • ignoreContactImages
    possible: true, false
    default: false
    If true update ignores contact images (also ignores activating a contact image).
  • ignoreAddreses
    possible: true, false
    default: false
    If true update ignores addresses.
  • ignoreCommuncationData
    possible: true, false
    default: false
    If true update ignores communication data.

Consumes

application/json
application/xml

com.matterial.mtr.api.object.Person

Produces

application/json
application/xml

com.matterial.mtr.api.object.LoginData

  • 200 OK
  • 400 BAD_REQUEST
  • 304 NOT_MODIFIED
  • 500 INTERNAL_SERVER_ERROR

Permission
Login

Sample
PUT http://localhost:8080/mtr-backend/api/person/personaldata


Remove person

Remove a person (account) from current client.
Special behaviour for multipleInstanceInstallation:
Additionally only instance-admins are allowed to remove persons!
This removes a person (account) also from current client (because there should only be one per instance) and removes the person (credential) from current instance.
URL
DELETE <application-url>/api/person/byaccount/<accountId>

Path parameter

parameter mandatory possible values default description
accountId yes - - account-id

Produces

text/plain

Integer - count of removed

  • 200 OK
  • 400 BAD_REQUEST
  • 304 NOT_MODIFIED
  • 500 INTERNAL_SERVER_ERROR

Permission
EDIT_PERSON + instanceOwnerRequired (on multipleInstanceInstallation)

Sample
DELETE http://localhost:8080/mtr-backend/api/person/byaccount/8


Reconvert contact-images of a person

Reconverts the contact-images of a person. This regenerates all thumbnails even if they already exists.
URL
PUT <application-url>/api/person/bycontact/<contactId>/convert

Path parameter

parameter mandatory possible values default description
contactId yes - - contact-id

Produces

text/plain

Integer - count of contacts

  • 200 OK
  • 500 INTERNAL_SERVER_ERROR

Permission
EDIT_PERSON

Sample
PUT http://localhost:8080/mtr-backend/api/person/bycontact/2/convert


Convert contact-images of all persons

(Re)converts the contact-images of all persons. If “regenerate=true” this regenerates all thumbnails even if they already exists.

URL
PUT <application-url>/api/person/convert

Query parameter

parameter possible values default description
regenerate true, false false if true, this regenerates all thumbnails even if they already exists

Produces

text/plain

Integer - count of contacts

  • 200 OK
  • 500 INTERNAL_SERVER_ERROR

Permission
ADMINISTRATE_ALL

Sample
PUT http://localhost:8080/mtr-backend/api/person/convert


Get contact-image by contact-id and contact-image-id

URL
GET <application-url>/api/person/bycontact/<contactId>/contactimage/<contactImageId>

Path parameter

parameter possible values default description
contactId - - contact-id
contactImageId - - contact-image-id

Query parameter

parameter possible values default description
loadPdf true, false false get pdf
loadThumbnail true, false false get thumbnail

Produces
ContactImage as stream

  • 200 OK
  • 204 NO CONTENT
  • 404 NOT_FOUND
  • 500 INTERNAL_SERVER_ERROR

Permission
Login

Sample
GET http://localhost:8080/mtr-backend/api/person/bycontact/2/contactimage/3

×