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());