Overview

Export as JSON for BI tools
Export as CSV
Parameters

Authentication & Authorization

A UAT token should be used, as described in the Authentication & Tokens section.

The following permission is required:
- scans_download

Exporting As JSON

`/api/v2/dashboard/scans/`

Exporting scan data for BI purposes should be done as json via cursor mode. This method will export all scans for all products by default, and provides the best performance.

Parameters

Parameter	Description
`page_mode`	`"cursor"` required. Failure to send this will result in inconsistent pagination
`timeframe`	A timeframe is required, eg. `1m` for 1 month. Using `date_from/date_to` is also supported

After initial loading of data is complete, the timeframe should be adjusted down to 1w or 1m.
See the full list for more filter options if required.

Example

Make the first request using the paramters as described above. After retrieving the results, follow the next links for all subsequent requests. Responses will not contain overlapping data.

https://api.scantrust.com/api/v2/dashboards/scans/
    ?page_mode=cursor
    &timeframe=1m

The response will include a next link. This link should be used to make the next request, and should not be modified. When there is no more data available the next link will be null and reading should stop.

Parameter	Required?	Description
campaign_id	required	ID of the campaign
timeframe	required if date_from not specified	1y(past 1 year), 2m(past 2 months), 3w(past 3 weeks), 1d(past 1 day)
date_from	required if timeframe not specified	ISO date (e.g. 2018-12-21)
date_to	optional	ISO date (e.g. 2018-12-21). Default to current date if not specified
flags	optional	counterfeit,out-of-market etc.
activation_status	optional	inactive=0, active=1, blacklisted=2
{scm field}	optional	Any SCM field key/value as a filter.
product	optional	product ID (not SKU)

See the response format section for the full contents of a scan record.

{
  "next": "https://api.scantrust.com/...?cursor=...",
  "previous": null,
  "results": [
    {
      "uuid": "ec56f4ab-ed5a-4759-ad4c-7e5e59e650ea",
      "code_message": "K84KI50SIV0610KYXLBYPQBH"
      // ...
    }
  ]
}

Exporting As CSV

`/api/v2/dashboard/scans/csv/`

CSV export supports all parameters, with a few changes:

Required: either campaign or product
limit is not supported

It is possible to download scan data as CSV if required, though this is not recommended for large amounts of data. Support for doing so will be removed in the future.

Data export via the JSON Api is recommended.

https://api.scantrust.com/api/v2/dashboards/scans/csv/
    ?timeframe=1w
    &campaign=43929

Example Response Data

CSV response data does not follow the same naming conventions as the JSON body for historical reasons. Please take care to note the differences, but in general this means that nested objects are now scm.field, product_name is product.name, etc.

HTTP/1.1 200 OK
Content-Disposition: attachment; filename=filtered_scan_data.csv;
Content-Encoding: gzip
Content-Length: 176990
Content-Type: text/csv

-- body --

scan.uuid,scan.datetime,scan.timestamp,scan.app,scan.reason,scan.result,scan.computed_status,scan.auth_failure_mode,scan.flags,scan.unique_user,scan.install_id,scan.utid,user.email,code.extended_id,code.serial_number,code.activation_status,code.blacklist_reason,product.id,product.sku,product.name,product.brand_name,device.imei,device.model,device.model_name,device.os,location.method,location.country_code,location.country,location.province,location.city,location.lat,location.lng,scm.case_number,scm.consumed_date,scm.distributor,scm.entry_port,scm.factory_date,scm.intended_market,scm.pallet_number,scm.production_batch,scm.production_date,scm.production_line,scm.qa_inspector,scm.rcontainer,scm.reel_id,scm.rfid,scm.rza_test_run,scm.sell_by_date,scm.shipment_number,scm.tbox
c08af33c-720b-4a3f-a89f-0f86f39d5152,2021-04-14T09:30:36.531580Z,1618392636,other,query,ok,failure,,blacklisted,118901e4-9d04-11eb-a54f-fa97856bd60e,,118901e4-9d04-11eb-a54f-fa97856bd60e,,B84EC06A80061SA7842119AA,GN3NYVYR,2,4,2017,12345678901234,SmartMilk ELN,SmartMilk,,MAC,other,other,ip_address,HK,Hong Kong,Central,Central,22.2795000,114.1460000,,,,,,,,,,,,,,,,,,
4ca631eb-d68a-40ec-8b24-17026f28df3b,2021-03-17T12:54:23.219715Z,1615985663,other,query,ok,verified,,,e586c198-871f-11eb-a6d6-fa3f7f318d1b,,e586c198-871f-11eb-a6d6-fa3f7f318d1b,,1CE523C048043SMPHGF3SF544215B1C,EDZDSAEY,1,0,1919,SS001,SantiagoShoes2017,JJ,,IPHONE,iPhone,ios,ip_address,KR,South Korea,Seoul,Seoul,37.5985000,126.9783000,,,,,10/1/18,us,,,1/1/18,,,C1,1,,TR1,,ship_1,763C950618043SMPHGF3S4F94A13BE5

