Contacts
Xero provides a clean way of working with Xero contacts.
To work with contacts first call ->contacts() followed by a method.
Xero::contacts();
List Contacts
To list contacts, call the contacts()->get() method.
Xero docs for listing contacts - https://developer.xero.com/documentation/api/contacts#GET
Filtering Contacts
You can filter contacts using the filter
method:
The filter can be chained to the get method, or you can use the filter method directly.
$query = Xero::contacts();
if ($this->accountNumber) {
$query->filter('where', 'AccountNumber=="'.$this->accountNumber.'"');
}
if ($this->email) {
$query->filter('where', 'EmailAddress=="'.$this->email.'"');
}
if ($this->contactId) {
$query->filter('where', 'ContactID==Guid("'.$this->contactId.'")');
}
if ($this->searchTerm) {
$query->filter('searchTerm', $this->searchTerm);
}
if ($this->includeArchived) {
$query->filter('includeArchived', $this->includeArchived);
}
$query->filter('order', 'name')
->get();
Example Filters
Search term
$contacts = Xero::contacts()
->filter('searchTerm', $searchTerm)
->get();
Search by id
$contacts = Xero::contacts()
->filter('where', 'ContactID==Guid("'.$this->contactId.'")');
->get();
Search by AccountNumber
$contacts = Xero::contacts()
->filter('where', 'AccountNumber=="'.$this->accountNumber.'"')
->get();
Search by email
$contacts = Xero::contacts()
->filter('where', 'EmailAddress=="'.$email.'"')
->get();
Include archived contacts
$contacts = Xero::contacts()
->filter('includeArchived', 'true')
->get();
Paginate results
$contacts = Xero::contacts()
->filter('page', 2)
->get();
Sort results
$contacts = Xero::contacts()
->filter('order', 'name')
->get();
View Contacts
To view a single contact, a find method can be called passing in the contact id
Xero::contacts()->find(string $contactId);
Create Contacts
To create a contact, call a store method passing in an array
of contact data:
See https://developer.xero.com/documentation/api/contacts#POST for the array contents specifications
Xero::contacts()->store($data);
From version 1.1.14, you can also use the ContactDTO class to create a contact:
use Dcblogdev\Xero\DTOs\ContactDTO;
// Using the DTO
$contactDTO = new ContactDTO(
name: 'ACME Inc',
firstName: 'John',
lastName: 'Doe',
emailAddress: 'john.doe@example.com',
isCustomer: true
);
// Add an address
$contactDTO->addresses[] = ContactDTO::createAddress(
addressType: 'POBOX',
addressLine1: '123 Main St',
city: 'New York',
region: 'NY',
postalCode: '10001',
country: 'USA'
);
// Add a phone number
$contactDTO->phones[] = ContactDTO::createPhone(
phoneType: 'MOBILE',
phoneNumber: '555-1234'
);
// Create the contact
$contact = Xero::contacts()->store($contactDTO->toArray());
// Alternatively, create directly with an array
$contact = Xero::contacts()->store([
'Name' => 'ACME Inc',
'FirstName' => 'John',
'LastName' => 'Doe',
'EmailAddress' => 'john.doe@example.com',
'IsCustomer' => true,
'Addresses' => [
[
'AddressType' => 'POBOX',
'AddressLine1' => '123 Main St',
'City' => 'New York',
'Region' => 'NY',
'PostalCode' => '10001',
'Country' => 'USA'
]
],
'Phones' => [
[
'PhoneType' => 'MOBILE',
'PhoneNumber' => '555-1234'
]
]
]);
Update Contacts
To update, a contact 2 params are required the contact id and an array of data to be updated:
See https://developer.xero.com/documentation/api/contacts#POST for details on the fields that can be updated.
$addresses = [];
$addresses[] = ContactDTO::createAddress(
$addressType,
$addressLine1,
null,
null,
null,
$city,
$region,
$postalCode,
$country
);
$addresses = [];
$phones[] = ContactDTO::createPhone(
$phoneType,
$phoneNumber,
$phoneAreaCode,
$phoneCountryCode
);
$contactDTO = new ContactDTO(
name: $name,
firstName: $firstName ?: null,
lastName: $lastName ?: null,
emailAddress: $emailAddress ?: null,
accountNumber: $accountNumber ?: null,
bankAccountDetails: $bankAccountDetails ?: null,
taxNumber: $taxNumber ?: null,
isSupplier: $isSupplier,
isCustomer: $isCustomer,
website: $website ?: null,
addresses: $addresses,
phones: $phones
);
Xero::contacts()->update($contactId, $contactDTO->toArray());
Archive Contacts
To archive a contact, you update the contact and update the contactStatus
field:
$contactDTO = new ContactDTO(
contactStatus: 'ARCHIVED'
);
Xero::contacts()->update($contactId, $contactDTO->toArray());