Client Addresses

11 views Markdown

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.
typestringindividual or corporate.
emailstringEmail address.
phonestringPhone; digits only are stored.
identitystringIdentity or tax number.
companyobjectTax 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).
statusstringactive or passive.
Errors 2
not_found404No such client or address.
insufficient_scope403The key lacks the required scope.
Request 
curl 'https://panel.example.com/api/v1/admin/clients/42/addresses' \
  -H "Authorization: Bearer $API_KEY" \
  -H 'Accept: application/json'
const res  = await fetch('https://panel.example.com/api/v1/admin/clients/42/addresses', {
  headers: { Authorization: `Bearer ${apiKey}` },
});
const body = await res.json();
$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);
$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.
typestringindividual or corporate. Defaults to individual.
labelstringAddress label.
phonestringPhone; digits only are stored.
identitystringIdentity or tax number.
companyobjectTax 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 -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":"[email protected]","country_id":840,"state":"California","city":"San Francisco","address":"123 Market Street","zipcode":"94105","is_default":true}'
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":"[email protected]","country_id":840,"state":"California","city":"San Francisco","address":"123 Market Street","zipcode":"94105","is_default":true}),
});

const body = await res.json();
$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'      => '[email protected]',
        'country_id' => 840,
        'state'      => 'California',
        'city'       => 'San Francisco',
    ]),
]);

$body = json_decode(curl_exec($ch), true);
curl_close($ch);
$response = Api::Clients()->CreateClientAddress([
    'id'         => 42,
    'full_name'  => 'John Doe',
    'email'      => '[email protected]',
    'country_id' => 840,
    'state'      => 'California',
    'city'       => 'San Francisco',
    'is_default' => true,
]);

$addressId = $response['data']['id'] ?? 0;
Response 
{
  "data": {
    "id": 13,
    "full_name": "John Doe",
    "type": "individual",
    "country_id": 840,
    "city": "San Francisco",
    "zipcode": "94105",
    "is_default": true,
    "status": "active"
  }
}
{
  "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 'https://panel.example.com/api/v1/admin/clients/42/addresses/13' \
  -H "Authorization: Bearer $API_KEY"
const res  = await fetch('https://panel.example.com/api/v1/admin/clients/42/addresses/13', {
  headers: { Authorization: `Bearer ${apiKey}` },
});
const body = await res.json();
$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);
$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_required422full_name is required.
email_invalid422A valid email is required.
country_required422country_id is required.
state_required422state is required.
city_required422city is required.
insufficient_scope403The key lacks the required scope.
Request 
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":"[email protected]","country_id":840,"state":"California","city":"San Francisco","address":"123 Market Street","zipcode":"94105","is_default":true}'
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":"[email protected]","country_id":840,"state":"California","city":"San Francisco","address":"123 Market Street","zipcode":"94105","is_default":true}),
});

const body = await res.json();
$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);
// 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'      => '[email protected]',
    '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 -X DELETE 'https://panel.example.com/api/v1/admin/clients/42/addresses/13' \
  -H "Authorization: Bearer $API_KEY"
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();
$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);
$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.

Was this helpful?

Thanks for your feedback!

Still Need Help?

Our support team is here around the clock for anything you can't find above.

Contact Us Open a Ticket

We use cookies to keep you signed in, remember your language and currency, and improve the site. Cookie Policy