Skip to content
4HSE Developers DEV

AddressBook

An AddressBook is a contact entry. It links contact information (phone, email, PEC, fax, etc.) to an entity on the platform: a person, an office, a project, or a supplier.

Use this API to:

  • Add a contact (email, phone, etc.) to a person, office, or supplier
  • Find all contacts for an entity (filter by entity_id)
  • Search for a contact by value (e.g. find who has a specific phone number)
Version
2.0.0
OpenAPI version
3.0.0

Authentication

Section titled “ Authentication ”

OAuth2

Section titled “OAuth2 ”

Security scheme type: oauth2

Flow type: password

Token URL: https://auth.4hse.com/realms/4hse/protocol/openid-connect/token

AccessToken

Section titled “AccessToken ”

Security scheme type: apiKey

Query parameter name: access-token

Operations

Section titled “Operations”

index

Section titled “index”
POST
/v2/address-book/index

Returns a paginated list of contacts.

The entity_id query parameter is optional. If provided, filters contacts for that specific entity. If omitted, returns contacts for all accessible entities in the project (people, offices, suppliers).

Most useful filters:

  • entity_id: all contacts for a person, office, or supplier
  • type: filter by contact type (e.g. Email, telephone)
  • value: search by contact value

Authorizations

Section titled “Authorizations ”

Query Parameters

Section titled “Query Parameters ”
entity_id
string format: uuid

Filter contacts for this entity (person_id, office_id, project_id, or unit_id).

Request Body

Section titled “Request Body ”

Parameters for searching contacts

object
filter
object
delivery_id

Unique identifier of the contact entry. Auto-generated if not provided.

string format: uuid
type
required

Contact type:

  • telephone: landline phone
  • mobilephone: mobile phone
  • Email: email address
  • PEC: certified email
  • Fax: fax number
  • Skype: Skype contact
  • Web: website URL
string
<= 50 characters
Allowed values: telephone Email mobilephone Fax Skype Web PEC
value
required

The contact value (e.g. phone number, email address, website URL).

string
<= 70 characters
description

Optional description of the contact (e.g. “Work”, “Personal”, “Emergency”).

string
<= 140 characters
note

Additional notes.

string
<= 255 characters
entity_id
required

The entity this contact belongs to. Can be:

  • A person_id for a person’s contact
  • An office_id for an office’s contact
  • A project_id for a project’s contact
  • A unit_id for a supplier’s contact
string format: uuid
per-page
integer
default: 100 >= 1
page
integer
default: 1 >= 1
sort
string
Allowed values: type entity_id value
Example
{
  "filter": {
    "type": "Email"
  },
  "per-page": 20,
  "page": 1,
  "sort": "type"
}

Responses

Section titled “ Responses ”
200
Section titled “200 ”

List of contacts

Array<object>
object
delivery_id

Unique identifier of the contact entry. Auto-generated if not provided.

string format: uuid
type
required

Contact type:

  • telephone: landline phone
  • mobilephone: mobile phone
  • Email: email address
  • PEC: certified email
  • Fax: fax number
  • Skype: Skype contact
  • Web: website URL
string
<= 50 characters
Allowed values: telephone Email mobilephone Fax Skype Web PEC
value
required

The contact value (e.g. phone number, email address, website URL).

string
<= 70 characters
description

Optional description of the contact (e.g. “Work”, “Personal”, “Emergency”).

string
<= 140 characters
note

Additional notes.

string
<= 255 characters
entity_id
required

The entity this contact belongs to. Can be:

  • A person_id for a person’s contact
  • An office_id for an office’s contact
  • A project_id for a project’s contact
  • A unit_id for a supplier’s contact
string format: uuid

Headers

Section titled “Headers ”
X-Pagination-Current-Page
integer

Current page

X-Pagination-Page-Count
integer

Total number of pages

X-Pagination-Per-Page
integer

Number of items per page

X-Pagination-Total-Count
integer

Total number of items

create

Section titled “create”
POST
/v2/address-book/create

Creates a new contact entry.

Requires entity_id, type, and value. The delivery_id is auto-generated if not provided.

The entity_id can be a person_id, office_id, project_id, or unit_id.

Authorizations

Section titled “Authorizations ”

Request Body required

Section titled “Request Body required ”

Contact to create

object
delivery_id

Unique identifier of the contact entry. Auto-generated if not provided.

string format: uuid
type
required

Contact type:

  • telephone: landline phone
  • mobilephone: mobile phone
  • Email: email address
  • PEC: certified email
  • Fax: fax number
  • Skype: Skype contact
  • Web: website URL
string
<= 50 characters
Allowed values: telephone Email mobilephone Fax Skype Web PEC
value
required

The contact value (e.g. phone number, email address, website URL).

string
<= 70 characters
description

Optional description of the contact (e.g. “Work”, “Personal”, “Emergency”).

string
<= 140 characters
note

Additional notes.

string
<= 255 characters
entity_id
required

The entity this contact belongs to. Can be:

  • A person_id for a person’s contact
  • An office_id for an office’s contact
  • A project_id for a project’s contact
  • A unit_id for a supplier’s contact
string format: uuid
Example
{
  "entity_id": "e3a1f5d2-8c4b-4e7a-9f6d-2b1c3d4e5f6a",
  "type": "Email",
  "value": "john.smith@example.com",
  "description": "Work email"
}

