Skip to main content

Legacy SOAP API

Legacy SOAP API

This API is principally provided for those upgrading to Address Lookup from Hopewiser’s original SOAP API.

This API will continue to be supported as part of Address Lookup. However, if you are just starting an integration we think you will prefer our new SOAP Address Service API.

SOAPAtlas API

For clients employing .NET, we have a .NET WSDL which is specifically targeted towards users choosing to deploy utilising .NET.

Most other users will want to use the unbounded WSDL which has been tested as compliant with Basic Profile 1.0 and Basic Profile 1.1 with the WSI test tool, making it the recommended WSDL.

We also have a soaparray WSDL which uses SOAP array encoding for those client systems which cannot work with the unbounded WSDL.

Users who cannot import a WSDL file will need to use the sample XML responses and requests provided in the documentation for each call to interact with the SOAP service. The documentation describes the unbounded endpoint which has the cleanest XML.

Related Topics

Refer to “Functions”, “Data Fields”, “Status Codes” and “Sample Code” sections below.

See also the Frequently Asked Questions

Functions

Login

Logs in to the Hopewiser SOAP server and starts a client session.

Syntax

string session_id = soap.login(string login, string password);

Usage

When a client application invokes the Login call, it passes in a user name and password. Upon invocation, the Hopewiser SOAP server authenticates the login and returns the Session ID for the session. This session ID must be used in all subsequent calls to the Hopewiser SOAP server.

Client applications do not need to explicitly log out to end the session. Sessions expire automatically after a period of inactivity.

Samples

<SOAP-ENV:Envelope>
  <SOAP-ENV:Body>
    <ns1:login>
      <login>
        <login>my_user</login>
        <password>my_password</password>
      </login>
    </ns1:login>
  </SOAP-ENV:Body>
</SOAP-ENV:Envelope>
<SOAP-ENV:Envelope SOAP-ENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
  <SOAP-ENV:Body>
    <namesp1:loginResponse>
      <session_id>my_user.1bb3db9b-ca7a-494b-97de-7af05f5a688b-r-banjo=1+</session_id>
    </namesp1:loginResponse>
  </SOAP-ENV:Body>
</SOAP-ENV:Envelope>

Version

Obtains SOAP Server version information from the Hopewiser SOAP Server. The Module Id should be omitted or left blank.

If you have purchased access to more than one dataset, you can specify which you would like to use in the Dataset input. If you omit the field, provide an empty value or use the value “default”, the default for the login associated with the session is used. A typical dataset name is uk-rm-paf-internal which indicates the Royal Mail PAF for UK data being used internally by an organisation. Contact your account holder for information on which datasets you should have access to. They will have been provided with the information or can contact our support desk.

Syntax

Version version = soap.version(string session_id , "" [, string dataset]);

where for example:

version = {
            'SERVER' => 'SOAPAtlas Version: A/S 1.0.25',
            'ATLAS'  => 'Atlas Version: 3.50.01 (fh:3.5.0 xfh:2.0.0)',
            'PAF'    => 'MAF Version 34 (U )  UNITED KINGDOM  Built 20120321',
          };

Usage

When a client application invokes the Version call, it passes in a Session ID and an optional Dataset. Upon invocation, the Hopewiser SOAP server authenticates the Session ID and returns a Version structure similar to that described above.

Samples

<SOAP-ENV:Envelope>
  <SOAP-ENV:Body>
    <ns1:version>
      <version>
        <session_id>SESSION</session_id>
        <dataset>uk-rm-paf-internal</dataset>
      </version>
    </ns1:version>
  </SOAP-ENV:Body>
</SOAP-ENV:Envelope>
<SOAP-ENV:Envelope SOAP-ENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
  <SOAP-ENV:Body>
    <namesp1:versionResponse>
      <version>
        <ATLAS>Atlas Version: 3.50.02 (fh:3.5.0 xfh:2.0.0)</ATLAS>
        <PAF>MAF Version 36 (U )  UNITED KINGDOM  Built 20120524</PAF>
        <SERVER>SOAPAtlas Version: A/S 1.0.31</SERVER>
      </version>
    </namesp1:versionResponse>
  </SOAP-ENV:Body>
