Integrating with the Tracking API

Through the Tracking API, subscribers to Xure Certificate Tracking services can obtain real-time data on the certification status of their tagged suppliers. Alongside core status data, callers can also obtain information on:

• The site to which the certification belongs; and other sites covered by the certification
• The assurance scheme and certification body who awarded the certificate
• The activities (known as Enterprises in Xure) for which the certification is valid
• Additional scheme-specific data

Certification data can be obtained through the Tracking API for the following assurance schemes:

• Red Tractor Produce
• Red Tractor Crops
• Red Tractor Beef & Lamb
• Red Tractor Dairy
• Red Tractor Pigs
• LEAF Marque

Pre-requisites for tracker integration

In order to access data through the API, each site requires:

• A set of tagged or confirmed trading relationships in Xure for the supplier sites to be tracked, unless ad-hoc tracking is to be used (see below)
• A current subscription to one or more Certificate Tracking services for the assurance schemes to be verified
• A current subscription to the Xure API Tracking Data Access service

Certificate Tracking subscriptions are priced per-site, based on the number of suppliers tracked for each assurance scheme. Top-tier, (unlimited) subscriptions also allow ‘ad-hoc’ verification of the certification status across an entire scheme membership. Where supplier lists are dynamic or not known in advance, e.g. when booking animals into an abattoir lairage, ad-hoc checking permits the real-time validation of assurance status on a case-by-case basis without the supplier needing to have been tagged in Xure.

Integrators and Solution Providers

Subscriptions must be taken out by the end user of the integrated system. Where an IT supplier is integrating tracker data into a software package they offer to multiple clients, each client will require their own tracking subscription, and the results returned by the tracker may only be disseminated within that organisation.

If you wish to investigate use of the API and its suitability for integration with your software, contact us to discuss getting access to tracking services on a temporary basis under an NDA.

Integration approaches

There are two different approaches to integrating with the Tracking API. The choice between them depends on the fundamental nature of your business; whether you deal with a relatively consistent group of suppliers, or have a very large and dynamic supply base.

Bulk data for tagged suppliers

If you have a relatively stable supplier base, or approval and audit processes that companies must complete before being added to your supplier list, you may find that tracking tagged suppliers allows for the simplest and most efficient integration.

Tracked certificates for all tagged suppliers can be easily obtained through a single HTTP GET request to the List all certificates tracked by a site method. Results are returned in XML or JSON format:

GET https://api.xure.co/v1/track/certificates/1OXH0BEN62.9ZFPJ5N3YUY94.eb HTTP/1.1
Accept: text/xml

Example certificate tracking request for all tagged suppliers

<TrackedCertificatesResult>
  <Certificates>
    <Item>
      <TaggedSite>BA Burrows</TaggedSite>
      <TaggedSiteIdentifier>1OXH0BEN62.9ZFPIPFO429OF</TaggedSiteIdentifier>
      <TaggedSiteReference/>
      <TaggedSitePostcode>ME17 3JB</TaggedSitePostcode>
      <TaggedSiteCountry>United Kingdom</TaggedSiteCountry>
      <Scheme>Red Tractor Demo</Scheme>
      <SchemeIdentifier>2RRVTHNXTS.A2YRDYYK6DH2C</SchemeIdentifier>
      <MembershipNumber>108</MembershipNumber>
      <MembershipStatus>Current</MembershipStatus>
      <Certifier>Test Certification Body</Certifier>
      <CertifierIdentifier>0349EQH8NH.16LGK2X51SG4P</CertifierIdentifier>
      <CertificateIdentifier>2RRVTHNXTS.A2YRL8O0J6T8A</CertificateIdentifier>
      <CertificateStatus>Valid</CertificateStatus>
      <CertificateStatusDetail>FULL</CertificateStatusDetail>
      <CertificateExpiryDate>2019-07-31T00:00:00.000+01:00</CertificateExpiryDate>
      <CheckDate>2018-12-12T15:35:00.000+00:00</CheckDate>
      <CertificateEnterprises/>
      <CertifiedSites>
        <Item>
          <SiteName>BA Burrows</SiteName>
          <SiteAddress>Workhouse Lane, Sutton Valence, Kent</SiteAddress>
          <SitePostcode>ME17 3JB</SitePostcode>
          <SiteCountry>United Kingdom</SiteCountry>
          <IsPrimary>true</IsPrimary>
          <SiteIdentifiers/>
        </Item>
      </CertifiedSites>
    </Item>
    ...
  </Certificates>
</TrackedCertificatesResult>  

Example certificate tracking response in XML format

Your suppliers must be tagged in Xure before you can obtain tracking data through this method. You can also associate your own supplier reference code with each tag. This simplifies the integration process as you can use this code to quickly match up the supplier records held in your own systems.

Ad-hoc requests for individual suppliers

If your supplier base varies day-to-day it may be too onerous to tag them in advance. Instead, if you have a top-tier (unlimited) tracking subscription, you can issue ad-hoc requests to verify the certification status of any member in an assurance scheme.

This approach is particularly suitable for markets and abattoirs where the source of incoming animals may not be known in advance, or for traders and merchants in other sectors with a very large supplier base.

Certificates for a matching suppliers can be obtained through a HTTP GET request to the Search certificates tracked by a site method. Each request must specify the set of business identifiers for the supplier which will be used to match against certified sites known to Xure. As before, results are returned in XML or JSON format.

This method may also be used by subscribers on lower tiers to search amongst their tagged supply base to obtain certification data relating to a specific supplier.

Using tracking data to verify status

Status is specified as one of four validity states, regardless of any scheme-specific rules. This must always be used to determine the certification status of a site.

High-volume use

All API use is subject to quota limits. When your quota limit is reached, API access will be temporarily restricted. If you intend to make a large number of frequent requests to the tracking API, e.g. for ad-hoc validation of assurance status in real time:

• Always use a bearer token as authorisation to eliminate the overhead of repeated user authentications
• Contact us to obtain an API key for your application to enable a larger request quota

All API requests are logged and monitored and we reserve the right to take measures against users whose activity causes the service to become degraded.