Find Clients Service

The Find Clients service is a DISQ service used to retrieve client fixed and dynamic fields, as well as client address fixed and dynamic fields. DISQ services in general allow an external application to access data in the OIPA system by using requests, which utilize a formal XML schema that is both easy to understand and flexible in its application.

In OIPA, a client is an entity that represents an individual or an organization. Client is one of several entities supported in the DISQ model. The Client entity is a child entity with respect to the Company entity, and is a parent entity with respect to the Address entity.

Using the Find Clients DISQ request, the user can retrieve client data stored in the following database tables:

AsClient
AsClientField
AsAddress
AsAddressField
AsAddressRole

Field names used in DISQ requests are case sensitive, and any field included in the request must be configured in OIPA at the context where the request is being sent.

Find Client Elements/Attributes

Element/Tag	Definition	Element/Attribute Value and Description
<DisqRequest>	Required element: The parent element of a DISQ request.
<Header>	Optional element: Container element for the <Message ID> and <TimeStamp> elements.
<MessageId>	Optional element: Designates a message ID for the DISQ request.	A string value
<TimeStamp>	Optional element: Designates a timestamp for the DISQ request.	A string representing a timestamp
<Context>	Required element: The Context is the DISQ means of identifying the resource of an entity. Since Context is tied to the Action being requested, it is essential that the Context uniquely identifies a single resource. For the Find Clients service, Company is the only context allowed.
<Company>	Required element: Establishes the resource from which the client is found.
<CompanyName>	Required element: Holds the name of the company to which the client belongs.	The name of a company to which a client belongs.
<Find>	Required element: The parent element of the Find action. Find is a data retrieval action that can retrieve multiple resources for an entity in the system. From the Client context, the Find action retrieves multiple clients.
<Client>	Required, repeatable element: Holds child elements that specify the entity whose data is to be retrieved. When multiple <Client> elements are present, the request will retrieve clients that satisfy the criteria within any one of the <Client> elements.
<ClientGuid>	Optional element: Holds the GUID for the client whose information is being requested. If a client GUID is provided, the individual client is directly identified, and no other identifying criteria will be recognized.	A client's GUID.
<[Client fixed field]>	Optional, repeatable element: The name of each of these elements should be the name of a client fixed field, such as LastName, FirstName or TaxID. These elements and their values are used to identify clients. When multiple client fixed field elements are used within the <Client> element, the request will only retrieve clients that satisfy all of the specified client criteria. If there are multiple references to the same fixed field, only the last reference is recognized.	The value to search for. See the Client Fixed Fields section below for a complete list of client fixed fields that can be used in a DISQ request. For example: <LastName>Smith</LastName> <FirstName>John</FirstName>
<Addresses>	Optional element: A container element for the <Address> sub-element. This element should be used when a clients' address information can aid in identifying clients.
<Address>	Optional element: This element is used to list the address criteria to be used in identifying clients. If more than one <Address> element is present, only the first will be recognized.
<[Address fixed field]>	Required, repeatable element: The name of each of these elements should be the name of an address fixed field, such as <City> or <CountryCode>. If one or more clients have addresses that satisfy the criteria specified within these elements, the clients will be returned from the service. When multiple address fixed field elements are used within the <Find> action, the request will only retrieve clients that satisfy all of the specified address criteria. At least one address fixed field must be provided if searching for addresses. If there are multiple references to the same fixed field, only the last reference is recognized.	The value to search for. See the Address Fixed Fields section below for a complete list of address fixed fields that can be used in a DISQ request. For example: <City>Philadelphia</City> <CountryCode>US</CountryCode>
<ResponseFormat>	Optional element: The <ResponseFormat> section allows the requestor to specify what should be included in the response from the DISQ request. The responses returned from a Find Client service can contain fixed and dynamic field data for both client and address fields. Note: If <ResponseFormat> is omitted, then only client fixed fields are returned, as that is the default response type.
<ResponseType>	Optional element: This element specifies whether only client fixed fields should be returned from the request, or if other field data should be returned as well.	Default: Only client fixed fields will be returned from the request. Custom: The user can specify client dynamic fields, address fixed fields and address dynamic fields to be returned along with client fixed fields.
<Client>	Optional element: This element allows client dynamic fields to be returned when valid child elements are present. If multiple <Client> elements are present, only the last is recognized. If this element is omitted, only Client fixed fields are returned.
<Fields>	Optional element: This is the container element for the client dynamic field data that should be returned from the request. If this element is empty, data for all client dynamic fields will be returned. If multiple <Fields> elements are present, only the last is recognized. If this element is omitted, only client fixed fields will be returned.
<[Client dynamic field]>	Optional, repeatable element: The name of each of these elements should be the name of a client dynamic field. Data will be returned for each dynamic client field specified. If a field is repeated, the return will contain one instance of the field’s data.
<Addresses>	Optional element: The presence of this element indicates that address data should be returned. Its child elements specify which Address resources should be returned and whether all or specific address fixed field information should be returned.
<Address>	Optional, repeatable element: This is the container element for the address dynamic field data that should be returned from the request. If this element is empty, only fixed address fields will be returned for all addresses. When more than one <Address> element is provided, the request will return all addresses that satisfy any one of the conditions specified across all the <Address> elements.
<[Address fixed field]>	Optional, repeatable element: The name of each of these elements should be the name of an address fixed field, such as <City> or <CountryCode>. These elements provide the criteria that filter the address resources to return in the response. If more than one address fixed field element is present, an address must satisfy all the criteria contained within the same <Address> element to be returned from the request.	The value to search for. See the Address Fixed Fields section below for a complete list of address fixed fields that can be used in a DISQ request. For example: <City>Philadelphia</City>
<Fields>	Optional element: This is the container element for the address dynamic field data that should be returned from the request. If this element is empty, data for all address dynamic fields will be returned. If multiple <Fields> elements are provided, only the last will be recognized.
<[Address dynamic field]>	Optional, repeatable element: The name of each of these elements should be the name of an address dynamic field. Data will be returned for each dynamic address field specified.