</SOAP-ENV:Envelope>

AH21

Obtains a list of matching premises for a given postcode from the Hopewiser SOAP Server.

Syntax

Addresses [] addresses = soap.ah21(string session_id, string input [, string data] [, string dataset]);

where for example:

input = 'WA14 5NL,HOPE*';

data = 'DISTRICT_LEVEL,TOWN,POSTCODE,COUNTY,COUNTRY';

dataset = 'uk-rm-paf-internal';

address = [
              {
                'LABEL' => [
                             'Hopewiser Ltd',
                             'Merlin Court',
                             'Atlantic Street',
                             'ALTRINCHAM',
                             'Cheshire',
                             'WA14 5NL',
                             'UNITED KINGDOM'
                           ],
                'DISTRICT_LEVEL' => [
                                      'Hopewiser Ltd',
                                      'Merlin Court',
                                      'Atlantic Street'
                                    ],
                'TOWN' => 'ALTRINCHAM',
                'POSTCODE' => 'WA14 5NL',
                'COUNTY' => 'CHESHIRE',
                'COUNTRY' => 'UNITED KINGDOM'
              }
            ];

Usage

When a client application invokes the AH21 call, it passes in a Session ID, an input string (consisting of a postcode and an optional premise separated by a comma) and an optional data string (consisting of any additional Data Fields which the user would like generated separated by commas). Upon invocation, the Hopewiser SOAP server authenticates the Session ID and returns an Addresses structure similar to that described above.

The LABEL element of the Addresses structure is ALWAYS returned whether or not a data string is provided. It is likely that this is the address that will be displayed to the user.

Choosing a dataset

If you have purchased access to more than one dataset, you can specify which you would like to use in the Dataset input (not to be confused with the data string). If you omit the field, provide an empty value or use the value “default”, the default for the login associated with the session is used. A typical dataset name is uk-rm-paf-internal which indicates the Royal Mail PAF for UK data being used internally by an organisation. Contact your account holder for information on which datasets you should have access to. They will have been provided with the information or you can contact our support team.

Samples

<SOAP-ENV:Envelope>
  <SOAP-ENV:Body>
    <ns1:ah21>
      <ah21>
        <session_id>SESSION</session_id>
        <input>WA14 5NL</input>
        <data>district_level,town,county,postcode,dps,country</data>
        <dataset>uk-rm-paf-internal</dataset>
      </ah21>
    </ns1:ah21>
  </SOAP-ENV:Body>
