POST Create Session

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

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

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:

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:

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:

Pass-Through Additional User Information

Authentication

Please read the Authentication section to learn more:

Authentication

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

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"
        ]
    }
}