Getting Started
===============

We use the industry standard OSCRE/PISCES format for structuring
requests.

This will need to be POSTed to the correct endpoint as described below.

API Credentials
~~~~~~~~~~~~~~~

Credentials are required when passing requests to our API.

You will need to speak to a member of our team to get an API username
and password.

Authentication
~~~~~~~~~~~~~~

In order to authenticate a request a API username and password need to
be passed in as part of the message body.

The following example shows how to format the Authentication element.

::

   <auth:Authentication>
       <auth:Header>
           <auth:Version>2.0</auth:Version>
           <auth:Mode/>
       </auth:Header>
       <auth:AuthenticationData>
           <auth:AuthenticationKey/>
           <auth:Username>api</auth:Username>
           <auth:Password>api</auth:Password>
       </auth:AuthenticationData>
   </auth:Authentication>

Crafting the XML request
~~~~~~~~~~~~~~~~~~~~~~~~

In order to place an order you will need to construct an XML document of
the following type:

::

   <ForwardSearchOrderSend xmlns="http://www.oscre.org/ns/SRCH-Version-02/OS/ForwardSearchOrderSend" xmlns:auth="http://www.oscre.org/ns/v1/piscesauthentication">
       <auth:Authentication>
       ....
       </auth:Authentication>
       <SearchOrder>
       ...
       </SearchOrder>
   </ForwardSearchOrderSend>

Search Order
^^^^^^^^^^^^

The next element is the SearchOrder element.

::

   <SearchOrder>
   ....
   </SearchOrder>

The following fields should be placed within this element.

Search Requester Reference (Required)
'''''''''''''''''''''''''''''''''''''

This your reference. We will store this with your order for future use.

::

   <SearchOrderReference>
       <Reference>01321635</Reference>
       <AllocatedBy>SearchFacilitatorParty</AllocatedBy>
   </SearchOrderReference>

Search Facilitator Reference (Required)
'''''''''''''''''''''''''''''''''''''''

This is your customer’s reference.

::

   <SearchOrderReference>
       <Reference>MY-CUSTOMER-REF</Reference>
       <AllocatedBy>SearchRequesterParty</AllocatedBy>
   </SearchOrderReference>

Subject Property (Required)
'''''''''''''''''''''''''''

The property specifics should be provided in the following element:

::

   <SubjectProperty>
   ....
   </SubjectProperty>

PAF Address
'''''''''''

Full address details for the property.

::

   <PAFAddress>
       <Organisation>Legal Bricks Searches Ltd</Organisation>
       <POBoxDetails/>
       <SubBuildingName/>
       <BuildingName>2 Dudley Court North</BuildingName>
       <BuildingNumber />
       <DependantThoroughfareName/>
       <DependantThoroughfareDescriptor/>
       <ThoroughfareName>Waterfront East</ThoroughfareName>
       <ThoroughfareDescriptor/>
       <DoubleDependantLocality/>
       <DependantLocality>Brierley Hill</DependantLocality>
       <PostTown>Dudley</PostTown>
       <County/>
       <PostCode>DY5 1XP</PostCode>                
   </PAFAddress>         

Easting / Northing coordinates
''''''''''''''''''''''''''''''

Provide a central point of the property

::

   <Point>
       <SequenceNumeric>1</SequenceNumeric>
       <EastingNumeric>398831.63</EastingNumeric>
       <NorthingNumeric>283710.5</NorthingNumeric>
   </Point>

Plan Geometry (Required)
''''''''''''''''''''''''

A boundary extent is required and can be provided as an array of
polygons. The first is considered the outer ring and further geometries
are inner rings.

The array of points must start and end with the same point to ensure
that there is a closed polygon.

::

   <PolygonList>
       <Polygon>
           <PolygonType>PROPERTY_EASTING_AND_NORTHING</PolygonType>
           <PolygonDefines>EASTING and NORTHING of the property</PolygonDefines>
           <NumberOfCoordinatesNumeric>1</NumberOfCoordinatesNumeric>
           <Point>
               <SequenceNumeric>1</SequenceNumeric>
               <EastingNumeric>398831.63</EastingNumeric>
               <NorthingNumeric>283710.5</NorthingNumeric>
           </Point>
           <Point>
               <SequenceNumeric>2</SequenceNumeric>
               <EastingNumeric>398864.88</EastingNumeric>
               <NorthingNumeric>283725</NorthingNumeric>
           </Point>
           ....
       </Polygon>
       ....
   </PolygonList> 

Plan Attachment (Dependent)
'''''''''''''''''''''''''''

If you have ordered a product that requires a plan, then you will need
to provide this as part of your order.

This should be provided as a base64 encoded binary object. The original
file should be a zipped gif file.

::

   <PlanAttachment>
       <EmbeddedFileBinaryObject>{base64_encoded_plan}</EmbeddedFileBinaryObject>                
   </PlanAttachment>

Search Product (Required)
'''''''''''''''''''''''''

You need to provide a ProductType and a LocalAuthority.

Example:

::

   <SearchProduct>
       <ProductType>PersonalLocalAuthoritySearch</ProductType>           
       <AdditionalProductInformation>
           <Value>Dudley Metropolitan Borough Council</Value>
           <Description>LocalAuthority</Description>
       </AdditionalProductInformation>    
   </SearchProduct>