</SOAP-ENV:Envelope>
<SOAP-ENV:Envelope SOAP-ENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
  <SOAP-ENV:Body>
    <namesp1:ah21Response>
      <addresses>
        <address>
          <COUNTRY>UNITED KINGDOM</COUNTRY>
          <COUNTY>CHESHIRE</COUNTY>
          <DISTRICT_LEVEL>
            <item>Carol Nash Training Centre</item>
            <item>Merlin Court</item>
            <item>Atlantic Street</item>
          </DISTRICT_LEVEL>
          <DPS>1DS</DPS>
          <LABEL>
            <item>Carol Nash Training Centre</item>
            <item>Merlin Court</item>
            <item>Atlantic Street</item>
            <item>ALTRINCHAM</item>
            <item>Cheshire</item>
            <item>WA14 5NL</item>
            <item>UNITED KINGDOM</item>
          </LABEL>
          <POSTCODE>WA14 5NL</POSTCODE>
          <TOWN>ALTRINCHAM</TOWN>
        </address>
        <address>
          <COUNTRY>UNITED KINGDOM</COUNTRY>
          <COUNTY>CHESHIRE</COUNTY>
          <DISTRICT_LEVEL>
            <item>Hopewiser Ltd</item>
            <item>Merlin Court</item>
            <item>Atlantic Street</item>
          </DISTRICT_LEVEL>
          <DPS>1HQ</DPS>
          <LABEL>
            <item>Hopewiser Ltd</item>
            <item>Merlin Court</item>
            <item>Atlantic Street</item>
            <item>ALTRINCHAM</item>
            <item>Cheshire</item>
            <item>WA14 5NL</item>
            <item>UNITED KINGDOM</item>
          </LABEL>
          <POSTCODE>WA14 5NL</POSTCODE>
          <TOWN>ALTRINCHAM</TOWN>
        </address>
        <address>
          <COUNTRY>UNITED KINGDOM</COUNTRY>
          <COUNTY>CHESHIRE</COUNTY>
          <DISTRICT_LEVEL>
            <item>Matrix Telmatics Ltd</item>
            <item>Merlin Court</item>
            <item>Atlantic Street</item>
          </DISTRICT_LEVEL>
          <DPS>1FO</DPS>
          <LABEL>
            <item>Matrix Telmatics Ltd</item>
            <item>Merlin Court</item>
            <item>Atlantic Street</item>
            <item>ALTRINCHAM</item>
            <item>Cheshire</item>
            <item>WA14 5NL</item>
            <item>UNITED KINGDOM</item>
          </LABEL>
          <POSTCODE>WA14 5NL</POSTCODE>
          <TOWN>ALTRINCHAM</TOWN>
        </address>
        <address>
          <COUNTRY>UNITED KINGDOM</COUNTRY>
          <COUNTY>CHESHIRE</COUNTY>
          <DISTRICT_LEVEL>
            <item>Northern Monitoring Services</item>
            <item>Merlin Court</item>
            <item>Atlantic Street</item>
          </DISTRICT_LEVEL>
          <DPS>1LU</DPS>
          <LABEL>
            <item>Northern Monitoring Services</item>
            <item>Merlin Court</item>
            <item>Atlantic Street</item>
            <item>ALTRINCHAM</item>
            <item>Cheshire</item>
            <item>WA14 5NL</item>
            <item>UNITED KINGDOM</item>
          </LABEL>
          <POSTCODE>WA14 5NL</POSTCODE>
          <TOWN>ALTRINCHAM</TOWN>
        </address>
        <address>
          <COUNTRY>UNITED KINGDOM</COUNTRY>
          <COUNTY>CHESHIRE</COUNTY>
          <DISTRICT_LEVEL>
            <item>T I C Group Ltd</item>
            <item>Merlin Court</item>
            <item>Atlantic Street</item>
          </DISTRICT_LEVEL>
          <DPS>1JY</DPS>
          <LABEL>
            <item>T I C Group Ltd</item>
            <item>Merlin Court</item>
            <item>Atlantic Street</item>
            <item>ALTRINCHAM</item>
            <item>Cheshire</item>
            <item>WA14 5NL</item>
            <item>UNITED KINGDOM</item>
          </LABEL>
          <POSTCODE>WA14 5NL</POSTCODE>
          <TOWN>ALTRINCHAM</TOWN>
        </address>
        <address>
          <COUNTRY>UNITED KINGDOM</COUNTRY>
          <COUNTY>CHESHIRE</COUNTY>
          <DISTRICT_LEVEL>
            <item>UK Coach Search Ltd</item>
            <item>Merlin Court</item>
            <item>Atlantic Street</item>
          </DISTRICT_LEVEL>
          <DPS>1ET</DPS>
          <LABEL>
            <item>UK Coach Search Ltd</item>
            <item>Merlin Court</item>
            <item>Atlantic Street</item>
            <item>ALTRINCHAM</item>
            <item>Cheshire</item>
            <item>WA14 5NL</item>
            <item>UNITED KINGDOM</item>
          </LABEL>
          <POSTCODE>WA14 5NL</POSTCODE>
          <TOWN>ALTRINCHAM</TOWN>
        </address>
      </addresses>
    </namesp1:ah21Response>
  </SOAP-ENV:Body>
</SOAP-ENV:Envelope>

