Endpoint Reference

Deal API

The Deal API returns full deal-level data for a single deal number. It is designed to support integrations that need a consolidated response including deal details, buyer information, vehicle data, seller data, and lienholder information. The attached Deal API draft describes the single-deal endpoint, headers, parameters, and a representative sample response.

Overview Endpoint Authentication Parameters Field Mapping Examples Sample Response
Method
GET

Returns one deal record based on a single deal number.

Endpoint
/v1/deal.asp

Single-deal endpoint for retrieving a complete deal payload.

Primary Parameter
dealid

Required integer query parameter representing the deal number in the DMS.

Overview

This endpoint is intended for scenarios where an integration needs a full view of one deal at a time. Rather than returning disconnected objects, the response is organized into a predictable structure that includes the request context, deal header, server account, owner records, vehicle data, seller data, and lienholder details. That makes it a good fit for title workflows, document generation, partner lookups, and other deal-specific processing.

Documentation pattern
This page is structured as a reusable template for future endpoint docs: overview, endpoint, authentication, parameters, field mapping, examples, and sample response. New endpoint pages can follow this same layout.
Optional state-specific fields
When state=ma is supplied, the response includes an additional ma object with Massachusetts-specific title application data, including Section I and Section K values.

Endpoint

Property Value
Method GET
URL https://api.carprolive.com/v1/deal.asp
Purpose Returns a single deal by deal number.

Authentication

Requests to this endpoint use header-based authentication. The current design expects both a vendor key and an integration key in the request headers. The draft documentation lists both required headers and their purpose.

Header Required Description
X-Vendor-Key Yes Vendor authentication key.
X-Integration-Key Yes Dealer integration key. 
X-Vendor-Key: {YOUR-VENDOR-KEY}
X-Integration-Key: {YOUR-CLIENT-INTEGRATION-KEY}

Parameters

The Deal API requires the dealid query string parameter. It also supports an optional state parameter for state-specific response extensions.

Name Type Required Description
dealid integer Yes Deal number in the DMS.
state string No Optional state-specific response mode. Currently supports ma to include additional Massachusetts title application fields.

Field Mapping

The response is grouped into logical sections so integrators can reliably map fields into downstream workflows. The draft field mapping lists request metadata, deal information, owners, vehicle data, seller fields, and lienholder information.

Top-level groups

request, deal, server_account, flags, owner1, owner2, vehicle, seller, lienholder1, and lienholder2.

Usage guidance

Future endpoint docs can use this same section to summarize response groupings first, followed by a compact field table that covers the most important mappings without overwhelming the reader.

Field Description
request.integration_keyDealer integration key.
request.server_idDealer internal ID.
request.deal_numberDeal number.
deal.stockStock number.
deal.delivery_dateDelivery date.
flags.has_cobuyerIndicates co-buyer presence.
owner1.first_nameBuyer first name.
owner1.last_nameBuyer last name.
owner2.first_nameCo-buyer first name.
owner2.last_nameCo-buyer last name.
vehicle.vinVIN.
vehicle.yearYear.
vehicle.makeMake.
vehicle.modelModel.
vehicle.trimTrim.
vehicle.conditionNEW/USED/DEMO.
seller.nameDealer name.
seller.addressDealer address.
seller.dealer_numberDealer number.
lienholder1.nameLienholder name.
lienholder1.account_numberAccount number.
lienholder1.lien_dateLien date.

Example Requests

The draft includes sample calls using a vendor key, a demo integration key, and several example deal ids including 1, 2, 20, and 21. The examples below are presented in a reusable format that can also be used for future endpoint docs. 

curl -X GET "https://api.carprolive.com/v1/deal.asp?dealid=1" \
-H "X-Vendor-Key: {YOUR-VENDOR-KEY}" \
-H "X-Integration-Key: {YOUR-CLIENT-INTEGRATION-KEY}"
https://api.carprolive.com/v1/deal.asp?dealid=1
https://api.carprolive.com/v1/deal.asp?dealid=1&state=ma
https://api.carprolive.com/v1/deal.asp?dealid=2
https://api.carprolive.com/v1/deal.asp?dealid=20
https://api.carprolive.com/v1/deal.asp?dealid=21

Sample Response

The attached draft includes a full sample response for dealid=1. That sample shows the complete structure returned by the endpoint, including nested request, deal, owner, vehicle, seller, and lienholder objects. To keep the page readable, the example is shown below inside a scrollable response container. 

