xure api - Site Instance

Site Instance

Obtain live certificate tracking data for all suppliers associated with a site

Path Parameters

Parameter	Description
site	A unique identifier for a site subscribed to certificate tracking services

List all certificates tracked by a site GET

Returns details of all the certificates that are associated with the suppliers for which trading relationships exist with the site. Use this method to obtain the certification status for all your suppliers at once.

To obtain certificate data via this method the site needs to be subscribed to the appropriate certificate tracking services for the assurance schemes you wish to verify, and additionally, have an API access subscription.

Parameters

Request Parameters

Parameter	Description
RelationshipIdentifier String	Set this to return only certificates issued for the supplier referenced in the given relationship
SchemeIdentifier String	Set this to filter the results to include only certificates issued against the given scheme
EnterpriseIdentifier String	Set this to filter the results to include only certificates that include the given enterprise
Status Enumeration	Set this to filter the results to include only certificates with the given status

Response Parameters

Parameter	Description
CheckDate Date / Time	The date for which the tracked certificates are valid
Certificates List	A list of all tracked certificates
TaggedSite String	The business or site name of the supplier site
TaggedSiteIdentifier String	The unique identifier associated with the supplier site
TaggedSiteReference String	The reference recorded in the trading relationship for the supplier
TaggedSitePostcode String	The postcode for the supplier site
TaggedSiteCountry String	The country of the supplier site
TaggedSiteIdentifiers List	Tagged Site IdentifiersOptional
IdentifierType String	Identifier TypeOptional
IdentifierValue String	Identifier ValueOptional
Scheme String	The scheme against which the certificate has been awarded
SchemeIdentifier String	The unique identifier assigned to the certification scheme
MembershipNumber String	The membership number within the certification scheme for which the certificate was awarded
MembershipStatus Enumeration	The stautus of the member within the certification scheme
Certifier String	The name of the certification body
CertifierIdentifier String	The unique identifier issued to the certification body
CertificateIdentifier String	The unique identifier assigned to the certificate
CertificateStatus Enumeration	The overall certification status of the member
CertificateStatusDetail String	The certification status as recorded on the certificate
CertificateExpiryDate Date / Time	The date beyond which the certificate is no longer valid
CertificateEnterprises List	The list of enterprises recorded on the certificateOptional
Enterprise String	The name of the enterprise
EnterpriseIdentifier String	The unique identiifer assigned to the enterprise
CertifiedSites List	The list of sites covered by the certificationOptional
SiteName String	The location or business name for the site
SiteAddress String	The first line of the address of the siteOptional
SitePostcode String	The postcode of the siteOptional
SiteCountry String	The country of the siteOptional
IsPrimary Boolean	This site is the main or primary site covered by the certification
SiteIdentifiers List	The list of business identifiers associated with the site
Identifier String	An identifier associated with the site
IdentifierType String	The type of identifier

Enumerations

Status Filter (Request)

Value	Description
	All certificates
Valid	Certificates that are valid and in date
Grace	Certificates that are valid but in grace period beyond certificate end date
Withdrawn	Certificates that have been permanently withdrawn
NotValid	Certificates that are not currently valid

Membership Status (Response)

Value	Description
Applied	The member is an applicant
Current	The membership is current
Closed	The member has left the scheme
Grace	The membership is in grace and is expected to be renewed
TransferredOut	The member has transferred to another certification body
TransferredIn	The member is transferring from another certification body

Certificate Status (Response)

Value	Description
Valid	Certificate is valid
Grace	Certificate is valid but in grace period beyond certificate end date
Withdrawn	Certificate has been permanently withdrawn
NotValid	Certificate is not currently valid

XML

Example Request

GET https://api.xure.co/v1/track/certificates/{site}.eb?RelationshipIdentifier=String&SchemeIdentifier=String&EnterpriseIdentifier=String&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>

Download full schema

JSON

Example Request

GET https://api.xure.co/v1/track/certificates/{site}.eb?RelationshipIdentifier=String&SchemeIdentifier=String&EnterpriseIdentifier=String&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},
            ...]},
        ...]},
    ...]}

Status Codes

Status and Error Codes

HTTP Status	Error Code and Description
200	The list of tracked certificates is provided in the response
400	DataError:EnterpriseIdentifier:InvalidIdentifier The EnterpriseIdentifier value provided in the request was not recognised as a known enterprise
400	DataError:RelationshipIdentifier:InvalidIdentifier
400	DataError:SchemeIdentifier:InvalidIdentifier The SchemeIdentifier value provided in the request was not recognised as a known scheme
400	OperationError:NoAPISubscription The site does not hold a current subcription for Xure Tracking API access, or a suitable API key authorising Tracking API access has not been provided in the request
400	OperationError:NoTrackingSubscription The site does not hold any current subscriptions to certificate tracking services
403

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 enterprises 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.

API Endpointhttps://api.xure.co/v1/track/certificates/{site}

Path Parameters

List all certificates tracked by a site GET

Parameters

Request Parameters

Response Parameters

Enumerations

Status Filter (Request)

Membership Status (Response)

Certificate Status (Response)

XML

Example Request

Response Schema

Example Response

JSON

Example Request

Example Response

Status Codes

Status and Error Codes

Interpreting tracking results

Determining certificate validity

API Endpoint
https://api.xure.co/v1/track/certificates/{site}