ListAPI

Searches using at least two address elements on the Hopewiser SOAP Server.

Syntax

Addresses [] addresses = soap.listapi(string session_id, string input [, string data] [, string dataset]);

where for example:

input = 'atlantic street,altrincham';

data = 'DISTRICT_LEVEL,TOWN,POSTCODE,COUNTY,COUNTRY';

dataset = 'uk-rm-paf-internal';

address = [
            {
              'ID' => '%+0%ATLANTIC STREET||ALTRINCHAM',
              'LABEL' => [
                           '+ Aegean Road,Atlantic Street,Broadheath,Altrincham',
                         ]
            },
            ...
            {
              'ID' => '%+6%ATLANTIC STREET||ALTRINCHAM',
              'LABEL' => [
                           '+ Atlantic Street,Altrincham'
                         ]
            },
            ...
          ];

or:

input = '%+1+0+6%ATLANTIC STREET||ALTRINCHAM';

data = 'DISTRICT_LEVEL,TOWN,POSTCODE,COUNTY,COUNTRY';

dataset = 'uk-rm-paf-internal';

address = [
              {
                'LABEL' => [
                                      'Hopewiser Ltd',
                                      'Merlin Court',
                                      'Atlantic Street',
                                      'ALTRINCHAM',
                                      'Cheshire',
                                      'WA14 5NL',
                                      'UNITED KINGDOM'

                           ],
                'DISTRICT_LEVEL' => [
                                      'Hopewiser Ltd',
                                      'Merlin Court',
                                      'Atlantic Street',
                           ],
                'TOWN' => 'ALTRINCHAM',
                'POSTCODE' => 'WA14 5NL',
                'COUNTY' => 'CHESHIRE',
                'COUNTRY' => 'UNITED KINGDOM'
              }
            ];

Usage

When a client application invokes the ListAPI call, it passes in a Session ID, an input string (consisting of at least two address elements separated by commas) and an optional data string (consisting of any additional Data Fields which the user would like generated separated by commas). Upon invocation, the Hopewiser SOAP server authenticates the Session ID and returns an Addresses structure similar to that described above.

The LABEL element of the Addresses structure is ALWAYS returned whether or not a data string is provided. It is likely that this is the address that will be displayed to the user.

The structure returned by the ListAPI call is always an array:

  • If multiple results are returned, each result will be a partial address and contain an ID. An ID can be re-submitted to the ListAPI call to expand on that partial address.
  • If a single result is returned it may or may not contain an ID. If it does contain an ID, the result is a partial address. The ID can be resubmitted to the ListAPI call to expand the partial address.
  • If a single result is returned and it does not contain an ID, the result is a complete address and as such any additional Data Fields requested will also be returned.

For instance, a search to find the full address of Hopewiser Ltd from a partial address of Atlantic Street, Altrincham would take the following steps:

Input to ListAPI Output from ListAPI
atlantic street,altrincham
address = [
            ...,
            {
              'ID' => '%+6%ATLANTIC STREET||ALTRINCHAM',
              'LABEL' => [
                           '+ Atlantic Street,Altrincham'
                         ]
            },
            ...
          ];
%+6%ATLANTIC STREET||ALTRINCHAM
address = [
            ...,
            {
              'ID' => '%+1+0+6%ATLANTIC STREET||ALTRINCHAM',
              'LABEL' => [
                           '  Hopewiser Ltd',
                           '+ Merlin Court',
                           '+ Atlantic Street,Altrincham'
                         ]
            },
            ...
          ];
%+1+0+6%ATLANTIC STREET||ALTRINCHAM
address = [
              {
                'LABEL' => [
                             'Hopewiser Ltd',
                             'Merlin Court',
                             'Atlantic Street',
                             'ALTRINCHAM',
                             'Cheshire',
                             'WA14 5NL',
                             'UNITED KINGDOM'
                           ],
                'DISTRICT_LEVEL' => [
                                      'Hopewiser Ltd',
                                      'Merlin Court',
                                      'Atlantic Street'
                                    ],
                'TOWN' => 'ALTRINCHAM',
                'POSTCODE' => 'WA14 5NL',
                'COUNTY' => 'CHESHIRE',
                'COUNTRY' => 'UNITED KINGDOM'
              }
            ];

