Canopy Connect

https://docs.usecanopy.com/
Admin
Canopy Connect is an API platform that provides access to fully structured and verified personal and...
Tokens:271,190
Snippets:665
Trust Score:8.7
Update:1 year ago
Show doc for...
Tokens:
Raw
### Install Canopy Connect Components (HTML)

Source: https://docs.usecanopy.com/reference/components-getting-started

Include the Canopy Connect Components script in your HTML for static installation. This method ensures the `CanopyConnectComponents` object is available globally if AMD is not defined. Do not use Subresource Integrity (SRI) verification.

```html
<script src="https://components.usecanopy.com/v1/cc-components.js"></script>
```

--------------------------------

### Getting Started with Canopy Connect API

Source: https://docs.usecanopy.com/reference

Information on how to get started with the Canopy Connect API, including account creation, key generation, and implementation options.

```APIDOC
## Getting Started with Canopy Connect API

### Description
Access fully structured and verified personal and commercial P&C insurance data via API.

### Implementation Options

- **SDK**: Easily implement Canopy Connect into your website and application with our easy-to-use SDK.
- **Components**: Use Canopy Connect Components to create a custom flow for your customers for more customization.
- **App**: Build an integration for other users of Canopy Connect, and interact with Canopy on their behalf.

### Webhooks
Set up webhooks on your backend to receive real-time notifications.

### Data Retrieval
Use our pulls API to retrieve the information you need for your application.

### Security
The API is served over HTTPS TLS version 1.2 and higher to ensure data privacy. HTTP and HTTPS with TLS versions below 1.2 are not supported. HTTP response status codes are used to indicate status and errors.
```

--------------------------------

### Install Canopy Connect Components Dynamically (JavaScript)

Source: https://docs.usecanopy.com/reference/components-getting-started

Dynamically load the Canopy Connect Components script into your application using JavaScript. This method allows for error handling during script loading, ensuring graceful failure if the script cannot be appended to the document head.

```javascript
const script = document.createElement('script');
script.src = "https://components.usecanopy.com/v1/cc-components.js";
document.head.append(script);
script.onerror = () => {
  // handle failure attempt
};
```

--------------------------------

### Running the Example App (Shell)

Source: https://docs.usecanopy.com/reference/apps-example

This command executes the Node.js example application. It requires the CLIENT_ID and CLIENT_SECRET environment variables to be set, which are obtained during app creation in Canopy Connect. The command initiates the app, which will likely start a local server to handle OAuth redirects.

```shell
CLIENT_ID='xxxxx' CLIENT_SECRET='yyyyy' node apps_example.js

```

--------------------------------

### Start Demo App Server using Node.js

Source: https://docs.usecanopy.com/reference/apps-example

Initializes and starts the HTTP server for the demo application. It listens on a specified host and port, logs the server address, and automatically opens the default browser to the application's homepage. This function is intended for development and demonstration purposes.

```javascript
/**
 * @returns {void}
 */
function startApp() {
    const server = createServer(handleAppRequest);

    const homepage = new URL('/', REDIRECT_URI);
    server.listen(Number(homepage.port), homepage.hostname, () => {
        console.log(`The demo app is running at ${homepage}`);
        openBrowser(homepage);
    });
}
```

--------------------------------

### Example: ADD_MORTGAGEE Servicing Action

Source: https://docs.usecanopy.com/reference/post-servicings

This JSON example outlines the structure for an ADD_MORTGAGEE servicing action. It includes the pull ID and a servicing action object of type ADD_MORTGAGEE. This snippet is a starting point for understanding how to add mortgagee information within the servicing actions framework.

```JSON
{
  "pull_id": "7aec3a23-0c86-41f7-937e-174af7c0aa6a",
  "servicing_actions": [
    {
      "type": "ADD_MORTGAGEE",
    }
  ]
}
```

--------------------------------

### cURL GET Request Example

Source: https://docs.usecanopy.com/reference/pulls-api

Example of a cURL GET request to the UseCanopy API. This demonstrates how to construct a request with the necessary URL and headers. Ensure you replace placeholders like 'teamId' and 'pullId' with actual values.

```shell
curl --request GET \
     --url https://app.usecanopy.com/api/v1.0.0/teams/teamId/pulls/pullId \
     --header 'accept: application/json'
```

--------------------------------

### Open URL in Browser Cross-Platform in JavaScript

Source: https://docs.usecanopy.com/reference/apps-example

This JavaScript function `openBrowser` opens a given URL in the user's default web browser. It dynamically selects the appropriate command-line utility based on the operating system (`open` for macOS, `start` for Windows, `xdg-open` for Linux/others). It uses the `exec` function to run the command. Dependencies include the `process.platform` property and an `exec` function (likely from `child_process`).

```javascript
/**
 * @param {URL} url
 * @returns {void}
 */
function openBrowser(url) {
    let command;
    switch (process.platform) {
        case 'darwin':
            command = 'open';
            break;
        case 'win32':
            command = 'start';
            break;
        default:
            command = 'xdg-open';
    }

    exec(`${command} ${url}`);
}
```

--------------------------------

### Initialize and Mount Canopy Connect Form Components (JavaScript)

Source: https://docs.usecanopy.com/reference/components-getting-started

