Example Request
GET https://api.xure.co/v1/track/certificates/{site}/adhoc.eb?Country=String&BusinessIdentifiers.IdentifierType=String&BusinessIdentifiers.Identifier=String&...&Postcode=String&MembershipNumber=String&SchemeIdentifier=String&EnterpriseIdentifier=String&CheckDate=DateTime&Status=String HTTP/1.1
Accept: text/xml
Response Schema
<?xml version="1.0" encoding="utf-8"?>
<xsd:schema elementFormDefault="qualified" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
<xsd:element name="TrackedCertificatesResult">
<xsd:complexType>
<xsd:sequence>
<xsd:element name="CheckDate" type="xsd:dateTime">
<xsd:annotation>
<xsd:documentation>The date for which the tracked certificates are valid</xsd:documentation>
</xsd:annotation>
</xsd:element>
<xsd:element name="Certificates">
<xsd:annotation>
<xsd:documentation>A list of all tracked certificates</xsd:documentation>
</xsd:annotation>
<xsd:complexType>
<xsd:sequence>
<xsd:element name="Item" minOccurs="0" maxOccurs="unbounded">
<xsd:complexType>
<xsd:sequence>
<xsd:element name="TaggedSite" type="xsd:string">
<xsd:annotation>
<xsd:documentation>The business or site name of the supplier site</xsd:documentation>
</xsd:annotation>
</xsd:element>
<xsd:element name="TaggedSiteIdentifier" type="xsd:string">
<xsd:annotation>
<xsd:documentation>The unique identifier associated with the supplier site</xsd:documentation>
</xsd:annotation>
</xsd:element>
<xsd:element name="TaggedSiteReference" type="xsd:string">
<xsd:annotation>
<xsd:documentation>The reference recorded in the trading relationship for the supplier</xsd:documentation>
</xsd:annotation>
</xsd:element>
<xsd:element name="TaggedSitePostcode" type="xsd:string">
<xsd:annotation>
<xsd:documentation>The postcode for the supplier site</xsd:documentation>
</xsd:annotation>
</xsd:element>
<xsd:element name="TaggedSiteCountry" type="xsd:string">
<xsd:annotation>
<xsd:documentation>The country of the supplier site</xsd:documentation>
</xsd:annotation>
</xsd:element>
<xsd:element name="TaggedSiteIdentifiers" minOccurs="0">
<xsd:complexType>
<xsd:sequence>
<xsd:element name="Item" minOccurs="0" maxOccurs="unbounded">
<xsd:complexType>
<xsd:sequence>
<xsd:element name="IdentifierType" minOccurs="0" type="xsd:string" />
<xsd:element name="IdentifierValue" minOccurs="0" type="xsd:string" />
</xsd:sequence>
</xsd:complexType>
</xsd:element>
</xsd:sequence>
</xsd:complexType>
</xsd:element>
<xsd:element name="Scheme" type="xsd:string">
<xsd:annotation>
<xsd:documentation>The scheme against which the certificate has been awarded</xsd:documentation>
</xsd:annotation>
</xsd:element>
<xsd:element name="SchemeIdentifier" type="xsd:string">
<xsd:annotation>
<xsd:documentation>The unique identifier assigned to the certification scheme</xsd:documentation>
</xsd:annotation>
</xsd:element>
<xsd:element name="MembershipNumber" type="xsd:string">
<xsd:annotation>
<xsd:documentation>The membership number within the certification scheme for which the certificate was awarded</xsd:documentation>
</xsd:annotation>
</xsd:element>
<xsd:element name="MembershipStatus">
<xsd:annotation>
<xsd:documentation>The stautus of the member within the certification scheme</xsd:documentation>
</xsd:annotation>
<xsd:simpleType>
<xsd:restriction base="xsd:string">
<xsd:enumeration value="Applied">
<xsd:annotation>
<xsd:documentation>The member is an applicant</xsd:documentation>
</xsd:annotation>
</xsd:enumeration>
<xsd:enumeration value="Current">
<xsd:annotation>
<xsd:documentation>The membership is current</xsd:documentation>
</xsd:annotation>
</xsd:enumeration>
<xsd:enumeration value="Closed">
<xsd:annotation>
<xsd:documentation>The member has left the scheme</xsd:documentation>
</xsd:annotation>
</xsd:enumeration>
<xsd:enumeration value="Grace">
<xsd:annotation>
<xsd:documentation>The membership is in grace and is expected to be renewed</xsd:documentation>
</xsd:annotation>
</xsd:enumeration>
<xsd:enumeration value="TransferredOut">
<xsd:annotation>
<xsd:documentation>The member has transferred to another certification body</xsd:documentation>
</xsd:annotation>
</xsd:enumeration>
<xsd:enumeration value="TransferredIn">
<xsd:annotation>
<xsd:documentation>The member is transferring from another certification body</xsd:documentation>
</xsd:annotation>
</xsd:enumeration>
</xsd:restriction>
</xsd:simpleType>
</xsd:element>
<xsd:element name="Certifier" type="xsd:string">
<xsd:annotation>
<xsd:documentation>The name of the certification body</xsd:documentation>
</xsd:annotation>
</xsd:element>
<xsd:element name="CertifierIdentifier" type="xsd:string">
<xsd:annotation>
<xsd:documentation>The unique identifier issued to the certification body</xsd:documentation>
</xsd:annotation>
</xsd:element>
<xsd:element name="CertificateIdentifier" type="xsd:string">
<xsd:annotation>
<xsd:documentation>The unique identifier assigned to the certificate</xsd:documentation>
</xsd:annotation>
</xsd:element>
<xsd:element name="CertificateStatus">
<xsd:annotation>
<xsd:documentation>The overall certification status of the member</xsd:documentation>
</xsd:annotation>
<xsd:simpleType>
<xsd:restriction base="xsd:string">
<xsd:enumeration value="Valid">
<xsd:annotation>
<xsd:documentation>Certificate is valid</xsd:documentation>
</xsd:annotation>
</xsd:enumeration>
<xsd:enumeration value="Grace">
<xsd:annotation>
<xsd:documentation>Certificate is valid but in grace period beyond certificate end date</xsd:documentation>
</xsd:annotation>
</xsd:enumeration>
<xsd:enumeration value="Withdrawn">
<xsd:annotation>
<xsd:documentation>Certificate has been permanently withdrawn</xsd:documentation>
</xsd:annotation>
</xsd:enumeration>
<xsd:enumeration value="NotValid">
<xsd:annotation>
<xsd:documentation>Certificate is not currently valid</xsd:documentation>
</xsd:annotation>
</xsd:enumeration>
</xsd:restriction>
</xsd:simpleType>
</xsd:element>
<xsd:element name="CertificateStatusDetail" type="xsd:string">
<xsd:annotation>
<xsd:documentation>The certification status as recorded on the certificate</xsd:documentation>
</xsd:annotation>
</xsd:element>
<xsd:element name="CertificateExpiryDate" type="xsd:dateTime">
<xsd:annotation>
<xsd:documentation>The date beyond which the certificate is no longer valid</xsd:documentation>
</xsd:annotation>
</xsd:element>
<xsd:element name="CertificateEnterprises" minOccurs="0">
<xsd:annotation>
<xsd:documentation>The list of enterprises recorded on the certificate</xsd:documentation>
</xsd:annotation>
<xsd:complexType>
<xsd:sequence>
<xsd:element name="Item" minOccurs="0" maxOccurs="unbounded">
<xsd:complexType>
<xsd:sequence>
<xsd:element name="Enterprise" type="xsd:string">
<xsd:annotation>
<xsd:documentation>The name of the enterprise</xsd:documentation>
</xsd:annotation>
</xsd:element>
<xsd:element name="EnterpriseIdentifier" type="xsd:string">
<xsd:annotation>
<xsd:documentation>The unique identiifer assigned to the enterprise</xsd:documentation>
</xsd:annotation>
</xsd:element>
</xsd:sequence>
</xsd:complexType>
</xsd:element>
</xsd:sequence>
</xsd:complexType>
</xsd:element>
<xsd:element name="CertifiedSites" minOccurs="0">
<xsd:annotation>
<xsd:documentation>The list of sites covered by the certification</xsd:documentation>
</xsd:annotation>
<xsd:complexType>
<xsd:sequence>
<xsd:element name="Item" minOccurs="0" maxOccurs="unbounded">
<xsd:complexType>
<xsd:sequence>
<xsd:element name="SiteName" type="xsd:string">
<xsd:annotation>
<xsd:documentation>The location or business name for the site</xsd:documentation>
</xsd:annotation>
</xsd:element>
<xsd:element name="SiteAddress" minOccurs="0" type="xsd:string">
<xsd:annotation>
<xsd:documentation>The first line of the address of the site</xsd:documentation>
</xsd:annotation>
</xsd:element>
<xsd:element name="SitePostcode" minOccurs="0" type="xsd:string">
<xsd:annotation>
<xsd:documentation>The postcode of the site</xsd:documentation>
</xsd:annotation>
</xsd:element>
<xsd:element name="SiteCountry" minOccurs="0" type="xsd:string">
<xsd:annotation>
<xsd:documentation>The country of the site</xsd:documentation>
</xsd:annotation>
</xsd:element>
<xsd:element name="IsPrimary" type="xsd:boolean">
<xsd:annotation>
<xsd:documentation>This site is the main or primary site covered by the certification</xsd:documentation>
</xsd:annotation>
</xsd:element>
<xsd:element name="SiteIdentifiers">
<xsd:annotation>
<xsd:documentation>The list of business identifiers associated with the site</xsd:documentation>
</xsd:annotation>
<xsd:complexType>
<xsd:sequence>
<xsd:element name="Item" minOccurs="0" maxOccurs="unbounded">
<xsd:complexType>
<xsd:sequence>
<xsd:element name="Identifier" type="xsd:string">
<xsd:annotation>
<xsd:documentation>An identifier associated with the site</xsd:documentation>
</xsd:annotation>
</xsd:element>
<xsd:element name="IdentifierType" type="xsd:string">
<xsd:annotation>
<xsd:documentation>The type of identifier</xsd:documentation>
</xsd:annotation>
</xsd:element>
</xsd:sequence>
</xsd:complexType>
</xsd:element>
</xsd:sequence>
</xsd:complexType>
</xsd:element>
</xsd:sequence>
</xsd:complexType>
</xsd:element>
</xsd:sequence>
</xsd:complexType>
</xsd:element>
</xsd:sequence>
</xsd:complexType>
</xsd:element>
</xsd:sequence>
</xsd:complexType>
</xsd:element>
</xsd:sequence>
</xsd:complexType>
</xsd:element>
</xsd:schema>
Example Response
HTTP/1.1 200 OK
Content-Type: text/xml
<?xml version="1.0" encoding="utf-8"?>
<TrackedCertificatesResult>
<CheckDate>xsd:dateTime</CheckDate>
<Certificates>
<Item>
<TaggedSite>xsd:string</TaggedSite>
<TaggedSiteIdentifier>xsd:string</TaggedSiteIdentifier>
<TaggedSiteReference>xsd:string</TaggedSiteReference>
<TaggedSitePostcode>xsd:string</TaggedSitePostcode>
<TaggedSiteCountry>xsd:string</TaggedSiteCountry>
<TaggedSiteIdentifiers>
<Item>
<IdentifierType>xsd:string</IdentifierType>
<IdentifierValue>xsd:string</IdentifierValue>
</Item>...</TaggedSiteIdentifiers>
<Scheme>xsd:string</Scheme>
<SchemeIdentifier>xsd:string</SchemeIdentifier>
<MembershipNumber>xsd:string</MembershipNumber>
<MembershipStatus>xsd:string</MembershipStatus>
<Certifier>xsd:string</Certifier>
<CertifierIdentifier>xsd:string</CertifierIdentifier>
<CertificateIdentifier>xsd:string</CertificateIdentifier>
<CertificateStatus>xsd:string</CertificateStatus>
<CertificateStatusDetail>xsd:string</CertificateStatusDetail>
<CertificateExpiryDate>xsd:dateTime</CertificateExpiryDate>
<CertificateEnterprises>
<Item>
<Enterprise>xsd:string</Enterprise>
<EnterpriseIdentifier>xsd:string</EnterpriseIdentifier>
</Item>...</CertificateEnterprises>
<CertifiedSites>
<Item>
<SiteName>xsd:string</SiteName>
<SiteAddress>xsd:string</SiteAddress>
<SitePostcode>xsd:string</SitePostcode>
<SiteCountry>xsd:string</SiteCountry>
<IsPrimary>xsd:boolean</IsPrimary>
<SiteIdentifiers>
<Item>
<Identifier>xsd:string</Identifier>
<IdentifierType>xsd:string</IdentifierType>
</Item>...</SiteIdentifiers>
</Item>...</CertifiedSites>
</Item>...</Certificates>
</TrackedCertificatesResult>
Example Request
GET https://api.xure.co/v1/track/certificates/{site}/adhoc.eb?Country=String&BusinessIdentifiers.IdentifierType=String&BusinessIdentifiers.Identifier=String&...&Postcode=String&MembershipNumber=String&SchemeIdentifier=String&EnterpriseIdentifier=String&CheckDate=DateTime&Status=String HTTP/1.1
Accept: application/json
Example Response
HTTP/1.1 200 OK
Content-Type: application/json
{"CheckDate":String,
"Certificates":[{"TaggedSite":String,
"TaggedSiteIdentifier":String,
"TaggedSiteReference":String,
"TaggedSitePostcode":String,
"TaggedSiteCountry":String,
"TaggedSiteIdentifiers":[{"IdentifierType":String,
"IdentifierValue":String},
...],
"Scheme":String,
"SchemeIdentifier":String,
"MembershipNumber":String,
"MembershipStatus":String,
"Certifier":String,
"CertifierIdentifier":String,
"CertificateIdentifier":String,
"CertificateStatus":String,
"CertificateStatusDetail":String,
"CertificateExpiryDate":String,
"CertificateEnterprises":[{"Enterprise":String,
"EnterpriseIdentifier":String},
...],
"CertifiedSites":[{"SiteName":String,
"SiteAddress":String,
"SitePostcode":String,
"SiteCountry":String,
"IsPrimary":Boolean,
"SiteIdentifiers":[{"Identifier":String,
"IdentifierType":String},
...]},
...]},
...]}
Specifying the search parameters
A search may specify multiple business identifiers, alongside a postcode for the site. A maximum of four identifiers (including postcode and membership number if specified) may be provided. These are used to match against certified sites known to Xure.
Results are scored according to the closeness of the match between identifiers, with certificates only returned for the top-scoring sites. This allows results to be obtained even where there are discrepancies between some of the search parameters given and the identifiers recorded on the system. Providing more search parameters will improve the accuracy of the results but it is the responsibility of the caller to check that the certificates returned match expectations, particularly when multiple sites are matched.
As the range of business identifiers which may be used to identify a site varies between countries, all requests must first specify the country being searched in. For example, in mainland Great Britain (country code GBR), the following identifiers may be used:
Business Identifier |
IdentifierType |
Example Format |
VAT Number |
vatno |
GB1234567890 |
Company Registation Number |
regisno |
12345678 or AB123456 |
Holding (CPH) Number |
holdingno |
12/345/6789 |
The allowable list of three-letter country codes is listed on the enumerations tab above, and more detailed information on those countries and the valid types and format of business identifiers available for each can be obtained through the Country Lookup API.
GET https://api.xure.co/v1/track/certificates/1OXH0BEN62.9ZFPJ5N3YUY94/adhoc.eb?Country=GBR&BusinessIdentifiers.IdentifierType=holdingno&BusinessIdentifiers.Identifier=12/345/6789 HTTP/1.1
Accept: text/xml
Request for certificates associated with holding number 12/345/6789 in Great Britain
To specify more than one business identifier, simply provide multiple pairs of BusinessIdentifiers.IdentifierType and BusinessIdentifiers.Identifier parameters in the request. An identifier type may only specified once per request.
Searching by membership number
In cases where you already know the certificate or membership number, you can search on this number only.
When searching by number you will need to also specify the identifier of the assurance scheme you wish to search in. The full list of the schemes available to a specific site are given in the results returned by the Certificate Tracking Sites endpoint.
GET https://api.xure.co/v1/track/certificates/1OXH0BEN62.9ZFPJ5N3YUY9/adhoc.eb?Country=GBR&MembershipNumber=12345&SchemeIdentifier=2RRVTHNXTS.A2YRDYYK6DH2C HTTP/1.1
Accept: text/xml
Request for certificates associated with a scheme's member number 12345
Requesting historic status
Normally the status information returned reflects the certificate as it is currently recorded in the Xure system. If you need to back-date an adhoc check, you can request that the results returned reflect the certificate status as it was recorded at a point in the past by setting the CheckDate parameter.
Historic coverage varies scheme-by-scheme and you may find incomplete information is returned if a request is made for a date more than six months in the past.
Interpreting tracking results
The results returned for each tracked certificate contain various distinct groups of information. It is important you understand how these groups are related in order to ensure you use the information correctly.
Group |
Parameters |
Description |
Tagged Site |
TaggedSite
TaggedSiteIdentifier
TaggedSiteReference
TaggedSitePostcode
TaggedSiteCountry
|
The tagged site group give the details relating to the business, site or location recorded in Xure with which the certification is associated.
If the site is tagged through a trading relationship and a supplier reference code has been recorded in Xure, this is returned as TaggedSiteReference. This can be used to match up the response with records held by your own CRM or ERP system.
|
Scheme Membership |
Scheme
SchemeIdentifier
MembershipNumber
MembershipStatus
|
The scheme membership group gives basic information about the scheme and the membership against which certification has been awarded. Note that the status given here relates to the membership, not the certificate. |
Certificate |
Certifier
CertifierIdentifier
CertificateIdentifier
CertificateStatus
CertificateStatusDetail
CertificateExpiryDate
CertificateEnterprises
|
The certificate group gives information about the certification itself; its status, coverage and expected expiry. See the guidance notes below on how to determine certificate validity from CertificateStatus.
|
Certified Sites |
CertifiedSites |
The certified sites group gives the business, site or locations covered by the certification exactly as reported by the issuer of the certificate. Any business identifiers recorded by the certificate issuer for a certified site are recorded in the SiteIdentifiers list. |
Determining certificate validity
The overall validity of a certificate is determined by checking the value returned for the CertificateStatus parameter. Regardless of any specific scheme rules, this will always give one of four overall validity states:
CertificateStatus in response |
Status as shown on certificate in the Xure website |
Explaination |
Valid |
VALID |
The member is assured and holds a certificate that expires in the future |
Grace |
VALID (GRACE) |
The member is assured and holds a certificate that has just expired or whose date has been temporarily extended by their certification body |
NotValid |
NOT VALID |
The member is not assured and the certificate is no longer valid |
Withdrawn |
WITHDRAWN |
The member is not assured and the certificate has been withdrawn by the certification body |
Where assurance scheme rules define further certification statuses such as "Destocked" or "No Storage" these are returned in the CertificateStatusDetail parameter. However, any certification decision you make should primarily rely on the CertificateStatus.
Whilst the expiry date of the member’s current certification is given, this date must not be used to assume continuing assurance. A certificate may be withdrawn at any time and therefore checks should continue to be made on a regular basis to verify that a site continues to be assured.
Some schemes require certificates to list a set of specific activities for which the member is certified. If you need to verify that a specific activity is covered, check the list of entprises recorded on the certificate in the CertifiedEnterprises list. Always use the EnterpriseIdentifier to find a matching enterprise in this list as the exact name returned in the Enterprise parameter may change over time. A complete list of the enterprises used by Xure is available through the Enterprises Lookup API.