And so we are able to reach our complete address in three steps.

Choosing a dataset

If you have purchased access to more than one dataset, you can specify which you would like to use in the Dataset input (not to be confused with the data string). If you omit the field, provide an empty field or use the value “default”, the default for the login associated with the session is used. A typical dataset name is uk-rm-paf-internal which indicates the Royal Mail PAF for UK data being used internally by an organisation. Contact your account holder for information on which datasets you should have access to; they will have been provided with the information or you can contact our support team.

Sample – Multiple Partial Addresses and Single Complete Address

<SOAP-ENV:Envelope>
  <SOAP-ENV:Body>
    <ns1:listapi>
      <listapi>
        <session_id>SESSION</session_id>
        <input>WA14 5NL</input>
        <data>district_level,town,county,postcode,dps,country</data>
        <dataset>uk-rm-paf-internal</dataset>
      </listapi>
    </ns1:listapi>
  </SOAP-ENV:Body>
</SOAP-ENV:Envelope>
<SOAP-ENV:Envelope SOAP-ENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
  <SOAP-ENV:Body>
    <namesp1:listapiResponse>
      <addresses>
        <address>
          <ID>%+0+0+0%WA14 5NL</ID>
          <LABEL>
            <item>  Carol Nash Training Centre</item>
            <item>+ Merlin Court</item>
            <item>+ Atlantic Street,Altrincham,Cheshire</item>
          </LABEL>
        </address>
        <address>
          <ID>%+1+0+0%WA14 5NL</ID>
          <LABEL>
            <item>  Hopewiser Ltd</item>
            <item>+ Merlin Court</item>
            <item>+ Atlantic Street,Altrincham,Cheshire</item>
          </LABEL>
        </address>
        <address>
          <ID>%+2+0+0%WA14 5NL</ID>
          <LABEL>
            <item>  Matrix Telmatics Ltd</item>
            <item>+ Merlin Court</item>
            <item>+ Atlantic Street,Altrincham,Cheshire</item>
          </LABEL>
        </address>
        <address>
          <ID>%+3+0+0%WA14 5NL</ID>
          <LABEL>
            <item>  Northern Monitoring Services</item>
            <item>+ Merlin Court</item>
            <item>+ Atlantic Street,Altrincham,Cheshire</item>
          </LABEL>
        </address>
        <address>
          <ID>%+4+0+0%WA14 5NL</ID>
          <LABEL>
            <item>  T I C Group Ltd</item>
            <item>+ Merlin Court</item>
            <item>+ Atlantic Street,Altrincham,Cheshire</item>
          </LABEL>
        </address>
        <address>
          <ID>%+5+0+0%WA14 5NL</ID>
          <LABEL>
            <item>  UK Coach Search Ltd</item>
            <item>+ Merlin Court</item>
            <item>+ Atlantic Street,Altrincham,Cheshire</item>
          </LABEL>
        </address>
      </addresses>
    </namesp1:listapiResponse>
  </SOAP-ENV:Body>
</SOAP-ENV:Envelope>
<SOAP-ENV:Envelope>
  <SOAP-ENV:Body>
    <ns1:listapi>
      <listapi>
        <session_id>SESSION</session_id>
        <input>%+1+0+0%WA14 5NL</input>
        <data>district_level,town,county,postcode,dps,country</data>
        <dataset>uk-rm-paf-internal</dataset>
      </listapi>
    </ns1:listapi>
  </SOAP-ENV:Body>