Initialize a Canopy Connect form and mount its input fields to specified DOM elements. The `form.components` object provides access to individual fields like username, password, and others, which can then be mounted to their respective selectors. An 'on ready' event is available for components.

```javascript
const form = CanopyConnectComponents.form(options);

const { username, password, thirdfield } = form.components;

form.on('ready', () => {
  // components are mounted and ready for input
});

if (username) {
  username.mount("#username"); // Use any selector or element object
}

if (password) {
  password.mount("#password"); // Use any selector or element object
}

if (thirdfield) {
  thirdfield.mount("#thirdfield"); // Use any selector or element object
}
```

--------------------------------

### Get All Widgets (Ruby)

Source: https://docs.usecanopy.com/reference/accounts-api

This Ruby snippet illustrates how to fetch widgets using the Net::HTTP library. It constructs the GET request with the appropriate URL and headers for the Canopy Connect API.

```ruby
require 'uri'
require 'net/http'

url = URI("https://app.usecanopy.com/api/v1.0.0/teams/teamId/widgets?limit=10")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["accept"] = "application/json"

response = http.request(request)
puts response.read_body
```

--------------------------------

### Add Mortgagee Payload Example

Source: https://docs.usecanopy.com/reference/get-pulls

This snippet provides an example of the payload required for an `ADD_MORTGAGEE` servicing action. It includes essential information like the policy number, mortgagee name, and address. The `type` field must be set to `ADD_MORTGAGEE`.

```json
{
  "type": "ADD_MORTGAGEE",
  "payload": {
    "carrier_policy_number": "string",
    "name": "string",
    "address": {
      "street_line1": "string",
      "street_line2": "string",
      "city": "string",
      "state": "string",
      "zip_code": "string",
      "zip_code_plus4": "string"
    }
  }
}
```

--------------------------------

### Get Pull Data by ID (JSON Example)

Source: https://docs.usecanopy.com/reference/get-pull-by-id

This snippet shows an example JSON response for the GET /pulls/:pullId endpoint. It details the structure of data returned, including pull information, associated policies, and dwelling details. This is useful for understanding the API's output for data retrieval operations.

```json
{
  "success": true,
  "pull": {
    "pull_id": "59ced597-b48f-49e3-9756-799e4c6f79a0",
    "status": "SUCCESS",
    "first_name": "Clark",
    "middle_name": "Joseph",
    "last_name": "Kent",
    "email": null,
    "account_email": "clark.kent@theplanet.com",
    "phone": "8885550000",
    "mobile_phone": "8885550000",
    "home_phone": "",
    "work_phone": "8885555555",
    "work_phone_extension": "",
    "insurance_provider_name": "statefarm",
    "team_id": "394661bc-6361-46f0-8b11-4106d6146cb4",
    "widget_id": "d2bb6d56-15ff-4760-a27c-362f9bce645a",
    "meta_data": {},
    "is_archived": false,
    "created_at": "2023-01-12T20:59:42.811Z",
    "public_alias": "demo",
    "deleted_at": null,
    "public_url": "https://app.usecanopy.com/c/demo",
    "no_policies": false,
    "no_drivers": false,
    "no_documents": false,
    "no_claims": false,
    "no_loss_events": false,
    "skipped_product_types": [
      "commercial"
    ],
    "type": "PULLING_DATA",
    "policies": [
      {
        "policy_id": "a5c3eac9-537c-4146-8de9-99fb55455126",
        "name": "HOME HO132483",
        "description": "Effective 12/13/2022 - 12/13/2023",
        "carrier_policy_number": "HO132483",
        "policy_type": "HOMEOWNERS",
        "effective_date": "2022-12-13T06:00:00.000Z",
        "expiry_date": "2023-12-13T06:00:00.000Z",
        "renewal_date": null,
        "canceled_date": null,
        "total_premium_cents": 175349,
        "carrier_name": "statefarm",
        "status": "ACTIVE",
        "limited_access": false,
        "form_of_business": null,
        "deductible_cents": null,
        "paid_in_full": true,
        "is_monoline": false,
        "dwellings": [
          {
            "dwelling_id": "dddac0de-99c0-461f-a729-2d4362d343f4",
            "mortgagee_name": "Metropolis Bank",
            "mortgage_loan_number": "123456789",
            "replacement_cost_cents": 50000000,
            "cash_value_cents": 50000000,
            "property_data_fetched": true,
            "loss_settlement_type": "REPLACEMENT_COST",
            "extended_replacement_cost_percent": 50,
            "address": {
              "address_id": "b321cd10-16f0-4738-bc5d-eb3a49e39722",
              "full_address": "344 Clinton Street, Apartment 3D, Brooklyn, NY, 11231",
              "country": null,
              "address_nature": "PHYSICAL",
              "number": "344",
              "street": "Clinton",
              "type": "St",
              "city": "Brooklyn",
              "state": "NY",
              "sec_unit_type": "Apartment",
              "sec_unit_num": "3D",
              "zip": "11231"
            },
            "coverages": [
              {
                "dwelling_coverage_id": "7985df7e-6811-43fd-b8d3-71d98a9c9766",
                "name": "DWELLING",
                "friendly_name": "Dwelling Liability",
                "premium_cents": 140675
              }
            ]
          }
        ]
      }
    ]
  }
}
```