The product type must match on the product types listed below.

Allowed product codes
                     

-  PersonalLocalAuthoritySearch
-  OfficialLLC1AndCON29
-  PersonalDrainageAndWaterSearch
-  OfficialDrainageAndWaterSearch
-  TitlePlan
-  ChancelSearch
-  CoalAndBrineReport
-  LandmarkEnvirosearch
-  GroundSureEnvirosearch
-  LandmarkHomecheckProfessional
-  LandmarkHomecheckFlood

Local authority names
                     

It’s preferred that you use the ONS Code for the local authority as this
will be easier for us to lookup when creating the order.

However, you can provide us a list of the local authority names stored
in your database so that we can make sure they map to ones in ours.

The Response
~~~~~~~~~~~~

The response will be of a ForwardSearchOrderSendAcknowledge type

::

   <ForwardSearchOrderSendAcknowledge xmlns="http://www.oscre.org/ns/SRCH-Version-02/OS/ForwardSearchOrderSendAcknowledge">        
       ....        
   </ForwardSearchOrderSendAcknowledge>

Fields
^^^^^^

Search Order Reference / Search Requester Party
'''''''''''''''''''''''''''''''''''''''''''''''

This is the original reference passed as part of the request - this is
stored with the order in our database

::

   <SearchOrderReference>
       <Reference>CUST_REF_01</Reference>
       <AllocatedBy>SearchRequesterParty</AllocatedBy>
   </SearchOrderReference>

Search Order Reference / Search Facilitator Party
'''''''''''''''''''''''''''''''''''''''''''''''''

This is the facilitor reference that you pass in. We pass this back
unaltered.

Example

::

   <SearchOrderReference>
       <Reference>99900555</Reference>
       <AllocatedBy>SearchFacilitatorParty</AllocatedBy>
   </SearchOrderReference>

Search Order Reference / Search Supplier Party
''''''''''''''''''''''''''''''''''''''''''''''

This is our reference that we generate when storing the order in our
database.

Example:

::

   <SearchOrderReference>
       <Reference>6919</Reference>
       <AllocatedBy>SearchSupplierParty</AllocatedBy>
       <Description>Legal Bricks</Description>
   </SearchOrderReference>

Errors
~~~~~~

You may recieve the following resonses from the server if there was a
probelm processing the request.

The XML was badly formed
^^^^^^^^^^^^^^^^^^^^^^^^

::

   <ForwardSearchOrderSendReject xmlns="http://www.oscre.org/ns/SRCH-Version-02/OS/ForwardSearchOrderSendReject">
       <RejectionResponse>
           <Reason>There is an error in XML document (1, 1496).</Reason>
       </RejectionResponse>
   </ForwardSearchOrderSendReject>

Authentication failed
^^^^^^^^^^^^^^^^^^^^^

::

   <ForwardSearchOrderSendReject xmlns="http://www.oscre.org/ns/SRCH-Version-02/OS/ForwardSearchOrderSendReject">
       <RejectionResponse>
           <Reason>Invalid user credentials</Reason>
       </RejectionResponse>
   </ForwardSearchOrderSendReject>

Reference missing
^^^^^^^^^^^^^^^^^

::

   <ForwardSearchOrderSendReject xmlns="http://www.oscre.org/ns/SRCH-Version-02/OS/ForwardSearchOrderSendReject">
       <RejectionResponse>
           <Reason>Missing SearchOrderReference for SearchFacilitatorParty</Reason>
       </RejectionResponse>
   </ForwardSearchOrderSendReject>

Plan not provided
^^^^^^^^^^^^^^^^^

::

   <ForwardSearchOrderSendReject xmlns="http://www.oscre.org/ns/SRCH-Version-02/OS/ForwardSearchOrderSendReject">
       <RejectionResponse>
           <Reason>A plan is required for this order</Reason>
       </RejectionResponse>
   </ForwardSearchOrderSendReject>

Invalid product type
^^^^^^^^^^^^^^^^^^^^

::

   <ForwardSearchOrderSendReject xmlns="http://www.oscre.org/ns/SRCH-Version-02/OS/ForwardSearchOrderSendReject">
       <RejectionResponse>
           <Reason>Unknown product type</Reason>
       </RejectionResponse>
   </ForwardSearchOrderSendReject>

Endpoints
~~~~~~~~~

You will be provided a set of credentials for both our testing and
production environments.

The URIs are as follows

Testing: https://api-testing.legalbricks.co.uk/pisces/v2

Production: https://api.legalbricks.co.uk/pisces/v2

Testing
~~~~~~~

Testing should be performed against the ‘testing’ environment (using the
testing endpoint as specified)

You can test using Curl, e.g ordering a search using the order sample
xml file:

::

   curl -X POST -H "Content-Type: application/xml" -d @/mnt/d/misc/xml/order.xml https://api-testing.legalbricks.co.uk/pisces/v2/

or PowerShell

::

   Invoke-RestMethod -Uri https://api-testing.legalbricks.co.uk/pisces/v2 -Method POST -InFile .\order.xml