Understanding the Session Payload

This section outlines the structure of the session payload that will be sent as a request body to the APIs developed by our buy-back partners, including the Max Price or Pricing API. As partners responsible for offering competitive pricing and assessing device conditions, it's crucial to understand the data you'll receive for accurate and efficient processing.

Payload Structure

The session payload encapsulates all necessary information about a trade-in device, organized into three key sections:

Device Assessments: Contains detailed grading assessments, providing insights into the device's physical condition and overall functionality. This section is pivotal for accurately appraising the device's value.
Device Identification: Includes essential identification details such as make, model, IMEI and more. This information ensures accurate and specific device evaluation.
Transaction Information: Presents transaction-related details, such as customer details, applicable in certain session states.
Session Metadata: Anything that doesn't fit into the above categories, such as the session state, the session ID, photos of the device and more.

We use JSON when sending the payload to your APIs, ensuring a consistent and structured format for easy parsing and processing. Here's the structure:

{
  "identification": { ... },
  "assessments": [ ... ],
  "metadata": { ... },
  "transaction": { ... }
}

Session State Variability

The comprehensiveness of the session payload can vary depending on the session's current state:

Creation

Empty at the beginning (only useful for internal use). You can utilise hooks here if you want to block / get notified about the session creation.

Identification

Focused on device identification. As an example you might get this:

{
  "identification": {
    "brand": "Apple",
    "model": "iPhone 12 Pro Max",
    "modelName": "A2410",
    "manufacturer": "Apple Inc",
    "color": "Silver",
    "capacity": "256GB",
    "description": "Apple iPhone 12 Pro Max 256GB Silver",
    "identifier": "3567231196XXXX"
  }
}

Post-Assessment - Get Price

Expanded to include grading results and some metadata. So that would be:

{
  "identification": { ... },
  "assessments": [
    {
      "component_group": "Cosmetic Classification",
      "weight": 1,
      "assessment_types": [
        "self-lcd-condition",
        "grader-lcd-condition"
      ],
      "component": "Display",
      "condition": "A"
    },
    {
      "condition": "Faulty",
      "component_group": "Functional Classification",
      "weight": 0,
      "assessment_types": [
        "back-camera-ai"
      ],
      "component": "Back Camera"
    },
    {
      "assessment_types": [
        "digitizer"
      ],
      "component": "Digitizer",
      "condition": "Faulty",
      "component_group": "Functional Classification",
      "weight": 0
    },
    {
      "condition": "Yes",
      "component_group": "Functional Classification",
      "weight": 1,
      "assessment_types": [
        "self-buttons-work"
      ],
      "component": "Buttons Work"
    },
    {
      "weight": 1,
      "assessment_types": [
        "grader-camera-cosmetics"
      ],
      "component": "Back Cameras",
      "condition": "A",
      "component_group": "Cosmetic Classification"
    },
    {
      "assessment_types": [
        "gyroscope"
      ],
      "component": "Gyroscope",
      "condition": "Faulty",
      "component_group": "Functional Classification",
      "weight": 0
    },
    {
      "weight": 1,
      "assessment_types": [
        "grader-front-cosmetics"
      ],
      "component": "Front Side",
      "condition": "A",
      "component_group": "Cosmetic Classification"
    },
    {
      "component_group": "Functional Classification",
      "weight": 0,
      "assessment_types": [
        "biometrics"
      ],
      "component": "Biometrics",
      "condition": "Faulty"
    },
    {
      "weight": 0,
      "assessment_types": [
        "front-camera-ai"
      ],
      "component": "Front Camera",
      "condition": "Faulty",
      "component_group": "Functional Classification"
    },
    {
      "component_group": "Cosmetic Classification",
      "weight": 1,
      "assessment_types": [
        "grader-back-cosmetics"
      ],
      "component": "Back Side",
      "condition": "A"
    },
    {
      "component_group": "Functional Classification",
      "weight": 0,
      "assessment_types": [
        "audio"
      ],
      "component": "Microphone",
      "condition": "Faulty"
    },
    {
      "condition": "Faulty",
      "component_group": "Functional Classification",
      "weight": 0,
      "assessment_types": [
        "audio"
      ],
      "component": "Speaker"
    },
    {
      "weight": 1,
      "assessment_types": [
        "grader-body-frame-cosmetics"
      ],
      "component": "Body Frame",
      "condition": "A",
      "component_group": "Cosmetic Classification"
    }
  ],
  "metadata": {
    "assessmentPhotos": ["https://....png","https://....png","https://....png"],
    "pandasSessionId": "1615f097-73ce-49aa-a987-ddf88f22ca7d",
    "locationId": "4565fb56-848b-4dae-b3c5-52cdf31296ce",
    "locationName": "Acme Co Store 34"
  }
}