Responses

Section titled “ Responses ”
201
Section titled “201 ”

Contact created successfully

object
delivery_id

Unique identifier of the contact entry. Auto-generated if not provided.

string format: uuid
type
required

Contact type:

  • telephone: landline phone
  • mobilephone: mobile phone
  • Email: email address
  • PEC: certified email
  • Fax: fax number
  • Skype: Skype contact
  • Web: website URL
string
<= 50 characters
Allowed values: telephone Email mobilephone Fax Skype Web PEC
value
required

The contact value (e.g. phone number, email address, website URL).

string
<= 70 characters
description

Optional description of the contact (e.g. “Work”, “Personal”, “Emergency”).

string
<= 140 characters
note

Additional notes.

string
<= 255 characters
entity_id
required

The entity this contact belongs to. Can be:

  • A person_id for a person’s contact
  • An office_id for an office’s contact
  • A project_id for a project’s contact
  • A unit_id for a supplier’s contact
string format: uuid
Example
{
  "delivery_id": "7e8f9012-3456-7890-abcd-ef7890123456",
  "entity_id": "e3a1f5d2-8c4b-4e7a-9f6d-2b1c3d4e5f6a",
  "type": "Email",
  "value": "john.smith@example.com",
  "description": "Work email"
}

view

Section titled “view”
GET
/v2/address-book/view/{id}

Retrieves a single contact by its ID.

Authorizations

Section titled “Authorizations ”

Path Parameters

Section titled “Path Parameters ”
id
required
string format: uuid

The delivery_id to retrieve.

Responses

Section titled “ Responses ”
200
Section titled “200 ”

Contact found

object
delivery_id

Unique identifier of the contact entry. Auto-generated if not provided.

string format: uuid
type
required

Contact type:

  • telephone: landline phone
  • mobilephone: mobile phone
  • Email: email address
  • PEC: certified email
  • Fax: fax number
  • Skype: Skype contact
  • Web: website URL
string
<= 50 characters
Allowed values: telephone Email mobilephone Fax Skype Web PEC
value
required

The contact value (e.g. phone number, email address, website URL).

string
<= 70 characters
description

Optional description of the contact (e.g. “Work”, “Personal”, “Emergency”).

string
<= 140 characters
note

Additional notes.

string
<= 255 characters
entity_id
required

The entity this contact belongs to. Can be:

  • A person_id for a person’s contact
  • An office_id for an office’s contact
  • A project_id for a project’s contact
  • A unit_id for a supplier’s contact
string format: uuid
404
Section titled “404 ”

Contact not found

update

Section titled “update”
PUT
/v2/address-book/update/{id}

Updates an existing contact.

Authorizations

Section titled “Authorizations ”

Path Parameters

Section titled “Path Parameters ”
id
required
string format: uuid

The delivery_id to update.

Request Body required

Section titled “Request Body required ”

Fields to update

object
delivery_id

Unique identifier of the contact entry. Auto-generated if not provided.

string format: uuid
type
required

Contact type:

  • telephone: landline phone
  • mobilephone: mobile phone
  • Email: email address
  • PEC: certified email
  • Fax: fax number
  • Skype: Skype contact
  • Web: website URL
string
<= 50 characters
Allowed values: telephone Email mobilephone Fax Skype Web PEC
value
required

The contact value (e.g. phone number, email address, website URL).

string
<= 70 characters
description

Optional description of the contact (e.g. “Work”, “Personal”, “Emergency”).

string
<= 140 characters
note

Additional notes.

string
<= 255 characters
entity_id
required

The entity this contact belongs to. Can be:

  • A person_id for a person’s contact
  • An office_id for an office’s contact
  • A project_id for a project’s contact
  • A unit_id for a supplier’s contact
string format: uuid
Example
{
  "value": "john.smith.new@example.com"
}

Responses

Section titled “ Responses ”
200
Section titled “200 ”

Contact updated successfully

object
delivery_id

Unique identifier of the contact entry. Auto-generated if not provided.

string format: uuid
type
required

Contact type:

  • telephone: landline phone
  • mobilephone: mobile phone
  • Email: email address
  • PEC: certified email
  • Fax: fax number
  • Skype: Skype contact
  • Web: website URL
string
<= 50 characters
Allowed values: telephone Email mobilephone Fax Skype Web PEC
value
required

The contact value (e.g. phone number, email address, website URL).

string
<= 70 characters
description

Optional description of the contact (e.g. “Work”, “Personal”, “Emergency”).

string
<= 140 characters
note

Additional notes.

string
<= 255 characters
entity_id
required

The entity this contact belongs to. Can be:

  • A person_id for a person’s contact
  • An office_id for an office’s contact
  • A project_id for a project’s contact
  • A unit_id for a supplier’s contact
string format: uuid
404
Section titled “404 ”

Contact not found

delete

Section titled “delete”
DELETE
/v2/address-book/delete/{id}

Deletes a contact.

Authorizations

Section titled “Authorizations ”

Path Parameters

Section titled “Path Parameters ”
id
required
string format: uuid

The delivery_id to delete.

Query Parameters

Section titled “Query Parameters ”
force
boolean

If true, deletes the contact.

Responses

Section titled “ Responses ”
204
Section titled “204 ”

Contact deleted successfully

400
Section titled “400 ”

Preview of affected entities (returned when force=false)