--------------------------------

### Example App Initialization and OAuth Flow (Node.js)

Source: https://docs.usecanopy.com/reference/apps-example

This Node.js script implements the client-side of the OAuth 2.0 authorization code flow with PKCE for Canopy Connect. It handles generating authorization requests, exchanging authorization codes for access tokens, and managing session data. Dependencies include Node.js built-in modules for crypto, http, and child_process. It sets up a basic HTTP server to listen for redirect URIs.

```javascript
// See https://docs.usecanopy.com/reference/apps-example

import assert from 'node:assert/strict';
import { exec } from 'node:child_process';
import { createHash, randomBytes } from 'node:crypto';
import { createServer } from 'node:http';

// You will need to set these environment variables to the values you were given
// when your App was created.
// https://docs.usecanopy.com/reference/apps-create
const { CLIENT_ID, CLIENT_SECRET } = process.env;
assert(CLIENT_ID, 'CLIENT_ID not set');
assert(CLIENT_SECRET, 'CLIENT_SECRET not set');

// You probably won’t need to change this value but it can be useful to choose a
// different API endpoint to inspect the requests.
const CANOPY_CONNECT_ORIGIN =
    process.env.CANOPY_CONNECT_ORIGIN ?? 'https://app.usecanopy.com';

/**
 * For production you will need to pre-configure any `redirect_uri` values you
 * want to use, however Apps in Sandbox Mode can use any localhost URL.
 * @see {@link https://docs.usecanopy.com/reference/apps-create#sandbox-mode}
 */
const REDIRECT_URI = new URL('http://localhost:25055/auth-result');

/**
 * A simple store for session data. Your app would probably use a database or
 * other caching software.
 * @type {Record<Session['id'], Session['data']>}
 */
const SESSIONS = {};
const SESSION_COOKIE = 'cc-app-demo-sid';

startApp();

/**
 * The first part of the OAuth 2.0 flow begins when a user asks to link your App
 * with their Canopy Connect account. You will redirect the user on to our
 * `/oauth2/authorize` endpoint.
 *
 * @see {@link https://docs.usecanopy.com/reference/apps-authorization}
 *
 * @returns {HandlerResult}
 */
function generateAuthRequest() {
    // We’ll use `state` to store a “nonce” for the request and ensure it
    // matches when the user returns to our App. This helps to prevent
    // Cross-Site Request Forgery (CSRF) attacks.
    const state = randomBytes(8).toString('hex');

    // Generate an OAuth PKCE code verifier and challenge.
    // https://docs.usecanopy.com/reference/apps-authorization#proof-key-for-code-exchange-pkce
    const codeVerifier = randomBytes(32).toString('base64url');
    const codeChallenge = createHash('sha256')
        .update(codeVerifier)
        .digest('base64url');

    // We’ll store the state and code verifier in a session to access later.
    const session = createSession({ state, codeVerifier });

    // Create the URI to send the user to.
    // https://docs.usecanopy.com/reference/apps-authorization#proof-key-for-code-exchange-pkce
    const url = new URL('/oauth2/authorize', CANOPY_CONNECT_ORIGIN);
    url.searchParams.set('client_id', `${CLIENT_ID}`);
    url.searchParams.set('redirect_uri', `${REDIRECT_URI}`);
    url.searchParams.set('scope', 'read:pulls read:webhooks write:webhooks');
    url.searchParams.set('response_type', 'code');
    url.searchParams.set('code_challenge_method', 'S256');
    url.searchParams.set('code_challenge', codeChallenge);
    url.searchParams.set('state', state);

    // We are going to use the default `query` mode so the user is returned to
    // our app in a GET request. We do not need to set a `response_mode`.
    // https://docs.usecanopy.com/reference/apps-authorization#response-data

    return {
        statusCode: 303,
        headers: {
            Location: url.toString(),
            'Set-Cookie': `${SESSION_COOKIE}=${session.id}; Path=/; HttpOnly`,
        },
    };
}

/**
 * When the user returns to our App they should have a `code` query parameter
 * with the Authorization Code we need to request an Access Token.
 *
 * @see {@link https://docs.usecanopy.com/reference/apps-authorization#response-data}
 *
 * @param {HandlerOptions} options
 * @returns {Promise<HandlerResult>}
 */
async function handleAuthResult({ requestHeaders, requestURL }) {
    const session = getSession(requestHeaders);
    assert(session?.data?.state, 'No session state');
    assert(session?.data?.codeVerifier, 'No session codeVerifier');

    try {
        const query = requestURL.searchParams;

        // We check that the returned `state` matches our request to protect our
        // user from CSRF attacks.
        if (query.get('state') !== session.data.state) {
            throw new Error(
                `Query param state does not match session state: ${query.get(
                    'state'

```

--------------------------------

### Get All Widgets (PHP)

Source: https://docs.usecanopy.com/reference/accounts-api

This PHP example uses cURL to make a GET request to the Canopy Connect API for retrieving widgets. It sets the necessary URL and 'accept' header.

```php
<?php

$curl = curl_init();

curl_setopt($curl, CURLOPT_URL, "https://app.usecanopy.com/api/v1.0.0/teams/teamId/widgets?limit=10");
curl_setopt($curl, CURLOPT_HTTPHEADER, [
  "accept: application/json",
]);

$response = curl_exec($curl);

if (curl_errno($curl)) {
    echo 'Error:' . curl_error($curl);
}

city = json_decode($response, true);

curl_close($curl);

print_r($response);

?>
```

--------------------------------

### Check Canopy Connect Service Health (Node.js)

Source: https://docs.usecanopy.com/reference/misc-api

This Node.js snippet shows how to fetch the health status of the Canopy Connect service using the 'axios' library. It sends a GET request to the health endpoint and handles the response. Ensure 'axios' is installed (`npm install axios`).

```javascript
const axios = require('axios');

const getHealth = async () => {
    try {
        const response = await axios.get('https://app.usecanopy.com/api/v1.0.0/health', {
            headers: {
                'accept': 'application/json'
            }
        });
        console.log(response.data);
        return response.data;
    } catch (error) {
        console.error('Error fetching health:', error);
        throw error;
    }
};

getHealth();
```

--------------------------------

### SERVICING Request Payload Example

Source: https://docs.usecanopy.com/reference/post-consent-and-connect

Example JSON payload for initiating a servicing request. This includes device details, consent information, insurer credentials, and specific servicing actions like adding a mortgagee. It demonstrates the structure for performing actions against insurance data.

```json
{
  "device_identifier": "127.0.0.1",
  "terms_version": 1,
  "consent_language": "By clicking <name of button> you agree to the Canopy Connect End User Privacy Policy and Terms of Service",
  "public_alias": "demo",
  "meta_data": {},
  "insurerName": "statefarm",
  "insurerUsername": "b6d60778-0e25-40d6-843c-626222c3e524",
  "insurerPassword": "2083eb68-0757-4aac-bf8d-d331b5271909",
  "servicing_actions": [
    {
      "type": "ADD_MORTGAGEE",
      "payload": {
        "carrier_policy_number": "HO132483",
        "name": "JP MORGAN CHASE BANK NA ISAOA ATIMA",
        "address": "PO BOX 47020, ATLANTA, GA 30362",
        "loan_number": "1234567890",
        "mortgagee_type": "FIRST"
      }
    }
  ]
}
```

--------------------------------

### Get All Widgets (Node.js)

Source: https://docs.usecanopy.com/reference/accounts-api

This Node.js example shows how to make a GET request to the Canopy Connect API to fetch all widgets for a team. It utilizes the 'axios' library for HTTP requests and includes the necessary URL and headers.

```javascript
const axios = require('axios');

const options = {
  method: 'GET',
  url: 'https://app.usecanopy.com/api/v1.0.0/teams/teamId/widgets',
  params: { limit: '10' },
  headers: {
    accept: 'application/json'
  }
};

axios.request(options).then(function (response) {
  console.log(response.data);
}).catch(function (error) {
  console.error(error);
});
```

--------------------------------

### Example: ADD_VEHICLE Servicing Action

Source: https://docs.usecanopy.com/reference/post-servicings

This JSON example demonstrates the structure for an ADD_VEHICLE servicing action. It includes detailed payload information such as policy number, vehicle specifics, owner details, coverage selections, and acquisition information. This is useful for understanding the required data when adding a vehicle to a policy.

```JSON
{
  "pull_id": "7aec3a23-0c86-41f7-937e-174af7c0aa6a",
  "servicing_actions": [
    {
      "type": "ADD_VEHICLE",
      "payload": {
        "carrier_policy_number": "AU192837",
        "vehicle": {
          "model_year": 2012,
          "vin": "3N1AB6AP0CL704240",
          "type": "PRIVATE_PASSENGER"
        },
        "replacing_vin": "3FAHP0HA8CR128394",
        "registered_owner_full_name": "John Smith",
        "registered_co_owner_full_name": "Alice Smith",
        "registered_state": "AL",
        "garaging_address": "344 Clinton Street, Brooklyn, NY, 11231",
        "is_customized": true,
        "primary_use": {
          "type": "COMMUTE",
          "days_driven_per_week": 1,
          "miles_driven_each_way": 1
        },
        "primary_driver_full_name": "John Smith",
        "annual_mileage": 10000,
        "current_mileage": 2000,
        "coverage_selections": {
          "BODILY_INJURY_LIABILITY": {
            "per_person_limit_cents": 10000000,
            "per_incident_limit_cents": 30000000
          },
          "PROPERTY_DAMAGE_LIABILITY": {
            "per_incident_limit_cents": 5000000
          },
          "PERSONAL_INJURY_PROTECTION": {
            "is_declined": true
          },
          "UNINSURED_MOTORISTS": {
            "is_declined": false,
            "per_person_limit_cents": 2500000,
            "per_incident_limit_cents": 5000000
          },
          "UNDERINSURED_MOTORISTS": {
            "is_declined": false,
            "per_person_limit_cents": 2500000,
            "per_incident_limit_cents": 5000000
          },
          "COLLISION": {
            "is_declined": false,
            "deductible_cents": 50000
          },
          "COMPREHENSIVE": {
            "is_declined": false,
            "deductible_cents": 50000
          },
          "EMERGENCY_ROAD_SERVICE": {
            "is_declined": true
          },
          "RENTAL_REIMBURSEMENT": {
            "is_declined": false,
            "per_day_limit_cents": 3000,
            "max_days": 30
          }
        },
        "safety_restraint_device": "NONE",
        "anti_theft_device": "UNKNOWN",
        "daytime_running_lights": true,
        "tracking_device": true,
        "vehicle_acquisition_date": "2023-08-16",
        "vehicle_ownership": {
          "type": "OWN"
        }
      }
    }
  ]
}
```

--------------------------------

### Check Canopy Connect Service Health (Python)

Source: https://docs.usecanopy.com/reference/misc-api

This Python snippet demonstrates how to check the health of the Canopy Connect service using the 'requests' library. It sends a GET request to the health endpoint with the 'accept' header and prints the JSON response. Ensure 'requests' is installed (`pip install requests`).

```python
import requests

url = 'https://app.usecanopy.com/api/v1.0.0/health'
headers = {
    'accept': 'application/json'
}

try:
    response = requests.get(url, headers=headers)
    response.raise_for_status()  # Raise an exception for bad status codes (4xx or 5xx)
    print(response.json())
except requests.exceptions.RequestException as e:
    print(f'Error fetching health: {e}')
```

--------------------------------

### Create a Servicing Pull (Initial Consent)

Source: https://docs.usecanopy.com/reference/servicings-api

Initiates a servicing pull by adding `servicing_actions` during the initial credential and consent collection.

```APIDOC
## POST /consentAndConnect

### Description
Creates a new consent and connect pull, optionally including `servicing_actions` to perform transactions on the insurance account.

### Method
POST

### Endpoint
/consentAndConnect

### Parameters
#### Request Body
- **consumer_credentials** (object) - Required - The credentials and consent information for the consumer.
- **servicing_actions** (array) - Optional - A list of servicing actions to be performed.
  - **action_type** (string) - Required - The type of servicing action (e.g., "UPDATE_MORTGAGEE_CLAUSE").
  - **payload** (object) - Required - The data required for the specific servicing action.

### Request Example
```json
{
  "consumer_credentials": {
    "username": "consumer_username",
    "password": "consumer_password"
  },
  "servicing_actions": [
    {
      "action_type": "UPDATE_MORTGAGEE_CLAUSE",
      "payload": {
        "new_mortgagee_clause": "Updated Mortgagee Clause Inc."
      }
    }
  ]
}
```

### Response
#### Success Response (200)
- **pull_id** (string) - The unique identifier for the created pull.
- **status** (string) - The current status of the pull.

#### Response Example
```json
{
  "pull_id": "pull_abc123",
  "status": "PENDING_CONSUMER_CONFIRMATION"
}
```
```

--------------------------------

### Create a Servicing Pull (New Credentials)

Source: https://docs.usecanopy.com/reference/how-to-use-servicing-1

Initiates a new servicing pull by collecting credentials and consent from a consumer for the first time. This API can include servicing actions.

```APIDOC
## POST /consentAndConnect

### Description
Collects credentials and consent from a consumer for the first time, optionally including servicing actions.

### Method
POST

### Endpoint
/consentAndConnect

### Parameters
#### Request Body
- **servicing_actions** (array) - Optional. A list of servicing actions to be performed during this pull.

### Request Example
```json
{
  "user_id": "user_123",
  "policy_number": "POLICY12345",
  "servicing_actions": [
    {
      "type": "UPDATE_MORTGAGEE_CLAUSE",
      "data": {
        "new_mortgagee_name": "New Mortgage Corp."
      }
    }
  ]
}
```

### Response
#### Success Response (200)
- **pull_id** (string) - The ID of the created pull.
- **status** (string) - The status of the pull.

#### Response Example
```json
{
  "pull_id": "pull_xyz789",
  "status": "PENDING_CONSUMER_CONSENT"
}
```
```

--------------------------------

### cURL GET Request for Property Data

Source: https://docs.usecanopy.com/reference/enrichment-api

This snippet demonstrates how to make a GET request to the UseCanopy API to retrieve property data. It includes the necessary URL, headers, and an example of how to specify the team ID. The response will be in JSON format.

```shell
curl --request GET \
     --url https://app.usecanopy.com/api/v1.0.0/teams/teamId/enrich/propertyData \
     --header 'accept: application/json'
```

--------------------------------

### Create a Servicing Pull (Existing Credentials)

Source: https://docs.usecanopy.com/reference/how-to-use-servicing-1

Creates a servicing pull using existing credentials and consent from a previous pull. Requires a `pull_id` and `servicing_actions`.

```APIDOC
## POST /servicings

### Description
Creates a servicing pull using existing credentials and consent from an existing pull. Requires a `pull_id` and `servicing_actions`.

### Method
POST

### Endpoint
/servicings

### Parameters
#### Request Body
- **pull_id** (string) - Required. The ID of the existing pull with credentials and consent.
- **servicing_actions** (array) - Required. A list of servicing actions to be performed.

### Request Example
```json
{
  "pull_id": "pull_xyz789",
  "servicing_actions": [
    {
      "type": "ADD_VEHICLE",
      "data": {
        "vin": "12345ABCDE",
        "year": 2023,
        "make": "Toyota",
        "model": "Camry"
      }
    }
  ]
}
```

### Response
#### Success Response (200)
- **servicing_pull_id** (string) - The ID of the newly created servicing pull.
- **status** (string) - The status of the servicing pull.

#### Response Example
```json
{
  "servicing_pull_id": "servicing_pull_111",
  "status": "PENDING_CONFIRMATION"
}
```
```

--------------------------------

### Check Canopy Connect Service Health (PHP)

Source: https://docs.usecanopy.com/reference/misc-api

This PHP snippet shows how to retrieve the health status of the Canopy Connect service using cURL. It sets the appropriate URL and headers for the GET request and outputs the response body. Ensure the cURL extension is enabled in your PHP installation.

```php
<?php

$url = 'https://app.usecanopy.com/api/v1.0.0/health';
$headers = [
    'accept: application/json'
];

$ch = curl_init($url);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);

$response = curl_exec($ch);

if (curl_errno($ch)) {
    echo 'Error:' . curl_error($ch);
} else {
    echo $response;
}

curl_close($ch);
?>
```

--------------------------------

### Proof Key for Code Exchange (PKCE) Implementation

Source: https://docs.usecanopy.com/reference/apps-authorization

Guidance on implementing PKCE, a security measure for the OAuth 2.0 authorization flow. Includes code examples for generating code verifiers and challenges.

```APIDOC
## Proof Key for Code Exchange (PKCE)

### Description
PKCE is used to protect the integrity of the OAuth 2.0 authorization flow. This section details how to generate the necessary `code_verifier` and `code_challenge`.

### Method
N/A (Client-side generation)

### Endpoint
N/A

### Parameters
N/A

### Request Example
#### PKCE Generation (Node.js)
```javascript pkce_example.js
import { createHash, randomBytes } from "node:crypto";

// Create a 32-octet random sequence to use as the code_verifier. We need to
// remember this as we’ll use it in the token request later.
const codeVerifier = randomBytes(32).toString("base64url");

// Use the code_verifier to generate a code_challenge to use in the
// authorization request now.
const codeChallenge = createHash("sha256")
  .update(codeVerifier)
  .digest("base64url");

const url = new URL("https://app.usecanopy.com/oauth2/authorize");
url.searchParams.set("code_challenge_method", "S256");
url.searchParams.set("code_challenge", codeChallenge);

// … add the other OAuth params and redirect the user to this URL …
```

### Response
N/A
```

--------------------------------

### API Key Authentication

Source: https://context7.com/context7/usecanopy/llms.txt

This section details how to authenticate API requests using an API key. It shows an example of making a GET request to retrieve pull data.

```APIDOC
## API Key Authentication

### Description
Authenticate API requests using your client ID and secret.

### Method
GET

### Endpoint
`https://api.usecanopy.com/v1/teams/{team_id}/pulls/{pull_id}`

### Headers
- `x-canopy-client-id`: Your client ID
- `x-canopy-client-secret`: Your client secret

### Request Example
```bash
curl https://api.usecanopy.com/v1/teams/team_123/pulls/pull_456 \
  -H "x-canopy-client-id: your_client_id" \
  -H "x-canopy-client-secret: your_client_secret"
```
```

--------------------------------

### Get JWT Expiry Date (JavaScript)

Source: https://docs.usecanopy.com/reference/apps-example

Retrieves the expiry date from an encoded JWT. It first decodes the JWT using `decodeJWT` and then converts the 'exp' timestamp to a Date object. Throws an error if the JWT is invalid or the expiry information is missing or malformed.

```javascript
/**
 * @param {string} encodedJWT
 * @returns {Date}
 */
function getJWTExpiry(encodedJWT) {
    const jwt = decodeJWT(encodedJWT);

    if (typeof jwt.exp !== 'number') {
        throw new Error(`Invalid JWT expiry “${jwt.exp}” in ${encodedJWT}`);
    }

    return new Date(jwt.exp * 1_000);
}
```

--------------------------------

### Form Methods

Source: https://docs.usecanopy.com/reference/components-reference-documentation

This section details the core methods of the Form component, including methods for checking readiness, submitting data, and accessing components.

```APIDOC
## .ready()

### Description
Returns a `Promise` that resolves when all components within the form have been successfully mounted and are ready for interaction.

### Method
`ready`

### Endpoint
N/A

### Parameters
None

### Request Example
```javascript
form.ready().then(() => {
  console.log('Form is ready!');
});
```

### Response
#### Success Response (200)
* **Promise** - A promise that resolves when the form is ready.
```

```APIDOC
## .submit()

### Description
Submits the input values from all components within the form. It returns a `Promise` that contains either validation errors or tokenized values.

### Method
`submit`

### Endpoint
N/A

### Parameters
None

### Request Example
```javascript
form.submit().then(result => {
  if (result.errors) {
    console.error('Validation errors:', result.errors);
  } else if (result.tokens) {
    console.log('Tokens:', result.tokens);
  }
});
```

### Response
#### Success Response (200)
* **Promise** - A promise that resolves with an object containing either `errors` or `tokens`.
  * **errors** (Object) - Present if any input fails validation. Format: `{ [username|password|thirdfield]: { error: string, isEmpty: boolean } }`
  * **tokens** (Object) - Present if all inputs pass validation. Format: `{ username: string, [password]: string, [thirdfield]: string }`
```

--------------------------------

### Project Details

Source: https://docs.usecanopy.com/reference/get-servicings

Details about the project and its data structures.

```APIDOC
## Project: /websites/usecanopy

### Data Structures

This section outlines the data structures used within the project, detailing properties, types, and requirements.

#### Type Enum

- **type** (string) - Enum: `"LEASE"`, `"FINANCE"`

#### Financing Companies

- **financing_companies** (array) - List of financing companies involved.
  - **items** (object)
    - **type** (string) - Enum: `"LIEN_HOLDER"`, `"OTHER_PARTY_TO_NOTIFY"`
    - **name** (string) - Example: `"Metropolis Bank"`
    - **address** (string) - Example: `"620 Atlantic Avenue, Brooklyn, NY, 11217"`
    - **required**: `["type", "name", "address"]`

#### Loan Duration

- **loan_duration_months** (integer) - Example: `60`

#### Required Fields for Financing Details

- **required**: `["type", "financing_companies", "loan_duration_months"]`

#### Event Payload

- **type** (string) - Required.
- **payload** (object) - Required.

#### Confirmation Data

- **confirmation_data** (object)
  - **requires_agent** (boolean) - Enum: `true` - Description: Change requires intervention from the policy's agent.
  - **coverage_selections** (object)
    - **propertyNames** (string) - Enum: `"SINGLE_LIMIT_LIABILITY"`, `"BODILY_INJURY_LIABILITY"`, `"PROPERTY_DAMAGE_LIABILITY"`, `"SUPPLEMENTAL_SPOUSAL_LIABILITY"`, `"PERSONAL_INJURY_PROTECTION"`, `"COMPREHENSIVE"`, `"FULL_GLASS"`, `"COLLISION_DEDUCTIBLE_WAIVER"`, `"COLLISION"`, `"UNINSURED_MOTORISTS"`, `"UNINSURED_MOTORIST_BODILY_INJURY_LIABILITY"`, `"UNINSURED_MOTORIST_PROPERTY_DAMAGE_LIABILITY"`, `"UNINSURED_MOTORIST_BODILY_INJURY_AND_PROPERTY_DAMAGE_LIABILITY"`, `"UNDERINSURED_MOTORISTS"`, `"UNDERINSURED_MOTORIST_BODILY_INJURY_LIABILITY"`, `"UNDERINSURED_MOTORIST_PROPERTY_DAMAGE_LIABILITY"`, `"UNDERINSURED_MOTORIST_BODILY_INJURY_AND_PROPERTY_DAMAGE_LIABILITY"`, `"UNINSURED_AND_UNDERINSURED_MOTORISTS"`, `"UNINSURED_AND_UNDERINSURED_MOTORIST_BODILY_INJURY_LIABILITY"`, `"UNINSURED_AND_UNDERINSURED_MOTORIST_PROPERTY_DAMAGE_LIABILITY"`


```

--------------------------------

### Submit Canopy Connect Form Credentials (JavaScript)

Source: https://docs.usecanopy.com/reference/components-getting-started

Submit user credentials collected by the Canopy Connect form and handle the resulting errors or tokens. The `form.submit()` method returns an object containing `errors` or `tokens`. If successful, tokens for username, password, and other fields can be accessed and submitted to your backend endpoints.

```javascript
document.getElementById("your-submit-button").on("click", async () => {
  const { errors, tokens } = await form.submit();
  if (errors) {
    // display form errors
    return;
  }
  const { username, password, thirdfield } = tokens;
  // submit the tokens to POST /consentAndConnect or POST /connect
});
```

--------------------------------

### Handler Creation (.create())

Source: https://docs.usecanopy.com/reference/sdk-reference-documentation

Creates a SDK Handler instance for your link. This method allows for extensive customization of the Canopy Connect widget's behavior and appearance.

```APIDOC
## .create(options)

### Description
Returns a [Handler](https://docs.usecanopy.com/reference/sdk-reference-documentation#handler). Creates a SDK Handler instance for your link.

### Method
Static method of [CanopyConnect](https://docs.usecanopy.com/reference/sdk-reference-documentation#canopyconnect)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **options** (Object) - Required - SDK Handler options.
  - **publicAlias** (String) - Required - The public alias of the link you would like to use. Each link has a unique public alias. You can view all your links on the [Links Page](https://app.usecanopy.com/dashboard/customize). The public alias is what follows after the `/c/`in your link's url. Example: the public alias for `https://app.usecanopy.com/c/demo`is `demo`.
  - **modal** (Boolean) - Optional - Default=true. Whether Canopy Connect should be in a modal. If `false`, `options.mount` will be used.
  - **mount** (String | Element | null) - Optional - Can be used when `options.modal=false`, this specifies where Canopy Connect should be mounted to and will mount there immediately when `.create()` is called. Alternatively you can use `.mount()` to mount after `.create()` is called.
  - **pullMetaData** (Object) - Optional - Arbitrary JSON-serializable data. The API returns this data in Pull.meta_data.
  - **consentToken** (String) - Optional - A token retrieved by pre-collecting consent to skip the first screen in the widget. Reference the [Consent API](https://docs.usecanopy.com/reference/post-consent) for more information.
  - **reconnectToken** (String) - Optional - When dropping the user into the Monitoring reconnect flow provide a `reconnectToken` instead of `consentToken`. See [How to use Monitoring](ref:how-to-use-monitoring-1).
  - **onAuthenticationSuccess** (Callback) - Optional - Triggered when the user successfully authenticates with their insurance provider. Reference the ['authenticationSuccess'](https://docs.usecanopy.com/reference/sdk-reference-documentation#onauthenticationsuccess) event for data parameters.
  - **onSelectCustomInsuranceProvider** (Callback) - Optional - Triggered when the user selects "Provide policy manually" while searching for their carrier. Contact [support@usecanopy.com](mailto:support@usecanopy.com) to enable this feature. Reference the ['selectCustomInsuranceProvider'](https://docs.usecanopy.com/reference/sdk-reference-documentation#onselectcustominsuranceprovider) event for data parameters.

### Request Example
```json
{
  "options": {
    "publicAlias": "your-link-alias",
    "modal": true,
    "mount": null,
    "pullMetaData": {
      "key": "value"
    },
    "consentToken": "optional-consent-token",
    "reconnectToken": "optional-reconnect-token",
    "onAuthenticationSuccess": "function() { console.log('Auth Success'); }",
    "onSelectCustomInsuranceProvider": "function() { console.log('Custom Provider Selected'); }"
  }
}
```

### Response
#### Success Response (200)
- **Handler** (Object) - A Canopy Connect SDK Handler instance.

#### Response Example
```json
{
  "handlerInstance": "[Handler Object]"
}
```
```

--------------------------------

### Include Canopy Connect Initialization Script (HTML)

Source: https://docs.usecanopy.com/reference/using-the-sdk

This snippet shows how to include the Canopy Connect SDK script in your HTML. Ensure this script is loaded directly from the provided CDN URL. Do not use Subresource Integrity (SRI) verification as it may prevent SDK updates.

```html
<script src="https://cdn.usecanopy.com/v2/canopy-connect.js"></script>
```

--------------------------------

### GET /websites/usecanopy/servicings

Source: https://docs.usecanopy.com/reference/get-servicings

Used to get all `ServicingActions`.

```APIDOC
## GET /websites/usecanopy/servicings

### Description
Used to get all `ServicingActions`.

### Method
GET

### Endpoint
/websites/usecanopy/servicings

### Parameters
#### Query Parameters
- **limit** (integer) - Optional - Pagination limit. Default is 100. Minimum 1, Maximum 100.
- **offset** (integer) - Optional - Pagination offset from the first result.
- **pull_id** (string) - Optional - Filter used to list `ServicingsActions` related to a `Pull`.

### Response
#### Success Response (200)
- **data** (array) - List of Servicing Actions.
- **meta** (object) - Metadata about the response.
  - **count** (integer) - The number of items returned.
  - **total** (integer) - The total number of items available.

#### Response Example
```json
{
  "data": [
    {
      "id": "647e9b1b-0b1b-4b1b-8b1b-1b1b1b1b1b1b",
      "created_at": "2023-01-01T10:00:00Z",
      "updated_at": "2023-01-01T10:00:00Z"
    }
  ],
  "meta": {
    "count": 1,
    "total": 10
  }
}
```

#### Error Response (400)
- **error** (string) - Enum: `INVALID_INPUT`

#### Error Response (401)
- **error** (string) - Enum: `UNAUTHORIZED`

#### Error Response (403)
- **error** (string) - Enum: `SUBSCRIPTION_INACTIVE`, `UNAUTHORIZED`
```

--------------------------------

### POST /monitorings

Source: https://docs.usecanopy.com/reference/post-monitoring

Creates a new monitoring resource.

```APIDOC
## POST /monitorings

### Description
Used to create a monitoring.

### Method
POST

### Endpoint
/monitorings

### Parameters
#### Request Body
- **name** (string) - Required - The name of the monitoring.
- **type** (string) - Required - The type of monitoring (e.g., "website", "api").
- **target** (string) - Required - The target URL or endpoint to monitor.
- **interval** (integer) - Optional - The interval in seconds for checks (default: 60).

### Request Example
```json
{
  "name": "Homepage Uptime",
  "type": "website",
  "target": "https://www.example.com",
  "interval": 300
}
```

### Response
#### Success Response (201 Created)
- **id** (string) - The unique identifier of the created monitoring.
- **name** (string) - The name of the monitoring.
- **type** (string) - The type of monitoring.
- **target** (string) - The target URL or endpoint.
- **interval** (integer) - The check interval.
- **createdAt** (string) - The timestamp when the monitoring was created.

#### Response Example
```json
{
  "id": "mon-12345abcde",
  "name": "Homepage Uptime",
  "type": "website",
  "target": "https://www.example.com",
  "interval": 300,
  "createdAt": "2023-10-27T10:00:00Z"
}
```
```
Tokens:
Raw