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

The API also supports submitting new contract-bond accounts through the RAP program. See the Account Submission Work Flow to get started.

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.

Cancellations current support two different reason codes: 499 - This is a cancellation because of a principal request 500 - This is a cancellation because of non-payment

If you submit a reason code of 499 and use an effective date of the cancellation that matches the bond's effective date, we will cancel the bond flat.

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.

The PATCH will respond with an update object with information about what changed. Use the id with the GET /v1/commercial_bonds/<bond number>/updates/<updated id> to retrieve additional information including documents. Those documents may include an endorsement, power of attorney, or invoice depending on the change.

Account Submission Work Flow

Account submissions let you create a new contract-bond account through the RAP program without manual data entry. There are two program types: RAP for contractors, and RAP for Developers for real-estate developers (everything in RAP plus project details). Both are submitted to the same endpoint and are told apart by the program_type field.

Your submission is automatically scoped to the agency tied to your API key, so you never send an agency id. To see the details of the API calls, see the API Reference.

Possible statuses

A submission moves through the following statuses. The create call returns pending; the others appear as underwriting reviews the account.

• pending: The submission has been received and is awaiting an underwriting decision. This is the initial status returned by the create call.
• approved: Underwriting approved the account. Bonds can be written up to the amounts in rap_limits.
• referred: The submission could not be decided automatically and is being reviewed by an underwriter.
• declined: Underwriting declined the account.
• applicant_pending: Merchants is waiting on the applicant before the account can proceed, for example to complete the indemnity agreement e-signature.
• archived: The submission has been archived and is no longer active.

Submit an account (RAP)

curl -X "POST" "https://api.mbctestweb.com/v1/account_submissions" \
     -H 'API_KEY: keykeykey' \
     -H 'Content-Type: application/json' \
     -d $'{
  "program_type": "RAP",
  "company_name": "Construction Company, Inc.",
  "dba": "ConCo",
  "type_of_work": "General Construction",
  "legal_structure": "LLC",
  "producer_name": "Bill Billings",
  "address": {
    "line1": "123 Main St.",
    "city": "Urbandale",
    "state": "IA",
    "zip": "50322"
  },
  "indemnity_details": {
    "name": "Carl Miller",
    "title": "Owner",
    "email": "owner@company.com"
  },
  "owners": [
    {
      "name": "Carl Miller",
      "ownership_percentage": 100,
      "marital_status": "Married",
      "ssn": "123-45-6789",
      "address": {
        "line1": "123 Main St.",
        "city": "Urbandale",
        "state": "IA",
        "zip": "50322"
      },
      "spouse": {
        "name": "Rebecca Miller",
        "email": "spouse@company.com"
      }
    }
  ],
  "program_questions": {
    "is_new_business": false,
    "is_business_in_new_york_borough": false,
    "has_ever_declared_bankruptcy": false,
    "has_ever_defaulted_on_contract": false,
    "has_previous_surety_claim": false,
    "has_recent_lawsuit": false,
    "has_bonds_with_another_surety": false
  }
}'

The above command returns JSON structured like this:

{
  "success": true,
  "account_submission": {
    "id": "12345",
    "status": "pending",
    "program_type": "RAP",
    "company_name": "Construction Company, Inc.",
    "producer_name": "Bill Billings",
    "rap_limits": {
      "single_bond_limit": 1000000,
      "aggregate_limit": 1000000
    },
    "created_at": "2024-10-02 14:49:23.573743000 -0500",
    "updated_at": "2024-10-02 14:49:23.573743000 -0500"
  }
}

This work flow creates a contract account for a contractor.

1. Use GET on /v1/agency/producers to look up the valid producers for your agency. The producer_name you submit must match one of these (case-insensitive), or the submission is rejected.
2. Gather the account details: company, address, type of work, legal structure, the indemnity signer, the program questions, and the owners. The owners' ownership_percentage values must total between 90 and 100.
3. Use POST on /v1/account_submissions with program_type set to RAP. On success you receive 201 with the created submission, its status of pending, and the rap_limits that apply to the account.
4. If the request is invalid you receive 422 with a body of { "success": false, "errors": { ... } }. Correct the reported fields and resubmit.
5. Keep the id from the response so you can check the status of the submission.

A few things to keep in mind:

• Providing an email in indemnity_details may trigger an e-signature email to that person for the indemnity agreement. Omit the email if you do not want that sent yet.
• program_questions.additional_details is required when has_previous_surety_claim, has_recent_lawsuit, or has_bonds_with_another_surety is true.
• ssn is write-only. It is accepted on submission but never returned in any response.

Submit an account (RAP for Developers)

This work flow creates a contract account for a real-estate developer. It is the RAP submission plus a project and three additional program questions.

1. Follow the steps above, but set program_type to RAP for Developers.
2. Include a project_details object. Set its bond_type to either Performance or Maintenance; each requires a different set of fields (see the API Reference).
3. Answer the three additional program questions: has_forfeiture_or_pay_on_demand_language, has_strict_financial_guarantees_or_obligations, and has_environmental_or_remediation_bonds.
4. Use POST on /v1/account_submissions and handle the response as you would for a RAP submission.

Request increased bond capacity

The base program limit is returned in rap_limits. To request a higher limit, include a capacity_request describing the applicant's largest completed project in the past three years.

1. Set capacity_request.requesting_increased_capacity to true.
2. Provide the largest_project_owner, largest_project_amount, and largest_project_description. These are required whenever increased capacity is requested.
3. Submit the account as usual. The rap_limits in the response reflect the capacity your submission qualifies for.

Check the status of a submission

1. Use GET on /v1/account_submissions/<account_submission_id> to retrieve the current status along with the full submission (without any SSNs).
2. Poll this endpoint to follow the submission from pending to a final approved, referred, or declined. A referred submission is being reviewed by an underwriter and will resolve to approved or declined.

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.