# User Addresses

## The UserAddress object

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `object` | string | Yes | Type of object is always `userAddress`. |
| `id` | string | Yes | Unique identifier for the address. |
| `city` | string | Yes | The city/municipality of the address. |
| `country` | string | Yes | The ISO 3166-1 alpha-2 country code of the address. |
| `createdAt` | string | Yes | The time the address was created. |
| `line1` | string | Yes | The first line of the address, e.g. street and house number. |
| `line2` | string,null | Yes | The second line of the address, e.g. apartment number. |
| `postalCode` | string,null | Yes | The postal code of the address. |
| `state` | string,null | Yes | The state/province/region of the address. |
| `user` | string | Yes | Unique identifier for the address user. |

---

## Retrieve a user address

`GET /projects/{project}/users/{user}/addresses/{address}`

Retrieves the details of an existing address for a given user.

### Path Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `project` | string | Yes | The unique identifier for the [project](https://developers.gigs.com/core/projects#the-project-resource). |
| `user` | string | Yes | The unique identifier for the user. |
| `address` | string | Yes | The unique identifier for the address. |

### Responses

#### 200 — Returns the address if it exists and is owned by the user.

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `object` | string | Yes | Type of object is always `userAddress`. |
| `id` | string | Yes | Unique identifier for the address. |
| `city` | string | Yes | The city/municipality of the address. |
| `country` | string | Yes | The ISO 3166-1 alpha-2 country code of the address. |
| `createdAt` | string | Yes | The time the address was created. |
| `line1` | string | Yes | The first line of the address, e.g. street and house number. |
| `line2` | string,null | Yes | The second line of the address, e.g. apartment number. |
| `postalCode` | string,null | Yes | The postal code of the address. |
| `state` | string,null | Yes | The state/province/region of the address. |
| `user` | string | Yes | Unique identifier for the address user. |

