LogoLogo
  • PAVE OpenAPI Overview
  • How PAVE Works
    • Capture Link
    • Guided Capture
    • Customer Disclosures
    • Identified Vehicle Information
    • Captured Photos
    • Text Notifications
    • Inspection Results
    • Condition Report (PDF)
    • Detected Damages
    • Grading
    • Languages
    • Accuracy & Limitations
  • INTEGRATIONS
    • Developer Docs
      • Authentication
        • Generate Access Token
      • Sessions
        • POST Create Session
        • GET Session Data
        • GET Session Photos
        • GET Session Notes
        • GET Session Results
        • PUT Update Session
        • DELETE Session
      • Webhooks
        • GET All Callbacks
        • GET View a Callback
        • POST Create New Callback
        • PUT Update a Callback
        • DELETE a Callback
      • Deep Linking
        • Deep Link with React Native App
        • Deep Link Native App
        • Deep Linking with Shareable Links
      • Pass-Through Additional User Information
      • Tracking Your Sessions
      • User Session Lifecycle
      • Developer Testing
    • Account Optional Add-ons
      • Capture Only Theme (CAPT)
        • Skip Pictures
      • Right-Hand-Drive Capture Flow
  • MANAGING YOUR ACCOUNT
    • Your Guide to PAVE's Account and Enterprise Dashboards
  • Hotspots
    • PAVE Hotspots API
    • Activating PAVE Hotspots
    • Developer Docs
      • Authentication
        • Generate Access Token
      • Sessions
        • POST Create Session
        • POST Upload Photos
        • GET Results
  • OTHER RESOURCES
    • PAVE Capture Troubleshooting Guide
      • iPhone (iOS) Issues
        • Does my mobile phone work with PAVE?
        • Can't Access Camera - Incorrect Web Browser Usage
        • Can't Access Camera - Camera Permission Not Enabled
        • Camera Screen is Locked and won't Rotate
        • Inspection Get's Stuck
        • Inspection Won't Begin or Complete
        • Getting Back to an In-Progress Inspection
        • Why do I keep getting asked to retake pictures?
      • Android Phone Issues
        • Does my mobile phone work with PAVE?
        • Can't Access Camera - Incorrect Web Browser Usage
        • Can't Access Camera - Camera Permission Not Enabled
        • Camera Screen is Locked and won't Rotate
        • Inspection Gets Stuck
        • Inspection Won't Begin or Complete
        • Getting Back to an In-Progress Inspection
        • Why do I keep getting asked to retake pictures?
    • Policies
      • Service Level Agreement and Standards
      • Service Delivery Sub-Processors & Processors
      • API Strategy and Architecture
      • Information Security Policy
        • Data Quality Guideline
        • Data Retention Policy
        • Backup and Disaster Recovery
        • Data Residency
        • Data Access Control
Powered by GitBook
On this page
  • Endpoint
  • Create New Session
  • The following are the attributes of the Vehicle Object:
  • The following are the attributes of the SMS Object:
  • The following are the attributes of the Options Object:
  • Example
  • Need to Pass-Through Additional User or Session Information?
  • Authentication
  • POST Create Session Response with Capture Link
  • Response Fields
  • Example Response
  1. Hotspots
  2. Developer Docs
  3. Sessions

POST Create Session

Create a new session for every User by generating a session_key.

Endpoint

POST https://openapi.paveapi.com/v1/sessions 

Headers

Accept: application/json
Content-type: application/json
API-Key: Your_API_Key
API-Token: Your_Generated_Access_Token
API-Timestamp: UTC Datetime
Headers
Description
Example

Accept

Specifies the format in which the response should be returned. In this case, the response should be returned in JSON.

Accept: application/json

Content-type

Specifies the format in which the request body should be sent. In this case, the request body should be sent in JSON.

Content-type: application/json

API-Key

The API Key for authentication.

API-Key: Your_API_Key

API-Token

The Access Token generated for the API Key for authentication.

