DealMachine API

openapi: 3.1.0
info:
  title: DealMachine API
  version: '2026-11-05'
  description: 'GENERATED FROM DOCUMENTATION by API Evangelist on 2026-11-05: 21 operation(s) read from 17 public documentation page(s) (each
    operation names its page in x-source). This is not the provider''s published contract; DealMachine has published no machine-readable contract
    that the pipeline could find. Engine: local.'
  x-evidence-tiers:
    code-example: 12
    documentation: 9
    pages-with-code: 11
    pages-read: 17
  x-generated-from: documentation
  x-provenance: generated
  x-authored-by: API Evangelist
  x-generated: '2026-11-05'
  x-generator: generate-contract-from-docs.py
  x-engine: local
  x-sources:
  - https://api.docs.dealmachine.com/reference/people-filters.md
  - https://api.docs.dealmachine.com/reference/property-filters.md
  - https://api.docs.dealmachine.com/api-reference/oauth/token.md
  - https://api.docs.dealmachine.com/api-reference/introduction.md
  - https://api.docs.dealmachine.com/api-reference/oauth/revoke.md
  - https://api.docs.dealmachine.com/api-reference/lists/get-list.md
  - https://api.docs.dealmachine.com/api-reference/oauth/userinfo.md
  - https://api.docs.dealmachine.com/api-reference/lists/add-items.md
  - https://api.docs.dealmachine.com/api-reference/oauth/authorize.md
  - https://api.docs.dealmachine.com/api-reference/prospects/files.md
  - https://api.docs.dealmachine.com/api-reference/prospects/notes.md
  - https://api.docs.dealmachine.com/api-reference/auth/device-code.md
  - https://api.docs.dealmachine.com/api-reference/lists/list-lists.md
  - https://api.docs.dealmachine.com/api-reference/phones/check-dnc.md
  - https://api.docs.dealmachine.com/api-reference/prospects/photos.md
  - https://api.docs.dealmachine.com/api-reference/account/get-plans.md
  - https://api.docs.dealmachine.com/api-reference/account/get-usage.md
