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
  • instanceOwner possible: true, false default: false filter by owner
  • 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
  • instanceOwner possible: true, false default: false filter by owner
  • 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
  • instanceOwner possible: true, false default: false filter by owner
  • 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.