API-Token: Your_Generated_Access_Token

API-Timestamp

The UTC Timestamp when the request was made.

API-Timestamp: UTC Datetime

Create New Session

To create a new session, post your related information to the PAVE endpoint to generate a session_key. A session_key is a unique identifier for each user that is used to create one-time-use links. The user can return to their link at any time to continue their session.

Providing a PAVE Capture Link to the user is a three-step process:

  1. Use the POST Create Session endpoint to obtain a session_key.

  2. Add the session_key to the PAVE Capture URL to create a unique link for the user.

  3. Provide the user with the link.

Sample Request

curl -H "Accept: application/json" \
     -H "Content-type: application/json" \
     -H "API-Key: Your_API_Key" \
     -H "API-Token: Your_Generated_Access_Token" \
     -H "API-Timestamp: UTC Datetime string, example: 2021-05-30T12:49:19Z" \
     -d '{
            "vehicle": {
                "vin":"JN1CV6AR9BMXXXXXX"
            }
        }' \
     -X POST https://openapi.paveapi.com/v1/session

The following are the attributes of the Vehicle Object:

The attributes of the Vehicle Object serve two purposes: they allow you to skip the step of capturing the VIN for your end-user and provide PAVE with information about the vehicle that will be used in the session results. These attributes are represented as key/value pairs in a JSON format, where each attribute is given a name and corresponding value

Attribute
Data Type
Description
Primary/Optional

vin

string

The unique identifier of the vehicle, represented as 17 characters

Primary if skipping VIN decode

year

numeric

The model year of the vehicle

Primary if skipping VIN decode

make

string

The manufacturer of the vehicle

Primary if skipping VIN decode

model

string

The model of the vehicle

Primary if skipping VIN decode

body_type

string

The type of body of the vehicle, such as sedan, SUV, etc.

Primary if skipping VIN decode

trim

string

The level of trim or features of the vehicle

Optional

transmission

string

The type of transmission in the vehicle

Optional

ext_col

string

The color of the exterior of the vehicle

Optional

int_col

string

The color of the interior of the vehicle

Optional

odom_reading

numeric

The odometer reading of the vehicle

Optional

odom_unit

string

The unit of measurement for the odometer reading, such as "KILOMETRES" or "MILES"

Optional

vehicle.json
"vehicle": {
                "vin":"JN1CV6AR9BMXXXXXX",
                "year":"2011",
                "make":"Infiniti",
                "model":"G37",
                "body_type":"Sedan",
                "trim":"Luxury",
                "transmission":"Automatic",
                "ext_col":"Malbec Black",
                "int_col":"Wheat",
                "odom_reading":330477,
                "odom_unit":"KILOMETRES"
}

The following are the attributes of the SMS Object:

The SMS Object contains the information required to send notifications via SMS in a session. This information is stored as named key/value pairs in a straightforward JSON format, providing a convenient optional way for the end-user to receive their capture link. The following are the attributes of the SMS Object:

Attribute
Description
Optional

to

The mobile number of the recipient to receive the PAVE Capture link as an SMS message.

Yes - if no "To" is provided, the "From" will get an SMS notification when the session only reaches the COMPLETE: STATUS.

to_name

The contact name of the individual who will receive the SMS message.

Yes

from

The mobile number of an individual on your team who will receive the PAVE inspection results as a link by SMS when the User completes their capture.

Yes

by

The name used in the message sent to the User to indicate where the link was generated from.

Yes

send_results_to_phototaker

Send the inspection result link to the person conducting the inspection

Yes

sms.json
"sms": {
    "to": "647-455-XXXX",
    "to_name": "Jane Smith",
    "from": "647-422-XXXX",
    "by": "Steve's Test Dealer"
    "send_results_to_phototaker": "false"
}

The following are the attributes of the Options Object:

The options object contains optional attributes that can be passed to customize the PAVE experience for each user. The object has the following properties:

