> ## Knowledge Base Index
> Fetch the complete knowledge base index at: https://helpdesk.resmarksystems.com/sitemap.xml
> Use this file to discover available pages before exploring further.
> Pure-Markdown content can be obtained by appending a '.md' suffix to the content URLs listed in the sitemap (without the trailing slash).

# WaiverSign API: Creating a Signing Session

To send participants to a WaiverSign signing page, create a signing session by sending a POST request to the API. The response includes a unique URL you redirect the participant to. Any participant information you include in the request will pre-populate the signing form, reducing manual entry for your signers.
 
### Endpoint
 
```
POST https://app.waiversign.com/ws/api/session
```
 
Send your request body as JSON with the `Content-Type: application/json` header. No authentication is required.
 
### Request Parameters
 
| Parameter | Type | Required | Description |
| ---- |
| documentIdList | array | Yes | One or more document IDs to be signed. See [WaiverSign API: Getting Started](https://helpdesk.resmarksystems.com/en-us/article/waiversign-api-getting-started-as6llu/) for how to find document IDs. |
| personInfoList | array | Yes | One or more Person objects representing participants. At minimum, one person with `isAdult` set to `true` is required. See Person Object below. |
| referenceId | string | No | Your own identifier for tracking this session (e.g., a booking ID). |
| returnUrl | string | No | URL to redirect the participant to after signing is complete. |
| callbackUrl | string | No | Server-side URL that receives a POST with signed waiver data when signing is complete. See [WaiverSign API: Handling Callbacks](https://helpdesk.resmarksystems.com/en-us/article/waiversign-api-handling-callbacks-6ywunm/) for details. |
| expiresAt | string | No | When the session expires, in UTC format. Defaults to 24 hours from creation. Accepts date (`"2025-12-31"`) or datetime (`"2025-01-01T23:01:01"`) format. |
 
### Person Object
 
Each entry in `personInfoList` represents one participant. Apart from `isAdult`, all fields are optional and are used for pre-population only. The signer can edit any pre-filled values on the signing page.
 
| Parameter | Type | Description |
| ---- |
| isAdult | boolean | Whether this person is an adult. Required. Exactly one person per session must have this set to `true`. All others should be `false` (minors). |
| firstName | string | First name |
| lastName | string | Last name |
| email | string | Email address |
| birthDate | string | Date of birth in `MM/DD/YYYY` format (e.g., `"01/10/1990"`) |
| title | string | Title (e.g., `"Mr."`, `"Mrs."`) |
| nickName | string | Nickname |
| middleName | string | Middle name |
| gender | string | Gender |
| organization | string | Organization or company name |
| streetAddress | string | Street address |
| city | string | City |
| state | object | State or province, as an object with `name` and `abbreviation` fields |
| country | string | Country as an Alpha-3 code (e.g., `"USA"`, `"MEX"`, `"CAN"`) |
| postalCode | string | Postal or ZIP code |
| phoneList | array | One or more Phone objects (see below) |
| identification | object | An Identification object (see below) |
| customFieldList | array | Custom field name/value pairs (see below) |
 
**State example:**
```json
{"name": "Utah", "abbreviation": "UT"}
```
 
### Phone Object
 
Each entry in a Person's `phoneList` represents one phone number. All fields are optional.
 
| Parameter | Type | Description |
| ---- |
| phoneType | string | One of: `"Home"`, `"Mobile"`, `"Toll-Free"`, `"Local"`, `"Work"`, `"Other"` |
| phoneNumber | string | Full phone number (e.g., `"+8012342232"`) |
| dialCode | string | Country dial code (e.g., `"+1"`) |
| formattedPhoneNumber | string | Display-formatted number (e.g., `"801-234-2232"`) |
 
### Identification Object
 
Used within a Person's `identification` field.
 
| Parameter | Type | Description |
| ---- |
| type | string | One of: `"Drivers License"`, `"Passport"`, `"Social Security"` |
| number | string | Last 4 digits of the identification number |
 
### Custom Fields
 
The `customFieldList` array lets you pre-populate custom fields that are configured on your waiver document. Each entry needs a `name` and a `value`:
 
```json
"customFieldList": [
  {"name": "Medications", "value": "Yes"},
  {"name": "Emergency Contact", "value": "Lisa Turner (888-888-8888)"}
]
```
 
| The `name` must match the custom field name configured on your document exactly, including capitalization and spacing. If the name doesn't match, the value won't pre-populate.
 
For checkbox-type fields, pass selected options as a comma-separated string:
 
```json
{"name": "Sandwich Toppings", "value": "Ham,Lettuce,Tomato,Mayo"}
```
 
### Example Request
 
This example creates a session for one adult and one minor to sign a single document. The adult's information will be pre-filled on the form.
 
```json
{
  "documentIdList": ["5afba2484fa1da256ed15c7c"],
  "personInfoList": [
    {
      "isAdult": true,
      "firstName": "Tim",
      "lastName": "Turner",
      "email": "tim@example.com",
      "birthDate": "01/01/2001",
      "streetAddress": "1234 Main",
      "city": "Sandy",
      "state": {"name": "Utah", "abbreviation": "UT"},
      "country": "USA",
      "postalCode": "84111",
      "phoneList": [
        {
          "phoneType": "Mobile",
          "phoneNumber": "+8012342232",
          "dialCode": "+1",
          "formattedPhoneNumber": "801-234-2232"
        }
      ],
      "customFieldList": [
        {"name": "Emergency Contact", "value": "Lisa Turner (888-888-8888)"}
      ]
    },
    {
      "isAdult": false,
      "firstName": "Lilly",
      "lastName": "Turner",
      "birthDate": "04/02/2017"
    }
  ],
  "referenceId": "booking-12345",
  "returnUrl": "https://www.yoursite.com/thank-you",
  "callbackUrl": "https://www.yoursite.com/api/waiver-callback",
  "expiresAt": "2025-12-31"
}
```
 
### Response
 
A successful request returns a JSON object with a signing URL:
 
```json
{
  "success": true,
  "payload": {
    "url": "https://app.waiversign.com/session/5ab4092d78553d5b33af4f54"
  }
}
```
 
Redirect the participant to the returned URL to begin the signing process.
 
### Error Responses
 
If a request is invalid, the API returns a `400` status code with a JSON object describing the problem:
 
```json
{
  "code": 400,
  "message": "The 'personInfoList' field is invalid. It should contain at least one object with at least 'isAdult' property set",
  "success": false
}
```
 
Common errors include:
 
* **Missing personInfoList:** `"The 'personInfoList' field is invalid. It should contain at least one object with at least 'isAdult' property set"`
* **Missing documentIdList:** `"The documentIdList field is required and must be an array."`
* **Invalid document ID:** `"The documentIdList field has the following invalid ids: [your_invalid_id]"`
### Things to Know
 
* **Both documentIdList and personInfoList are required.** Every session needs at least one document ID and at least one person with `isAdult` set to `true`.
* **One adult per session.** Exactly one person in `personInfoList` should have `isAdult: true`. You can include multiple minors (`isAdult: false`) alongside them.
* **Sessions expire.** If you don't set `expiresAt`, the session automatically expires 24 hours after creation. Once expired, the signing URL shows a "cannot find signed session" message and will no longer load.
* **Pre-populated data is editable.** Participants can change any values that were pre-filled through the API.