Quote Request Endpoint

Your own website can send a quote request straight into DrillerDB. It is the same endpoint the DrillerDB contractor directory uses for its Request a Quote form, so a request from your site lands exactly where a directory request does: the contractor is emailed, the homeowner gets a confirmation, and a linked DrillerDB account sees the request in its quote queue.

This page shows you how to send one, and how to describe the job site when the homeowner has a legal description instead of a street address.

Quick Start

1. Find your directory listing id. It is the company_id your DrillerDB directory page uses for its quote form. If you do not know it, ask support@drillerdb.com and we will send it.
2. Send a POST to https://app.drillerdb.com/api/ with a JSON body and Content-Type: application/json.
3. Put "request": "submitQuote" in the body, plus the required fields below.
4. Read response in the reply. success means the quote is stored and the contractor has been notified. fail means nothing was stored, and field names the input to fix.

No sign-in and no API key is needed. The endpoint is public because homeowners use it from a browser.

The request

{
  "request": "submitQuote",
  "company_id": 12345,
  "drillerEmail": "office@yourcompany.com",
  "firstName": "Pat",
  "lastName": "Homeowner",
  "userEmail": "pat@example.com",
  "phone": "555-555-0100",
  "currentAddress": "123 Main St, Guymon, OK 73942",
  "requestType": "New Well",
  "projectDetails": "Looking for a new domestic well on our acreage.",
  "isDifferentLocation": true,
  "serviceLocationText": "Family land north of town",
  "serviceTownship": "5",
  "serviceTownshipDir": "N",
  "serviceRange": "12",
  "serviceRangeDir": "E",
  "serviceSection": "14",
  "serviceQuarter1": "NW",
  "serviceQuarter2": "SE",
  "serviceState": "OK",
  "serviceCounty": "Texas"
}

Required fields

The server checks them in that order and stops at the first failure, so a reply names one field at a time.

Request type

The directory form offers New Well, Well Reconstruction, Pump Work, Service / Repairs Only and Other. The server accepts any text here. Only one value changes what happens next: a request type containing New Well starts a geology estimate for the job site, provided the site resolved to a location. Every other type is stored without one.

Optional fields

Step-by-Step: Describe the job site with a legal description

Many rural job sites have no street address. The endpoint accepts a Public Land Survey System description instead, and turns it into a map pin on the server.

1. Collect the township, township direction, range, range direction and section. All five travel together. Send four of the five and the server ignores the description entirely and stores the request with no location.
2. Add the quarter sections if the homeowner has them. serviceQuarter1 is the quarter of the section and serviceQuarter2 the quarter of that quarter, so NW then SE reads as the SE quarter of the NW quarter.
3. Send serviceState as the two-letter state code. The state chooses the survey meridian. If you leave it out, the server uses your own company's state.
4. Send serviceCounty whenever you have it. Some states are surveyed from more than one meridian, and the county is what picks between them. In Oklahoma the Panhandle counties (Cimarron, Texas and Beaver) are surveyed from the Cimarron meridian while the rest of the state uses the Indian meridian, so a Panhandle description sent without its county resolves to the wrong place. A county the server does not recognise is not an error: the description falls back to the state's default meridian, exactly as if no county had been sent.

Letters are accepted in either case. A value outside its range is refused with a reason such as "section out of range 1-36" or "townshipDir must be N or S". When a legal description is refused, the quote is still stored; it just has no location, and a New Well request then gets no geology estimate.

How the server chooses the job-site location

The server tries three sources in a fixed order and stops at the first one that produces a pin:

1. A pin you sent in serviceLat and serviceLng.
2. One geocode of serviceLocationText when you sent one, otherwise of currentAddress. The choice is by presence only: this step does not read isDifferentLocation, so a serviceLocationText you send is geocoded even when that flag is false.
3. The legal description.

So a request that carries both a street address and a legal description never uses the legal description unless the address failed to geocode. Send the legal description alone when it is the better source.

Two refusals apply to a legal description that did convert:

• Too far from you. A pin more than 500 miles from your company's own location is treated as a wrong-place match and dropped. That exists to catch a description resolved against the wrong meridian, which is why serviceCounty matters.
• Unverified. When the survey lookup cannot find the section and only a mathematical estimate is available, the pin is dropped rather than stored. An estimate from a meridian anchor is not a verified location.

In both cases the quote is still stored and you are still notified. The request simply arrives without a map pin, and you can add one when you open it.

The reply

A stored quote answers response: "success" in one of two shapes, and the shape depends on geologyStatus. Code against both.

Every request type except a New Well with a location (geologyStatus is not_applicable, or no_location when no pin could be resolved). The contractor is emailed at once, and the reply says whether that email went out:

{
  "response": "success",
  "quoteId": 98765,
  "confirmationSent": true,
  "contractorEmailSent": true,
  "geologyStatus": "not_applicable",
  "message": "Quote submitted successfully. Contractor has been notified.",
  "drillerdb_sync": "skipped",
  "drillerdb_proposal_id": null,
  "drillerdb_workorder_id": null,
  "approval_status": null
}

A New Well request with a location (geologyStatus is pending). The contractor's email waits for the geology estimate, so this shape has no contractorEmailSent key at all and a different message. Do not read contractorEmailSent as false here; it is absent:

{
  "response": "success",
  "quoteId": 98766,
  "confirmationSent": true,
  "geologyStatus": "pending",
  "message": "Quote submitted successfully. Contractor will be notified shortly.",
  "drillerdb_sync": "skipped",
  "drillerdb_proposal_id": null,
  "drillerdb_workorder_id": null,
  "approval_status": null
}

confirmationSent says whether the homeowner's confirmation email went out. drillerdb_sync, the two ids and approval_status describe what happened inside a linked DrillerDB account; they are skipped and null for a listing that is not linked to an account.

A validation failure looks like this, and nothing is stored:

{
  "response": "fail",
  "field": "phone",
  "error": "Please enter a valid phone number.",
  "message": "Please enter a valid phone number."
}

Troubleshooting

The reply says "Quote form is missing a valid company." company_id is missing, zero, or not a number. It is your directory listing id, not your DrillerDB account number. Ask support if you are unsure which id to use.

The request arrived with no map pin. Either the address did not geocode, or the legal description was incomplete, out of range, too far from your company, or could not be verified. Send serviceLat and serviceLng when your form can collect a pin, and always include serviceCounty with a legal description.

A Panhandle job site landed in the wrong part of the state. Add serviceCounty. Without it, an Oklahoma description resolves from the Indian meridian.

Related Topics

• Integrations & AI Assistants
• Partner API
• Customer Portal