</SOAP-ENV:Envelope>
<SOAP-ENV:Envelope SOAP-ENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
  <SOAP-ENV:Body>
    <namesp1:listapiResponse>
      <addresses>
        <address>
          <COUNTRY>UNITED KINGDOM</COUNTRY>
          <COUNTY>CHESHIRE</COUNTY>
          <DISTRICT_LEVEL>
            <item>Hopewiser Ltd</item>
            <item>Merlin Court</item>
            <item>Atlantic Street</item>
          </DISTRICT_LEVEL>
          <DPS>1HQ</DPS>
          <LABEL>
            <item>Hopewiser Ltd</item>
            <item>Merlin Court</item>
            <item>Atlantic Street</item>
            <item>ALTRINCHAM</item>
            <item>Cheshire</item>
            <item>WA14 5NL</item>
            <item>UNITED KINGDOM</item>
          </LABEL>
          <POSTCODE>WA14 5NL</POSTCODE>
          <TOWN>ALTRINCHAM</TOWN>
        </address>
      </addresses>
    </namesp1:listapiResponse>
  </SOAP-ENV:Body>
</SOAP-ENV:Envelope>

Logout

Ends the current client session on the Hopewiser SOAP server.

Syntax

int success = soap.logout(string session_id);

Usage

When a client application invokes the Logout call, it passes in a Session ID. Upon invocation, the Hopewiser SOAP server ends the associated client session.

Client applications do not need to explicitly log out to end the session. Sessions expire automatically after a period of inactivity.

Samples

<SOAP-ENV:Envelope>
  <SOAP-ENV:Body>
    <ns1:logout>
      <logout>
        <session_id>SESSION</session_id>
      </logout>
    </ns1:logout>
  </SOAP-ENV:Body>
</SOAP-ENV:Envelope>
<SOAP-ENV:Envelope SOAP-ENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
  <SOAP-ENV:Body>
    <namesp1:logoutResponse>
      <success>1</success>
    </namesp1:logoutResponse>
  </SOAP-ENV:Body>
</SOAP-ENV:Envelope>

Data Fields

Any call returning address data provides an optional input which allows the user to request more information than would otherwise be returned.

The default data and optional parameter are described for each function that provides this functionality.

Data Item Description
COUNTRY String field containing the country
COUNTRY_FLAG (UK only) – An indicator of the country of the relevant Post Town for the address. The codes are as follows:

  • E – England
  • S – Scotland
  • N – Northern Ireland
  • I – Eire
  • M – Isle of Man
  • C – Channel Islands
  • W – Wales (Anglicised)
  • H – Wales (Harlech)
  • B – Wales (both Anglicised and Harlech)

Note that for addresses close to the border between countries, the applicable Post Town may not necessarily be in the same country.

COUNTY String field containing the county
DEDUP_KEY String field containing a key for deduplication purposes
DEPARTMENT String field containing the department associated with an organisation where one exists
DISTRICT_1 String field containing the minor district of an address
DISTRICT_2 String field containing the major district of an address
DISTRICT_LEVEL An array containing formatted sub-premise, premise, street and district level information
DPS String field containing a 3-character DPS and checksum for the address or 8-character DPID in Australia
FORMATTED_FLAT String field containing the flat, formatted as if in a label
FORMATTED_FLOOR String field containing the floor, formatted as if in a label
FORMATTED_PREMISE_NO String field containing the premise number, formatted as if in a label
HOUSE_1 String field containing the primary house name for a delivery point (where one exists)
HOUSE_2 String field containing the secondary house name for a delivery point (where one exists)
ORGANISATION String field containing the organisation name for a delivery point (where one exists)
POSTCODE String field containing the postcode
STREET_1 String field containing the first street of the address
STREET_2 String field containing the second street of the address
ST_NAME (Australia only) – String field containing the street name without type
ST_TYPE (Australia only) – String field containing the street type
TOWN String field containing the town
UAID String field containing a unique address identifier

 

When PAF+NSPD data is referenced (passing “uk-nspd-paf-internal” as the dataset to ah21 or listapi) instead of plain PAF, the Extra Data fields listed below will also become available.

Data Item Description
GRID_X String field containing the X-part of the grid reference
GRID_Y String field containing the Y-part of the grid reference

 

