searchCustomers
Search for customers.
Description
This method allows you to search the customer database using flexible search terms. This method searches the customer database (aka recurring billing) not the transactions history. To search the transaction history for a specific customer, use either the searchTransactions or getCustomerHistory method.
Use as many or as few search terms as you like. With MatchAll set to "true," all terms must match to return a result. If the search does not yield the desired results, try broadening your search by eliminating terms, or change MatchAll to "false."
Valid field names for search and sort are:
- BillingAddress.FirstName
- BillingAddress.lastname
- BillingAddress.Company
- BillingAddress.Street
- BillingAddress.Street2
- BillingAddress.City
- BillingAddress.State
- BillingAddress.Zip
- BillingAddress.Country
- BillingAddress.Phone
- BillingAddress.Fax
- BillingAddress.Email
- Amount
- CustNum
- CustomerID
- Created
- Description
- Enabled
- Failures
- Modified
- Start
- Next
- Notes
- NumLeft
- OrderID
- ReceiptNote
- Schedule (1=Daily,2=Weekly,3=Bi-Weekly,4=Monthly,5=Bi-Monthly,6=Quarterly,7=Bi-Annually,8=Annually,9=First of Month, 10=Last Day of Month)
- SendReceipt
- Source
- Tax
- User
- CustomFields (custom1, custom2, custom3, etc)
See also searchcustomerscustom, searchcustomerscount, searchCustomerID
Syntax
CustomerSearchResult searchCustomers ( ueSecurityToken Token, SearchParam Search, boolean MatchAll, integer Start, integer Limit, string Sort)
Arguments
| Type | Name | Description |
|---|---|---|
| ueSecurityToken | Token | Merchant security token: used to identify merchant and validate transaction. |
| SearchParam | Search | Array of search parameters. |
| boolean | MatchAll | If set to "true," only results matching all search criteria will be returned, if set to "false," results matching any of the search criteria will be returned. |
| integer | Start | Start position, defaults to 0 (first customer found). |
| integer | Limit | Maximum number of customers to return in result. |
| string | Sort | Field name to sort the results by |
Return Value
| Type | Description |
|---|---|
| CustomerSearchResult | Returns results of customer search based on parameters set. |
Examples
PHP
For directions on how to set up the WSDL link, create "$token" and "$client", go to PHP Soap How-to.
<?php
try {
$search=array(
array(
'Field'=>'amount',
'Type'=>'gt',
'Value'=>'8.00'),
array(
'Field'=>'failures',
'Type'=>'gt',
'Value'=>'0')
);
$start=0;
$limit=10;
$matchall=true;
$RefNum=1009411;
$Sort = "fname";
$res=$client->searchCustomers($token,$search,$matchall,$start,$limit,$Sort);
print_r($res);
$this->assertTrue($res->CustomersMatched>0 && $res->CustomersReturned>0);
}
catch (SoapFault $e) {
die("Search Customers failed :" .$e->getMessage());
}
?>
.NET VB
Dim matchAll As Boolean
matchAll = True
Dim search(0) As newtek.SearchParam
search(0) = New newtek.SearchParam()
search(0).Field = "Created"
search(0).Type = "Contains"
search(0).Value = "2010-09-09"
Dim response As newtek.CustomerSearchResult = New newtek.CustomerSearchResult
response = client.searchCustomers(token, search, matchAll, "0", "10", "fname")
MsgBox(response.CustomersMatched)
.NET C
For directions on how to set up the WSDL link and create the "token" and "client" variables, go to the C Sharp .Net Soap How-to.
Boolean matchAll;
matchAll = true;
newtek.SearchParam[] search = new newtek.SearchParam[2];
search[0] = new newtek.SearchParam();
search[0].Field = "Created";
search[0].Type = "Contains";
search[0].Value = "2010-08-10";
newtek.CustomerSearchResult response = new newtek.CustomerSearchResult();
try
{
response = client.searchCustomers(token, search, matchAll, "0", "10", "fname");
MessageBox.Show(response.CustomersMatched);
}
catch (Exception err)
{
MessageBox.Show(err.Message);
}
XML
Request:
<?xml version="1.0" encoding="UTF-8"?>
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"xmlns:ns1="urn:newtek"
xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:SOAP-ENC="http://schemas.xmlsoap.org/soap/encoding/"
SOAP-ENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
<SOAP-ENV:Body>
<ns1:searchCustomers>
<Token xsi:type="ns1:ueSecurityToken">
<ClientIP xsi:type="xsd:string">123.123.123.123</ClientIP>
<PinHash xsi:type="ns1:ueHash">
<HashValue xsi:type="xsd:string">1766a93e46bf263b409d0f444b2eb34b00daa035</HashValue>
<Seed xsi:type="xsd:string">1345308215-test</Seed>
<Type xsi:type="xsd:string">sha1</Type>
</PinHash>
<SourceKey xsi:type="xsd:string">_B4P7C4K2w2ZCQQQXRqrxDj6agrS2NIT</SourceKey>
</Token>
<Search SOAP-ENC:arrayType="ns1:SearchParam[1]" xsi:type="ns1:SearchParamArray">
<item xsi:type="ns1:SearchParam">
<Field xsi:type="xsd:string">customerid</Field>
<Type xsi:type="xsd:string">contains</Type>
<Value xsi:type="xsd:string">380</Value>
</item>
</Search>
<MatchAll xsi:type="xsd:boolean">true</MatchAll>
<Start xsi:type="xsd:integer">0</Start>
<Limit xsi:type="xsd:integer">9999</Limit>
<Sort xsi:nil="true"/></ns1:searchCustomers>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>
Reponse:
<?xml version="1.0" encoding="utf-8"?>
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"xmlns:ns1="urn:newtek"
xmlns:SOAP-ENC="http://schemas.xmlsoap.org/soap/encoding/"xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
SOAP-ENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
<SOAP-ENV:Body>
<ns1:searchCustomersResponse>
<searchCustomersReturn xsi:type="ns1:CustomerSearchResult">
<Customers SOAP-ENC:arrayType="ns1:CustomerObject[1]" xsi:type="ns1:CustomerObjectArray">
<item xsi:type="ns1:CustomerObject">
<Amount xsi:type="xsd:double">44.93</Amount>
<BillingAddress xsi:type="ns1:Address">
<City xsi:type="xsd:string">Los Angeles</City>
<Company xsi:type="xsd:string">Acme Corp</Company>
<Country xsi:type="xsd:string">US</Country>
<Email xsi:type="xsd:string">joe@example.com</Email>
<Fax xsi:type="xsd:string">333-333-3334</Fax>
<FirstName xsi:type="xsd:string">John</FirstName>
<LastName xsi:type="xsd:string">Doe</LastName>
<Phone xsi:type="xsd:string">333-333-3333</Phone>
<State xsi:type="xsd:string">CA</State>
<Street xsi:type="xsd:string">1234 main st</Street>
<Street2 xsi:type="xsd:string">Suite #123</Street2>
<Zip xsi:type="xsd:string">12345</Zip>
</BillingAddress>
<Created xsi:type="xsd:dateTime">2015-12-07T16:35:00+08:00</Created>
<Currency xsi:type="xsd:string">0</Currency>
<CustNum xsi:type="xsd:string">4606627</CustNum>
<CustomData xsi:type="xsd:string"></CustomData>
<CustomFields SOAP-ENC:arrayType="ns1:FieldValue[0]" xsi:type="ns1:FieldValueArray" />
<CustomerID xsi:type="xsd:string">380</CustomerID>
<Description xsi:type="xsd:string">Weekly Bill</Description>
<Enabled xsi:type="xsd:boolean">true</Enabled>
<Failures xsi:type="xsd:int">0</Failures>
<LookupCode xsi:type="xsd:string"></LookupCode>
<Modified xsi:type="xsd:dateTime">2015-12-07T16:35:00+08:00</Modified>
<Next xsi:type="xsd:string">2016-12-01T12:00:00</Next>
<Notes xsi:type="xsd:string">Testing the soap addCustomer Function</Notes>
<NumLeft xsi:type="xsd:integer">50</NumLeft>
<OrderID xsi:type="xsd:string">1698032860</OrderID>
<PaymentMethods SOAP-ENC:arrayType="ns1:PaymentMethod[1]" xsi:type="ns1:PaymentMethodArray">
<item xsi:type="ns1:PaymentMethod">
<MethodType xsi:type="xsd:string">cc</MethodType>
<MethodID xsi:type="xsd:string">115</MethodID>
<MethodName xsi:type="xsd:string">CreditCard</MethodName>
<SecondarySort xsi:type="xsd:integer">8</SecondarySort>
<Created xsi:type="xsd:dateTime">2015-12-07T16:35:00+08:00</Created>
<Modified xsi:type="xsd:dateTime">2015-12-07T16:35:00+08:00</Modified>
<CardExpiration xsi:type="xsd:string">2018-12</CardExpiration>
<CardNumber xsi:type="xsd:string">XXXXXXXXXXXX7779</CardNumber>
<CardType xsi:type="xsd:string">V</CardType>
</item>
</PaymentMethods>
<PriceTier xsi:type="xsd:string"></PriceTier>
<ReceiptNote xsi:type="xsd:string">addCustomer test Created Charge</ReceiptNote>
<Schedule xsi:type="xsd:string">Weekly</Schedule>
<SendReceipt xsi:type="xsd:boolean">true</SendReceipt>
<Source xsi:type="xsd:string">Recurring</Source>
<Tax xsi:type="xsd:double">0</Tax>
<TaxClass xsi:type="xsd:string"></TaxClass>
<User xsi:type="xsd:string">(Auto)</User>
<URL xsi:type="xsd:string"></URL>
</item>
</Customers>
<CustomersMatched xsi:type="xsd:integer">1</CustomersMatched>
<CustomersReturned xsi:type="xsd:integer">1</CustomersReturned>
<Limit xsi:type="xsd:integer">1000</Limit>
<StartIndex xsi:type="xsd:integer">0</StartIndex>
</searchCustomersReturn>
</ns1:searchCustomersResponse>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>