Full Parameter List

It is recommended that you export data uising the standard method above, and then filter normally in your BI tool. If you do need to do futher filtering, the following parameters are supported:

Parameter	Type	Required?	Description
`campaign`	`int`	required¹	Show only scans from products in this campaign id e.g `7298`
`product`	`int`	required¹	Show only scans from this product id, e.g `10991`
`timeframe`	`str`	required²	`1[ymdw]`, ex: `10d` or `3m`. Will override `date_[from,to]`
`date_from`	`str`	required²	ISO 8601 date (eg. `2018-12-21T23:59:59.549Z`)
`date_to`	`str`	required²	ISO 8601 date (eg. `2018-12-21T23:59:59.549Z`)
`workorder`	`int`	optional	Show only scans from codes generated as part of this workorder
`code_message`	`str`	optional	Show only scans for this extended id (e.g. `dli2910_z37`)
`flags`	`str`	optional	`counterfeit`, `out-of-market`, etc.
`activation_status`	`int`	optional	inactive=0, active=1, blacklisted=2
`scm_{fieldname}`	`str`	optional	Any SCM field key & value, ex `scm_factory=co`
`limit`	`int`	optional	Number of scans to return per page. Not valid for CSV
`token`³	`int`	optional	You JWT access token can be passed here if required

One of these two fields is required. If both are passed, then product is used.
Either a timeframe or a from/to pair is required
Please use the standard Authorization header, support for this method is deprecated

Additional Information

How To Find Your Campaign ID

Choose "Campaigns" in the left hamburger menu
Click the Options icon for the campaign
The URL will contain the Campaign ID at the end:
1. /#/campaigns/43929/ indicates a Campaign ID of 43929

How to find your campaign SCM Field Keys

If you do not know the name of the scm fields you wish to filter by, you can find them in the campaign options:

Click on Campaigns in the left menu
Click the Options icon for the campaign
Click the SCM T&T tab

This panel contains all fields defined for the campaign. To filter by these, add an scm_ prefix to the key and pass as a querystring paramter.

A field with the key facility_id should be passed as scm_faclility_id

Additional Examples

List scans made in the previous one month for campaign 195, which were flagged out-of-market, and which have intended_market set to China (zh):

/api/v2/dashboard/scans/
  ?campaign=195
  &timeframe=1m
  &flags=out-of-market
  &scm_intended_market=zh

Show scans for campaign 195, made in the past year, and which were for codes that were Inactive (activation_status=0):

/api/v2/dashboard/scans/
  ?campaign=195
  &timeframe=1y
  &activation_status=1

Response Body (JSON)

The following body is for the standard JSON Export. If you do not use a cursor this will also have a count: int field.

{
  "next": null,
  "previous": null,
  "results": [
    // zero or more results
  ]
}

Response Item Format (JSON)

There are several sections in the json. For a glossary of all the scan results fields see Scan Data Glossary