servers:
- url: https://api.v2.dealmachine.com
paths:
  /health:
    get:
      operationId: get_health
      tags:
      - Health
      summary: Service health and source version
      x-source: https://api.docs.dealmachine.com/api-reference/introduction.md
      responses:
        '200':
          description: Success (status as documented)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetHealthResponse'
      x-evidence:
        kind: documentation
  /v1/account:
    get:
      operationId: get_v1_account
      tags:
      - Account
      summary: GET /v1/account
      x-source: https://api.docs.dealmachine.com/api-reference/introduction.md
      responses:
        '200':
          description: Success (shape read from the example response on the page)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetV1AccountResponse'
      x-evidence:
        kind: code-example
        language: curl
        snippet: 'curl https://api.v2.dealmachine.com/v1/account  -H "Authorization: Bearer dm_sk_live_xxx"

          ```'
  /v1/auth/device/code:
    post:
      operationId: post_v1_auth_device_code
      tags:
      - Auth
      summary: POST /v1/auth/device/code
      x-source: https://api.docs.dealmachine.com/api-reference/auth/device-code.md
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PostV1AuthDeviceCodeRequest'
      responses:
        '201':
          description: Success (shape read from the example response on the page)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PostV1AuthDeviceCodeResponse'
      x-evidence:
        kind: code-example
        language: curl
        snippet: "curl\n    curl -X POST https://api.v2.dealmachine.com/v1/auth/device/code  -H \"Content-Type: application/json\"  -d '{\n  \
          \      \"client_id\": \"dealmachine-next-cli\",\n        \"device_name\": \"MacBook Pro\"\n      }'\n    ```"
  /v1/enrichment/name:
    post:
      operationId: post_v1_enrichment_name
      tags:
      - Enrichment
      summary: To find a person by name, use POST /v1/enrichment/name
      x-source: https://api.docs.dealmachine.com/reference/people-filters.md
      responses:
        '201':
          description: Success (status as documented)
      x-evidence:
        kind: documentation
  /v1/lists:
    get:
      operationId: get_v1_lists
      tags:
      - Lists
      summary: List All Lists
      description: Returns a paginated list of all saved lists for your organization, sorted by most recently updated.
      x-source: https://api.docs.dealmachine.com/api-reference/lists/list-lists.md
      parameters:
      - name: page
        in: query
        required: false
        schema:
          type: integer
        description: Page number.
      - name: per_page
        in: query
        required: false
        schema:
          type: integer
        description: Results per page (1-100).
      responses:
        '200':
          description: Success (status as documented)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetV1ListsResponse'
      x-evidence:
        kind: documentation
  /v1/lists/{listId}:
    get:
      operationId: get_v1_lists_listId
      tags:
      - Lists
      summary: Get List
      description: Retrieve a single list by its ID. Use this to poll for build completion after creating a list.
      x-source: https://api.docs.dealmachine.com/api-reference/lists/get-list.md
      parameters:
      - name: listId
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Success (status as documented)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetV1ListsListidResponse'
      x-evidence:
        kind: documentation
  /v1/lists/{listId}/items:
    post:
      operationId: post_v1_lists_listId_items
      tags:
      - Lists
      summary: Add Items to List
      x-source: https://api.docs.dealmachine.com/api-reference/lists/add-items.md
      parameters:
      - name: listId
        in: path
        required: true
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PostV1ListsListidItemsRequest'
      responses:
        '201':
          description: Success (status as documented)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PostV1ListsListidItemsResponse'
      x-evidence:
        kind: documentation
  /v1/oauth/authorize:
    get:
      operationId: get_v1_oauth_authorize
      tags:
      - Oauth
      summary: GET /v1/oauth/authorize
      x-source: https://api.docs.dealmachine.com/api-reference/oauth/authorize.md
      responses:
        '200':
          description: Success (status as documented)
      x-evidence:
        kind: code-example
        language: curl
        snippet: "curl\n    # Redirect the user's browser to this URL\n    open \"https://api.v2.dealmachine.com/v1/oauth/authorize? client_id=dm_cid_abc123&\
          \ redirect_uri=http://localhost:3000/callback& response_type=code& scope=account:read& state=random_state_string\"\n    ```"
  /v1/oauth/revoke:
    post:
      operationId: post_v1_oauth_revoke
      tags:
      - Oauth
      summary: POST /v1/oauth/revoke
      x-source: https://api.docs.dealmachine.com/api-reference/oauth/revoke.md
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PostV1OauthRevokeRequest'
      responses:
        '201':
          description: Success (shape read from the example response on the page)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PostV1OauthRevokeResponse'
      x-evidence:
        kind: code-example
        language: curl
        snippet: "curl\n    curl -X POST https://api.v2.dealmachine.com/v1/oauth/revoke  -H \"Content-Type: application/json\"  -d '{\n      \
          \  \"token\": \"dm_at_live_xxx\",\n        \"token_type_hint\": \"access_token\"\n      }'\n    ```"
  /v1/oauth/token:
    post:
      operationId: post_v1_oauth_token
      tags:
      - Oauth
      summary: POST /v1/oauth/token
      x-source: https://api.docs.dealmachine.com/api-reference/oauth/token.md
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PostV1OauthTokenRequest'
      responses:
        '201':
          description: Success (shape read from the example response on the page)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PostV1OauthTokenResponse'
      x-evidence:
        kind: code-example
        language: curl
        snippet: "curl -X POST https://api.v2.dealmachine.com/v1/oauth/token  -H \"Content-Type: application/json\"  -d '{\n        \"grant_type\"\
          : \"authorization_code\",\n        \"client_id\": \"dm_cid_abc123\",\n        \"client_secret\": \"dm_cs_xxx\",\n        \"code\": \"\
          dm_ac_xxx\",\n        \"redirect_uri\": \"http://localhost:3000/callback\"\n      }'\n    ```"
  /v1/oauth/userinfo:
    get:
      operationId: get_v1_oauth_userinfo
      tags:
      - Oauth
      summary: GET /v1/oauth/userinfo
      x-source: https://api.docs.dealmachine.com/api-reference/oauth/userinfo.md
      responses:
        '200':
          description: Success (shape read from the example response on the page)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetV1OauthUserinfoResponse'
      x-evidence:
        kind: code-example
        language: curl
        snippet: "curl\n    curl https://api.v2.dealmachine.com/v1/oauth/userinfo  -H \"Authorization: Bearer dm_at_live_xxx\"\n    ```"
  /v1/phones/dnc:
    post:
      operationId: post_v1_phones_dnc
      tags:
      - Phones
      summary: POST /v1/phones/dnc
      x-source: https://api.docs.dealmachine.com/api-reference/phones/check-dnc.md
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PostV1PhonesDncRequest'
      responses:
        '201':
          description: Success (shape read from the example response on the page)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PostV1PhonesDncResponse'
      x-evidence:
        kind: code-example
        language: curl
        snippet: "curl\n    curl -X POST \"https://api.v2.dealmachine.com/v1/phones/dnc\"  -H \"Authorization: Bearer dm_sk_live_xxx\"  -H \"\
          Content-Type: application/json\"  -d '{\n        \"phones\": [\n          { \"number\": \"5125551234\" },\n          { \"number\": \"\
          3145559876\" },\n          { \"number\": \"(212) 555-0100\" }\n        ]\n      }'\n    ```"
  /v1/plans:
    get:
      operationId: get_v1_plans
      tags:
      - Plans
      summary: GET /v1/plans
      x-source: https://api.docs.dealmachine.com/api-reference/account/get-plans.md
      responses:
        '200':
          description: Success (shape read from the example response on the page)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetV1PlansResponse'
      x-evidence:
        kind: code-example
        language: curl
        snippet: "curl\n    curl https://api.v2.dealmachine.com/v1/plans\n    ```"
  /v1/properties/search/count:
    post:
      operationId: post_v1_properties_search_count
      tags:
      - Properties
      summary: Count properties whose likely owner owns between 5 and 20 properties
      description: The count request is free. Returns total_properties, total_people, and total_results. Invalid numbers, values below 1, reversed
        bounds, or unsupported operators return HTTP 400 with an error identifying the filter and problem.
      x-source: https://api.docs.dealmachine.com/reference/property-filters.md
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PostV1PropertiesSearchCountRequest'
      responses:
        '201':
          description: Success (status as documented)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PostV1PropertiesSearchCountResponse'
      x-evidence:
        kind: documentation
  /v1/prospects/prospect_8812/notes:
    post:
      operationId: post_v1_prospects_prospect_8812_notes
      tags:
      - Prospects
      summary: POST /v1/prospects/prospect_8812/notes
      x-source: https://api.docs.dealmachine.com/api-reference/prospects/notes.md
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PostV1ProspectsProspect8812NotesRequest'
      responses:
        '201':
          description: Success (shape read from the example response on the page)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PostV1ProspectsProspect8812NotesResponse'
      x-evidence:
        kind: code-example
        language: curl
        snippet: "curl\n    curl -X POST \"https://api.v2.dealmachine.com/v1/prospects/prospect_8812/notes\"  -H \"Authorization: Bearer dm_sk_live_xxx\"\
          \  -H \"Content-Type: application/json\"  -d '{ \"body\": \"Owner called back, wants an offer by Friday\" }'\n    ```\n  </RequestExample>\n\
          </Aside>"
  /v1/prospects/{id}/files:
    get:
      operationId: get_v1_prospects_id_files
      tags:
      - Prospects
      summary: List files
      description: Attach, list, download, and delete files on a prospect
      x-source: https://api.docs.dealmachine.com/api-reference/prospects/files.md
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Success (status as documented)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetV1ProspectsIdFilesResponse'
      x-evidence:
        kind: documentation
    post:
      operationId: post_v1_prospects_id_files
      tags:
      - Prospects
      summary: Attach an uploaded file
      description: Attach an uploaded file
      x-source: https://api.docs.dealmachine.com/api-reference/prospects/files.md
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PostV1ProspectsIdFilesRequest'
      responses:
        '201':
          description: Success (status as documented)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PostV1ProspectsIdFilesResponse'
      x-evidence:
        kind: documentation
  /v1/prospects/{id}/files/upload-url:
    post:
      operationId: post_v1_prospects_id_files_upload_url
      tags:
      - Prospects
      summary: Get an upload target
      description: Files up to 25 MB are attached in two steps so the bytes never pass through the API
      x-source: https://api.docs.dealmachine.com/api-reference/prospects/files.md
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PostV1ProspectsIdFilesUploadUrlRequest'
      responses:
        '201':
          description: Success (status as documented)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PostV1ProspectsIdFilesUploadUrlResponse'
      x-evidence:
        kind: documentation
  /v1/prospects/{id}/notes:
    get:
      operationId: get_v1_prospects_id_notes
      tags:
      - Prospects
      summary: Prospect Notes
      x-source: https://api.docs.dealmachine.com/api-reference/prospects/notes.md
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Success (status as documented)
      x-evidence:
        kind: documentation
  /v1/prospects/{id}/photos:
    get:
      operationId: get_v1_prospects_id_photos
      tags:
      - Prospects
      summary: List photos, newest first
      x-source: https://api.docs.dealmachine.com/api-reference/prospects/photos.md
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Success (status as documented)
      x-evidence:
        kind: documentation
  /v1/usage:
    get:
      operationId: get_v1_usage
      tags:
      - Usage
      summary: GET /v1/usage
      x-source: https://api.docs.dealmachine.com/api-reference/account/get-usage.md
      responses:
        '200':
          description: Success (shape read from the example response on the page)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetV1UsageResponse'
      x-evidence:
        kind: code-example
        language: curl
        snippet: "curl\n    curl https://api.v2.dealmachine.com/v1/usage  -H \"Authorization: Bearer dm_sk_live_xxx\"\n    ```"
