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
