Account information¶

General information¶

Unless otherwise noted all requestst should be Authenticated with an Authorization: Bearer $access_token header. See OAuth 2 and Scopes

Note

Where it is considered useful APIs include properties outlined in the HAL specification these are not explicitly documented here

Get information about user¶

Get general information about the user

GET $base_url/api/v1/account/user

==>

{
    "_links": {
        "curies": [
            {
                "href": "https://localhost/todo/doc/{rel}",
                "name": "pl",
                "templated": true
            }
        ],
        "pl:account_organization": "/api/v1/account/organization",
        "self": {
            "href": "/api/v1/account/user"
        }
    },
    "uuid": "a8053b98-8edc-4280-9f66-2429a2792c16",
    "email": "user@example.com",
    "email_verified": true,
    "email_undeliverable": false,
    "login": "first_last",
    "title": "mr",
    "first_name": "First",
    "last_name": "Last",
    "language_code": "de",
    "phone": "+49 30 123456",
    "creation_date": "2007-01-31T14:22:26+00:00",
    "last_login": "2017-02-14T15:23:02+00:00",
    "time_zone": "Europe/Berlin",
    "time_zone_utc_offset": 3600

}

Parameters¶

The following query parameters may be supplied

embed:

Comma separated list of objects to embed. Currently the following values are allowed

account_organization:: Include organization data (see Get information about organization)
account_reseller:: Include information about reseller (see Get information about reseller)
account_reseller_contact:: Include contact information of reseller (see Get reseller contact data)

Response:¶

uuid:

A persistent unique id for the user

email:

Email address of the user

email_verified:

Flag indicating wether the email address was verified (This is done as part of the registration process, so it will almost always be true)

email_undeliverable:

It was determined that this email is no longer reachable. This flag can be used to avoid sending email that would most likely bounce anyway or to indicate to the user that he should check that the address in his profile is still correct.

login:

Optional. A login name for the user. Most applications should ignore this value, it only exists for compatibility with accounts created in the past.

title:

Specifies how the user should be addressed. Defined values are

mr
mrs
not_set

first_name:

First name of the user

last_name:

Last name of the user

language_code:

Preferred language of the user as ISO-639-1 language code

phone:

Phone number of the user

creation_date:

Date where the user account was created (ISO-8601 combined date & time format)

last_login:

Date of the last login (ISO-8601 combined date & time format)

time_zone:

Time zone recently used by the user. Falls back to UTC, if no specific time zone was set for the user. Will be provided as a string, as specified in the IANA database (https://www.iana.org/time-zones)

time_zone_utc_offset:

Offset from the time zone provided in the “time_zone” field to UTC in seconds, at the time of the request.

Change account data¶

PUT $base_url/api/v1/account/user
Content-type: application/json

{
  "title": "mr",
  "first_name": "new first name",
  "last_name": "new last name",
  "language_code": "en",
  "phone": "+49 30 123456",
}

==>

{}

Parameters:¶

All parameters have to be provided as JSON document in the request body. The Content-type: header of the request must be set to application/json

title:

Specifies how the user should be addressed. Defined values are

mr
mrs
not_set

first_name:

First name of the user

last_name:

Last name of the user

language_code:

Preferred language of the user as ISO-639-1 language code

phone:

Phone number of the user

Response¶

On success the server responds with HTTP status code 200. The returned body is a (currently empty) JSON document.

Get information about organization¶

Get general information about the users organization

GET $base_url/api/v1/account/organization

==>

{
    "_links": {
        "self": {
            "href": "/api/v1/account/organization"
        }
    },
    "address": "123 Test Rd.",
    "city": "Test city",
    "consolidated_name": "Test LLC",
    "country_code": "DEU",
    "country_code_iso2": "DE",
    "name": "Test LLC",
    "organization_number": 16331,
    "type": "commercial",
    "professions": ["manufacturer", "other"],
    "uuid": "635bf630-99c3-4f9f-8985-f114a7c708e7",
    "zip_code": "",
    "pcon_community": "yes",
    "logo_url": "https://login.pcon-soloutions.com/core/static/rt/organization_logos/ebzoppwlggdv7j4oww4ko4jtey.png"
}

Response:¶

uuid:

A persistent unique id of the organization

organization_number:

This number uniquely identifies the organization within pCon.login and should be used when referring to the organization in communication (it is known to both users and staff, as opposed to the uuid which is more suited for technical purposes due to properties inherent to uuids).

type:

Type of the organization. Currently the following values are defined:

not_set:: Organization type was not specified
commercial:: A commercial organization
private:: Organization represents a private individual
educational:: Organization represents an educational institution
other:: Other organization type

name:

Name of the organization (explicitly set).

consolidated_name:

Depending on the type of the organization it may not have an explicit name, in these instances this property contains a suitable replacement.

country_code:

ISO-3166-1 alpha-3 code of the country where the organization is situated.

country_code_iso2:

ISO-3166-1 alpha-2 code of the country where the organization is situated.

zip_code:

ZIP code of city where the organization is situated.

city:

Name of city where the organization is situated.

address:

Street address where organization is situated.

professions:

List of profession identifiers that categorize the areas where the organization is active. Currently defined values are

manufacturer
designer
distributor
agent
architect
other

This may be expanded in the future, therefore clients should expect unknown values here

pcon_community:

Specifies wether the organization has been validated as a “pCon community” account defined values are

yes
no
requested (organization has requested to be verified, but verification is still in progress)
declined (organization has requested to be verified, but access to pcon community was not granted)

logo_url:

URL of the organization logo.

Note

These logos will be present in different formats and sizes. Currently we accept images in the formats gif, jpeg, png and svg with dimensions up to 400x400.

Whenever the organization changes its logo it will be saved via a new random name. Therefore there should be no issues with browsers caching the logo, but clients must make sure to not use a stale url since the old logo may no longer exists.

Change Organization data¶

PUT $base_url/api/v1/account/organization
Content-type: application/json

{
    "address": "123 Test Rd.",
    "city": "Test city",
    "country_code_iso2": "DE",
    "name": "Test LLC",
    "professions": ["manufacturer", "other"],
    "zip_code": "123457"
}

==>

{}

Parameters:¶

name:

Name of the organization

country_code:

ISO-3166-1 alpha-3 code of the country where the organization is situated.

country_code_iso2:

ISO-3166-1 alpha-2 code of the country where the organization is situated.

zip_code:

ZIP code of city where the organization is situated.

city:

name of city where the organization is situated.

address:

Street address where organization is situated.

professions:

Categorizes the areas where the organization is active. Currently defined values are

manufacturer
designer
distributor
agent
architect
other

Note

Only parameters that are to be changed should be passed. All unspecified parameters will keep their current value. To change the country the organization is situated in, only one of country_code or country_code_iso2 needs to specified.

Response¶

On success the server responds with HTTP status code 200. The returned body is a (currently empty) JSON document.

Get information about reseller¶

Query the reseller responsible for the user (or rather his organization)

GET $base_url/api/v1/account/reseller

==>

{
    "_links": {
        "self": {
            "href": "/api/v1/account/reseller"
        }
    },
    "name": "EasternGraphics GmbH",
    "short_name": "EGR-DE"
}

Parameters¶

The following query parameters may be supplied

embed:

Comma separated list of objects to embed. Currently the following values are allowed

account_reseller_contact:: Include contact information of reseller (see Get reseller contact data)

Response:¶

short_name:: A shorthand name that uniquely identifies the reseller
name:: Name of the reseller

Get reseller contact data¶

Query contact information of the reseller responsible for the organization

GET $base_url/api/v1/account/reseller/contact

==>

{
    "_links": {
        "self": {
            "href": "/api/v1/account/reseller/contact"
        }
    },
    "address": "Albert-Einstein-Stra\u00dfe 1",
    "city": "Ilmenau",
    "country_code": "DEU",
    "country_code_iso2": "DE",
    "email": "info@easterngraphics.com",
    "logo_url": "https://localhost:5000/core/static/images/resellers/egr-de.png",
    "name": "EasternGraphics GmbH",
    "phone": "+49 3677 67820",
    "website": "https://www.easterngraphics.com",
    "zip_code": "98693"
}

Response:¶

name:: Name of the reseller
address:: Street address where the reseller is situated
zip_code:: Zip code of the city where the reseller is situated
city:: Name of the city where the reseller is situated
country_code:: ISO-3166-1 alpha-3 code of the country where the reseller is situated
country_code_iso2:: ISO-3166-1 alpha-3 code of the country where the reseller is situated
email:: Contact email of the reseller
phone:: Phone number to contact the reseller
website:: URL of the resellers website
logo_url:: URL of the resellers logo.

Note

These logos will be present in different formats and sizes. Currently we accept images in the formats gif, jpeg, png and svg with dimensions up to 400x400.

Currently this logo always uses the same name for a given reseller, therefore some users may still see an older logo from there browsers cache. This behaviour is an implementation detail that should not be relied upon.

Query existing resellers¶

Query all currently defined resellers of pCon.login

GET /api/v1/resellers

==>

{
    "resellers": [
        {
            "short_name": "EGR-BX",
            "name": "EasternGraphics Benelux B.V."
        },
        {
            "short_name": "EGR-DE",
            "name": "EasternGraphics GmbH"
        }
    ],
    "_links": {
        "self": {
            "href": "/api/v1/resellers"
        }
    }
}

Response¶

resellers:

List of currently defined resellers, each with the following properties

short_name:: A shorthand name that uniquely identifies the reseller
name:: Name of the reseller

Get groups of an organization¶

Query all groups present in an organization.

Note

Not all user will have the required permission to enumerate all groups in their organization and this API will fail with HTTP status 403 for them.

GET $base_url/api/v1/account/organization/groups?lang=en

==>

{
    "groups" : [
        {
            "uuid" : "56ad96fd-cfab-4a3c-921b-bf3e0b34ec96",
            "name" : "Administrators",
            "tag" : "admin"
        },
        {
            "uuid" : "30a7fb03-ebf6-47d2-9703-20427f51f720",
            "name" : "Standard Users",
            "tag" : "standard"
        },
        {
            "uuid" : "b71b4abb-12cc-475c-a526-0f8b84def2b9",
            "name" : "Globale Lizenzadministratoren",
            "tag" : null
        },
    ],
    "_links" : {
        "self" : {
            "href" : "/api/v1/account/organization/groups"
        }
    }
}

Parameters¶

The following query parameters may be supplied

lang:: Optional. Language as ISO-639-1 code. Texts will be in this language if translations are available

Response¶

groups:

List of groups in the organization, each with these properties

uuid:

Unique identifier of the group

name:

The (display) name of the group

tag:

Some groups are automatically created by the system. If this property is not null it identifies such a special group and its intended purpose. Currently the following tags are defined:

all:: This group automatically contains all users of the organization
standard:: Predefined group for regular users of the organization
admin:: Predefined group for adminstrators of the organization

color_index:

A simple number starting from 0 that can be used to visually distinguish groups (in pCon.login it references a background color, hence the name, but applications are free to choose different visual represenations as appropriate for their ui)

Get groups assigned to the user¶

Get all groups of which the user is a member

GET $base_url/api/v1/account/user/groups?lang=en

==>

{
    "groups" : [
        {
            "uuid" : "30a7fb03-ebf6-47d2-9703-20427f51f720",
            "name" : "Standard Users",
            "tag" : "standard"
        },
        {
            "uuid" : "b71b4abb-12cc-475c-a526-0f8b84def2b9",
            "name" : "Globale Lizenzadministratoren",
            "tag" : null
        },
    ],
    "_links" : {
        "self" : {
            "href" : "/api/v1/account/user/groups"
        }
    }
}

Parameters¶

The following query parameters may be supplied

lang:: Optional. Language as ISO-639-1 code. Texts will be in this language if translations are available

Response¶

groups:

List of groups in the organization, each with these properties

uuid:: Unique identifier of the group
name:: The (display) name of the group
tag:: Identifies special system groups, see defined tag values
color_index:: A simple number starting from 0 that can be used to visually distinguish groups (in pCon.login it references a background color, hence the name, but applications are free to choose different visual represenations as appropriate for their ui)

Mark group as in use (deprecated)¶

This function is deprecated and should no longer be used. Use Register stored data referencing pCon.login object instead.

Mark a group as in use. If a user tries to delete a group that is still in use a warning will be issued.

Note

Users can decide to delete the group despite the warning, applications must therefore be prepared to handle disappearing groups!

POST $base_url/api/v1/account/mark_group_in_use
Content-type: application/json

{
    "group_uuid": "5c24d6f9-9ab4-43ca-8c31-f32b75d14bfd",
    "client_reference": "planning:815",
    "use": {
        "en": "Planning \"Ground floor, room 107\"",
        "de": "Planung \"Ground floor, room 107\"",
    }
}

==>

{
    "result": "ok"
}

Parameters¶

group_uuid:: The group that should be marked as in use. The group must belong to the user’s organization.
client_reference:: A short (max 191 characters) string that should represent the “source object” using the group. This is never shown to the user and only used to tie the group to an application defined object. If the group was already marked in use with the same client_reference, the existing reference will be updated.
use:: A text describing the source object, provided as a json object with ISO-639-1 language codes as key and the text as the value. This is shown to the user as part of the warning when trying to delete a group that is still in use. At least one language <-> text pair must be provided.

Response¶

result:: Currently always “ok”, non-existing groups or otherwise invalid parameters will fail with an appropriate http status.

Unmark group as in use (deprecated)¶

This function is deprecated and should no longer be used.

The mark group in use functionality has been superseded by Register stored data referencing pCon.login object.

Remove a reference to a group.

POST $base_url/api/v1/account/unmark_group_in_use
Content-type: application/json

{
    "group_uuid": "5c24d6f9-9ab4-43ca-8c31-f32b75d14bfd",
    "client_reference": "planning:815"
}

==>

{
    "result": "ok"
}

Parameters¶

group_uuid:: Optional. The group that should be marked as in use. The group must belong to the user’s organization. If this is not specified or null references to all groups with the given client_reference will be released
client_reference:: A short (max 255 characters) string that should represent the “source object” using the group. See Mark group as in use (deprecated).

Response¶

result:: Currently always “ok”, invalid parameters will fail with an appropriate http status. This will API will also succeed if there is no reference to remove (e.g. if group was deleted despite being in use, or unmark_group_in_use was already called on this reference)

Create a new group containing containing the current user¶

Create a new group that initially contains the user associated with the access token that is used. This will work, even if the user has no admin permissions in the organization. The intended use case for this is to link resources in your service that should be available to multiple users in the organization, subject to access control by the organizations administrators. If the resource should only be available to the user there is no need to create a group, link the resource to the user uuid instead. Similarly, if it should be available to the whole organization without restriction use the organization uuid as the link.

This API should be used sparingly in order to not spam the organization with too many groups. Use a descriptive name (e.g. $ServiceName Adminstrators) and reuse an existing group where possible. For this purpose a special error result along with the existing groups uuid will be returned if a group with the passed name already exists.

Depending on your use case you may also offer the user the option to choose another already existing group. (see Get groups assigned to the user and Get groups of an organization)

The scope modify_account is required to use this API.

POST $base_url/api/v1/account/organization/group/new_for_self
Content-type: application/json

{
  "name": "Foo Administrators",
  "description": "Users in this group can create, modify and delete Foo documents"
}

==>

{
  "result": "ok",
  "group_uuid": "af3ec33c-8192-4811-82a9-7b377c8b25fb"
}

Parameters¶

name:: Required. The name of the group to be created
description:: Optional. A description of the groups purpose.

Response¶

result:

Result of the operation

ok:: Group was sucessfully created, it’s uuid will be in the group_uuid property
err_duplicate_group_name:: A group with this name already exists. The uuid of the existing group will be in the group_uuid property.

Other result codes should be expected and treated as an error

group_uuid:

For result == ok, the uuid of the created group, for result == err_duplicate_group_name the uuid of the already existing group with the given name.

Get administrators of the user¶

Query administrators responsible for the user.

GET $base_url/api/v1/account/administrators/$type

==>

{
    "administrators": [
        {
            "email": "test.admin@example.com",
            "email_verified": true,
            "email_undeliverable": false,
            "login": "",
            "title": "mrs",
            "first_name": "Test",
            "last_name": "Admin",
            "language_code": "de",
            "phone": "+49 30 123456"
        },
        {
            "email": "other.admin@example.com",
            "email_verified": true,
            "email_undeliverable": false,
            "login": "",
            "title": "mr",
            "first_name": "Other",
            "last_name": "Admin",
            "language_code": "de",
            "phone": "+49 30 123457"
        },
    ]
}

Parameters¶

type:

Currently the following types of administrators are defined:

organization:: $General admin of the organization, can assign other admins
users:: Responsible for management of users (invite new users, assign users to groups, …)
licenses:: Responsible for mangement of the organizations licenses
update_channels:: Responsible for management of the organizations channels

Response¶

adminstrators:

List of administrators where each has the following properties:

email:

Email address of the user

email_verified:

Flag indicating wether the email address was verified (This is done as part of the registration process, so it will almost always be true)

email_undeliverable:

It was determined that this email is no longer reachable. This flag can be used to avoid sending email that would most likely bounce anyway or to indicate to the user that he should check that the address in his profile is still correct.

login:

Optional. A login name for the user. Most applications should ignore this value, it only exists for compatibility with accounts created in the past.

title:

Specifies how the user should be addressed. Defined values are

mr
mrs
not_set

first_name:

First name of the user

last_name:

Last name of the user

language_code:

Preferred language of the user as ISO-639-1 language code

phone:

Phone number of the user

Create new notification¶

Adds a new new notification for the user associated with the access token. This API requires the notifications scope.

POST /api/v1/account/notification/new
Content-type: application/json

{
    "text": "Something must be done",
    "actions": [
        {
            "button_text": "Do Something",
            "action_url": "https://example.com/action/do?id=8015",
            "is_main_action": true,
            "dismiss_notification": true
        },
        {
            "button_text": "Cancel",
            "dismiss_notification": true
        }
    ]
}

==>

{"result": "ok", "notification_uuid": "b0ba4b74-4701-48cb-b873-34db77d92383"}

Parameters¶

An object with the following properties:

text:

String. Text of the notification

category_uuid:

String, Optional. Uuid identifying this notification (or set of notifications).

expires:

String, Optional. ISO 8601 Date when the notification will no longer be valid.

actions:

List of action items, Optional. Each item is an object with the following properties:

button_text:: String. Text of the action
is_main_action:: Boolean, Optional. Marks this action as a primary action. Multiple actions may be marked as primary action.
is_cancel_action:: Boolean, Optional. If true this action should be executed when the notification is discarded. Only one action may be marked as cancel action
open_url:: String, Optional. Http(s) URL that should be opened when this action is executed
action_url:: String, Optional. Http(s) URL that will be invoked when this action is executed. The given URL will receive a POST-Request with an empty JSON-Object as body. This may be extended with additional information in the future
dismiss_notification:: Boolean, Optional. Automatically dismiss this notification when the action is executed. Defaults to true if not specified.

Response¶

result:: “ok” If the request was successful. Other values should be treated as errors.
notification_uuid:: UUID of the created notification

Get notifications¶

This returns notifications for the use and requires the access token to have the notifications scope.

GET /api/v1/account/notifications

==>

{
    "notifications": [
        {
            "uuid": "bf646d70-3689-481b-87e3-1cb2e86e19af",
            "category_uuid": null,
            "creation_date": "2020-04-06T08:23:30+00:00",
            "expires": null,
            "text": "Something important has happend",
            "actions": [
                {
                    "button_text": "Open website",
                    "dismiss_notification": true,
                    "id": 18,
                    "is_cancel_action": false,
                    "is_main_action": true,
                    "open_url": "https://example.com"
                },
                {
                    "button_text": "Cancel",
                    "id": 19,
                    "is_cancel_action": false,
                    "is_main_action": false
                }
            ]
        }
    ]
}

Response¶

Returns an object with one proptery notifications containing the list of notification items. Each item is itself an object with the following properties:

uuid:

Automatically generated unique id of the notification

category_uuid:

UUID that was specified when creating the notification. Multiple notifications may use the same category_uuid at the discretion of the creating application. (May be null)

creation_date:

ISO 8601 Date string when the notification was created

expires:

ISO 8601 Date string when the notification expires, or null if this notification does not expire.

text:

String with the notifications message text

actions:

List of action items. Each is an object with the following properties:

id:: Integer. Id of the action
button_text:: String. Text of the action.
is_main_action:: Boolean. Marks a “primary” action of the notication. Multiple actions may be marked as main action.
is_cancel_action:: Boolean. Marks this action as cancel action. The cancel action is automatically invoked when the notifcation is discarded
open_url:: String, Optional. Http(s) URL When the users clicks this action button a new tab with the given URL should be opened.
dismiss_notification”:: Boolean, Optional. If this property exists and is true the client should delete the notification when this action is triggered. This is used in conjunction with open_url where the client is responsible for executing the action.

Implementation notes¶

Clients that display notifications must follow these rules when implementing notifications:

If the action does not specify an open_url the trigger notification action api should be invoked with the action and afterwards the notifications should be updated.

If an open_url is specified it should be open in a new tab. If the action has the dismiss_notification property set to true the client must invoke the delete notification API for this notification

When a notification is dismissed the client should check whether a cancel action with an open_url is present, in which case a new tab with that url should be opened

Discard notification¶

Discard existing notification(s)

DELETE /api/v1/account/notification/$UUID

==>

{"result": "ok"}

Parameters¶

The last path component of the url must be a notification uuid or category_uuid (in the latter case more than one notification may be discarded if multiple notifications share the same category uuid)

Response¶

result:: “ok” when the notification(s) were successfully discarded. Other values should be treated as errors

Register stored data referencing pCon.login object¶

This API allows applications to tell pCon.login that they store data for a pCon.login object like an organization or user. pCon.login can then inform the user that they may loose access to data stored in the application if they want to delete that object. Additionaly the application can specify a hook url to be notified when the given object is deleted in order to remove the then stale data.

POST $base_url/api/v1/account/register_stored_data_on_client
Content-type: application/json

{
    "object_type": "group",
    "object_uuid": "5c24d6f9-9ab4-43ca-8c31-f32b75d14bfd",
    "delete_hook_url": "https://example.com/webhooks/plog_group_deleted"
}

==>

{
    "result": "ok",
    "hook_id": "6gRVWvUFwuifJx6dc2jk2p"
}

Parameters¶

object_type:: String. Type of object to register the hook for. Must be one of: - organization - user - group
object_uuid:: The uuid of the object for which the client stores data.
client_id:: String. Optional. OAuth2 client id of the application that stores the data. If not specified, the client_id is derived from the access_token that is used. This is useful for applications that provide an API for other applications themselves and thus may work with tokens from another application
delete_hook_url:: String. Optional. An https:// url that is notified when the user is deleted.

Response¶

result:: Currently always “ok”, invalid parameters will fail with an apropriate http status code
hook_id:: String. The id of the registered hook. Can be used to unregister the hook if the client no longer stores the data.

Hook Request¶

The url given by delete_hook_url will receive a POST request like this:

POST /webhooks/plog_group_deleted
Content-type: application/json

{
    "hook_type": "delete_notification",
    "hook_id": "6gRVWvUFwuifJx6dc2jk2p",
    "object_type": "group",
    "object_uuid": "5c24d6f9-9ab4-43ca-8c31-f32b75d14bfd"
}

All fields in the example above will always be present. hook_type will always be set to delete_notification, the other fields correspond to the same named fields of the request/ response parameters.

Upon successful execution of the hook the response to that post request should be a 200 OK response containing a json object with its result property set to ok.

200 OK
Content-type: application/json

{
  "result": "ok"
}

Otherwise the server will consider the notification as failed and will retry it.

Unregister stored data referencing pCon.login object¶

Clears previously registered hook that marks a pCon.login object as referecenced by an application.

POST $base_url/api/v1/account/unregister_stored_data_on_client
Content-type: application/json

{
    "hook_id": "6gRVWvUFwuifJx6dc2jk2p"
}

==>

{
    "result": "ok",
}

Parameters¶

hook_id:: The id returned when registering the hook

Response¶

result:: Currently always “ok”