Transaction

All-encompassing, including customer and transaction details. So same as before but with an added transaction key:

{
  "identification": { ... },
  "assessments": [ ... ],
  "metadata": { ... },
  "transaction": {
    "fullName": "John Doe",
    "email": "[email protected]",
    "phoneNumber": "+4412345690631",
  }
}

Detailed Field Documentation

`identification` keys

Key	Type	Sample Value	Description
`brand`	string	"Apple"	The brand of the device.
`model`	string	"iPhone 12 Pro Max"	The model of the device.
`modelName`	string	"A2410"	The model name of the device, including the regulatory number.
`manufacturer`	string	"Apple Inc"	The manufacturer of the device.
`capacity`	string	"128GB"	The capacity of the device, available on iOS and selected Android devices.
`description`	string	"Apple iPhone 12 Pro Max 256GB Silver"	A full description of the device.
`identifier`	string	"356723119677240"	The IMEI for smartphones, or S/N for smartwatches.
`secondaryIdentifier`	string	"356723119677241"	(Optional) Some devices have a secondary IMEI.
`color`	string	"Silver"	(Optional) The color of the device.

`assessments` structure

N items of the following structure:

{
  "component_group": "Functional Classification",
  "weight": 0,
  "assessment_types": ["audio"],
  "component": "Microphone",
  "condition": "Faulty"
}

Assessment Fields:

Key	Type	Sample Value	Description
`component`	string	"Microphone"	The name of the component being assessed.
`condition`	string	"Working", "Faulty", "A", "B", "C", "D", "Yes"	The condition or status of the component. Varies by component type (see component table below).
`component_group`	string	"Functional Classification"	The classification group: "Functional Classification" for functional tests or "Cosmetic Classification" for cosmetic assessments.
`weight`	number	0 or 1	The weight assigned to this assessment (0 or 1).
`assessment_types`	Array<string>	`["audio"]`	An array of assessment type identifiers that indicate how this assessment was performed (e.g., "audio", "digitizer", "biometrics", etc.).

In the following table we're describing the different components we support and the possible conditions:

Component	Possible Values	Component Group	Description
`Digitizer`	Working, Faulty	Functional Classification	The test verifies that all areas of the screen can detect touch.
`Speaker`	Working, Faulty	Functional Classification	The test verifies whether the speaker is functioning or not.
`Microphone`	Working, Faulty	Functional Classification	The test verifies whether the microphone is functioning or not.
`Biometrics`	Working, Faulty	Functional Classification	The test assesses the functionality of Touch ID and Face ID, whether it's working or not.
`Front Camera`	Working, Faulty	Functional Classification	The test examines the front camera's capability to focus on a face.
`Back Camera`	Working, Faulty	Functional Classification	The test assesses back camera's capability to focus on objects.
`Gyroscope`	Working, Faulty	Functional Classification	The test assesses the functionality of the gyroscope, whether it's working or not.
`Buttons Work`	Yes	Functional Classification	The test verifies whether the device buttons are functioning properly.
`Front Side`	A, B, C, D	Cosmetic Classification	This test evaluates the cosmetic condition of the device's front side, checking for cracks or scratches.
`Back Side`	A, B, C, D	Cosmetic Classification	This test evaluates the cosmetic condition of the device's back side, checking for cracks or scratches.
`Body Frame`	A, B, C, D	Cosmetic Classification	This test evaluates the cosmetic condition of the device's body frame, checking for cracks or scratches.
`Back Cameras`	A, B, C, D	Cosmetic Classification	This test evaluates the cosmetic condition of the device's back cameras, checking for cracks or scratches.
`Display`	A, C	Cosmetic Classification	This test examines the device's Display for any blemishes, which are minor or superficial imperfections.
`Battery Class`	A, B, C	System	This test is assessed algorithmically, where A: ≥ 94%, B: 93%-86%, and C: ≤ 85% battery percentage.

`metadata` keys

Key	Type	Sample Value	Description
`assessmentPhotos`	Array<string>	`[ 'URL_1', 'URL_2' ]`	An array of strings representing links to images of the device photos.
`pandasSessionId`	string	UUID	The internal session id (it’s used on our end but might be useful to external integrators as well)
`locationId`	string	UUID	(Available on physical transactions): The internal location ID in which this session took place
`locationName`	string	Acme Co Store 34	(Available on physical transactions): The location name

`transaction` keys

Key	Type	Sample Value	Description
`fullName`	string	John Doe	The full name of the customer.
`email`	string	[email protected]	The email of the customer.
`phoneNumber`	string	+3053908XXXXX	The phone number of the customer with the country code.

Component Definitions Getting started