REST - Person
REST-Interface
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 -
demoOnly
possible: true, false
default: false
only load demo users, if true -
hideDemo
possible: true, false
default: false
hide demo users, if true -
limitedOnly
possible: true, false
default: false
only load limited users, if true -
hideLimited
possible: true, false
default: false
hide limited users, 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
- used to get last author(s) of an document,
-
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
- used to get last author(s) of an document,
-
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
- accountId
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
- accountId
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
Set limited-flag
Downgrading an account as limited. Such accounts have limited permissions. Related roles have no effect. Limited accounts currently only get the permission comment.
URL
PUT <application-url>/api/person/byaccount/<accountId>/limited
Path parameter
- accountId
Produces
text/plain
Integer - updated
- 200 OK
- 400 BAD_REQUEST
- 402 PAYMENT REQUIRED
- 304 NOT_MODIFIED
- 500 INTERNAL_SERVER_ERROR
Permission
instanceOwnerRequired, EDIT_PERSON
Sample
PUT http://localhost:8080/mtr-backend/api/person/byaccount/8/limited
Unset limited-flag
Upgrading an account as unlimited. Such accounts have permissions according to their related roles.
URL
DELETE <application-url>/api/person/byaccount/<accountId>/limited
Path parameter
- accountId
Produces
text/plain
Integer - updated
- 200 OK
- 400 BAD_REQUEST
- 402 PAYMENT REQUIRED
- 304 NOT_MODIFIED
- 500 INTERNAL_SERVER_ERROR
Permission
instanceOwnerRequired, EDIT_PERSON
Sample
DELETE http://localhost:8080/mtr-backend/api/person/byaccount/8/limited
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
