Skip to main content
POST
/
deals
Create deal
curl --request POST \
  --url https://api.myupfront.com/v1/deals \
  --header 'Content-Type: application/json' \
  --header 'x-upfront-key: <api-key>' \
  --data '
{
  "agent_id": "123",
  "close_price": 100000000,
  "net_commission": 900000,
  "expected_close_date": "2023-01-01",
  "side": "SELLER",
  "address": "<string>",
  "reference_id": "lrq5bpyabc",
  "listing_id": "123",
  "gross_commission": 1000000,
  "agent_units": 10,
  "side_percentage": 10000,
  "status": "PENDING",
  "close_reason": "EXPIRED",
  "deal_type": "SALE",
  "property_type": "RESIDENTIAL",
  "client_metadata": {
    "key": "value"
  },
  "contacts": [
    "<contact_id>"
  ],
  "requirement_documents": {
    "123": "https://example.com/document.pdf"
  },
  "sides": [
    {
      "contact_id": "<contact_id>",
      "gross_commission": 1000000,
      "agent_units": 1,
      "side_percentage": 100
    }
  ]
}
'
{
  "id": "123",
  "status": "CLOSED",
  "phase": "APPLICATION",
  "expiry_date": "2023-02-27",
  "created_at": "2023-02-27T00:00:00Z",
  "listing_contract": {
    "id": "123",
    "side": "SELLER",
    "side_split": 10000,
    "sale_price": 100000000,
    "net_agent_commission": 1850000,
    "gross_agent_commission": 2500000,
    "commission_rate": 250,
    "expected_close_date": "2023-02-27",
    "created_at": "2023-02-27T00:00:00Z",
    "address": {
      "line1": "123 Main St",
      "line2": "Apt 1",
      "city": "New York",
      "state": "NY",
      "zip": "90210"
    },
    "agent": {
      "id": "<string>",
      "email": "[email protected]",
      "first_name": "<string>",
      "last_name": "<string>"
    }
  },
  "application": {
    "id": "<string>",
    "status": "PENDING",
    "decisioned_on": "<string>",
    "created_at": "<string>",
    "deal_id": "<string>",
    "requested_amount": 123,
    "offers": [
      {
        "id": "123",
        "expiry_date_time": "2023-02-27T00:00:00Z",
        "origination_fee_percent": 0.05,
        "percent_of_commission": 0.1,
        "created_at": "2023-02-27T00:00:00Z"
      }
    ]
  },
  "quotes": [
    {
      "id": "123",
      "created_at": "2023-02-27T00:00:00Z",
      "estimated_percent_min": 500,
      "estimated_percent_max": 750,
      "estimated_amount_min": 1540125,
      "estimated_amount_max": 1581750
    }
  ],
  "contacts": [
    {
      "id": "123",
      "contactSchemaId": "123",
      "type": "SELLER",
      "fields": [
        {
          "id": "123",
          "fieldSchemaId": "123",
          "label": "Test",
          "type": "TEXT",
          "value": "<string>"
        }
      ]
    }
  ],
  "sides": [
    {
      "contact_id": "<string>",
      "gross_commission": 1,
      "agent_units": 1,
      "side_percentage": 1
    }
  ],
  "metadata": {
    "key": "value"
  },
  "external_id": "123"
}

Authorizations

​
x-upfront-key
string
header
required

Upfront API key

Body

application/json

The deal to create

​
agent_id
string
required
Example:

"123"

​
close_price
number | null
required

The close price of the property, in cents.

Required range: x >= 0
Example:

100000000

​
net_commission
number | null
required

The net commission after fees, in cents.

Example:

900000

​
expected_close_date
string
required
Example:

"2023-01-01"

​
side
enum<string>
required
Available options:
BUYER,
SELLER,
DOUBLE,
REF,
OTHER
Example:

"SELLER"

​
address
required
Required string length: 1 - 255
​
reference_id
string
Example:

"lrq5bpyabc"

​
listing_id
string
Example:

"123"

​
gross_commission
number | null

The gross commission before fees, in cents.

Required range: x >= 0
Example:

1000000

​
agent_units
number | null

The number of units the agent is representing, in tenths. Typically 10 units (1.0) per side.

Required range: x >= 0
Example:

10

​
side_percentage
number | null

The percentage of the deal the agent is representing, in basis points.

Required range: x >= 0
Example:

10000

​
status
enum<string>
Available options:
UNAPPROVED,
PENDING,
CLOSED,
VOID
Example:

"PENDING"

​
close_reason
enum<string> | null
Available options:
EXPIRED,
MANUAL_CLOSE,
FALLEN_THROUGH
Example:

"EXPIRED"

​
deal_type
enum<string>

The type of deal (SALE or RENTAL)

Available options:
SALE,
RENTAL
Example:

"SALE"

​
property_type
enum<string>

The type of property (RESIDENTIAL or COMMERCIAL)

Available options:
RESIDENTIAL,
COMMERCIAL
Example:

"RESIDENTIAL"

​
client_metadata
object

Additional metadata for the client.

Example:
{ "key": "value" }
​
contacts
string[]
Example:
["<contact_id>"]
​
requirement_documents
object
Example:
{ "123": "https://example.com/document.pdf" }
​
sides
object[]
Example:
[
  {
    "contact_id": "<contact_id>",
    "gross_commission": 1000000,
    "agent_units": 1,
    "side_percentage": 100
  }
]

Response

The updated deal

​
id
string
required
Example:

"123"

​
status
string
required
Example:

"CLOSED"

​
phase
string
required
Example:

"APPLICATION"

​
expiry_date
string | null
required
Example:

"2023-02-27"

​
created_at
string
required
Example:

"2023-02-27T00:00:00Z"

​
listing_contract
object
required
​
application
object
required
​
quotes
object[]
required
​
contacts
object[]
required
​
sides
object[]
required
​
metadata
object
required
Example:
{ "key": "value" }
​
external_id
string
Example:

"123"