{
  "success": true,
  "data": {
    "request": {
      "integration_key": "{YOUR-CLIENT-INTEGRATION-KEY}",
      "server_id": "0000000002",
      "deal_number": 1
    },
    "deal": {
      "rid": 3,
      "deal_number": 1,
      "cta_number": "",
      "stock": "887",
      "delivery_date": "2022-04-26",
      "contract_date": null,
      "buyer1_id": 549149,
      "buyer2_id": 142306,
      "bank_id": 189,
      "company_id": 1
    },
    "server_account": {
      "name": "DIRECT LINK CORPORATION",
      "address": "840 Route 3a",
      "city": "Bow",
      "state": "NH",
      "zip_code": "03275",
      "phone": "888-890-5022",
      "email": "sales@directlinkcorp.com"
    },
    "flags": {
      "has_cobuyer": true
    },
    "owner1": {
      "rid": 549149,
      "first_name": "FRANCIS",
      "middle_name": "ZACHARY",
      "last_name": "ALAMEDA",
      "generation": "",
      "license_number": "",
      "dob": null,
      "mailing_address": "88 GRAFTON AVE APT 2",
      "mailing_city": "NEWARK",
      "mailing_state": "RI",
      "mailing_zip": "01220",
      "mailing_county": "",
      "legal_address": "",
      "legal_city": "",
      "legal_state": "",
      "legal_zip": "",
      "garage_address": "88 GRAFTON AVE APT 2",
      "garage_city": "NEWARK",
      "garage_state": "RI",
      "garage_zip": "01220",
      "email": "",
      "cell_phone": "000-000-0000",
      "home_phone": "000-000-0000",
      "work_phone": "000-000-0000"
    },
    "owner2": {
      "rid": 142306,
      "first_name": "JOAN",
      "middle_name": "FAYE",
      "last_name": "AOACOMMON",
      "generation": "",
      "license_number": "987654321",
      "dob": "1962-03-13",
      "mailing_address": "13 CHARM ST",
      "mailing_city": "FANTASY ISLAND",
      "mailing_state": "IL",
      "mailing_zip": "60750",
      "mailing_county": "",
      "legal_address": "",
      "legal_city": "",
      "legal_state": "",
      "legal_zip": "",
      "garage_address": "1 FERRY ST",
      "garage_city": "HOOKSETT",
      "garage_state": "NH",
      "garage_zip": "03106",
      "email": "test@test.com",
      "cell_phone": "000-000-0000",
      "home_phone": "000-000-0000",
      "work_phone": "000-000-0000"
    },
    "vehicle": {
      "rid": 2,
      "stock": "887",
      "vin": "1B4HS58N32F105283",
      "year": 2012,
      "make": "DODGE",
      "model": "DURANGO",
      "model_number": "",
      "body_type": "WAGON 4 DR.",
      "trim": "4DR 4WD SLT PLUS",
      "color": "BLACK",
      "interior_color": "",
      "odometer": 55693,
      "cylinders": 8,
      "gross_weight": "6400# GVWR",
      "fuel": "GAS",
      "condition": "USED",
      "title_number": "",
      "title_state": "",
      "title_issued_date": null,
      "engine": "4.7L (287) SOHC SMPI V8 inch Magnum inch engine",
      "doors": 4,
      "transmission": "AUTO",
      "drive": "FOUR WHEEL DRIVE"
    },
    "seller": {
      "rid": null,
      "name": null,
      "address": null,
      "city": null,
      "state": null,
      "zip": null,
      "county": null,
      "phone": null,
      "fax": null,
      "email": null,
      "dealer_number": null,
      "dmv_facility": null
    },
    "lienholder1": {
      "rid": 189,
      "name": "BANK OF AMERICA",
      "address": "1 WALL ST. SUITE# 4",
      "city": "WESTFORD",
      "state": "MA",
      "zip": "10963",
      "phone": "508-369-5998",
      "fax": "508-698-9665",
      "email": "shawn@directlinkcorp.com",
      "gov_code": "55987",
      "account_number": "0032698554",
      "lien_date": "2022-04-26"
    },
    "lienholder2": {
      "name": "NONE",
      "address": "",
      "city": "",
      "state": "",
      "zip": "",
      "lien_date": null
    }
  }
}

Sample Response (state=ma)

When state=ma is provided, the response includes an additional ma object with Massachusetts-specific data. 

{
    "success": true,
    "data": {
        "request": {
            "integration_key": "2XZC8J0RLVYDU631XW772Q57V6LQT0",
            "server_id": "0000000002",
            "deal_number": 1
        },
        ...
        "ma": {
            "section_i": {
                "sale_by_registered_dealer": true,
                "total_sales_price": 22399,
                "taxable_sales_price": 2399,
                "ma_sales_tax_paid": 167.93,
                "trade_1": {
                    "stock": "EFSE5",
                    "year": 2010,
                    "make": "HONDA",
                    "model": "ACCORD SDN",
                    "vin": "1HGCP2F82AA145362",
                    "allowance": 20000
                },
                "trade_2": {
                    "stock": "0",
                    "year": null,
                    "make": null,
                    "model": null,
                    "vin": null,
                    "allowance": 0
                }
            },
            "section_k": {
                "insurance_company": "AMERICAN INSURANCE CORPORATION",
                "insurance_code": ""
            }
        }
    }
}
This page establishes the baseline structure for future endpoint docs: concise overview, clear request details, authentication, parameter reference, compact mapping, example calls, and a contained sample response section.