# Client Addresses

https://dev.wisecp.com/es/client-addresses

The five endpoints that read, add, update and delete an address in a client's address book.

## Overview

A client can hold several addresses, and an invoice is issued to one of them. The address book is separate from the client record.

One address is the default. Making a new address the default clears the flag on the previous one; there is never more than one default.

> **Notification preferences**
> 
> A notification preference is stored as a bitmask: one number carrying several choices.

## Reference

### Listing Addresses

get/api/v1/admin/clients/{id}/addresses

`Clients/GetClientAddresses` admin

Returns the client's whole address book. The default one is flagged with `is_default`.

Response fields data[] — 17

idintAddress id.

full_namestringFull name.

labelstringAddress label, for example `Office`.

typestring`individual` or `corporate`.

emailstringEmail address.

phonestringPhone; digits only are stored.

identitystringIdentity or tax number.

companyobject 3 fieldsTax details on a corporate address.

namestringTrading name.

tax_numberstringTax number.

tax_officestringTax office.

country_idintCountry id. Resolve with `reference/countries`.

statestringState or region.

citystringCity.

addressstringStreet address.

zipcodestringPostcode. At most 20 characters.

is_defaultboolWhether this is the default address.

email_notificationsintEmail notification preference (bitmask).

sms_notificationsintSMS notification preference (bitmask).

statusstring`active` or `passive`.

Errors 2

not_found404No such client or address.

insufficient_scope403The key lacks the required scope.

Request cURL JavaScript PHP (HTTP) PHP (Internal)

```bash
curl 'https://panel.example.com/api/v1/admin/clients/42/addresses' \
  -H "Authorization: Bearer $API_KEY" \
  -H 'Accept: application/json'
```

```javascript
const res  = await fetch('https://panel.example.com/api/v1/admin/clients/42/addresses', {
  headers: { Authorization: `Bearer ${apiKey}` },
});
const body = await res.json();
```

```php
$ch = curl_init('https://panel.example.com/api/v1/admin/clients/42/addresses');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER     => ['Authorization: Bearer ' . $apiKey],
]);

$body = json_decode(curl_exec($ch), true);
curl_close($ch);
```

```php
$response = Api::Clients()->GetClientAddresses(['id' => 42]);

foreach ($response['data'] as $address) {
    if ($address['is_default']) {
        $invoiceAddress = $address;
    }
}
```

### Adding an Address

post/api/v1/admin/clients/{id}/addresses

`Clients/CreateClientAddress` admin

Adds a record to the address book and returns it in the same schema as the list.

Body 16 fields, 5 required

full_namestringrequiredFull name.

emailstringrequiredValidated for format.

country_idintrequiredCountry id. List: `reference/countries`.

statestringrequiredState or region.

citystringrequiredCity.

typestring`individual` or `corporate`. Defaults to `individual`.

labelstringAddress label.

phonestringPhone; digits only are stored.

identitystringIdentity or tax number.

companyobject 3 fieldsTax details on a corporate address.

namestringTrading name.

tax_numberstringTax number.

tax_officestringTax office.

addressstringStreet address.

zipcodestringPostcode. At most 20 characters.

is_defaultboolMakes this the default address.

email_notificationsintEmail notification preference. Defaults to all on.

sms_notificationsintSMS notification preference. Defaults to all on.

overwrite_invoicesboolApplies this address to the client's open invoices as well.

Response fields data

dataobjectThe address created, returned with `201`. Same shape as the list schema.

Errors 4

not_found404No such client or address.

email_invalid422Email format is not valid.

address_add_failed500The record could not be created.

insufficient_scope403The key lacks the required scope.

Request cURL JavaScript PHP (HTTP) PHP (Internal)

```bash
curl -X POST 'https://panel.example.com/api/v1/admin/clients/42/addresses' \
  -H "Authorization: Bearer $API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"full_name":"John Doe","email":"john@example.com","country_id":840,"state":"California","city":"San Francisco","address":"123 Market Street","zipcode":"94105","is_default":true}'
```

```javascript
const res = await fetch('https://panel.example.com/api/v1/admin/clients/42/addresses', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${apiKey}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({"full_name":"John Doe","email":"john@example.com","country_id":840,"state":"California","city":"San Francisco","address":"123 Market Street","zipcode":"94105","is_default":true}),
});

const body = await res.json();
```

```php
$ch = curl_init('https://panel.example.com/api/v1/admin/clients/42/addresses');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST           => true,
    CURLOPT_HTTPHEADER     => [
        'Authorization: Bearer ' . $apiKey,
        'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS => json_encode([
        'full_name'  => 'John Doe',
        'email'      => 'john@example.com',
        'country_id' => 840,
        'state'      => 'California',
        'city'       => 'San Francisco',
    ]),
]);

$body = json_decode(curl_exec($ch), true);
curl_close($ch);
```

```php
$response = Api::Clients()->CreateClientAddress([
    'id'         => 42,
    'full_name'  => 'John Doe',
    'email'      => 'john@example.com',
    'country_id' => 840,
    'state'      => 'California',
    'city'       => 'San Francisco',
    'is_default' => true,
]);

$addressId = $response['data']['id'] ?? 0;
```

Response 201 422

```json
{
  "data": {
    "id": 13,
    "full_name": "John Doe",
    "type": "individual",
    "country_id": 840,
    "city": "San Francisco",
    "zipcode": "94105",
    "is_default": true,
    "status": "active"
  }
}
```

