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 PAVE Capture URL (User Link):
https://{{your_account_name}}.vehiclecapture.com/{{session_key}}​
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:
Attribute
Description
Default Value
theme
Choose between PRO or LITE.
PRO
redirect_url
The redirect_url is the handoff URL that we will send your User to at the end of their PAVE session to continue their journey on your application or website.
https://paveapi.com
client_id
To protect your User's privacy we prefer that you send us only a client ID to avoid storing or listing any Personal Identifiable Information (PII) on our servers or from being included in the JSON object response.
NULL
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:
"session": {
    "theme": "LITE",
    "redirect_url": "https://your_redirect_url.com",
    "client_id": "SOUTH234889"
}
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:
"session": {
    "theme": "PRO",
    "redirect_url": "https://your_redirect_url.com",
    "client_id": "SOUTH234889"
}
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:
"session": {
    "theme": "CAPT",
    "redirect_url": "https://your_redirect_url.com",
    "client_id": "SOUTH234889"
}
​
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:
Pass-Through Additional User 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:
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
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"
        ]
    }
}

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

Attribute	Description	Default Value
theme	Choose between PRO or LITE.	PRO
redirect_url	The `redirect_url` is the handoff URL that we will send your User to at the end of their PAVE session to continue their journey on your application or website.	https://paveapi.com
client_id	To protect your User's privacy we prefer that you send us only a client ID to avoid storing or listing any Personal Identifiable Information (PII) on our servers or from being included in the JSON object response.	NULL

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

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

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

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

Sessions

GET Session Data

Last modified 5mo ago