Introduction

Merchants Bonding API.

The Merchants Bonding API supports the full lifecyle of commercial bonds. This includes:

• Quoting, ordering, issuing
• Bond documents
• Correcting and endorsing
• Canceling and reinstating
• Bond form metadata via the /v1/obligations endpoint

Glossary of Surety Bond Terms

Date Formats

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

API Definitions

Work Flow

There are a number of ways to order, quote and issue commercial bonds. For instant issue bonds, which do not require credit check, you can order and issue the bond in a single step. See the Order commercial bonds workflow below.

If you prefer to get a quote before issuing a bond, you can follow the "Quote commercial bond" flow below.

Below lists a number of different work flows and operations. To see the details of the API calls, see the API Reference

Order commercial bonds

This work flow allows you to order and issue a bond in a single API call. After doing that you can retrieve the documents.

1. Use GET on /v1/obligations for obligation id's you will use to validate or submit and order.
2. Use POST on /v1/orders/validate to send order parameters and determine if it would succeed. optional
3. Use POST on /v1/orders to send us an order and issue it in a single step.
4. Use GET on /v1/orders/<order id> to look up an order.
5. Use GET on /v1/orders/<order id>/documents to retrieve documents for an order.
6. Use GET on /v1/orders/<order id>/documents/<identifier> to retrieve a specific document for an order.

Quote commercial bond

This creates a quote for a bond that is valid for 60 days. When the quote is approved you can then issue the bond with another API call. You can also edit quotes to change information.

1. Use GET on /v1/obligations for obligation id's you will use to validate or submit and order.
2. Use GET on /v1/obligations/<obligation id> to find out what optional fields are avaiable on the obligation.
3. 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. _Note: This is a v2 endpoint

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

Issue commercial bond

This lets you issue a bond from a quote. You can only issue approved bonds.

1. 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'.
2. Use GET on /v1/orders/<order id>/documents to retrieve documents for an order.
3. Use GET on /v1/orders/<order id>/documents/<identifier> to retrieve a specific document for an order.

Cancel commercial bond

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

Non-renew a commercial bond

1. Use POST on /v1/commercial_bonds/<bond number/nonrenew to cancel a bond as a non-renew.

Reinstate commercial bond

1. 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

1. 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.

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.

Obligations

There a some specific rules around bond approvals that are determined by the values below.

• instant_issue: when true the bond will be approved instantly if the bond amount is below the instant_issue_upper_limit value
• instant_issue_upper_limit: the top bond dollar amount where instant issue could happen
• automated_underwriting: when true we will try to credit approve the bond when the bond amount is below the automated_underwriting_upper_limit value
• automated_underwriting_upper_limit: the top bond dollar amount where credit approval could happen

Anything quote or order with a bond amount above the automated_underwriting_upper_limit will end up as pending and need manual approval from an underwriter inside Merchants. There are other types of quotes that could be pending. For example if the credit check fails. Or when we don't recieve owner information for the quote.

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.