#### 404 — The requested resource doesn't exist.

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `object` | string | Yes | Type of object is always `error`. |
| `code` | string | No | An optional machine-readable description of the error. Present for errors that could be handled programmatically. |
| `details` | object[] | No | Optional array containing specific information for the current error.  <!-- theme: info --> > #### Preview > > This property is currently in preview and might change in the future. > > We’re excited to hear your feedback and ideas. Please send an email > to [support@gigs.com](mailto:support@gigs.com) to share your thoughts.  |
| `documentation` | string[] | No | An optional list of URLs providing further information to resolve the error. |
| `hint` | string | No | An optional explanation how to resolve the error. |
| `message` | string | Yes | A human readable description of the error. |
| `type` | string | Yes | The type of [error](https://developers.gigs.com/api/error-handling) returned. |

#### 422 — The request can't be processed, often due to an invalid parameter or incompatible system state.

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `object` | string | Yes | Type of object is always `error`. |
| `code` | string | No | An optional machine-readable description of the error. Present for errors that could be handled programmatically. |
| `details` | object[] | No | Optional array containing specific information for the current error.  <!-- theme: info --> > #### Preview > > This property is currently in preview and might change in the future. > > We’re excited to hear your feedback and ideas. Please send an email > to [support@gigs.com](mailto:support@gigs.com) to share your thoughts.  |
| `documentation` | string[] | No | An optional list of URLs providing further information to resolve the error. |
| `hint` | string | No | An optional explanation how to resolve the error. |
| `message` | string | Yes | A human readable description of the error. |
| `type` | string | Yes | The type of [error](https://developers.gigs.com/api/error-handling) returned. |

---

## Delete a user address

`DELETE /projects/{project}/users/{user}/addresses/{address}`

Retrieves the details of an existing user address and deletes it.

### Path Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `project` | string | Yes | The unique identifier for the [project](https://developers.gigs.com/core/projects#the-project-resource). |
| `user` | string | Yes | The unique identifier for the user. |
| `address` | string | Yes | The unique identifier for the address. |

### Responses

#### 200 — Returns the address after a successful deletion.

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `object` | string | Yes | Type of object is always `userAddress`. |
| `id` | string | Yes | Unique identifier for the address. |
| `city` | string | Yes | The city/municipality of the address. |
| `country` | string | Yes | The ISO 3166-1 alpha-2 country code of the address. |
| `createdAt` | string | Yes | The time the address was created. |
| `line1` | string | Yes | The first line of the address, e.g. street and house number. |
| `line2` | string,null | Yes | The second line of the address, e.g. apartment number. |
| `postalCode` | string,null | Yes | The postal code of the address. |
| `state` | string,null | Yes | The state/province/region of the address. |
| `user` | string | Yes | Unique identifier for the address user. |

#### 404 — The requested resource doesn't exist.

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `object` | string | Yes | Type of object is always `error`. |
| `code` | string | No | An optional machine-readable description of the error. Present for errors that could be handled programmatically. |
| `details` | object[] | No | Optional array containing specific information for the current error.  <!-- theme: info --> > #### Preview > > This property is currently in preview and might change in the future. > > We’re excited to hear your feedback and ideas. Please send an email > to [support@gigs.com](mailto:support@gigs.com) to share your thoughts.  |
| `documentation` | string[] | No | An optional list of URLs providing further information to resolve the error. |
| `hint` | string | No | An optional explanation how to resolve the error. |
| `message` | string | Yes | A human readable description of the error. |
| `type` | string | Yes | The type of [error](https://developers.gigs.com/api/error-handling) returned. |

#### 422 — The request can't be processed, often due to an invalid parameter or incompatible system state.

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `object` | string | Yes | Type of object is always `error`. |
| `code` | string | No | An optional machine-readable description of the error. Present for errors that could be handled programmatically. |
| `details` | object[] | No | Optional array containing specific information for the current error.  <!-- theme: info --> > #### Preview > > This property is currently in preview and might change in the future. > > We’re excited to hear your feedback and ideas. Please send an email > to [support@gigs.com](mailto:support@gigs.com) to share your thoughts.  |
| `documentation` | string[] | No | An optional list of URLs providing further information to resolve the error. |
| `hint` | string | No | An optional explanation how to resolve the error. |
| `message` | string | Yes | A human readable description of the error. |
| `type` | string | Yes | The type of [error](https://developers.gigs.com/api/error-handling) returned. |

---

## List all user addresses

`GET /projects/{project}/users/{user}/addresses`

Returns a list of addresses owned by the given user. The addresses returned are sorted by creation date, with the most recently created addresses appearing first.

### Path Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `project` | string | Yes | The unique identifier for the [project](https://developers.gigs.com/core/projects#the-project-resource). |
| `user` | string | Yes | The unique identifier for the user. |

### Responses

#### 200 — Returns a list of address objects.

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `object` | string | Yes | Type of object is always `list`. |
| `items` | object[] | Yes | List of objects of type `userAddress`. |
| `moreItemsAfter` | string,null | Yes | A unique identifier to be used as `after` pagination parameter if more items are available sorted after the current batch of items. |
| `moreItemsBefore` | string,null | Yes | A unique identifier to be used as `before` pagination parameter if more items are available sorted before the current batch of items. |

#### 404 — The requested resource doesn't exist.

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `object` | string | Yes | Type of object is always `error`. |
| `code` | string | No | An optional machine-readable description of the error. Present for errors that could be handled programmatically. |
| `details` | object[] | No | Optional array containing specific information for the current error.  <!-- theme: info --> > #### Preview > > This property is currently in preview and might change in the future. > > We’re excited to hear your feedback and ideas. Please send an email > to [support@gigs.com](mailto:support@gigs.com) to share your thoughts.  |
| `documentation` | string[] | No | An optional list of URLs providing further information to resolve the error. |
| `hint` | string | No | An optional explanation how to resolve the error. |
| `message` | string | Yes | A human readable description of the error. |
| `type` | string | Yes | The type of [error](https://developers.gigs.com/api/error-handling) returned. |

---

## Create a user address

`POST /projects/{project}/users/{user}/addresses`

Create a new address for the given user with the provided parameters.

If any validations fail during the user address creation process,
detailed information will be provided in the error response body.
If applicable, suggested alternative values for properties that do not
pass the validations will also be included.

Please note that there is a maximum limit of 10 active addresses permitted per user.
Attempts to exceed this limit will result in an error response. Addresses must also
be unique for a given user.

### Body

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `city` | string | Yes | The city/municipality of the address. |
| `country` | string | Yes | The ISO 3166-1 alpha-2 country code of the address. |
| `line1` | string | Yes | The first line of the address, e.g. street and house number. |
| `line2` | string,null | No | The second line of the address, e.g. apartment number. |
| `state` | string,null | No | The state/province/region of the address. Required for US/CA addresses to be a valid ISO 3166-2 2 letter code. |
| `postalCode` | string,null | No | The postal code of the address. Required for countries with postal codes. |

### Path Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `project` | string | Yes | The unique identifier for the [project](https://developers.gigs.com/core/projects#the-project-resource). |
| `user` | string | Yes | The unique identifier for the user. |

### Responses

#### 201 — Returns the created address.

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `object` | string | Yes | Type of object is always `userAddress`. |
| `id` | string | Yes | Unique identifier for the address. |
| `city` | string | Yes | The city/municipality of the address. |
| `country` | string | Yes | The ISO 3166-1 alpha-2 country code of the address. |
| `createdAt` | string | Yes | The time the address was created. |
| `line1` | string | Yes | The first line of the address, e.g. street and house number. |
| `line2` | string,null | Yes | The second line of the address, e.g. apartment number. |
| `postalCode` | string,null | Yes | The postal code of the address. |
| `state` | string,null | Yes | The state/province/region of the address. |
| `user` | string | Yes | Unique identifier for the address user. |

#### 404 — The requested resource doesn't exist.

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `object` | string | Yes | Type of object is always `error`. |
| `code` | string | No | An optional machine-readable description of the error. Present for errors that could be handled programmatically. |
| `details` | object[] | No | Optional array containing specific information for the current error.  <!-- theme: info --> > #### Preview > > This property is currently in preview and might change in the future. > > We’re excited to hear your feedback and ideas. Please send an email > to [support@gigs.com](mailto:support@gigs.com) to share your thoughts.  |
| `documentation` | string[] | No | An optional list of URLs providing further information to resolve the error. |
| `hint` | string | No | An optional explanation how to resolve the error. |
| `message` | string | Yes | A human readable description of the error. |
| `type` | string | Yes | The type of [error](https://developers.gigs.com/api/error-handling) returned. |

#### 422 — The address creation request can't be processed, due to an invalid parameter or incompatible system state.

---