{
  "uuid": "4ca631eb-d68a-40ec-8b24-17026f28df3b",
  "code_message": "1CE523C048043SMPHGF3SF544215B1C",
  "consumer_email": "",
  "app": "other",
  "reason": "query",
  "result": "ok",
  "auth_failure_mode": "",
  "activation_status": 1,
  "blacklist_reason": 0,
  "computed_status": "verified",
  "classification": 1,
  "is_blacklisted": false,
  "status": "third-party",
  "creation_date": "2021-03-17T12:54:23.219715Z",
  "scan_timestamp": "2021-03-17T12:54:23.219715Z",
  "mobile_scan_timestamp": null,
  "device": {
    "model": "IPHONE",
    "model_name": "iPhone",
    "os": "ios",
    "brand": "Apple"
  },
  // current scm data at the time of download
  "scm_data": {
    "tbox": "763C950618043SMPHGF3S4F94A13BE5",
    "reel_id": "1",
    "rcontainer": "C1"
  },
  "country_name": "South Korea",
  "country_code": "KR",
  "province_name": "Seoul",
  "city": "Seoul",
  "lat": 37.5985,
  "lng": 126.9783,
  "serial_number": "EDZDSAEY",
  "product_id": 1919,
  "product_sku": "SS001",
  "product_name": "SantiagoShoes2017",
  "product_image": "c/446/product/blob-tjyztv.png",
  "code_id": 7519082,
  "flags": [],
  // user related fields
  "install_id": null,
  "utid": "e586c198-871f-11eb-a6d6-fa3f7f318d1b",
  // optional user filds
  "user_id": 400,
  "user": {
    "first_name": "User",
    "last_name": "Name",
    "email": "user.name@company.com"
  }
}

GET: /api/v2/dashboard/scans/csv

Retrieves a CSV-version of the scan-data.

Note: All parameters and filters applicable to /api/v2/dashboard/scans/ are identical (see above)

The response will be formatted as comma-separated non-quoted CSV with header. For an example see below.

There are several sections of the CSV which are broken up with dot-notation, for example: scan.computed, code.extended_id, etc. For a glossary of all the scan results fields see Scan Data Glossary

Response (200): Status OK

Example CSV:

scan.uuid,scan.datetime,scan.timestamp,scan.app,scan.reason,scan.result,scan.computed_status,scan.auth_failure_mode,scan.flags,scan.unique_user,scan.install_id,scan.utid,user.email,code.extended_id,code.serial_number,code.activation_status,code.blacklist_reason,product.id,product.sku,product.name,product.brand_name,device.imei,device.model,device.model_name,device.os,location.method,location.country_code,location.country,location.province,location.city,location.lat,location.lng,scm.case_number,scm.consumed_date,scm.distributor,scm.entry_port,scm.factory_date,scm.intended_market,scm.pallet_number,scm.production_batch,scm.production_date,scm.production_line,scm.qa_inspector,scm.rcontainer,scm.reel_id,scm.rfid,scm.rza_test_run,scm.sell_by_date,scm.shipment_number,scm.tbox
c08af33c-720b-4a3f-a89f-0f86f39d5152,2021-04-14T09:30:36.531580Z,1618392636,other,query,ok,failure,,blacklisted,118901e4-9d04-11eb-a54f-fa97856bd60e,,118901e4-9d04-11eb-a54f-fa97856bd60e,,B84EC06A80061SA7842119AA,GN3NYVYR,2,4,2017,12345678901234,SmartMilk ELN,SmartMilk,,MAC,other,other,ip_address,HK,Hong Kong,Central,Central,22.2795000,114.1460000,,,,,,,,,,,,,,,,,,
4ca631eb-d68a-40ec-8b24-17026f28df3b,2021-03-17T12:54:23.219715Z,1615985663,other,query,ok,verified,,,e586c198-871f-11eb-a6d6-fa3f7f318d1b,,e586c198-871f-11eb-a6d6-fa3f7f318d1b,,1CE523C048043SMPHGF3SF544215B1C,EDZDSAEY,1,0,1919,SS001,SantiagoShoes2017,JJ,,IPHONE,iPhone,ios,ip_address,KR,South Korea,Seoul,Seoul,37.5985000,126.9783000,,,,,10/1/18,us,,,1/1/18,,,C1,1,,TR1,,ship_1,763C950618043SMPHGF3S4F94A13BE5

Overview

Authentication & Authorization​

Exporting As JSON​

/api/v2/dashboard/scans/​

Parameters​

Example​

Exporting As CSV​

/api/v2/dashboard/scans/csv/​

Example Response Data​

Full Parameter List​

Additional Information​

How To Find Your Campaign ID​

How to find your campaign SCM Field Keys​

Additional Examples​

Response Body (JSON)​

Response Item Format (JSON)​

GET: /api/v2/dashboard/scans/csv​