When Market Location data is referenced (passing “uk-ml-plus” as the dataset to ah21 or listapi) instead of PAF, the Extra Data fields listed below will also be available. Note that fields are only populated when the specific data is available.

Data Item Description
CRO_NUMBER Company Registration Number. This is an 8-digit number padded with leading zeroes where necessary, e.g. 01234567.
TURNOVER The company’s turnover in pounds.
OFFICE_TYPE Provides an indication of whether a particular site is the head office, a branch or just a single site. The codes are as follows:

  • H – Head Office
  • B – Branch
  • S – Single Site
  • X – Unknown
FAX_No The company’s fax number.
SIC_DESCRIPTION Description, maximum 80 characters, of the company’s business, e.g. HAIRDRESSING AND OTHER BEAUTY TREATMENT.
EXEC_JOB_TITLE The senior executive’s job title.
EXEC_SURNAME The senior executive’s surname.
EXEC_FIRST_NAME The senior executive’s first name.
EXEC_TITLE The senior executive’s title, e.g. MR, MRS.
EMPLOYEE_BAND Provides an indication of the number of employees. The codes are as follows:

  • A – 1-4
  • B – 5-9
  • C – 10-19
  • D – 20-49
  • E – 50-99
  • F – 100-199
  • G – 200-499
  • H – 500-999
  • I – 1000+
  • X – Unknown
EMPLOYEE_COUNT The number of employees.
URN The Unique Reference Number of the company, e.g. ABCD123.
HEADING_DESCRIPTION A generic description of the company, e.g. BARBERS.
HEADING_CODE Code that correlates with the Heading Description.
SIC_CODE Identification code that correlates with the SIC Description.
TELEPHONE_NO The company’s telephone number.

Status Codes

If an error occurs during the invocation of a SOAP call, the Hopewiser SOAP server returns a SOAP fault element containing information related to the error.

Possible error codes returned are as follows:

Code Error Name Description
10000 Fatal Error This error code is returned when an internal error occurs processing the request. If the error persists, please contact support with as much information as possible.
10001 Atlas Error This error code is returned when a general Atlas error occurs. For instance, no match could be found or the search matched too many entries.
10002 Login Error This error code is returned when an error occurs during the Login call. For instance, an invalid username / password combination may have been provided.
10003 Session Error This error code is returned when an invalid Session ID is used. For instance, the Session ID may have expired.
10004 Timeout Error This error code is returned when a request takes too long and times-out. Requests will time-out if they take longer than 5 seconds to process.
10005 Field Error This error code is returned when an item is requested as data which does not exist. Refer to the Data Fields section above for a list of valid fields.
10006 Permission Error This error code is returned when the login does not have permission to perform the action that was requested. Either you have no credit available or you have requested a dataset for which you do not have credit.
10007 Input Error This error code is returned when there is a problem with the request. Either the request is malformed or a non-existent dataset was requested.

 

Sample Faults XML

<SOAP-ENV:Envelope SOAP-ENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
  <SOAP-ENV:Body>
    <SOAP-ENV:Fault>
      <faultcode>SOAP-ENV:10001</faultcode>
      <faultstring>Insufficient search criteria</faultstring>
      <faultactor>http://cloud.hopewiser.com/soapatlas/unbounded</faultactor>
    </SOAP-ENV:Fault>
  </SOAP-ENV:Body>
</SOAP-ENV:Envelope>
<SOAP-ENV:Envelope SOAP-ENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
  <SOAP-ENV:Body>
    <SOAP-ENV:Fault>
      <faultcode>SOAP-ENV:10007</faultcode>
      <faultstring>Invalid dataset requested: a-bad-name</faultstring>
      <faultactor>http://cloud.hopewiser.com/soapatlas/unbounded</faultactor>
    </SOAP-ENV:Fault>
  </SOAP-ENV:Body>
</SOAP-ENV:Envelope>

Sample Code

We have .NET sample code available for download

.NET SOAP Sample

.NET SOAP Sample Documentation (PDF)