---
title: "AddressBook"
url: "https://dev.4hse.com/api/addressbook"
---

# 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 ”](#authentication)

### OAuth2

[Section titled “OAuth2 ”](#oauth2)

**Security scheme type:** oauth2

**Flow type:** password

**Token URL:** [https://auth.4hse.com/realms/4hse/protocol/openid-connect/token](https://auth.4hse.com/realms/4hse/protocol/openid-connect/token)

### AccessToken

[Section titled “AccessToken ”](#accesstoken)

**Security scheme type:** apiKey

**Query parameter name:** access-token

## Operations

[Section titled “Operations”](#operations)

### index

[Section titled “index”](#operation-indexAddressBook-post)

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 ”](#authorizations)

-   **[OAuth2](/api/addressbook/#oauth2)**
-   **[AccessToken](/api/addressbook/#accesstoken)**

#### Query Parameters

[Section titled “Query Parameters ”](#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 ”](#request-body)

Parameters for searching contacts

Select media typeapplication/json

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 ”](#responses)

##### 200

[Section titled “200 ”](#200)

List of contacts

Select media typeapplication/json

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 ”](#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”](#operation-createAddressBook-post)

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 ”](#authorizations)

-   **[OAuth2](/api/addressbook/#oauth2)**
-   **[AccessToken](/api/addressbook/#accesstoken)**

#### Request Body required

[Section titled “Request Body required ”](#request-body)

Contact to create

Select media typeapplication/json

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 ”](#responses)

##### 201

[Section titled “201 ”](#201)

Contact created successfully

Select media typeapplication/json

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”](#operation-viewAddressBook-get)

GET

/v2/address-book/view/{id}

-   

Retrieves a single contact by its ID.

## Authorizations

[Section titled “Authorizations ”](#authorizations)

-   **[OAuth2](/api/addressbook/#oauth2)**
-   **[AccessToken](/api/addressbook/#accesstoken)**

#### Path Parameters

[Section titled “Path Parameters ”](#path-parameters)

**id**

required

string format: uuid

The delivery\_id to retrieve.

#### Responses

[Section titled “ Responses ”](#responses)

##### 200

[Section titled “200 ”](#200)

Contact found

Select media typeapplication/json

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 ”](#404)

Contact not found

### update

[Section titled “update”](#operation-updateAddressBook-put)

PUT

/v2/address-book/update/{id}

-   

Updates an existing contact.

## Authorizations

[Section titled “Authorizations ”](#authorizations)

-   **[OAuth2](/api/addressbook/#oauth2)**
-   **[AccessToken](/api/addressbook/#accesstoken)**

#### Path Parameters

[Section titled “Path Parameters ”](#path-parameters)

**id**

required

string format: uuid

The delivery\_id to update.

#### Request Body required

[Section titled “Request Body required ”](#request-body)

Fields to update

Select media typeapplication/json

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 ”](#responses)

##### 200

[Section titled “200 ”](#200)

Contact updated successfully

Select media typeapplication/json

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 ”](#404)

Contact not found

### delete

[Section titled “delete”](#operation-deleteAddressBook-delete)

DELETE

/v2/address-book/delete/{id}

-   

Deletes a contact.

## Authorizations

[Section titled “Authorizations ”](#authorizations)

-   **[OAuth2](/api/addressbook/#oauth2)**
-   **[AccessToken](/api/addressbook/#accesstoken)**

#### Path Parameters

[Section titled “Path Parameters ”](#path-parameters)

**id**

required

string format: uuid

The delivery\_id to delete.

#### Query Parameters

[Section titled “Query Parameters ”](#query-parameters)

**force**

boolean

If true, deletes the contact.

#### Responses

[Section titled “ Responses ”](#responses)

##### 204

[Section titled “204 ”](#204)

Contact deleted successfully

##### 400

[Section titled “400 ”](#400)

Preview of affected entities (returned when force=false)

This site is protected by reCAPTCHA and the Google [Privacy Policy](https://policies.google.com/privacy) and [Terms of Service](https://policies.google.com/terms) apply.