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

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.

Replace {{your_account_name}} with the username for your PAVE account and replace {{session_key}} with the session_key returned from your request.

Introducing the New End-User Capture URL: Your Branded URL is Now Available for Use

We are excited to announce that the new end-user capture URL is now live and ready for use. You can now start using your own branded capture URL in place of the previously listed URL

https://{{your_account_name}}.vehiclecapture.com/{{session_key}}

Embed as CTA:
<a href="https://{{your_account_name}}.vehiclecapture.com/{{session_key}}><Start Inspection</a>.

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",
                "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"
            },
            "session": {
                "theme": "LITE",
                "redirect_url": "https://www.url-to-redirect-user-to.com",
                "client_id": "SOUTH234889"
            },
            "sms": {
                "to": "647-455-XXXX",
                "to_name": "Jane Smith",
                "from": "647-422-XXXX",
                "by": "Steve Test Dealer"
            }
        }' \
     -X POST https://openapi.paveapi.com/v1/sessions

Optional Fields in Payload for Non-SMS Method: Including Redirect URL is Highly Recommended"

If you are not using the SMS method, none of the fields in the payload are mandatory. However, it is highly recommended to include the redirect_url field at a minimum in order to provide a more seamless user experience

Customizable User Experience for Every Session

Enhance the PAVE experience for each User by including additional data in your request. This information is optional and if not included, a session based on the default PAVE settings (the default being the PRO version) will be generated. Each session contains information specific to that session, which you supply in your request, organized as key/value pairs in a flat JSON format.

The following are the attributes of the Session Object:

Theme Options

PAVE API currently offers three different themes for your Capture UI: LITE, PRO, and CAPT. Each theme offers a different user flow and the resulting data.

LITE Theme

The LITE theme is a lightweight user flow intended for non-professional users (Consumers). This theme does not return any session results at the end of the user flow (after completing the Disclosures and Announcements section) and will send them to the redirect_url to be included in the request.

Here's how to set the LITE theme:

Within a PAVE Business account

"session": {
    "theme": "LITE",
    "redirect_url": "https://your_redirect_url.com",
    "client_id": "SOUTH234889"
}

Within a PAVE Enterprise account

"session": {
    "theme": "LITE",
    "redirect_url": "https://your_redirect_url.com",
    "client_id": "SOUTH234889",
    "root_id": 11123
}

PRO Theme

The PRO theme offers an extended user flow that includes an overview of all the vehicle information, a description of all the detected damages, and the ability for users to edit, describe, add photos and label added damages.

Here's how to set the PRO theme:

Within a PAVE business account

"session": {
    "theme": "PRO",
    "redirect_url": "https://your_redirect_url.com",
    "client_id": "SOUTH234889"
}

Within a PAVE Enterprise account

"session": {
    "theme": "PRO",
    "redirect_url": "https://your_redirect_url.com",
    "client_id": "SOUTH234889"
    "root_id": 11123
}

CAPT Theme

The CAPT theme requires activation on your account and allows you to set the user flow to only capture selected photos that are quality checked as they get captured. This theme does not include any type of damage detection or inspection.

Please ensure the API key you are using has a CAPT theme associated to it before using.

Here's how to set the CAPT theme:

Within a PAVE Business Account

"session": {
    "theme": "CAPT",
    "redirect_url": "https://your_redirect_url.com",
    "client_id": "SOUTH234889"
}

Within a PAVE Enterprise Account

"session": {
    "theme": "CAPT",
    "redirect_url": "https://your_redirect_url.com",
    "client_id": "SOUTH234889"
    "root_id": 11123
}

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:

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.

Please read the Authentication section to learn more:

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

Last updated