Introduction

Merchants Bonding API.

Glossary of Surety Bond Terms

Term	Description
Account	A principal (business or individual) that has an established relationship with an agency for bonding purposes.
Agency	An insurance agency authorized to sell and service surety bonds on behalf of Merchants Bonding Company.
Attorney-in-Fact	A licensed agent authorized to sign bonds on behalf of the surety company.
Bond Amount	The maximum liability/coverage of the bond, also known as the penal sum.
Cancellation	The termination of a bond before its expiration date, initiated by the principal, obligee, or surety. May result in a return premium calculated on a flat (full refund) or pro-rata (partial refund) basis. Notices of Cancellation are sent to the principal and obligee.
Commercial Bond	A surety bond that guarantees compliance with licenses, permits, or regulations (e.g., notary bonds, contractor license bonds). Also known as a license and permit bond.
Contract Bond	A surety bond that guarantees performance of a construction contract, including payment and performance bonds, bid bonds, and maintenance bonds.
License Plate	Internal code identifying an obligation type (e.g., "PNOTR" for Notary). Used in order requests.
Non-Renewal	A decision by the surety not to renew a bond beyond its current term. Takes effect at the bond's expiration date and typically results in no return premium, since the bond completes its full term.
Obligee	The party (typically a government entity) that requires the bond and is protected by it.
Obligation	A specific bond type for a particular state and bond amount combination. Each obligation has a unique ID and may have state-specific requirements.
Premium	The amount paid for the bond.
Reinstatement	The restoration of a previously cancelled or terminated bond back to active status. Reverses a prior cancellation, restores premium and commission amounts, and generates rescind notices to the principal and obligee.
Principal	The party who purchases the bond and is obligated to perform the bonded obligation (e.g., a contractor or notary).
Surety	The insurance company (Merchants Bonding Company) that guarantees the principal's performance.

Date Formats

All dates use ISO 8601 format: YYYY-MM-DD (e.g., 2024-01-15).

API Definitions

Term	Meaning
API key	Identifier used by software during requests that identify the requestor.
Order	An API request to issue a bond immediately upon approval. Contains principal information, bond details, and payment information.
Quote	An API request to obtain bond approval without immediate issuance. Requires a separate fulfillment step to issue the bond.
Correction	A minor change to an existing bond or order. These updates are only available within 60 days of the submission date and only on certain fields.
Updateable Field	Fields that can be updated by the updates API.
Correctable Field	Fields that can be changed by the corrections API.

Work Flow

The expected use of this API depends on what you are looking to do.

Order commercial bonds

Use GET on /v1/obligations for obligation id's you will use to validate or submit and order.
Use POST on /v1/orders/validate to send order parameters and determine if it would succeed.
Use POST on /v1/orders to send us an order.
Use GET on /v1/orders/<order id> to look up an order.
Use GET on /v1/orders/<order id>/documents to retrieve documents for an order.
Use GET on /v1/orders/<order id>/documents/<identifier> to retrieve a specific document for an order.

Quote commercial bond

Use GET on /v1/obligations for obligation id's you will use to validate or submit and order.
Use GET on /v1/obligations/<obligation id> to find out what optional fields are avaiable on the obligation.
Use POST on /v1/quotes to send request for a quote on a specific obligation for an applicant. This will return an order id.

Edit quote

You can edit approved quotes and orders. You cannot edit an issued or fulfilled order.

Use PATCH on /v2/orders/<order id> to send request with a JSON payload of attributes you want to change.

Issue commercial bond

Use POST on /v1/orders/<order id>/issue to bind the quote and issue the bond. This only works if the order status is 'approved'.
Use GET on /v1/orders/<order id>/documents to retrieve documents for an order.
Use GET on /v1/orders/<order id>/documents/<identifier> to retrieve a specific document for an order.

Cancel commercial bond

Use POST on /v1/commercial_bonds/<bond number/cancel to cancel the bond.

Reinstate commercial bond

Use POST on /v1/commercial_bonds/<bond number/reinstate to reinstate the bond. It will be reinstated as of the date of cancellation.

Endorse or update commercial bond

Use PATCH on /v1/commercial_bonds/<bond number> to update the bond with changes. The changes are passed in as JSON with attributes of the changed fields.

Contract bond Work In Progress reports

Use POST v1/documents/<principal or contractor name>/MM/YYYY/<type> to send WIP documents for a particular month and year.

Authentication

Merchants Bonding uses API keys to allow access to the API.

Our API expects for the API key to be included in all API requests to the server in a header that looks like the following:

API_KEY: keykeykeykey

Your API key also controls whether you can submit work in progress updates, commercial bond information, or both.

This is maintained by Merchants Bonding company.

Errors

{
  "success": false,
  "errors": {
    "field": [
      "a reason",
      "another reason"
    ],
    "another_field": [
      "a reason",
    ]
  }
}

There will be an errors key in the response, which will typically have a field or attribute name (bond_amount), with possibly multiple error messages.

Error Code	Meaning
400	Bad Request
401	Unauthorized
403	Forbidden
404	Not Found
405	Method Not Allowed
406	Not Acceptable
500	Internal Server Error