```json
{
  "error": {
    "code": "email_invalid",
    "message": "A valid email is required."
  }
}
```

### Address Detail

get/api/v1/admin/clients/{id}/addresses/{addr_id}

`Clients/GetClientAddress` admin

Returns one address. The schema is the same as in the list.

Response fields data

dataobjectThe address itself. Same shape as the list schema.

Errors 2

not_found404No such client or address.

insufficient_scope403The key lacks the required scope.

Request cURL JavaScript PHP (HTTP) PHP (Internal)

```bash
curl 'https://panel.example.com/api/v1/admin/clients/42/addresses/13' \
  -H "Authorization: Bearer $API_KEY"
```

```javascript
const res  = await fetch('https://panel.example.com/api/v1/admin/clients/42/addresses/13', {
  headers: { Authorization: `Bearer ${apiKey}` },
});
const body = await res.json();
```

```php
$ch = curl_init('https://panel.example.com/api/v1/admin/clients/42/addresses/13');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER     => ['Authorization: Bearer ' . $apiKey],
]);

$body = json_decode(curl_exec($ch), true);
curl_close($ch);
```

```php
$response = Api::Clients()->GetClientAddress(['id' => 42, 'addr_id' => 13]);
```

### Updating an Address

put/api/v1/admin/clients/{id}/addresses/{addr_id}

`Clients/UpdateClientAddress` admin full replace

Updates the address. The body takes **the same fields as create**, and the required ones stay required.

Body the same 16 fields as create

full_namestringrequiredFull name.

emailstringrequiredValidated for format.

country_idintrequiredCountry id.

statestringrequiredState or region.

citystringrequiredCity.

overwrite_invoicesboolApplies the change to the client's open invoices as well.

Response fields data

dataobjectThe address after the update. Same shape as the list schema.

Errors 7

not_found404No such client or address.

full_name_required422`full_name` is required.

email_invalid422A valid email is required.

country_required422`country_id` is required.

state_required422`state` is required.

city_required422`city` is required.

insufficient_scope403The key lacks the required scope.

Request cURL JavaScript PHP (HTTP) PHP (Internal)

```bash
curl -X PUT 'https://panel.example.com/api/v1/admin/clients/42/addresses/13' \
  -H "Authorization: Bearer $API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"full_name":"John Doe","email":"john@example.com","country_id":840,"state":"California","city":"San Francisco","address":"123 Market Street","zipcode":"94105","is_default":true}'
```

```javascript
const res = await fetch('https://panel.example.com/api/v1/admin/clients/42/addresses/13', {
  method: 'PUT',
  headers: {
    Authorization: `Bearer ${apiKey}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({"full_name":"John Doe","email":"john@example.com","country_id":840,"state":"California","city":"San Francisco","address":"123 Market Street","zipcode":"94105","is_default":true}),
});

const body = await res.json();
```

```php
$ch = curl_init('https://panel.example.com/api/v1/admin/clients/42/addresses/13');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST  => 'PUT',
    CURLOPT_HTTPHEADER     => [
        'Authorization: Bearer ' . $apiKey,
        'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS => json_encode($address),
]);

$body = json_decode(curl_exec($ch), true);
curl_close($ch);
```

```php
// The required fields are sent again: this is a full update, not a partial one.
$response = Api::Clients()->UpdateClientAddress([
    'id'         => 42,
    'addr_id'    => 13,
    'full_name'  => 'John Doe',
    'email'      => 'john@example.com',
    'country_id' => 840,
    'state'      => 'California',
    'city'       => 'San Francisco',
]);
```

### Deleting an Address

delete/api/v1/admin/clients/{id}/addresses/{addr_id}

`Clients/DeleteClientAddress` admin

Deletes the address and returns the id that was removed.

Response fields data

deletedboolWhether the delete succeeded.

idintId of the deleted address.

Errors 1

not_found404No such client or address.

Request cURL JavaScript PHP (HTTP) PHP (Internal)

```bash
curl -X DELETE 'https://panel.example.com/api/v1/admin/clients/42/addresses/13' \
  -H "Authorization: Bearer $API_KEY"
```

```javascript
const res = await fetch('https://panel.example.com/api/v1/admin/clients/42/addresses/13', {
  method: 'DELETE',
  headers: { Authorization: `Bearer ${apiKey}` },
});

const body = await res.json();
```

```php
$ch = curl_init('https://panel.example.com/api/v1/admin/clients/42/addresses/13');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST  => 'DELETE',
    CURLOPT_HTTPHEADER     => ['Authorization: Bearer ' . $apiKey],
]);

$body = json_decode(curl_exec($ch), true);
curl_close($ch);
```

```php
$response = Api::Clients()->DeleteClientAddress(['id' => 42, 'addr_id' => 13]);
```

## Pitfalls

> **There is only one default**
> 
> Flagging an address with `is_default` clears the flag on the previous one. You do not have to update the old address; two defaults cannot exist.

> **Open invoices do not change by themselves**
> 
> Updating an address does not reach invoices that were already issued. Send `overwrite_invoices` if you want it to.

> **The update is not partial**
> 
> The endpoint is `PUT`. Leave a required field out and the request is refused; sending only the changed field is not enough.

## Related Articles

- [Client Endpoints](https://dev.wisecp.com/en/client-endpoints)
- [Request and Response Format](https://dev.wisecp.com/en/request-and-response-format)
- [API Authentication and Permissions](https://dev.wisecp.com/en/api-authentication-and-permissions)