Property
Description
Type
Optional

client_id

A string that represents the client's identifier

string

Yes

contact

An object that holds information about the user's contact

object

Yes

first_name

A string that represents the first name of the user's contact

string

Yes

last_name

A string that represents the last name of the user's contact

string

Yes

Example

"options": {
    "client_id": "DLVNQC",
    "contact": {
      "first_name": "Luan",
      "last_name": "tran"
    }
}

Need to Pass-Through Additional User or Session Information?

The PAVE API allows you to pass additional information about specific users in the JSON results for a session. This is useful when you want to combine information from different sources in a single session, for example, from a lead form on a website to the results payload sent to your CRM.

Visit this section for more information:

Authentication

The PAVE Capture API requires authentication for all API calls, which is achieved through the use of an HMAC-SHA256 message hash as a header within the request.

POST Create Session Response with Capture Link

This section describes the response format for the POST request to create a session for a vehicle inspection, which includes the capture link to provide to the end-user. The response is in JSON format and contains the following fields:

Response Fields

Property
Description
Type
Optional

theme

The theme of the vehicle inspection session. This field is optional and defaults to "LITE" if not provided.

string

Yes

active

A boolean value that indicates whether the session is active or not. This field is required and must be set to true.

boolean

No

status

The status of the session. This field is optional and defaults to "IDLE" if not provided.

string

Yes

options

An optional field that can be used to provide additional options for the session.

null

Yes

language

The language of the session. This field is optional and defaults to "en" (English) if not provided.

string

Yes

created_at

The date and time when the session was created in ISO 8601 format.

string

No

updated_at

The date and time when the session was last updated in ISO 8601 format.

string

Yes

capture_url

The capture link should be provided to the end user for starting the vehicle inspection. The URL is now branded to your account consisting of the account username and the session key.

string

No

session_key

A unique key that identifies the vehicle inspection session.

string

No

redirect_url

The URL the end-user will be redirected to after the vehicle inspection.

string

Yes

inspect_ended_at

An optional field that can specify the date and time when the vehicle inspection ended in ISO 8601 format.

Null

Yes

inspect_started_at

An optional field that can specify the date and time when the vehicle inspection started in ISO 8601 format.

Null

Yes

Example Response

Here is an example response for the POST request to create a vehicle inspection session with the capture link included:

Sample Response (201:Ok)

{
    "session_key": "XXX-ABCDE12345",
    "theme": "PRO",
    "active": true,
    "status": "IDLE",
    "redirect_url": "https://www.url-to-redirect-user-to.com",
    "inspect_started_at": null,
    "inspect_ended_at": null,
    "created_at": "2021-05-25T11:50:49.000000Z",
    "updated_at": "2021-05-25T11:50:49.000000Z",
    "language": "EN",
    "capture_url": "https://demoadmin.vehiclecapture.com/TCB-123...",
    "options": {
        "client_id": "SOUTH234889",
        "sms": {
            "to": "647-455-XXXX",
            "to_name": "Jane Smith",
            "from": "647-422-XXXX",
            "by": "Steve's Test Dealer",           
        }
    },
    "vehicle": {
        "vin": "JN1CV6AR9BMXXXXXX"
    }    
}

The "capture_url" field contains the capture link that should be provided to the end user for starting the vehicle inspection. The "session_key" field contains a unique key identifying the vehicle inspection session. The end-user will be redirected to the "redirect_url" after completing the vehicle inspection.

Sample Response (400:Bad Request)

{
    "message": "Required fields are missing or invalid.",
    "errors": {
        "session.redirect_url": [
            "Invalid redirect url"
        ],
        "sms.to": [
            "Invalid phone number"
        ],
        "vehicle.vin": [
            "VIN is too short, it must be 17 characters"
        ]
    }
}
PreviousSessionsNextPOST Upload Photos

Last updated 2 years ago

Please read the section to learn more:

Pass-Through Additional User Information
Authentication
Authentication