components:
  schemas:
    GetHealthResponse:
      type: object
      properties:
        status:
          type: string
          description: Health status, e.g., "ok"
        version:
          type: string
          description: Service version
        timestamp:
          type: string
          description: ISO‑8601 timestamp of the health check
        sourceCommit:
          type: string
          description: Full Git commit hash embedded during the build (may be null for local builds)
    GetV1AccountResponse:
      type: object
      properties:
        dm_property_id:
          type: string
        full_address:
          type: string
        address:
          type: string
        city:
          type: string
        state:
          type: string
        zip:
          type: string
        latitude:
          type: number
        longitude:
          type: number
        images:
          type: object
          properties:
            street_view:
              type: string
            satellite:
              type: string
            roadmap:
              type: string
        estimated_value:
          type: integer
        estimated_equity_percentage:
          type: integer
        num_bedrooms:
          type: integer
        contacts:
          type: array
          items:
            type: object
            properties:
              dm_person_id:
                type: string
              full_name:
                type: string
              phones:
                type: array
                items:
                  type: object
                  properties:
                    number:
                      type: string
                    type:
                      type: string
                    is_dnc:
                      type: boolean
              match_status:
                type: string
    PostV1AuthDeviceCodeRequest:
      type: object
      properties:
        client_id:
          type: string
        device_name:
          type: string
    PostV1AuthDeviceCodeResponse:
      type: object
      properties:
        client_id:
          type: string
        device_name:
          type: string
    GetV1ListsResponse:
      type: object
      properties:
        data:
          type: array
          description: Array of list objects.
        pagination:
          type: object
          description: Pagination information.
    GetV1ListsListidResponse:
      type: object
      properties:
        data:
          type: object
          description: Object containing list details.
    PostV1ListsListidItemsRequest:
      type: object
      properties:
        ids:
          type: array
          description: Array of property or person IDs to add (1-10,000 per request).
        id_type:
          type: string
          description: 'Type of IDs: `internal_property_id` or `internal_person_id`.'
        add_as_prospects:
          type: boolean
          description: Whether the records also become prospects in your workspace. Pass `false` to file them in the list without tracking them
            as prospects.
      required:
      - ids
    PostV1ListsListidItemsResponse:
      type: object
      properties:
        '200':
          type: string
          description: Items Added
        '404':
          type: string
          description: List Not Found
        '402':
          type: string
          description: Prospect Limit Reached
    PostV1OauthRevokeRequest:
      type: object
      properties:
        token:
          type: string
        token_type_hint:
          type: string
    PostV1OauthRevokeResponse:
      type: object
      properties:
        revoked:
          type: boolean
    PostV1OauthTokenRequest:
      type: object
      properties:
        grant_type:
          type: string
        client_id:
          type: string
        client_secret:
          type: string
        code:
          type: string
        redirect_uri:
          type: string
    PostV1OauthTokenResponse:
      type: object
      properties:
        access_token:
          type: string
        refresh_token:
          type: string
        token_type:
          type: string
        expires_in:
          type: integer
        scope:
          type: string
    GetV1OauthUserinfoResponse:
      type: object
      properties:
        sub:
          type: string
        org_id:
          type: integer
        org_name:
          type: string
        scope:
          type: string
        token_id:
          type: string
        app_name:
          type: string
    PostV1PhonesDncRequest:
      type: object
      properties:
        phones:
          type: array
          items:
            type: object
            properties:
              number:
                type: string
    PostV1PhonesDncResponse:
      type: object
      properties:
        data:
          type: array
          items:
            type: object
            properties:
              input:
                type: object
                properties:
                  number:
                    type: string
              matched:
                type: boolean
              do_not_call:
                type: boolean
              phone_type:
                type: string
              carrier:
                type: string
        totals:
          type: object
          properties:
            submitted:
              type: integer
            matched:
              type: integer
            unmatched:
              type: integer
        credits:
          type: object
          properties:
            used:
              type: integer
            people:
              type: integer
            deduplicated:
              type: integer
    GetV1PlansResponse:
      type: object
      properties:
        plans:
          type: array
          items:
            type: object
            properties:
              id:
                type: string
              name:
                type: string
              description:
                type: string
              type:
                type: string
              pricing:
                type: object
                properties:
                  currency:
                    type: string
                  monthly_price_cents:
                    type: integer
                  annual_price_cents:
                    type: integer
                  is_per_user:
                    type: boolean
              credits:
                type: object
                properties:
                  enrichment_per_month:
                    type: integer
                  enrichment_per_year:
                    type: integer
                  ai_per_month:
                    type: integer
              features:
                type: array
                items:
                  type: string
              stripe_price_ids:
                type: object
                properties:
                  monthly:
                    type: string
                  annual:
                    type: string
              seats:
                type: object
                properties:
                  min:
                    type: integer
                  max:
                    type: integer
        free_tier:
          type: object
          properties:
            enrichment_credit_cap:
              type: integer
            ai_credit_cap:
              type: integer
            api_access:
              type: boolean
            counts_and_estimates_cost_credits:
              type: boolean
            enrichment_requires_subscription:
              type: boolean
            available_operations:
              type: array
              items:
                type: string
    PostV1PropertiesSearchCountRequest:
      type: object
      properties:
        locations:
          type: array
          description: 'Array of location objects, e.g. { "type": "state", "code": "TX" }'
        anchor:
          type: string
          description: Anchor for the search, e.g. "properties"
        contact_audience:
          type: string
          description: Audience for contacts, e.g. "owners"
        filters:
          type: array
          description: Array of filter objects. Each filter includes filter_id, operator, and value.
      required:
      - locations
      - anchor
      - contact_audience
      - filters
    PostV1PropertiesSearchCountResponse:
      type: object
      properties:
        total_properties:
          type: integer
          description: Number of properties matching the query
        total_people:
          type: integer
          description: Number of people (contacts) matching the query
        total_results:
          type: integer
          description: Alias for total_properties
    PostV1ProspectsProspect8812NotesRequest:
      type: object
      properties:
        body:
          type: string
    PostV1ProspectsProspect8812NotesResponse:
      type: object
      properties:
        data:
          type: object
          properties:
            id:
              type: string
            prospect_id:
              type: string
            body:
              type: string
            author:
              type: object
              properties:
                type:
                  type: string
                user_id:
                  type:
                  - string
                  - 'null'
                name:
                  type:
                  - string
                  - 'null'
                api_key_id:
                  type: string
            created_at:
              type: string
              format: date-time
            updated_at:
              type: string
              format: date-time
    GetV1ProspectsIdFilesResponse:
      type: object
      properties:
        data:
          type: array
          description: Array of file objects
    PostV1ProspectsIdFilesRequest:
      type: object
      properties:
        s3_key:
          type: string
          description: S3 key returned from the upload‑url step
        file_name:
          type: string
          description: Original file name
        file_size:
          type: integer
          description: Size of the file in bytes
        content_type:
          type: string
          description: MIME type of the file
      required:
      - s3_key
      - file_name
      - file_size
      - content_type
    PostV1ProspectsIdFilesResponse:
      type: object
      properties:
        data:
          type: object
          description: Details of the attached file
    PostV1ProspectsIdFilesUploadUrlRequest:
      type: object
      properties:
        file_name:
          type: string
          description: Name of the file to upload
        content_type:
          type: string
          description: MIME type of the file
      required:
      - file_name
      - content_type
    PostV1ProspectsIdFilesUploadUrlResponse:
      type: object
      properties:
        upload_url:
          type: string
          description: Presigned URL for uploading the file bytes (valid 5 minutes)
        s3_key:
          type: string
          description: S3 object key to reference the uploaded file
    GetV1UsageResponse:
      type: object
      properties:
        name:
          type: string
        is_paid:
          type: boolean
  securitySchemes:
    bearer:
      type: http
      scheme: bearer
security:
- bearer: []
tags:
- name: Account
- name: Auth
- name: Enrichment
- name: Health
- name: Lists
- name: Oauth
- name: Phones
- name: Plans
- name: Properties
- name: Prospects
- name: Usage