AFD Engine API makes using address management and bank validation in .NET easy, minimising your work to get an integration up and running quickly, while also providing full flexibility to customise it to your requirements. Regardless of if you are using it with a Windows Form, ASP .NET or a backend application our .NET class library makes integration with your application simple.
If you wish to integrate directly into a WinForms application, please see information about WinForms below.
To use AFD Engine API you first need to install an AFD product (Windows only) or have access to an Evolution server. You can download the API here.
To use AFD Engine API in .NET simply add a Reference to your project to our class library (AFD.API.dll). To do this right click the References item under your project in Solution Explorer select “Add Reference”, and use the Browse Tab to browse to the library file.
Engine API can be easily used in any .NET application including ASP .NET applications, WPF/Silverlight, backends etc. and you can determine if and how to display results on any interface you provide.
Add the following line to the top of your form’s .cs file to reference the AFD.API:
using AFD.API;
To create an instance of the Engine class add the following line to your code:
Engine engine = new Engine(EngineType.Address);
(You can also use EngineType.Bank or EngineType.Email if wanting to carry out Bank or Email Validation). If you wish to mix Address, Bank and/or Email validation simply create multiple instances of the Engine class.
If using an evolution server rather than a locally installed product set the Authentication property to an instance of the Authentication class for your server, e.g.:
engine.Authentication = new Authentication("http://myserver:81", "333333", "password");
To find an address record from the postcode or any fragment of the address use the Find method on an instance of the Engine class with the lookup string you wish to use and one of the following operations:
This will return:
You can then iterate through the engine.Records collection to process each result in your application. This collection has the method getField(string) which you can use to return any of the fields for the result.
For example:
// Create instance of the Engine class
Engine engine = new Engine(EngineType.Address);
// Lookup the records
int results = engine.Find("b11 1aa", Operation.FastFindLookup);
// Check for error
if (results < 0) {
MessageBox.Show(engine.LastErrorText);
return;
}
// Iterate through results
foreach (AFD.API.Record record in engine.Records) {
// Obtain the fields you require – some examples:
string list = record.GetField("List");
string organisation = record.GetField("Organisation");
string property = record.GetField("Property");
string street = record.GetField("Street");
string locality = record.GetField("Locality");
string town = record.GetField("Town");
string postcode = record.GetField("Postcode");
// display a string for the result
// - replace with a function to process the result in your application?
MessageBox.Show(list);
}
The number of results returned for FastFind operations will be limited by the MaxRecords Property of the Engine class instance. When using installed data, it may also be limited by the Timeout Property. For evolution, the server’s pre-configured MaxSearchTime may be a limiting factor.
To carry out a search for an Address:
The Find function will return:
You can then iterate through the engine.Records collection to process each result in your application. This collection has the method getField(string) which you can use to return any of the fields for the result.
For example:
// Create instance of the Engine class
Engine engine = new Engine(EngineType.Address);
// Set the fields to Search
engine.Clear();
engine.SetField("street", "Commercial Street");
engine.SetField("town", "Birmingham");
// Search for the records
int results = engine.Find(null, Operation.Search);
// Check for error
if (results < 0) {
MessageBox.Show(engine.LastErrorText);
return;
}
// Iterate through results
foreach (AFD.API.Record record in engine.Records) {
// Obtain the fields you require – some examples:
string list = record.GetField("List");
string organisation = record.GetField("Organisation");
string property = record.GetField("Property");
string street = record.GetField("Street");
string locality = record.GetField("Locality");
string town = record.GetField("Town");
string postcode = record.GetField("Postcode");
// display a string for the result
// - replace with a function to process the result in your application?
MessageBox.Show(list);
}
The number of results returned for Search operations will be limited by the MaxRecords Property of the Engine class instance. When using installed data it may also be limited by the Timeout Property. For evolution the server’s pre-configured MaxSearchTime may be a limiting factor.
Bank records can be looked up or searched for in exactly the same way as Address records. The difference being that the Engine class must be instantiated with a parameter of EngineType.Bank rather than EngineType.Address.
The applicable operations are:
An example of a Bank Lookup:
// Create instance of the Engine class
Engine engine = new Engine(EngineType.Bank);
// Lookup the records
int results = engine.Find("560036", Operation.FastFindLookup);
// Check for error
if (results < 0) {
MessageBox.Show(engine.LastErrorText);
return;
}
// Iterate through results
foreach (AFD.API.Record record in engine.Records) {
// Obtain the fields you require – some examples:
string list = record.GetField("List");
string sortcode = record.GetField("SortCode");
string ownerBankFullName = record.GetField("OwnerBankFullName");
string branchTitle = record.GetField("FullBranchTitle");
string location = record.GetField("Location");
string directDebits = record.GetField("BACSDirectDebits");
// display a string for the result
// - replace with a function to process the result in your application?
MessageBox.Show(list);
}
To validate an account number use the setField method to set the value of the sort code and account number (alternatively the IBAN can be used)
You may also wish to set the clearing system if you want to restrict validation to the UK (BACS), or Irish (IPSO) systems only.
Call Find with Operation.ValidateAccount (the Lookup parameter will be ignored)
Following successful validation a single record will be returned. It is recommended you use the sortcode and account number returned rather than that you supplied as non-standard length account numbers will be transcribed for you.
An example of a Bank Account Validation:
// Create instance of the Engine class
Engine engine = new Engine(EngineType.Bank);
// Set the Account Details to validate
engine.Clear();
engine.SetField("SortCode", "774814");
engine.SetField("AccountNumber", "24782346");
// RollNumber can also be set if applicable, IBAN can also be validated instead
// Validate the Account Details
int results = engine.Find(null, Operation.AccountValidate);
// Check for error, e.g. invalid account number
if (results < 0) {
MessageBox.Show(engine.LastErrorText);
return;
}
// Success will return a single result
string sortcode = engine.GetField("SortCode");
string accountNumber = engine.GetField("AccountNumber");
string iban = engine.GetField("IBAN");
string rollNumber = engine.GetField("RollNumber");
string typeOfAccount = engine.GetField("TypeOfAccount");
string clearingSystem = engine.GetField("ClearingSystem");
MessageBox.Show(“Account Number is Valid");
To validate a debit or credit card number use the setField method to set the value of the card number and optionally expiry date. (The expiry date is checked that it is in range for the current date if provided).
Call Find with Operation.ValidateCard (the Lookup parameter will be ignored).
Following successful validation a single record will be returned.
An example of Card Number Validation:
// Create instance of the Engine class
Engine engine = new Engine(EngineType.Bank);
// Set the field to Validate
engine.Clear();
engine.SetField("cardnumber", "4694782385016585");
engine.SetField("expirydate", "10/17"); // This field is optional
// Validate the Card Details
int results = engine.Find(null, Operation.CardValidate);
// Check for error, e.g. invalid account number
if (results < 0) {
MessageBox.Show(engine.LastErrorText);
return;
}
// Success will return a single result
string cardType = engine.GetField("CardType");
MessageBox.Show(“Valid: “ + cardType);
To validate an email address from an instance of the Engine class instantiated with EngineType.Email simply call the Find method with the email address to validate and Operation.EmailValidate.
An example of Email Address Validation:
// Create instance of the Engine class
Engine engine = new Engine(EngineType.Email);
// Validate the Email
int results = engine.Find("support@afd.co.uk", Operation.EmailValidate);
// Check for error, e.g. invalid Email Address
if (results < 0) {
MessageBox.Show(engine.LastErrorText);
return;
}
// Email Address is Valid
MessageBox.Show("Email Address is Valid");
If you have returned results following an address or bank lookup or search and require to fetch one of those results again you can do this with a Retrieve operation. An example when you might wish to do this if is returning a list of results to the user, wanting to minimise data passed and then need to retrieve the full record when a user selects an individual record.
To do this you need to store the key (use getField(“Key”) to obtain this) when processing the original record.
Please note that this Key is unique in a particular dataset so can be used statelessly or across multiple servers as long as the same version of the data is still in use. It is not unique across future versions of the data and therefore should not be stored in a database as a unique reference.
To retrieve a record call Find with the key for the record specified in the lookup field and an operation of Operation.Retrieve.
A single result will be returned which you can then process.
This will return:
For example:
// Create instance of the Engine class
Engine engine = new Engine(EngineType.Address);
// Lookup the records
int results = engine.Find("B11 1AA1001", Operation.Retrieve);
// Check for error
if (results < 0) {
MessageBox.Show(engine.LastErrorText);
return;
}
// Obtain the fields you require – some examples:
string organisation = engine.GetField("Organisation");
string property = engine.GetField("Property");
string street = engine.GetField("Street");
string locality = engine.GetField("Locality");
string town = engine.GetField("Town");
string postcode = engine.GetField("Postcode");
For ease of use the Find method used in the previous sections returns all results at once until a predetermined timeout or maximum record count is reached (if applicable). When used with an evolution server there is little point to doing anything else as results have to result from the same web request.
However in some cases when using an installed product, you may wish to return results one-by-one as they are called off or provide your own mechanism for determining when to abort a search (for example based on the actual results that come back).
In such scenarios rather than calling Find, you can call the FindFirst and FindNext methods. FindFirst has identical parameters to Find but rather than returning the results in the Records collection, it instead returns one result at a time (FindNext takes no parameters).
You do also need to be aware that FindFirst and/or FindNext will sometimes return a value of 0 indicating a record or sector break which is provided to give the opportunity to cancel long searches and at which point no new result will be returned.
An example of an Address Fast-Find, identical that given in section 4.2.1 but using findFirst and FindNext is as follows:
// Create instance of the Engine class
Engine engine = new Engine(EngineType.Address);
// Lookup the records
int result = engine.FindFirst("b11 1aa", Operation.FastFindLookup);
// Check for Error, but note if 0 has been returned it is still possible no results will be found
if (result < 0) {
MessageBox.Show(engine.LastErrorText);
return;
}
// Process and call off each result
long results = 0;
while (result >= 0) {
if (result > 0) {
// obtain some of the fields for the result to use in your application
string list = engine.GetField("List");
string organisation = engine.GetField("Organisation");
string property = engine.GetField("Property");
string street = engine.GetField("Street");
string locality = engine.GetField("Locality");
string town = engine.GetField("Town");
string postcode = engine.GetField("Postcode");
// display a string for the result
// - replace with a function to process the result in your application?
MessageBox.Show(list);
results++;
}
else if (result == 0) {
// sector or record break – take the chance to allow user to cancel?
}
// set your own condition(s) to abort the search
if (results > 500) break;
result = engine.FindNext();
}
if (results > 0) {
// success
}
else {
MessageBox.Show("No Results Found");
}
}
The following functions are available in the Engine Class:
void Clear()
This clears the fields, necessary prior to setting criteria for a search (not necessary for fast-finds and postcode lookups).
string GetField(string)
This property returns the value of the specified field name for the current record. When using Find to return multiple results at once you should use the GetField method of a Record in the Records collection property instead to retrieve fields from any record returned.
int Find(string Lookup, Operation, optional SkipOptions)
Carries out an operation using the AFD API. For a lookup, card or email validation the Lookup parameter specifies the lookup string (for example a postcode, sortcode, card number or email address). The Operation specifies the operation to carry out.
The following Operations are supported:
| Engine Type | Operation | Description |
|---|---|---|
| Address | FastFindLookup | Looks up an address fragement specified by the Lookup parameter. This could be a postcode or fields from an address. |
| PostcodePropertyLookup | Looks up an address from the specified postcode and optionally property (e.g. “277, B11 1AA”) specified by the Lookup parameter. | |
| PostcodeLookup | Looks up an address from the specified postcode. | |
| Search | Searches for an address specified by criteria set by calling setField for the appropriate fields prior to calling this function (lookup parameter is ignored and can be null) | |
| Retrieve | Retrieves a previously returned record. The required records key field should be specified as the lookup parameter. | |
| Bank | FastFindLookup | Looks up a sort code or searches for a bank from the fragment given as specified by the Lookup parameter. |
| Search | Searches for a bank branch specified by critieria set by calling setField for the appropriate fields prior to calling this function (lookup parameter is ignored and can be null). | |
| Retrieve | Retrieves a previously returned record. The required records key field should be specified as the lookup parameter. | |
| AccountValidate | Validates an account number. Use setField to set both the sortcode and account number or alternatively the IBAN prior to calling this function. The lookup parameter is ignored. | |
| CardValidate | Validates a card number. The lookup parameter should be set to the card number to validate. | |
| EmailValidate | Validates an email address. The lookup parameter should be set to the email address to validate. |
For address functions you can optionally set the SkipOptions to a member of the SkipOptions enumeration to skip records in large searches. These options are as follows:
| Skip Option | Description |
|---|---|
| None | Default – Returns all matching records (unless a timeout or maximum number of records is reached). |
| Address | Only returns the first matching record per address (or household). Only has any effect with Names & Numbers. |
| Postcode | Only returns the first matching record for each postcode. |
| Sector | Returns the first matching record per Sector (this is the portion of the postcode prior to the space and the first digit afterwards, e.g. “B11 1”). |
| Outcode | Returns the first matching record per Outcode (this is the portion of the postcode prior to the space, e.g. “B11”); |
| Town | Returns the first matching record per Royal Mail Post Town. |
| Area | Returns the first matching record per Postcode Area (this is the letters at the start of the postcode, e.g. “B” or “AB”). |
This function returns the number of matching records returned, or a value < 0 if an error has occurred. Use the LastErrorText property to obtain a human readable version of an error.
int FindFirst(string Lookup, AFD.API.Operation Operation)
This method is identical in parameters to Find. The difference being that it will obtain the first result only (or sometimes a record or sector break in a long search). You can then call FindNext() to obtain subsequent records.
In general it is recommended you use Find to obtain results as this simplifies calling off results and in-built support for the MaxRecords and, for installed data, Timeout properties to restrict long searches to help prevent your application becoming unresponsive. However in cases were you are using locally installed data and wish to have full control over this process this method gives you that flexibility.
Some examples were you might use this would be if you wish to return results to the user as they are called off rather than at the end of a long search, or you wish to be able to determine when to abort a search based on the results themselves or user intervention then this method gives you that flexibility.
The return codes are the same as for Find with the addition of 0 which indicates a record or sector break, when returned no result has been returned (You will need to call FindNext to continue the search). This allows the opportunity to cancel long searches after a predetermined timeout etc. if required.
int FindNext()
This method is used following a call to FindFirst to repeatedly call off subsequent records. It will return 1 on success, 0 on a record or sector break (indicating no new result has been returned but giving the opportunity to cancel or provide user responsiveness) or -6 to indicate the end of a search.
bool InsertRecord(int)
This function is not relevant when not using with an instance of Windows Forms and will always return false in such cases.
string LastErrorText()
This returns human readable text for the last error to occur (will return an empty string if the last operation was successful). While you may wish to display your own error text for some errors it is recommended that you fall-back to using this for any error code you have not handled yourself.
bool SetField (string FieldName, string FieldValue)
Sets the value of the specified field for searching.
DialogOptions and Mappings are not documented in this section as they are ignored unless Engine is instantiated for use specifically with a Windows Form (see Section 3 for futhur details).
Set the number of address fields to use when returning free address fields with GetField (e.g. address1, address2, etc.). The default is 6, setting this to the same number as the fields you have causes Engine to squeeze fields in as required.
Boolean value indicating if the Organisation is included in free address field (i.e. if you obtain address1, address2, etc.)
Returns human readable descriptive text for the last operation. Returns an empty string if no error occurred (result code >= 0).
Returns the result code for the last operation. While be < 0 if an error occurred or > 0 if successful.
Sets the Maximum number of records to return from any lookup or search (default 500).
Following an option calling Find this is a collection of the results (Record objects). Each Record in the collection has a getField method used to obtain individual fields for that result.
Sets the maximum time in seconds to spend searching for records (Default is 30 seconds). This helps prevent very long searches making an application unresponsive or a very vague search taking too long when it could instead be refined. This is applicable to installed products only. For evolution the server will be preconfigured with a MaxSearchTime which has the same effect.
Indicates that the Town will always be returned in upper case (default and preferred by Royal Mail for address labels)
The Record class cannot be instantiated on its own. A collection of Record objects is returned by the Records Property of the Engine class following an operation calling Find`.
The class has a single method GetField. This property returns the value of the specified field name for the record.
This collection is used on instantiating the Engine class to specify the type of Engine used. The values are Address for Address Management (e.g. Address Fastfind, Search, etc.), Bank for BankFinder (e.g. Account or Card Validation) or Email for Email Validation.
You cannot mix types in one instance of the Engine class, but you can have multiple instances of the class of different types called in the same function in your code
This collection is used to specify the operation carried out. Section 4.3.3 provides a table with the valid Operations for each EngineType.
The possible return codes, available as the return code from FindFirst or the LastResult property, are as follows:
These are the possible codes returned:
| Value | Description |
|---|---|
| 0 | The search/lookup has not completed but may take some time and so is returning to give the user the option to cancel a long search. |
| 1 | The function was successful and a matching record has been returned. |
| 2 | This applies only to Bankfinder account number validation and indicates that the function was successful and the account number should be taken as valid. However, as account numbers on this sortcode cannot be validated you may wish to double check it is correct. |
These specify the possible errors returned from any API function:
| Value | Description |
|---|---|
| -1 | The field specification string specified is invalid. This shouldn’t be returned under normal circumstances. |
| -2 | No records matching your lookup or search criteria were found. |
| -3 | The record number provided (e.g. when re-retrieving an item from a list box) is invalid. |
| -4 | An error occurred attempting to open the AFD data files. Check they are correctly installed. |
| -5 | An error occurred reading the data. Likely to be due to corrupt data so software may need to be re-installed. |
| -6 | End of Search (when the last result has already been called off – indicates there are no more results to return). |
| -7 | Indicates there is an error with the product registration. Normally due to it having expired. Run the Welcome program to re-register the software. |
| -8 | Occurs if you attempt to search for a Name and Organisation at the same time. Also occurs with Postcode Plus if the UDPRN field is searched for at the same time as any other field. |
| -99 | Indicates that the user clicked the cancel button if the DLL internal list box was used. |
| -12 | The sort code specified for an account number validation does not exist. |
| -13 | The sortcode specified for an account number validation is invalid. |
| -14 | The account number specified for an account number validation is invalid. |
| -21 | The sort code and account number given are for a building society account which also requires a roll number for account credits. No roll number has been supplied or is incorrect for this building society. |
| -22 | The International Bank Account Number provided is in an invalid format |
| -23 | The IBAN provided contains a country that is not recognised as valid |
| -24 | Both an IBAN and Account Number was provided and these details do not match. |
| -15 | The expiry date specified for a card validation is invalid. |
| -16 | The card has expired |
| -18 | The card number specified for a card validation is invalid. |
| -19 | The card number specified is a Visa card which can be used in an ATM only. |
| -20 | While the card number appears to be a valid one, the card is not of any of the known types and is therefore unlikely to be acceptable for payment. |
The AFD.API.Authentication Object is used to specify authentication details to use Engine with an evolution server. If you do not assign one to the Authentication property of the Engine class then a default instance is created which uses local installed product.
We strongly recommend that the details passed to create an instance of the Authentication object are stored as modifiable configuration parameters in your application, so that details can be changed in the future without needing to alter code.
There are three initialisers for the Authentication object:
This creates a version to work with installed data only. You will require a copy of an AFD product installed on each machine your software runs on. This is the fastest and most efficient method and is particularly ideal for offline use.
This creates a version to work with AFD’s server. You pass it your serial number and password.
This creates a version to work with your own server. The Server parameter should be a string including the protocol, server and (if not 80) the port so as to give wide compatibility. For example http://server:81
With ASP .NET webpages you can easily use Engine with the Engine class as described in Section 4 of this manual.
If you wish to use auto-configuration with your webpage you may wish to consider using Engine Web rather than Engine API as Engine Web uses JavaScript and AJAX to lookup addresses in-line from your webpage.
If using Engine API in an ASP .NET webpage an example of obtaining address results to add to a list box is as follows:
protected void ButtonLookup_Click(object sender, EventArgs e)
{
// Create an instance of the Engine class for Address operations
AFD.API.Engine engine = new AFD.API.Engine(AFD.API.EngineType.Address);
// Lookup the postcode or fast-find string in the TextLookup TextBox
int results = engine.Find(TextLookup.Text,
AFD.API.Operation.FastFindLookup);
// Add Items to ListBoxAddress For The User To Select From
ListBoxAddress.AutoPostBack = true;
foreach (AFD.API.Record record in engine.Records) {
string ListText = record.GetField("list");
string ListValue = record.GetField("key");
ListItem item = new ListItem(ListText, ListValue);
ListBoxAddress.Items.Add(item);
}
}
On selecting an item from a List Box the record can be re-looked up to provide full address details for submission, an example of this:
protected void ListBoxAddress_SelectedIndexChanged(object sender, EventArgs e)
{
// Create an instance of the Engine class for Address operations
AFD.API.Engine engine = new
AFD.API.Engine(AFD.API.EngineType.Address);
// Lookup the selected item
int results = engine.Find(ListBox1.SelectedValue,AFD.API.Operation.Retrieve);
// Assign the address to fields on the Form
TextBoxOrganisation.Text = engine.GetField("organisation");
TextBoxProperty.Text = engine.GetField("property");
TextBoxStreet.Text = engine.GetField("street");
TextBoxLocality.Text = engine.GetField("locality");
TextBoxTown.Text = engine.GetField("town");
TextBoxPostcode.Text = engine.GetField("postcode");
}
This currently includes Postcode, Plotter, Postcode Plus & Names & Numbers.
● = Fields returned by this product and fully searchable.
⚬ = Fields returned by this product, but not searchable.
Note: the alternative address formats provided do share some of the same fields where their data is identical, but you should not mix and match other fields between the different formats as this could lead to address corruption. For example, with Standard Address Fields the Street or Locality field could include a street number, whereas with Raw PAF Fields the number would be in the separate Number field.
| Field Name | Default Size | Description | Postcode | Plotter | Postcode Plus/Bus. | Names & Numbers |
|---|---|---|---|---|---|---|
| Lookup | 255 | Specify postcode (or zipcode) and fast-find lookup strings here for lookup operations. | ● | ● | ● | ● |
| Key | 255 | Provides a key which can be used to easily retrieve the record again, e.g. when a user clicks on an item in the list box. | ● | ● | ● | ● |
| List | 512 | Provides a list item formatted to be added to a list box for this record. | ⚬ | ⚬ | ⚬ | ⚬ |
| Product | 40 | Indicates the product name used. [10] | ⚬ | ⚬ | ⚬ | ⚬ |
| Occupant Fields | ||||||
| Name | 120 | Full name (includes title, first name, middle initial and surname). | ⚬ | |||
| Gender | 6 | The gender (M or F) of the resident if known. | ● | |||
| Forename | 30 | The first name of the resident. | ● | |||
| MiddleInitial | 6 | The middle initial of the resident. | ● | |||
| Surname | 30 | The surname/last name of the resident. | ● | |||
| OnEditedRoll | 6 | Indicates if the resident is on the edited electoral roll (i.e. they have not opted out). Set to Y if they are on the Edited Roll, N if not, blank for Organisation and other records). To search set to #Y to return only records on the electoral roll, #N only for those not on the electoral roll or !N for all records including Organisations but excluding those not on the Edited Roll. | ● | |||
| DateOfBirth | 10 | The residents date of birth if known (electoral roll attainers in the last 10 years only). | ● | |||
| Residency | 6 | Gives time in years that the occupant has lived at this address. | ● | |||
| Household Composition | 106 | Describes the household composition of the selected address. | ● | |||
| Organisation | 120 | Full business name (includes any department). | ● | ● | ||
| Property | 120 | Property (building-includes any sub-building). | ● | ● | ||
| Street | 120 | Delivery Street (includes any sub-street). | ● | ● | ● | ● |
| Locality | 70 | Locality (sometimes a village name – in ZipAddress used for Urbanization). | ● | ● | ● | ● |
| Town | 30 | Postal Delivery Town (or City). | ● | ● | ● | ● |
| Postcode | 10 | The Royal Mail Postcode for this address (or ZipCode). | ● | ● | ● | ● |
| Organisation Name | 60 | Business Name. | ● | ● | ||
| Department | 60 | Department Name. | ● | ● | ||
| Sub Building | 60 | Sub Building Name. | ● | ● | ||
| Building | 60 | Building Name. | ● | ● | ||
| Number | 10 | House Number | ● | ● | ||
| Dependent Thoroughfare | 60 | Sub-Street Name. | ● | ● | ● | ● |
| Thoroughfare | 60 | Street Name. | ● | ● | ● | ● |
| Double Dependent Locality | 35 | Sub-Locality Name. | ● | ● | ● | ● |
| Dependent Locality | 35 | Locality Name (Urbanization in ZipAddress). | ● | ● | ● | ● |
| Identifier | 8 | Provides a unique identifier for the address (the Royal Mail UDPRN). | ● | ● | ||
| BuildDate | 10 | Provides the build date, which can be used as the start date, entry date, and update date fields for BS7666. | ⚬ | ⚬ | ||
| Administrator | 20 | Provides the administrator of the gazetteer (AFD). | ⚬ | ⚬ | ||
| Language | 5 | Provides the language (ENG). | ⚬ | ⚬ | ||
| SubUnit | 60 | Sub-Unit of a building where needed. | ● | ● | ||
| Building Name | 60 | Building name where present. | ● | ● | ||
| Building Number | 10 | Building number, including 17A, 17-19, etc. . | ● | ● | ||
| SubStreet | 60 | Sub-street where needed. | ● | ● | ||
| Delivery Street | 60 | Designated Street Name. | ● | ● | ● | ● |
| SubLocality | 60 | Sub-locality where required. | ● | ● | ● | ● |
| Delivery Locality | 60 | Locality name (or Urbanisation). | ● | ● | ● | ● |
| Delivery Town | 30 | Postal Town name (or City). | ● | ● | ● | ● |
| Code | 10 | The Postcode (or ZipCode). | ● | ● | ● | ● |
| Postal County | 30 | Royal Mail supplied postal county. | ● | ● | ● | ● |
| Abbreviated Postal County | 30 | Royal Mail approved abbreviation is used where available for the postal county. | ● | ● | ● | ● |
| Optional County | 30 | Postal counties including optional ones for most addresses which would otherwise not have a county name. | ● | ● | ● | ● |
| Abbreviated Optional County | 30 | Royal Mail approved abbreviation is used where available for the optional county. | ● | ● | ● | ● |
| Traditional County | 30 | The traditional county name for this postcode. | ● | ● | ⚬ | ● |
| Administrative County | 30 | The administrative county name for this postcode. | ● | ● | ⚬ | ● |
| Outcode | 4 | The Outcode portion of the Postcode (the portion before the space). | ● | ● | ● | ● |
| Incode | 3 | The Incode portion of the Postcode (the portion after the space). | ● | ● | ● | ● |
| DPS | 2 | The Delivery Point Suffix which along with the postcode uniquely identifies the letterbox. | ⚬ | ● | ||
| Postcode From | 8 | Used with Postcode field to provide a range for searching. Also returns any changed postcode from a lookup. | ⚬ | ⚬ | ● | ● |
| Postcode Type | 6 | L for Large User Postcode, S for Small User. | ⚬ | ⚬ | ⚬ | ● |
| Mailsort Code | 5 | Used for obtaining bulk mail discounts. | ⚬ | ⚬ | ⚬ | ● |
| UDPRN | 8 | Royal Mail Unique Delivery Point Reference Number assigned to this letter box. | ● | ● | ||
| JustBuilt | 10 | AFDJustBuilt – Contains the date of inclusion on PAF for properties thought to be recently built. The date is stored numerically in descending format in the form YYYYMMDD. YYYY is the year, MM is the month and DD is the day. For example 20080304 is 04/03/2008. | ● | ● | ||
| Phone Number Related Fields | ||||||
| Phone | 20 | STD Code or Phone Number. | ● | ● | ● | ● |
| Geographical Fields | ||||||
| GridE | 10 | Grid Easting as a 6 digit reference. | ⚬ | ● | ● | |
| GridN | 10 | Grid Northing as a 6/7 digit reference. | ⚬ | ● | ● | |
| Latitude | 10 | Latitude representation of Grid Reference in Decimal Format (WGS84). | ⚬ | ● | ● | |
| GBGridE | 10 | UK Based Grid Easting as a 6 digit reference. Always returns the UK based grid even for Northern Ireland addresses. | ⚬ | ● | ● | |
| GBGridN | 10 | UK Based Grid Northing as a 6/7 digit reference. | ⚬ | ● | ● | |
| NIGridE | 10 | Northern Irish Grid Based Grid Easting as a 6 digit reference. Always returns the Irish base grid even for mainland UK addresses. | ⚬ | ● | ● | |
| NIGridN | 10 | Northern Irish Grid Based Grid Northing as a 6/7 digit reference. . | ⚬ | ● | ● | |
| Longitude | 10 | Longitude representation of Grid Reference in Decimal Format (WGS84). | ⚬ | ● | ● | |
| Miles | 6 | Distance from supplied grid reference. | ● | ● | ||
| KM | 6 | Distance from supplied grid reference. | ● | ● | ||
| Phone | 60 | STD Code or Phone Number. | ⚬ | ● | ||
| Urban Rural Code | 2 | Provides a code which indicates if an area is mainly urban or rural and how sparsely populated those areas are. [11] | ⚬ | ● | ||
| Urban Rural Name | 60 | Provides a description which goes along with the UrbanRuralCode. | ⚬ | ● | ||
| SOALower | 9 | Lower level Super Output Area (Data Zone in Scotland, Super Output Area in Northern Ireland). | ⚬ | ● | ||
| SOAMiddle | 9 | Middle level Super Output Area (Intermediate Geography in Scotland, not applicable for Northern Ireland). | ⚬ | ● | ||
| SubCountry Name | 20 | Provides the devolved or non-UK country name (e.g. England, Scotland, Wales etc.). | ⚬ | ● | ||
| Ward Code | 9 | Code identifying the electoral ward for this postcode. | ⚬ | ● | ||
| Ward Name | 50 | Name identifying the electoral ward for this postcode. | ⚬ | ● | ||
| Authority Code | 9 | Local/Unitary Authority for this Postcode (same as the start of the ward code). | ⚬ | ● | ||
| Authority | 50 | Local / Unitary Authority for this postcode. | ⚬ | ● | ||
| Constituency Code | 9 | Parliamentary Constituency Code for this postcode. | ⚬ | ● | ||
| Constituency | 50 | Parliamentary Constituency for this postcode. | ⚬ | ● | ||
| Devolved Constituency Code | 9 | Devolved Constituency Code for this postcode (currently covers Scotland). | ⚬ | ● | ||
| Devolved Constituency Name | 50 | Devolved Constituency Name for this postcode (currently covers Scotland). | ⚬ | ● | ||
| EER Code | 9 | Code identifying the European Electoral Region for this postcode. | ⚬ | ● | ||
| EER Name | 40 | Name identifying the European Electoral Region for this postcode. | ⚬ | ● | ||
| LEA Code | 3 | Code identifying the Local Education Authority for this postcode. | ⚬ | ● | ||
| LEA Name | 50 | Name identifying the Local Education Authority for this postcode. | ⚬ | ● | ||
| TV Region | 30 | ISBA TV Region (not TV Company). | ⚬ | ● | ||
| Postcode Level Property Indicator Fields | ||||||
| Occupancy | 6 | Indication of the type of occupants of properties found on the selected postcode. [4] | ⚬ | ⚬ | ⚬ | ● |
| Occupancy Description | 30 | Description matching the Occupancy. [4] | ⚬ | ⚬ | ⚬ | ⚬ |
| Address Type | 6 | Indication of the type of property level data to capture to have the full address for a property on the selected postcode. [5] | ⚬ | ⚬ | ⚬ | ● |
| Address Type Description | 55 | Description matching the Address Type. [5] | ⚬ | ⚬ | ⚬ | ⚬ |
| NHS Code | 6 | National Health Service Area Code. | ⚬ | ● | ||
| NHS Name | 50 | National Health Service Area Name. | ⚬ | ● | ||
| PCT Code | 9 | National Health Service Clinical Commissioning Group Code for England (Local Health Board Code in Wales, Community Health Partnership in Scotland, Local Commissioning Group in Northern Ireland, Primary Healthcare Directorate in the Isle of Man). | ⚬ | ● | ||
| PCT Name | 50 | Name matching the PCT Code field. | ⚬ | ● | ||
| Censation Code | 10 | Censation Code assigned to this Postcode. | ⚬ | ⚬ | ⚬ | ● |
| Censation Label | 50 | Provides a handle for the Censation Code. | ⚬ | ⚬ | ⚬ | ● |
| Affluence | 30 | Affluence description. | ⚬ | ⚬ | ⚬ | ● |
| Lifestage | 100 | Lifestage description. | ⚬ | ⚬ | ⚬ | ● |
| Additional Census Info | 200 | Additional information from the Census. | ⚬ | ⚬ | ⚬ | ● |
| Business | 100 | Provides a description of the type of business. | ● | |||
| SIC Code | 10 | Standard Industry Classification Code for an organisation record. | ● | |||
| Size | 6 | Gives an indication of the number of employees of an organisation at this particular office. [7] | ● | |||
| Location Type | 6 | The type of Business Location, e.g. Head Office or Branch Office. | ● | |||
| Branch Count | 6 | The number of branches for this business. | ● | |||
| Group ID | 6 | An ID of the Group were a business is part of a wider group. | ● | |||
| Modelled Turnover | 15 | The modelled annual turnover for the business. | ● | |||
| National Size | 6 | Gives an indication of the number of employees of an organisation covering all sites. [7] | ● | |||
| Alias Localities | 4 | Returns the number of alias records present for the postcode sector in which this result resides. | ⚬ | ● | ||
| Alias Locality | 35 | Returns an alias (non-postal) locality that resides in the postcode sector that this address is contained in. Note that many postcode sectors have multiple alias localities and as such you can include this field multiple times to return multiple localities. | ⚬ | ● | ||
| Advanced/Premium Fields | ||||||
| DataSet | 15 | With Postcode Plus and Welsh data can be set to ‘Welsh” to obtain the Welsh language version of an address in Wales where available. If not set then the English language version will be returned. With TraceMaster this indicates an historic dataset to use. [9] | ● | |||
| Council Tax Band | 6 | Provides the Council Tax Band for the selected property. Requires Names & Numbers. | ● |
Notes:
[3] STD Code Only – No Phone Number Present
[4] Possible Occupancy values and descriptions are as follows (information in brackets not part of the description):
[5] Possible Address Type values and descriptions are as follows (information in brackets not part of the description):
[6] The household composition field includes both a number and description and can have any of the following values.
[7] The Size property can have any of the following values:
A. 1 to 9 employees
B. 10 to 19 employees
C. 20 to 49 employees
D. 50 to 99 employees
E. 100 to 199 employees
F. 200 to 499 employees
G. 500 to 999 employees
H. 1000+
[8] The phone match type will be set to F if the phone number has been matched to the full name of this resident, or S if just to the surname. This can be useful for identifying the bill payer among multiple residents.
[9] DataSet property when used with the Names & Numbers TraceMaster product can currently be any of the following years: 1998, 1999, 2000, 2001, 2002, 2003, 2004, 2005 or Current (for the current data). Only one year can be specified at a time and searches/lookup’s will fail if the specified year has not been installed. New years are automatically accessible when they become available if installed with no change required to the DLL or your application.
[10] The Product field can have any of the following values:
AFD Postcode
AFD Postcode Plotter
AFD Postcode Plus
AFD Names & Numbers
AFD Names & Numbers TraceMaster
[11] The Urban Rural Code differs from England and Wales, Scotland and Northern Ireland. The possible codes and there meanings are as follows:
England & Wales
1. Urban (Sparse): Falls within Urban settlements with a population of 10,000 or more and the wider surrounding area is sparsely populated
2. Town and Fringe (Sparse): Falls within the Small Town and Fringe areas category and the wider surrounding area is sparsely populated.
3. Village (Sparse): Falls within the Village category and the wider surrounding area is sparsely populated.
4. Hamlet and Isolated Dwelling (Sparse): Falls within the Hamlet and Isolated Dwelling category and thee wider surrounding area is sparsely populated.
5. Urban (Less Sparse): Falls within urban settlements with a population of 10,000 or more and the wider surrounding area is less sparsely populated.
6. Town and Fringe (Less Sparse): Falls within the Small Town and Fringe areas category and the wider surrounding area is less sparsely populated.
7. Village (Less Sparse): Falls within the village category and the wider surrounding area is less sparsely populated.
8. Hamlet and Isolated Dwelling (Less Sparse): Falls within the Hamlet & Isolated Dwelling category and the wider surrounding area is less sparsely populated
Scotland
S1. Large Urban Area: Settlement of over 125,000 people.
S2. Other Urban Area: Settlement of 10,000 to 125,000 people.
S3. Accessible Small Town: Settlement of 3,000 to 10,000 people, within 30 minutes drive of a settlement of 10,000 or more.
S4. Remote Small Town: Settlement of 3,000 to 10,000 people, with a drive time of 30 to 60 minutes to a settlement of 10,000 or more.
S5. Very Remote Small Town: Settlement of 3,000 to 10,000 people, with a drive time of over 60 minutes to a settlement of 10,000 or more.
S6. Accessible Rural: Settlement of less than 3,000 people, within 30 minutes drive of a settlement of 10,000 or more.
S7. Remote Rural: Settlement of less than 3,000 people, with a drive time of 30 to 60 minutes to a settlement of 10,000 or more.
S8. Very Remote Rural: Settlement of less than 3,000 people, with a drive time of over 60 minutes to a settlement of 10,000 or more.
Northern Ireland
A – E (Urban):
A. Belfast Metropolitan Urban Area
B. Derry Urban Area
C. Large Town: 18,000 and under 75,000 people
D. Medium Town: 10,000 and under 18,000 people
E. Small Town: 4,500 and under 10,000 people
F – H (Rural):
F. Intermediate Settlement: 2,250 and under 4,500 people
G. Village: 1,000 and under 2,250 people
H. Small Village, Hamlet or Open Countryside: Less than 1,000 people
[12] The record type will be one of the following:
General Delivery
Highrise
Firm
Street
PO Box
Rural Route/Highway Contract
Multi-Carrier Route
This currently includes Postcode, Plotter, Postcode Plus & Names & Numbers.
● = Fields returned by this product and fully searchable.
⚬ = Fields returned by this product, but not searchable.
Note: the alternative address formats provided do share some of the same fields where their data is identical, but you should not mix and match other fields between the different formats as this could lead to address corruption. For example, with Standard Address Fields the Street or Locality field could include a street number, whereas with Raw PAF Fields the number would be in the separate Number field.
C&CCC Related Fields (Not applicable to IPSO Records)
| Field Name | Default Size | Description | BankFinder |
|---|---|---|---|
| General Fields | |||
| Lookup | 255 | Specify postcode (or zipcode) and fast-find lookup strings here for lookup operations. | ● |
| Clearing System | 25 | Clearing system for this record. [3] | ⚬ |
| Key | 40 | Provides a key which can be used to easily retrieve the record again, e.g. when a user clicks on an item in the list box. | ● |
| List | 512 | Provides a list item formatted to be added to a list box for this record. | ⚬ |
| Product | 40 | Provides the product name used. [10] | ⚬ |
| Search Text | 255 | Specify text to search for within any of the BankFinder fields. | ● |
| General Bank Fields | |||
| SortCode | 6 | Bank’s Sortcode. | ● |
| Bank BIC | 8 | Bank BIC Code. [1] | ● |
| Branch BIC | 3 | Branch BIC Code. [1] | ● |
| Sub Branch Suffix | 2 | Allows a branch to be uniquely identified where there is a cluster of branches sharing the same Sort Code. [1] | ⚬ |
| Short Branch Title | 27 | The official title of the branch. | ● |
| Full Branch Title | 105 | Extended title for the institution. | ● |
| Central Bank Country Code | 2 | The ISO Country code for beneficiary banks in other countries. | ⚬ |
| Central Bank Country Name | 20 | The country name corresponding to the ISO code given. | ⚬ |
| Supervisory Body Code | 1 | Indicates the supervisory body for an institution that is an agency in any of the clearings. [2] | ⚬ |
| Supervisory Body Name | 50 | The name of the supervisory body. [2] | ⚬ |
| Deleted Date | 10 | Specifies the date the branch was closed if it is not active. | ⚬ |
| Branch Type | 20 | The branch type – Main Branch, Sub or NAB Branch, Linked Branch. | ⚬ |
| Main Branch SortCode | 6 | Set for linked branches in a cluster. It identifies the main branch for the cluster. For IPSO records this is set to the branch that would handle transactions for this sortcode when the branch has been amalgamated with another. | ● |
| Location | 60 | Where present helps indicate the physical location of the branch. | ● |
| Branch Name | 35 | Defines the actual name or place of the branch. | ● |
| Alternative Branch Name | 35 | An alternative name or place for the branch where applicable. | ● |
| Owner Bank Short Name | 20 | Short version of the name of the Owning Bank. | ● |
| Owner Bank Full Name | 70 | Full version of the name of the Owning Bank. | ● |
| Owner Bank Code | 4 | The four digit bank code of the Owning Bank. [1] | ⚬ |
| Standard Address Fields (formatted as an address would appear on an envelope) | |||
| Organisation | 120 | Owner Bank Full Name. | ● |
| Property | 65 | Bank Postal Address: Property (Building) | ⚬ |
| Street | 60 | Bank Postal Address: Street | ⚬ |
| Locality | 60 | Bank Postal Address: Locality | ⚬ |
| Town | 30 | Bank Postal Address: Town | ● |
| County | 30 | Bank Postal Address: County (Optional) | ⚬ |
| Postcode | 8 | The Royal Mail Postcode for this address. | ● |
| Raw PAF Fields (formatted closer to how they appear on Raw PAF, useful if your database stores fields this way) | |||
| OrganisationName | 60 | Owner Bank Full Name. | ● |
| SubBuilding | 60 | Bank Postal Address: Sub-Building Name | ⚬ |
| Building | 60 | Bank Postal Address: Building Name | ⚬ |
| Number | 10 | Bank Postal Address: House Number | ⚬ |
| Dependent Thoroughfare | 60 | Bank Postal Address: Sub-Street Name | ⚬ |
| Thoroughfare | 60 | Bank Postal Address: Street Name | ⚬ |
| Double Dependent Locality | 35 | Bank Postal Address: Sub-Locality Name | ⚬ |
| Dependent Locality | 35 | Bank Postal Address: Locality Name | ⚬ |
| Town | 30 | Bank Postal Address: Postal Delivery Town | ● |
| County | 30 | Bank Postal Address: County (Optional) | ⚬ |
| Postcode | 8 | The Royal Mail Postcode for this address. | ● |
| Alternative Postcode Fields | |||
| Outcode | 4 | The portion of the postcode before the space. | ● |
| Incode | 3 | The portion of the postcode after the space. | ● |
| Phone | 20 | Phone Number for this bank. | ● |
| Fax | 20 | Fax Number for this bank (IPSO only). | ⚬ |
| BACS Related Fields (Not applicable to IPSO Records) | |||
| BACS Status | 5 | Indicates the BACS Clearing Status. [4] | ⚬ |
| BACS Status Description | 60 | Provides a description for the status. [4] | ⚬ |
| BACS Last Change | 10 | Date on which BACS data was last amended. | ⚬ |
| BACS Closed Clearing | 10 | Indicates the date the branch is closed in BACS clearing if applicable. | ⚬ |
| BACS Redirected From Flag | 1 | Set to R if other branches are redirected to this sort code. | ⚬ |
| BACS Redirected To SortCode | 6 | Set to R if other branches are redirected to this sort code. | ⚬ |
| BACS Settlement Bank Code | 4 | BACS Bank Code of the bank that will settle payments for this branch. | ⚬ |
| BACS Settlement Bank Short Name | 20 | Short form name of the settlement bank. | ⚬ |
| BACS Settlement Bank Full Name | 70 | Full form name of the settlement bank. | ⚬ |
| BACS Settlement Bank Section | 2 | Numeric data required for BACS to perform its settlement. | ⚬ |
| BACS Settlement Bank SubSection | 2 | Numeric data required for BACS to perform its settlement. | ⚬ |
| BACS Handling Bank Code | 4 | BACS Bank Code of the member that will take BACS output from this branch. | ⚬ |
| BACS Handling Bank Short Name | 20 | Short form name of the handling bank. | ⚬ |
| BACS Handling Bank Full Name | 70 | Full form name of the handling bank. | ⚬ |
| BACS Handling Bank Stream | 2 | Numeric code defining the stream of output within the Handling Bank that will be used or payments to this branch. | ⚬ |
| BACS Account Numbered | 1 | Set to 1 if numbered bank accounts are used. | ⚬ |
| BACS DDI Voucher | 1 | Set to 1 if Paper Vouchers have to be printed for Direct Debit Instructions. | ⚬ |
| BACS Direct Debits | 1 | Set to 1 if branch accepts Direct Debits. | ⚬ |
| BACS Bank Giro Credits | 1 | Set to 1 if branch accepts Bank Giro Credits. | ⚬ |
| BACS Building Society Credits | 1 | Set to 1 if branch accepts Building Society Credits. | ⚬ |
| BACS Dividend Interest Payments | 1 | Set to 1 if branch accepts Dividend Interest Payments. | ⚬ |
| BACS Direct Debit Instructions | 1 | Set to 1 if branch accepts Direct Debit Instructions. | ⚬ |
| BACS Unpaid Cheque Claims | 1 | Set to 1 if branch accepts Unpaid Cheque Claims. | ⚬ |
| CHAPS Related Fields (Not applicable to IPSO Records) | |||
| CHAPSP Status | 1 | Indicates the CHAPS Sterling clearing Status. [5] | ⚬ |
| CHAPSP Status Description | 80 | Provides a description for the status. [5] | ⚬ |
| CHAPSP Last Change | 10 | Date on which CHAPS Sterling data was last amended. | ⚬ |
| CHAPSP Closed Clearing | 10 | Indicates the date the branch is closed in CHAPS Sterling clearing if applicable. | ⚬ |
| CHAPSP Settlement Bank Code | 3 | CHAPS ID of the bank that will settle payments for this branch. | ⚬ |
| CHAPSP Settlement Bank Short Name | 20 | Short form of the name of the settlement bank. | ⚬ |
| CHAPSP Settlement Bank Full Name | 70 | Full form of the name of the settlement bank. | ⚬ |
| CHAPSE Status | 1 | Indicates the CHAPS Euro clearing Status. [6] | ⚬ |
| CHAPSE Status Description | 80 | Provides a description for the status. [6] | ⚬ |
| CHAPSE Last Change | 10 | Date on which CHAPS Euro data was last amended. | ⚬ |
| CHAPSE Closed Clearing | 10 | Indicates the date the branch is closed in CHAPS Euro clearing if applicable. | ⚬ |
| CHAPSE Euro Routing BIC Bank | 8 | Specifies the SWIFT closed user group Bank BIC to which CHAPS Euro payments for this branch should be routed. | ⚬ |
| CHAPSE Euro Routing BIC Branch | 3 | Specifies the SWIFT closed user group Branch BIC to which CHAPS Euro payments for this branch should be routed. | ⚬ |
| CHAPSE Settlement Bank Code | 3 | CHAPS ID of the bank that will settle payments for this branch. | ⚬ |
| CHAPSE Settlement Bank Short Name | 20 | Short form of the name of the settlement bank. | ⚬ |
| CHAPSE Settlement Bank Full Name | 70 | Full form of the name of the settlement bank. | ⚬ |
| CHAPSE Return Indicator | 1 | Set to R if this is the branch to which CHAPS Euro payments should be sent. | ⚬ |
| C&CCC Related Fields (Not applicable to IPSO Records) | |||
| CCCC Status | 1 | Indicates the C&CCC clearing status. [7] | ⚬ |
| CCCC Status Description | 40 | Provides a description for the status. [7] | ⚬ |
| CCCC Last Change | 6 | Date on which C&CCC data was last amended. | ⚬ |
| CCCC Closed Clearing | 30 | Indicates the date the branch is closed in C&CCC clearing if applicable. | ⚬ |
| CCCC Settlement Bank Code | 3 | BACS generated code of the bank that will settle payments for this branch. | ⚬ |
| CCCC Settlement Bank Short Name | 20 | Short form of the name of the settlement bank. | ⚬ |
| CCCC Settlement Bank Full Name | 70 | Full form of the name of the settlement bank. | ⚬ |
| CCCC Debit Agency SortCode | 50 | When the Status field is set to ‘D’ this specifies where cheque clearing is handled for this branch. | ⚬ |
| CCCC Return Indicator | 6 | Set if this is the branch that other banks should return paper to. It will only be set for a sortcode of a Member. | ⚬ |
| Validation Related Fields | |||
| Account Number | 12 | The account number to validate (set along with the sort code field for account number validation). | ● |
| Type Of Account | 1 | The type of account field required for transmitting data to BACS when the account number has been translated. | ⚬ |
| Roll Number | 20 | For some building society credit accounts a roll number is required. This can be specified here for validation. | ● |
| IBAN | 50 | The International Bank Account Number. This contains the sort code and account number in a standardised format for cross-border transactions. | ● |
| Building Society Name | 70 | For building society accounts requiring a roll number this will contain the name of the receiving building society as this sometimes differs from the bank branch that the payment passes through. | ⚬ |
| Card Number | 20 | Used to specify a card number to validate. | ● |
| Expiry Date | Optional field to specify an expiry date to validate along with the card number. | ● | |
| Card Type | 30 | Indicates the card type following validation. [8] | ⚬ |
Notes:
[1] Does not apply to records in the IPSO (Irish Payment Services Organisation) clearing system.
[2] The supervisory body code and name can be any of the following:
A. Bank of England
B. Building Society Commission
C. Jersey, Guernsey or Isle of Man authorities
D. Other
[3] The clearing system property can have one of the following values:
United Kingdom (BACS) – For branch records for the UK clearing system
Ireland (IPSO) – For branch records on the Irish Payment Services Organisation Clearing System
Both UK and Irish – Returned by Account Number Validation only when a branch is on both systems.
Note, that you should only accept account numbers validated on the Irish system if you can clear through both the Irish (IPSO) system as well as the UK (BACS) system.
[4] Possible values for the BACS Status and Description fields are as follows:
M. Branch of a BACS Member
A. Branch of an Agency Bank
I. Member of the Irish Clearing Services (IPSO)
Does not accept BACS Payments
[5] Possible values for the CHAPS Sterling Status and Description fields are as follows:
M. Direct Branch of a CHAPS £ Member that Accepts CHAPS £ Payments
A. Branch of an Agency Bank that Accepts CHAPS £ Payments
I. Indirect Branch of a Member or Agency Bank that Accepts CHAPS £ Payments
Does not accept CHAPS £ Payments
[6] Possible values for the CHAPS Euro Status and Description fields are as follows:
D. Direct Branch of a CHAPS € Member that Accepts CHAPS € Payments
I. Indirect Branch of a Member or Agency Bank that Accepts CHAPS € Payments
Does not accept CHAPS € Payments
[7] Possible values for the C&CCC Status and Description fields are as follows:
M. Branch of a C&CCC Member
F. Full Agency Bank Branch
D. Debit Agency Branch Only
Not Part of the C&CCC Clearing
[8] Possible values for the card type field are as follows:
MasterCard
Visa
American Express
Visa Debit
Electron
Visa Purchasing
UK Maestro
International Maestro
Solo and Maestro
JCB
Charities Aid Foundation
MasterCard Debit
[10] The Product field would have the value ‘AFD BankFinder’.
Engine automatically configures itself for many Windows Forms minimising the work you need to do as a developer to get AFD Software working with your application.
This guide is intended to assist you in getting started with using Engine with Windows Forms. It is recommended you read this guide first and then refer to the main manual for advanced settings, if desired, once you have it working.
If you wish to integrate a non-WinForms application or in the backend of any application you should refer to the other .NET API Quick Start Guide instead.
To use AFD Engine API you first need to install an AFD product (Windows only) or have access to an Evolution server (Java as a client is then completely platform independent). For Windows development and testing you can download data-restricted evaluation products from our website’s evaluation page.
To use AFD Engine API in .NET simply add a Reference to your project to our class library (AFD.API.dll). To do this right click the References item under your project in Solution Explorer select “Add Reference”, and use the Browse Tab to browse to the library file.
You can quickly and easily add Address Management functionality to your application with the following steps:
Add the following line to the top of your form’s .cs file:
using AFD.API;
In the Form_Load method of your form add the following line of code:
Engine engine = new Engine(this);
If using an evolution server rather than a locally installed product set the Authentication property to an instance of the Authentication class for your server, e.g.:
engine.Authentication = new Authentication("http://myserver:81", "333333", "password");
You should replace myserver:81 with the name of your server and port, 333333 with your AFD Serial number and password with your password.
When you run your application Engine will attempt to identify address fields on your form. If you type a postcode into any text box on your form you will be prompted to select the correct address for insertion if the user of your application wishes to do so.
In most cases you will want to customise this depending on your requirements to trigger the lookup from a field and button on your form, insert non-address elements etc. and potentially even obtain fields that you do not display on your Form. The following sections detail the options available to do so.
If you require to insert a field on your Form that is has not been detected by Engine or you need to tweak or alter the fields inserted you can easily do this by using the Methods of the Engine.Mapping object.
To add or replace a field mapping for a control on your form, e.g. a TextBox, use the Add method. For example if you have a TextBox Control named “txtCensation” that you want to use for the Censation Code, simply add the following line after instantiating the Engine class:
engine.Mappings.Add(txtCensation, "CensationCode");
You can additionally specify the following additional parameters to the Add method:
If you wish to remove a mapping for a field that Engine has mapped that you don’t want included, simply pass that Control to the Remove method: For example if you don’t want a field txtStreet mapped:
engine.Mappings.Remove(txtStreet);
This method clears all Mappings and is useful if you wish to change mappings substantially as you can then add each Control you wish to Map yourself using the Add method.
When you pass a Form, or keyword this, to Engine it will attempt to auto-detect all Input controls on that Form.
However if you have multiple addresses on the same screen, e.g. a Shipping and Billing address and wish these to be detected separately, simply initialise Engine twice with each of the Containers (e.g. a Frame or Panel) rather than the Form itself.
For example:
Engine engineShipping = new Engine(fraShipping);
Engine engineBilling = new Engine(fraBilling);
By default Engine will auto-detect when you enter a postcode into any field in your application and display matching addresses for the user to choose from.
However to provide full fast-find functionality you can trigger Engine from your own Button on your Form. To do this simply carry out the following steps:
Engine wlll then insert the selected address in the same way as when Engine auto-detects the Postcode.
If you would prefer Engine to only trigger from your own button when you create an instance of the Engine class use the AutoLookup parameter to disable automatic lookup, e.g. “engine = new Engine(this, true, false);”. (The middle parameter is used to disable automatic configuration of Form fields).
Engine contains many options for customisation, for example you can control the dialog position and size, its title, icon and other aspects of the Form. You can also carry out a search in the same way as the Lookup above. For full details of these please see the main Engine .NET API guide.
Engine also contains support for Bank account and Debit/Credit card validation if you have BankFinder. For these please see the .NET API Quick Start Guide as there use is not Windows Forms specific.
Even when displaying a Windows Form you do not need to use Engine in this way. If you prefer to integrate at the backend or manually set and retrieve the fields required you can also do this. For full details please see the .NET API Quick Start guide.
We serve thousands of organisations and a network of hundreds of partners across multiple industry sectors, enabling them to have full confidence in their contact data.