REST - Person

REST-Interface

Get person by accountid

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

Path parameter

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

Query parameter

parameter mandatory possible values default description
loadClients no true, false false load clients
loadAddresses no true, false false load addresses
loadCommunicationData no true, false false load com data
loadRoles no true, false false load roles
loadContactImages no true, false false load contact images
loadBioDocumentLanguageKey no true, false false load bio document

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

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

Query parameter

parameter mandatory possible values default description
loadClients no true, false false load clients
loadAddresses no true, false false load addresses
loadCommunicationData no true, false false load com data
loadRoles no true, false false load roles
loadContactImages no true, false false load contact images
loadBioDocumentLanguageKey no true, false false load bio document

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
  • followedDocumentId document, that persons follow
  • followedLanguageId language, that persons follow does only work together with “followedcategoryid” 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
  • followedDocumentId document, that persons follow
  • followedLanguageId language, that persons follow does only work together with “followedcategoryid” 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
  • followedDocumentId document, that persons follow
  • followedLanguageId language, that persons follow does only work together with “followedcategoryid” 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

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

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

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

×
Peter's Problem.