> ## Documentation Index > Fetch the complete documentation index at: https://developers.investorlift.com/llms.txt > Use this file to discover all available pages before exploring further. # Read one deal > Reads one deal with its media, its verification state, the seller stub and the address block. ## OpenAPI ````yaml GET /buy/deals/{deal_id} openapi: 3.1.0 info: title: Investorlift Marketplace API version: '2026-09-18' summary: List, publish and trade wholesale real estate deals on Investorlift. description: >- The Marketplace API gives a seller organization and a buyer account the same actions the Investorlift application gives them. A seller creates a draft, publishes a deal, reads its leads and answers offers. A buyer searches deals, asks for an address, makes an offer and keeps a buy box. Every answer carries a request id, and every refusal carries a problem code with one recovery sentence. contact: name: Investorlift support email: support@investorlift.com servers: - url: https://api.investorlift.com/marketplace/v1 description: Production security: - oauth2: [] tags: - name: sell description: What a seller organization does with its drafts and deals. - name: buy description: What a buyer account does with deals, offers and buy boxes. - name: me description: What this token can do right now. - name: events description: >- What Investorlift sends to a webhook endpoint, one entry for each event type. paths: /buy/deals/{deal_id}: get: tags: - buy summary: Read one deal description: >- Reads one deal with its media, its verification state, the seller stub and the address block. The address block carries the address state and the agreement with its URL. The read also carries your own offers and requests on the deal. The seller phone is the Investorlift tracking number of the deal manager. This read counts one row against the daily deal budget. operationId: getMarketplaceDeal parameters: - name: deal_id in: path required: true description: The public id in the path, for example deal_id as mdl_a1b2c3d4e5f6. schema: type: string responses: '200': description: Success headers: X-Request-Id: $ref: '#/components/headers/XRequestId' content: application/json: schema: type: object properties: data: $ref: '#/components/schemas/DealDetail' meta: $ref: '#/components/schemas/Meta' required: - data - meta additionalProperties: false '400': description: Identifier malformed headers: X-Request-Id: $ref: '#/components/headers/XRequestId' content: application/problem+json: schema: $ref: '#/components/schemas/Problem.invalid_id' '401': description: Not authenticated headers: X-Request-Id: $ref: '#/components/headers/XRequestId' content: application/problem+json: schema: $ref: '#/components/schemas/Problem.unauthorized' '403': description: Designation missing, Refused, Scope missing, Terms not accepted headers: X-Request-Id: $ref: '#/components/headers/XRequestId' content: application/problem+json: schema: oneOf: - $ref: '#/components/schemas/Problem.designation_required' - $ref: '#/components/schemas/Problem.forbidden' - $ref: '#/components/schemas/Problem.insufficient_scope' - $ref: '#/components/schemas/Problem.terms_required' '404': description: Not found headers: X-Request-Id: $ref: '#/components/headers/XRequestId' content: application/problem+json: schema: $ref: '#/components/schemas/Problem.not_found' '405': description: Method not allowed headers: X-Request-Id: $ref: '#/components/headers/XRequestId' content: application/problem+json: schema: $ref: '#/components/schemas/Problem.method_not_allowed' '429': description: Cap reached, Daily cap reached headers: X-Request-Id: $ref: '#/components/headers/XRequestId' content: application/problem+json: schema: oneOf: - $ref: '#/components/schemas/Problem.cap_reached' - $ref: '#/components/schemas/Problem.daily_cap_reached' '503': description: Service unavailable headers: X-Request-Id: $ref: '#/components/headers/XRequestId' content: application/problem+json: schema: $ref: '#/components/schemas/Problem.origin_error' security: - oauth2: - deals:read components: headers: XRequestId: description: The id this answer shares with the Investorlift request log. schema: type: string schemas: DealDetail: type: object properties: id: type: string description: The deal id, mdl_. status: type: string enum: - available - pending - sold asking_price: type: integer minimum: -9007199254740991 maximum: 9007199254740991 description: A whole number of dollars. arv_estimate: type: integer minimum: -9007199254740991 maximum: 9007199254740991 description: A whole number of dollars. min_emd: type: integer minimum: -9007199254740991 maximum: 9007199254740991 description: The smallest earnest money deposit this seller takes. condition: type: string enum: - FULL_GUT - LIGHT_REHAB - MAJOR_REHAB - TEAR_DOWN - TURN_KEY description: type: string description: The seller text, with contact details removed. has_price_drop: type: boolean deal_types: type: array items: type: string enum: - subject_to - creative_financing description: Creative terms the seller offers. asset_type: anyOf: - type: string enum: - property - note - hei - tax_lien - tax_deed - lease_option - type: 'null' occupancy: anyOf: - type: string enum: - owner_occupied - tenant_occupied - vacant - type: 'null' repair_estimate: anyOf: - type: object properties: min: anyOf: - type: integer minimum: -9007199254740991 maximum: 9007199254740991 description: A whole number of dollars. - type: 'null' max: anyOf: - type: integer minimum: -9007199254740991 maximum: 9007199254740991 description: A whole number of dollars. - type: 'null' required: - min - max additionalProperties: false - type: 'null' description: The repair range the seller states. monthly_hoa: anyOf: - type: integer minimum: -9007199254740991 maximum: 9007199254740991 description: A whole number of dollars. - type: 'null' address: $ref: '#/components/schemas/DealDetailAddress' property: type: object properties: type: anyOf: - type: string enum: - single_family - duplexes - multifamily - condo - townhouse - manufactured - land - commercial - type: 'null' beds: anyOf: - type: number - type: 'null' baths: anyOf: - type: number - type: 'null' sq_footage: anyOf: - type: number - type: 'null' lot_size: anyOf: - type: number - type: 'null' lot_size_unit: anyOf: - type: string enum: - sqft - acres - type: 'null' year_built: anyOf: - type: number - type: 'null' required: - type - beds - baths - sq_footage - lot_size - lot_size_unit - year_built additionalProperties: false images: type: array items: type: object properties: id: type: string url: type: string display_order: type: integer minimum: -9007199254740991 maximum: 9007199254740991 required: - id - url - display_order additionalProperties: false verification: type: object properties: status: anyOf: - type: string - type: 'null' required: - status additionalProperties: false description: What the Investorlift verification team recorded for this deal. seller: anyOf: - $ref: '#/components/schemas/DealSellerDetail' - type: 'null' published_at: anyOf: - type: string format: date-time pattern: >- ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$ - type: 'null' expires_at: type: string format: date-time pattern: >- ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$ created_at: type: string format: date-time pattern: >- ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$ updated_at: type: string format: date-time pattern: >- ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$ repair_scope: anyOf: - type: string - type: 'null' description: The seller scope of repairs, with contact details removed. videos: type: array items: type: object properties: id: type: string title: anyOf: - type: string - type: 'null' video_code: anyOf: - type: string - type: 'null' poster_url: anyOf: - type: string - type: 'null' required: - id - title - video_code - poster_url additionalProperties: false documents: type: array items: type: object properties: id: type: string type: type: string created_at: type: string format: date-time pattern: >- ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$ required: - id - type - created_at additionalProperties: false my_offers: type: array items: $ref: '#/components/schemas/OwnOffer' description: Every round of your own chains. my_requests: type: array items: $ref: '#/components/schemas/OwnRequest' required: - id - status - asking_price - arv_estimate - min_emd - condition - description - has_price_drop - deal_types - asset_type - occupancy - repair_estimate - monthly_hoa - address - property - images - verification - seller - published_at - expires_at - created_at - updated_at - repair_scope - videos - documents - my_offers - my_requests additionalProperties: false Meta: type: object properties: request_id: type: string description: The id this answer shares with the log. api_version: type: string description: The contract version the body is rendered at. required: - request_id - api_version additionalProperties: false Problem.invalid_id: allOf: - $ref: '#/components/schemas/Problem' description: >- Identifier malformed. Send the public id with its type prefix, for example mdl_a1b2c3d4e5f6. properties: type: const: https://developers.investorlift.com/marketplace/errors#invalid_id title: const: Identifier malformed status: const: 400 code: const: invalid_id recovery: const: >- Send the public id with its type prefix, for example mdl_a1b2c3d4e5f6. Problem.unauthorized: allOf: - $ref: '#/components/schemas/Problem' description: >- Not authenticated. Send a current access token for this API, and start a new authorization when the token is expired. properties: type: const: https://developers.investorlift.com/marketplace/errors#unauthorized title: const: Not authenticated status: const: 401 code: const: unauthorized recovery: const: >- Send a current access token for this API, and start a new authorization when the token is expired. Problem.designation_required: allOf: - $ref: '#/components/schemas/Problem' description: >- Designation missing. Finish the onboarding of the side you call, then repeat the call. properties: type: const: >- https://developers.investorlift.com/marketplace/errors#designation_required title: const: Designation missing status: const: 403 code: const: designation_required recovery: const: Finish the onboarding of the side you call, then repeat the call. designation: description: The designation the side of this operation needs. type: string enum: - seller - buyer Problem.forbidden: allOf: - $ref: '#/components/schemas/Problem' description: >- Refused. Ask Investorlift support why the account, the client or the organization is stopped. properties: type: const: https://developers.investorlift.com/marketplace/errors#forbidden title: const: Refused status: const: 403 code: const: forbidden recovery: const: >- Ask Investorlift support why the account, the client or the organization is stopped. Problem.insufficient_scope: allOf: - $ref: '#/components/schemas/Problem' description: >- Scope missing. Start a new authorization that asks for the scope named in the detail. properties: type: const: >- https://developers.investorlift.com/marketplace/errors#insufficient_scope title: const: Scope missing status: const: 403 code: const: insufficient_scope recovery: const: >- Start a new authorization that asks for the scope named in the detail. scope: type: string enum: - marketplace:profile - deals:read - deals:write - offers:read - offers:write - inquiries:read - inquiries:write - leads:read - leads:write - contacts:read - reviews:read - buy_boxes:manage - webhooks:manage - events:read description: The scope this operation needs. required: - scope Problem.terms_required: allOf: - $ref: '#/components/schemas/Problem' description: >- Terms not accepted. Accept the Marketplace API Terms on the consent page, then start a new authorization. properties: type: const: >- https://developers.investorlift.com/marketplace/errors#terms_required title: const: Terms not accepted status: const: 403 code: const: terms_required recovery: const: >- Accept the Marketplace API Terms on the consent page, then start a new authorization. agreement_id: type: string description: The version of the Marketplace API Terms to accept. required: - agreement_id Problem.not_found: allOf: - $ref: '#/components/schemas/Problem' description: >- Not found. Check the id, and check that the account you call with owns the resource. properties: type: const: https://developers.investorlift.com/marketplace/errors#not_found title: const: Not found status: const: 404 code: const: not_found recovery: const: >- Check the id, and check that the account you call with owns the resource. Problem.method_not_allowed: allOf: - $ref: '#/components/schemas/Problem' description: >- Method not allowed. Use one of the methods the documentation lists for this path. properties: type: const: >- https://developers.investorlift.com/marketplace/errors#method_not_allowed title: const: Method not allowed status: const: 405 code: const: method_not_allowed recovery: const: Use one of the methods the documentation lists for this path. Problem.cap_reached: allOf: - $ref: '#/components/schemas/Problem' description: >- Cap reached. Wait for the time in Retry-After, or raise your trust tier with the step in GET /me. properties: type: const: https://developers.investorlift.com/marketplace/errors#cap_reached title: const: Cap reached status: const: 429 code: const: cap_reached recovery: const: >- Wait for the time in Retry-After, or raise your trust tier with the step in GET /me. Problem.daily_cap_reached: allOf: - $ref: '#/components/schemas/Problem' description: >- Daily cap reached. Wait for the next day in UTC, or raise your trust tier with the step in GET /me. properties: type: const: >- https://developers.investorlift.com/marketplace/errors#daily_cap_reached title: const: Daily cap reached status: const: 429 code: const: daily_cap_reached recovery: const: >- Wait for the next day in UTC, or raise your trust tier with the step in GET /me. Problem.origin_error: allOf: - $ref: '#/components/schemas/Problem' description: >- Service unavailable. Repeat the call in a minute, and tell Investorlift support when the answer stays the same. properties: type: const: https://developers.investorlift.com/marketplace/errors#origin_error title: const: Service unavailable status: const: 503 code: const: origin_error recovery: const: >- Repeat the call in a minute, and tell Investorlift support when the answer stays the same. DealDetailAddress: type: object properties: status: type: string enum: - hidden - requested - approved - declined description: >- hidden at the start. requested after your address request. approved once the seller shares the street. declined after the seller declines. street: description: The street line. Absent until the status is approved. type: string city: anyOf: - type: string - type: 'null' state: anyOf: - type: string - type: 'null' zip: anyOf: - type: string - type: 'null' county: anyOf: - type: string - type: 'null' latitude: anyOf: - type: number - type: 'null' longitude: anyOf: - type: number - type: 'null' is_approximate: type: boolean description: True while the coordinates sit on the coarse grid. agreement: type: object properties: id: type: string description: >- The agreement the address request binds to. Send it back in accept_agreement. url: type: string description: >- Where a person reads the agreement. Show it before the person accepts. accepted: type: boolean description: True once the buyer organization accepted it for this deal. required: - id - url - accepted additionalProperties: false required: - status - city - state - zip - county - latitude - longitude - is_approximate - agreement additionalProperties: false DealSellerDetail: type: object properties: id: type: string description: The seller id, slr_. name: type: string handle: anyOf: - type: string - type: 'null' description: The public handle of the organization. rating: anyOf: - type: number - type: 'null' description: The average star rating Mogul shows. review_count: type: integer minimum: -9007199254740991 maximum: 9007199254740991 member_since: anyOf: - type: string format: date-time pattern: >- ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$ - type: 'null' phone: anyOf: - type: string - type: 'null' description: >- The Investorlift tracking number of the deal manager, or null. Investorlift owns this number and rotates it. required: - id - name - handle - rating - review_count - member_since - phone additionalProperties: false OwnOffer: type: object properties: id: type: string description: The offer id, ofr_. status: type: string enum: - new - accepted - declined - countered - withdrawn offer_amount: type: integer minimum: -9007199254740991 maximum: 9007199254740991 description: A whole number of dollars. emd_amount: type: integer minimum: -9007199254740991 maximum: 9007199254740991 description: A whole number of dollars. financing: type: string enum: - cash - lender round: type: integer minimum: -9007199254740991 maximum: 9007199254740991 submitted_by: type: string enum: - buyer - seller created_at: type: string format: date-time pattern: >- ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$ updated_at: type: string format: date-time pattern: >- ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$ required: - id - status - offer_amount - emd_amount - financing - round - submitted_by - created_at - updated_at additionalProperties: false OwnRequest: type: object properties: id: type: string description: The inquiry id, inq_. type: type: string enum: - inquiry - address_request address_state: anyOf: - type: string enum: - requested - approved - declined - type: 'null' description: >- The state of an address request: requested, approved or declined. It is null on a plain inquiry. message: type: string created_at: type: string format: date-time pattern: >- ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$ required: - id - type - address_state - message - created_at additionalProperties: false Problem: type: object description: >- One refusal, as RFC 9457 application/problem+json. The code picks the status, the title and the recovery sentence. properties: type: type: string format: uri description: The errors page anchor of the code. title: type: string description: The short title of the code. status: type: integer description: The HTTP status of this answer. code: type: string enum: - address_unavailable - agreement_required - api_offers_disabled - below_floor - cap_reached - client_limit - daily_cap_reached - deal_changed - deal_closed - deal_incomplete - designation_required - draft_under_review - duplicate_inquiry - forbidden - idempotency_conflict - idempotency_in_progress - idv_required - insufficient_balance - insufficient_role - insufficient_scope - invalid_body - invalid_id - invalid_parameter - invalid_transition - lead_locked - method_not_allowed - no_organization - not_a_member - not_found - offer_exists - offer_required - offer_superseded - organization_required - origin_error - person_exists - preview_expired - preview_mismatch - proof_of_funds_expired - proof_of_funds_missing - rate_limited - requirement_unmet - resource_exists - resource_limit - strike_exists - strike_window_closed - terms_required - unauthorized - unknown_parameter - validation_failed - webhook_limit - webhook_url_refused - wrong_side description: The problem code. Read this, never the title. detail: type: string description: What happened for this one request. recovery: type: string description: One sentence that says what to do next. request_id: type: string description: The id this answer shares with the log. required: - type - title - status - code - detail - recovery - request_id securitySchemes: oauth2: type: oauth2 description: >- Authorization code with PKCE. The person grants the scopes on the Investorlift consent page and accepts the Marketplace API Terms there. flows: authorizationCode: authorizationUrl: https://mogul.investorlift.com/api/auth/oauth2/authorize tokenUrl: https://mogul.investorlift.com/api/auth/oauth2/token refreshUrl: https://mogul.investorlift.com/api/auth/oauth2/token scopes: marketplace:profile: Read your account, your organization and your trust tier. deals:read: Read your deals as a seller, and the deals you see as a buyer. deals:write: >- Create drafts, add media and documents, publish deals and change their status. offers:read: >- Read the offers on your deals as a seller, and your own offers as a buyer. offers:write: Make, counter, accept, decline and withdraw offers. inquiries:read: >- Read the inquiries and address requests on your deals, and your own. inquiries:write: Send inquiries and address requests, and answer address requests. leads:read: Read the leads on your deals with their history. leads:write: Set a lead status, add a lead and file a strike. contacts:read: >- Read the email address and the phone number of a buyer on your deals. reviews:read: Read a seller public profile and the reviews of that seller. buy_boxes:manage: Read and change your buy boxes and their alerts. webhooks:manage: Create, read and delete the webhook endpoints of your side. events:read: Read the event feed of your side. ```` ## Related topics - [Read one deal](/api-reference/buy/read-one-deal.md) - [Read the leads of one deal](/api-reference/sell/read-the-leads-of-one-deal.md)