Lookup, identification and enrichment

Updated

Enrichment

The best way to get data on an Apple device is by using the lookup call to enrich data. This is particularly effective for lookups on serial and IMEI data, and it is able to return a lot of related device data. If you simply need to get properties for a given identifier, see the classic Lookup section below.

This is its request format: https://di-api.reincubate.com/v2/lookup/

There are two ways to access this functionality.

Summary requests using GET

A lookup can be performed with a request in the format like https://di-api.reincubate.com/v2/lookup/[IDENTIFIER-VALUE]/

This provides a simple way to access DeviceIdentifier data. However, this relies on automatic identification of value types, and won't always provide as much data as a fuller POST request.

Full requests using POST

To use these, the API must receive a POST request of JSON data similar to the following:

{
  "primary": {
    "identifier": "iPhone5,2",
    "type": "apple_identifier"
  },
  "additional": [{
    "identifier": "F2TK4TZ7DTWF",
    "type": "apple_serial"
  },{
    "identifier": "013554006297015",
    "type": "gsma_imei"
  },{
    "identifier": "8965880812100011146",
    "type": "gsma_iccid"
  }]
}

In this JSON structure, the primary identifier value is mandatory and must represent either an Apple serial number, IMEI, or model.

Passing type values is optional, but it safeguards against potential collisions. Any type value documented in the supported identifiers sections of this documentation is acceptable for a type value. Thus, at its simplest, a valid request could look like this:

{
  "primary": {
      "identifier": "DMPRC0P8H1MD"
  }
}

The additional dictionary is also entirely optional. However, those values allow the API to narrow down results and provide greater accuracy in its responses. It is highly recommended to send as much additional data as is available for a device.

The API will return data in a uniform format as described in the supported identifiers section in its response.

Examples

{
  "primary": {
    "identifier": "iPhone5,2",
    "type": "apple_identifier"
  },
  "additional": [{
    "identifier": "F2TK4TZ7DTWF",
    "type": "apple_serial"
  },{
    "identifier": "013554006297015",
    "type": "gsma_imei"
  },{
    "identifier": "8965880812100011146",
    "type": "gsma_iccid"
  }]
}
{
    "warranty": {
        "url": "https://checkcoverage.apple.com/gb/en?sn=F2TK4TZ7DTWF",
        "apple_care_status": "LIKELY_EXPIRED",
        "apple_care_plus_status": "GSX_REQUIRED"
    },
    "production": {
        "week": "2013-01-22",
        "city": "Zhengzhou",
        "company": "Foxconn",
        "country": "China"
    },
    "hardware": {
        "model": "N42",
        "revision": [
            {
                "platform": "s5l8950x",
                "name": "N42AP",
                "cpid": 35152,
                "bdid": 2
            }
        ]
    },
    "meta": {
        "account": 34,
        "primary_identifier_type": "apple_identifier",
        "timestamp": "2019-11-04T13:11:04.605882",
        "results_narrowed_by_additional_identifiers": true,
        "primary_identifier": "iPhone5,2",
        "credits_remaining": -1,
        "cache_status": "UNCACHED"
    },
    "mobile": {
        "serial": "629701",
        "registration_country": "CTIA (PTCRB)",
        "reporting_body": "United States"
    },
    "marketing": {
        "images": [
            {
                "url": "https://di-api.reincubate.com/resource-d47c4d432532037b31e69be8fbc66dcb/",
                "width": 450,
                "height": 330
            },
            {
                "url": "https://di-api.reincubate.com/resource-4cb3c6fe7c62f327cd11712196c221b0/",
                "width": 120,
                "height": 120
            }
        ],
        "names": [
            "iPhone 5",
            "iPhone 5 (GSM, CDMA)"
        ]
    },
    "security": {
        "primary_identifier_anonymised": "F2TK4•••DTWF",
        "identifier_fraud": {
            "code": "ADDITIONAL_MISSING",
            "message": "Fraud scoring requires use of the `additional` parameter in your request.",
            "score": 0
        }
    },
    "valuation": {
        "resale": [
            {
                "url": "https://www.apple.com/shop/trade-in",
                "vendor": "official_tradein",
                "value": "$0.00"
            }
        ],
        "retail": []
    },
    "specification": {
        "configuration_code": [
            {
                "colour": null,
                "code": "DTWF",
                "storage": "16 GB"
            }
        ],
        "mpn": [
            {
                "factory_lock": "UNKNOWN",
                "colour": "Silver",
                "code": "D298",
                "storage": "16 GB",
                "distribution": null
            },
            {
                "factory_lock": "UNKNOWN",
                "colour": "Black",
                "code": "D297",
                "storage": "16 GB",
                "distribution": null
            }
        ],
        "type_allocation_code": [],
        "family": [],
        "summary": {
            "factory_lock": null,
            "colour": null,
            "storage": "16 GB",
            "url": "https://support.apple.com/kb/SP655",
            "unique_to_region": null,
            "distribution": null
        }
    },
    "software": {
        "shipped": "10.3.3",
        "name": "iOS",
        "latest": "10.3.4"
    }
}

Lookup

The API provides functionality to look up details for a given identifier. The lookup call is RESTful and takes the following format:

https://di-api.reincubate.com/v1/*[IDENTIFIER-TYPE]*/*[IDENTIFIER-VALUE]*/

See the supported identifiers sections for information on the identifier formats supported.

Examples

https://di-api.reincubate.com/v1/apple-identifiers/iPhone5,3/

$ python -m deviceidentifier.cli.apple_identifier iPhone5,3
{
    "id": "iPhone5,3",
    "image": {
        "height": 330,
        "url": "https://di-api.reincubate.com/resource-775ac9634280be8d7dfb0b75b4727f69/",
        "width": 450
    },
    "product": {
        "line": "iPhone",
        "sku": "iPhone 5c"
    },
    "variant": "GSM + CDMA"
}

Identification

The API provides functionality to identify an unknown identifier. The lookup call is RESTful and takes the following format:

https://di-api.reincubate.com/v1/identify-identifier/*[IDENTIFIER-VALUE]*/

See the supported identifiers sections for information on the identifier formats supported.

Examples

https://di-api.reincubate.com/v1/identify-identifier/iPhone5,3/

$ python -m deviceidentifier.cli.identify_identifier iPhone5,3
{
    "iPhone5,3": [
        "apple_identifier"
    ]
}
wzxhzdk:70 Calls to the API through this client then become easy: wzxhzdk:71 wzxhzdk:72 -->

How can we help?

Our support team are here to help!

Our office hours are Monday to Friday, 9 AM to 5 PM GMT. The time is currently 5:41 AM GMT.

We aim to reply to all messages within one working day.

Go to support section › Contact the enterprise team ›
Our awesome support team

Can we improve this article?

We love hearing from users: why not drop us an email, leave a comment, or tweet @reincubate?

© 2008 - 2019 Reincubate Ltd. All rights reserved. Registered in England and Wales #5189175, VAT GB151788978. Reincubate® is a registered trademark. Privacy & terms. We recommend 2FA. Built with in London.