REST API for marketplaces

As a marketplace, you can initiate Dealform transactions on behalf of your users.

Overview

The Dealform API is a RESTful JSON API. That means it is designed to:

  • follow standard RESTful conventions
  • accept JSON-formatted requests
  • return JSON-formatted responses

Contents

This guide covers the following topics:

Authentication

API authentication is key-based.

API keys can only be generated by marketplace users with a verified email.

As a verified marketplace user, you can create an API key by going to Account > API keys > Create an API key. Immediately save your key secret, because it will never be displayed again.

Your API key value must be provided in an "Authorization" header with a "Token" type, like this:

Authorization: Token 55555555-5555-5555-5555-555555555555

API key types

  • Live: For actual production purposes, where real records will be created, real emails will be sent, etc. Do NOT use Live keys for development or testing.
  • Test (default): For development and testing purposes, where no records will be created or emails sent, and dummy responses will be returned. These dummy responses are formatted exactly like live responses.

Every response includes a live key with a boolean value indicating if you are using a live API key.

Warning: Don't forget to use a live API key in your production environment. If Dealform is giving you success responses, but your requests don't otherwise seem successful, it is because you are using a test API key.

Errors

If your request encounters an error, the API will return an error response with this structure: 

{
  "errors": [
    "Your authentication key is invalid."
  ]
}

Acquisitions

You can use the API to create Acquisitions on behalf of buyers and sellers, to start the Dealform transaction process. You can also use the API to check the status of any Acquisition you created previously.

Create Acquisition

Start a transaction on behalf of a buyer and seller. Dealform will contact both parties to confirm they wish to proceed, then will continue to lead them through the transaction process.

Endpoint

POST https://www.dealform.com/api/v1/acquisitions

Parameters

  • buy_side_lead_email (String) - Required
    The email of the buy-side lead. (Dealform will send an invite to this email.)
  • name (String) - Required
    The buyer's email address. Provide this if you want Dealform to send an email to the buyer with the response_url. Leave this empty if you do not know the buyer's email address or want to send the response_url to the buyer your own way.
  • sell_side_lead_email (String) - Required
    The email of the sell-side lead. (Dealform will send an invite to this email.)

Response

After creating an Acquisition, you can ask both parties to check their email for an invitation from Dealform.

Example Request JSON

{
  "buy_side_lead_email": "buyer@example.com",
  "name": "Central Texas HVAC LLC",
  "sell_side_lead_email": "seller@example.com"
}

Example Response JSON

{
  "created_at": "2025-04-03T17:34:00.043Z",
  "id": "5bd50131-74ba-4132-9115-dba4c50985ec",
  "live": false,
  "name": "Central Texas HVAC LLC",
  "number": 5555,
  "object": "Acquisition",
  "state": "pending"
}

Read Acquisition

Get the details of an existing Acquisition.

Endpoint

GET https://www.dealform.com/api/v1/acquisitions/:id

Response

Example Request JSON

{
}

Example Response JSON

{
  "created_at": "2025-04-03T17:34:00.043Z",
  "id": "5bd50131-74ba-4132-9115-dba4c50985ec",
  "live": false,
  "name": "Central Texas HVAC LLC",
  "number": 5555,
  "object": "Acquisition",
  "state": "pending"
}

Questions or suggestions

If you have any questions or suggestions, please contact support.