# POST Create Session ### Endpoint ``` POST https://openapi.paveapi.com/v1/sessions ``` #### Headers ```makefile 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 | {% code title="vehicle.json" %} ```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" } ``` {% endcode %} ### 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 | {% code title="sms.json" %} ```json "sms": { "to": "647-455-XXXX", "to_name": "Jane Smith", "from": "647-422-XXXX", "by": "Steve's Test Dealer" "send_results_to_phototaker": "false" } ``` {% endcode %} ### 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 ```json "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: {% content-ref url="../../../integrations/developer-docs/pass-through-additional-user-information" %} [pass-through-additional-user-information](https://docs.paveapi.com/integrations/developer-docs/pass-through-additional-user-information) {% endcontent-ref %} ## Authentication {% hint style="warning" %} 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. {% endhint %} Please read the [Authentication](https://docs.paveapi.com/integrations/developer-docs/authentication) section to learn more: {% content-ref url="../../../integrations/developer-docs/authentication" %} [authentication](https://docs.paveapi.com/integrations/developer-docs/authentication) {% endcontent-ref %} ## 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" ] } } ``` --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.paveapi.com/hotspots/developer-docs/sessions/post-create-session.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.