Client Fixed Fields

Below are all of the client fixed fields that can be used to identify a client.

AdditionalPrefix
AdditionalSuffix
AlternateName1
AlternateName2
AlternateName3
AlternateName4
AlternateName5
BirthCountryCode
BirthRegionCode
CheckBox1
CheckBox2
CitizenshipCountryCode
ClientGuid
Combo1

Address Fixed Fields

Below are all of the address fixed fields that can be used to identify a client.

AddressGuid
Line1
Line2
Line3
Line4
Line5
Line6
AddressRoleCode

AddressRoleGuid
City
CountryCode
DefaultFlag
EffectiveDate
Email
EmailCorrespondenceFlag
ExpirationDate

FaxNumber
MunicipalityCode
PhoneNumber
PostalId
RegionCode
StateCode

XML Schema

<DisqRequest>

<Header>

<MessageId>[message id]</MessageId>

<TimeStamp>[time stamp]</TimeStamp>

</Header>

<Context>

<Company>

<CompanyName>[company name]</CompanyName>

</Company>

</Context>

<Find>

<Client>

<ClientGuid>[ClientGUID]</ClientGuid>

<[client_fixed_field_1]>[value to search]</[client_fixed_field_1]>

<[client_fixed_field_n]>[value to search]</[client_fixed_field_n]>

<Addresses>

<Address>

<[address_fixed_field_1]>[value to search]</[address_fixed_field_1]>

<[address_fixed_field_n]>[value to search]</[address_fixed_field_n]>

</Address>

</Addresses>

</Client>

<Client>. . .</Client>

</Find>

<ResponseFormat>

<ResponseType>[Default|Custom]</ResponseType>

<Client>

<Fields>

<[client_dynamic_field_1]></[client_dynamic_field_1]>

<[client_dynamic_field_n]></[client_dynamic_field_n]>

</Fields>

<Addresses>

<Address>

<[address_fixed_field_1]>[value to search]</[address_fixed_field_1]>

<[address_fixed_field_n]>[value to search]</[address_fixed_field_n]>

<Fields>

<[address_dynamic_field_1]></[address_dynamic_field_1]>

<[address_dynamic_field_n]></[address_dynamic_field_n]>

</Fields>

</Address>

<Address> . . . </Address>

</Addresses>

</Client>

</ResponseFormat>

</DisqRequest>