MethodFi Entities API

openapi: 3.2.0
info:
  title: Methodfi Entities API
  version: '1.0'
  description: 'Operations tagged Entities across 2 of this provider''s published API definitions: methodfi-openapi-original.yml, methodfi-openapi.yml. Each path carries the servers of the definition it was published in.'
servers:
- url: https://production.methodfi.com
  description: Production
- url: https://sandbox.methodfi.com
  description: Sandbox
- url: https://dev.methodfi.com
  description: Development
tags:
- name: Entities
  description: Individuals, corporations, and receive-only entities
paths:
  /entities:
    get:
      operationId: listEntities
      summary: List all entities
      description: Returns a paginated list of entities.
      tags:
      - Entities
      security:
      - SecretKey: []
      parameters:
      - $ref: '#/components/parameters/method_version'
      - $ref: '#/components/parameters/PageParam'
      - $ref: '#/components/parameters/PageLimitParam'
      - $ref: '#/components/parameters/PageCursorParam'
      - $ref: '#/components/parameters/FromDateParam'
      - $ref: '#/components/parameters/ToDateParam'
      - name: status
        in: query
        required: false
        description: Filter entities by status.
        schema:
          type: string
          enum:
          - active
          - incomplete
          - disabled
      - name: type
        in: query
        required: false
        description: Filter entities by type.
        schema:
          type: string
          enum:
          - individual
          - corporation
      - name: name
        in: query
        required: false
        description: Filter entities by their name.
        schema:
          type: string
      - $ref: '#/components/parameters/expand_entities'
      responses:
        '200':
          description: A list of entities.
          headers:
            Pagination-Page:
              description: Current page number.
              schema:
                type: integer
            Pagination-Page-Count:
              description: Total number of pages.
              schema:
                type: integer
            Pagination-Page-Limit:
              description: Number of items per page.
              schema:
                type: integer
            Pagination-Total-Count:
              description: Total number of items across all pages.
              schema:
                type: integer
            Pagination-Page-Cursor-Prev:
              description: Cursor for the previous page, if available.
              schema:
                type:
                - string
                - 'null'
            Pagination-Page-Cursor-Next:
              description: Cursor for the next page, if available.
              schema:
                type:
                - string
                - 'null'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EntityListResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/InternalError'
    post:
      operationId: createEntity
      summary: Create an entity
      description: Creates a new entity.
      tags:
      - Entities
      security:
      - SecretKey: []
      parameters:
      - $ref: '#/components/parameters/method_version'
      - $ref: '#/components/parameters/idempotency_key'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateEntityRequest'
            examples:
              individual:
                summary: Create an individual entity
                value:
                  type: individual
                  individual:
                    first_name: Jane
                    last_name: Doe
                    phone: '+15125550123'
                    email: jane@example.com
                    dob: '1990-05-21'
                  address:
                    line1: 123 Main St
                    line2: null
                    city: Austin
                    state: TX
                    zip: '78701'
                  metadata:
                    customer_reference: ent-001
              corporation:
                summary: Create a corporation entity
                value:
                  type: corporation
                  corporation:
                    name: Example Holdings LLC
                    dba: Example Holdings
                    ein: '123456789'
                  address:
                    line1: 123 Main St
                    line2: null
                    city: Austin
                    state: TX
                    zip: '78701'
      responses:
        '200':
          description: The created entity.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EntityResponse'
              examples:
                individual:
                  summary: Individual entity
                  value:
                    success: true
                    data:
                      id: ent_au22b1fbFJbp8
                      type: individual
                      individual:
                        first_name: Jane
                        last_name: Doe
                        phone: '+15125550123'
                        dob: '1990-05-21'
                        email: jane@example.com
                      address:
                        line1: 123 Main St
                        line2: null
                        city: Austin
                        state: TX
                        zip: '78701'
                      verification:
                        identity:
                          verified: true
                          matched: true
                          latest_verification_session: evf_aBcDeFgHiJkLm
                          methods: []
                        phone:
                          verified: true
                          latest_verification_session: evf_nOpQrStUvWxYz
                          methods: []
                      connect: null
                      credit_score: null
                      attribute: null
                      vehicle: null
                      products:
                      - connect
                      - credit_score
                      restricted_products:
                      - attribute
                      - identity
                      - manual_connect
                      - vehicle
                      subscriptions: []
                      available_subscriptions:
                      - connect
                      - credit_score
                      restricted_subscriptions:
                      - attribute
                      status: active
                      error: null
                      metadata: null
                      created_at: '2024-12-05T10:05:21.742Z'
                      updated_at: '2024-12-05T10:11:17.823Z'
                    message: null
                corporation:
                  summary: Corporation entity
                  value:
                    success: true
                    data:
                      id: ent_bWxYzAbCdEfGh
                      type: corporation
                      corporation:
                        name: Example Holdings LLC
                        dba: Example Holdings
                        ein: '123456789'
                        owners: []
                      address:
                        line1: 123 Main St
                        line2: null
                        city: Austin
                        state: TX
                        zip: '78701'
                      status: active
                      error: null
                      metadata: null
                      created_at: '2024-12-03T17:08:05.455Z'
                      updated_at: '2024-12-03T17:08:05.455Z'
                    message: null
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/InternalError'
    servers:
    - url: https://production.methodfi.com
      description: Production
    - url: https://sandbox.methodfi.com
      description: Sandbox
    - url: https://dev.methodfi.com
      description: Development
  /entities/{entityId}:
    get:
      operationId: retrieveEntity
      summary: Retrieve an entity
      description: Returns a single entity by its identifier.
      tags:
      - Entities
      security:
      - SecretKey: []
      parameters:
      - $ref: '#/components/parameters/method_version'
      - $ref: '#/components/parameters/EntityIdParam'
      - $ref: '#/components/parameters/expand_entities'
      responses:
        '200':
          description: The requested entity.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EntityResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/InternalError'
    put:
      operationId: updateEntity
      summary: Update an entity
      description: Updates an existing entity.
      tags:
      - Entities
      security:
      - SecretKey: []
      parameters:
      - $ref: '#/components/parameters/method_version'
      - $ref: '#/components/parameters/EntityIdParam'
      - $ref: '#/components/parameters/idempotency_key'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateEntityRequest'
            examples:
              individual:
                summary: Update an individual entity
                value:
                  individual:
                    phone: '+15125550124'
                    email: jane.doe@example.com
                  metadata:
                    crm_status: verified
              corporation:
                summary: Update a corporation entity
                value:
                  corporation:
                    dba: Example Finance
      responses:
        '200':
          description: The updated entity.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EntityResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/InternalError'
    servers:
    - url: https://production.methodfi.com
      description: Production
    - url: https://sandbox.methodfi.com
      description: Sandbox
    - url: https://dev.methodfi.com
      description: Development
  /entities/{ent_id}:
    parameters:
    - $ref: '#/components/parameters/EntityId'
    get:
      operationId: getEntity
      tags:
      - Entities
      summary: Retrieve an entity
      responses:
        '200':
          description: The entity
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EntityResponse_2'
      security:
      - bearerAuth: []
    put:
      operationId: updateEntity
      tags:
      - Entities
      summary: Update an entity
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EntityCreateRequest'
      responses:
        '200':
          description: The updated entity
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EntityResponse_2'
      security:
      - bearerAuth: []
    servers:
    - url: https://production.methodfi.com
      description: Production
    - url: https://sandbox.methodfi.com
      description: Sandbox
    - url: https://dev.methodfi.com
      description: Development (simulations enabled)
  /entities/{ent_id}/credit_scores:
    parameters:
    - $ref: '#/components/parameters/EntityId'
    get:
      operationId: retrieveEntityCreditScores
      tags:
      - Entities
      summary: Retrieve credit scores
      responses:
        '200':
          description: Credit score data
          content:
            application/json:
              schema:
                type: object
      security:
      - bearerAuth: []
    servers:
    - url: https://production.methodfi.com
      description: Production
    - url: https://sandbox.methodfi.com
      description: Sandbox
    - url: https://dev.methodfi.com
      description: Development (simulations enabled)
  /entities/{ent_id}/verification_sessions:
    parameters:
    - $ref: '#/components/parameters/EntityId'
    post:
      operationId: createEntityVerificationSession
      tags:
      - Entities
      summary: Create a verification session
      description: Create an SMS, KBA, SNA, or BYO verification session for the entity.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EntityVerificationSessionRequest'
      responses:
        '200':
          description: Verification session
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EntityVerificationSessionResponse'
      security:
      - bearerAuth: []
    get:
      operationId: listEntityVerificationSessions
      tags:
      - Entities
      summary: List verification sessions
      responses:
        '200':
          description: Verification sessions
          content:
            application/json:
              schema:
                type: object
      security:
      - bearerAuth: []
    servers:
    - url: https://production.methodfi.com
      description: Production
    - url: https://sandbox.methodfi.com
      description: Sandbox
    - url: https://dev.methodfi.com
      description: Development (simulations enabled)
components:
  schemas:
    AccountDebitCard:
      type:
      - object
      - 'null'
      description: Debit card account details. Present when `type` is `debit_card`.
      properties:
        network:
          type: string
          description: The card network.
        mask:
          type: string
          description: Last 4 digits of the card number.
        issuer:
          type: string
          description: The card issuer.
    EntityIndividualResource:
      allOf:
      - $ref: '#/components/schemas/EntityBase'
      - type: object
        required:
        - products
        - restricted_products
        - subscriptions
        - available_subscriptions
        - restricted_subscriptions
        properties:
          type:
            type: string
            enum:
            - individual
          individual:
            $ref: '#/components/schemas/EntityIndividual'
          verification:
            $ref: '#/components/schemas/EntityVerification'
          connect:
            $ref: '#/components/schemas/EntityExpandableConnect'
          credit_score:
            $ref: '#/components/schemas/EntityExpandableCreditScore'
          attribute:
            $ref: '#/components/schemas/EntityExpandableAttribute'
          vehicle:
            $ref: '#/components/schemas/EntityExpandableVehicle'
          products:
            type: array
            items:
              type: string
            description: Products currently active for this entity.
          restricted_products:
            type: array
            items:
              type: string
            description: Products restricted for this entity.
          subscriptions:
            type: array
            items:
              type: string
            description: Active subscriptions for this entity.
          available_subscriptions:
            type: array
            items:
              type: string
            description: Subscriptions available for this entity.
          restricted_subscriptions:
            type: array
            items:
              type: string
            description: Subscriptions restricted for this entity.
    EntityExpandableCreditScore:
      title: EntityExpandableCreditScore
      description: Expandable. The entity credit score ID or expanded credit score object.
      example: crs_pn4ca33GRnrJm
      oneOf:
      - type: string
        pattern: ^crs_\w+$
      - type: 'null'
      - $ref: '#/components/schemas/EntityCreditScore'
    EntityVerification:
      type:
      - object
      - 'null'
      properties:
        identity:
          $ref: '#/components/schemas/EntityVerificationIdentity'
        phone:
          $ref: '#/components/schemas/EntityVerificationPhone'
    AccountPaymentInstrument:
      type: object
      description: A payment instrument for an account.
      required:
      - id
      - account_id
      - status
      - type
      - created_at
      - updated_at
      properties:
        id:
          type: string
          description: Unique identifier for the payment instrument.
          pattern: ^pmt_inst_\w+$
          example: pmt_inst_aTJMbnCjw34yQ
        account_id:
          type: string
          description: The account this payment instrument belongs to.
          pattern: ^acc_\w+$
        status:
          type: string
          description: Current status of the payment instrument.
          enum:
          - pending
          - in_progress
          - completed
        type:
          type: string
          description: The type of payment instrument.
          enum:
          - card
          - network_token
          - inbound_achwire_payment
        chargeable:
          type: boolean
          description: Whether this payment instrument is currently chargeable.
        card:
          type:
          - object
          - 'null'
          description: Card details. Present when type is card.
          properties:
            number:
              type: string
              description: The card number.
            exp_month:
              type: string
              description: Card expiration month.
            exp_year:
              type: string
              description: Card expiration year.
            billing_zip_code:
              type: string
              description: Billing zip code.
        network_token:
          type:
          - object
          - 'null'
          description: Network token details. Present when type is network_token.
          properties:
            token:
              type: string
              description: The network token value.
        inbound_achwire_payment:
          type:
          - object
          - 'null'
          description: ACH/wire payment details. Present when type is inbound_achwire_payment.
          properties:
            account_number:
              type: string
              description: The account number.
            routing_number:
              type: string
              description: The routing number.
        error:
          $ref: '#/components/schemas/ResourceError'
        created_at:
          type: string
          format: date-time
          description: Timestamp when the payment instrument was created.
        updated_at:
          type: string
          format: date-time
          description: Timestamp when the payment instrument was last updated.
    CreateCorporationEntityRequest:
      type: object
      required:
      - type
      - corporation
      properties:
        type:
          type: string
          description: The type of entity to create.
          enum:
          - corporation
        corporation:
          $ref: '#/components/schemas/CreateEntityCorporation'
        address:
          $ref: '#/components/schemas/Address'
        metadata:
          $ref: '#/components/schemas/Metadata'
    AccountSensitive:
      type: object
      description: Sensitive data for an account.
      required:
      - id
      - account_id
      - status
      - type
      - fields
      - created_at
      - updated_at
      properties:
        id:
          type: string
          description: Unique identifier for the sensitive record.
          pattern: ^astv_\w+$
          example: astv_aTJMbnCjw34yQ
        account_id:
          type: string
          description: The account this sensitive data belongs to.
          pattern: ^acc_\w+$
        status:
          type: string
          description: Current status of the sensitive data request.
          enum:
          - completed
          - pending
          - failed
        type:
          type: string
          description: The type of sensitive data.
        fields:
          type: array
          description: List of sensitive data fields retrieved.
          items:
            type: object
            properties:
              name:
                type: string
                description: Name of the field.
              value:
                type: string
                description: Value of the field.
        error:
          $ref: '#/components/schemas/AccountSensitiveResourceError'
        created_at:
          type: string
          format: date-time
          description: Timestamp when the sensitive record was created.
        updated_at:
          type: string
          format: date-time
          description: Timestamp when the sensitive record was last updated.
    EntityListResponse:
      allOf:
      - $ref: '#/components/schemas/ListEnvelope'
      - type: object
        properties:
          data:
            type: array
            items:
              $ref: '#/components/schemas/Entity'
    AccountUpdate:
      type: object
      description: An update record for an account.
      required:
      - id
      - account_id
      - status
      - type
      - created_at
      - updated_at
      properties:
        id:
          type: string
          description: Unique identifier for the update.
          pattern: ^upd_\w+$
          example: upd_aTJMbnCjw34yQ
        account_id:
          type: string
          description: The account this update belongs to.
          pattern: ^acc_\w+$
        status:
          type: string
          description: Current status of the update.
          enum:
          - completed
          - pending
          - failed
        type:
          type: string
          description: The liability type of the account being updated.
          enum:
          - credit_card
          - auto_loan
          - mortgage
          - personal_loan
          - student_loan
          - student_loans
          - bnpl
          - fintech
        source:
          type: string
          description: The data source used for this update.
          enum:
          - direct
          - snapshot
        data_as_of:
          type:
          - string
          - 'null'
          format: date-time
          description: The timestamp of the data used to complete this update.
        credit_card:
          type:
          - object
          - 'null'
          description: Credit card update data. Present when `type` is `credit_card`.
          properties:
            sub_type:
              type:
              - string
              - 'null'
            opened_at:
              type:
              - string
              - 'null'
              format: date
            closed_at:
              type:
              - string
              - 'null'
              format: date
            balance:
              type:
              - integer
              - 'null'
              description: Current balance in cents.
            last_payment_amount:
              type:
              - integer
              - 'null'
              description: Last payment amount in cents.
            last_payment_date:
              type:
              - string
              - 'null'
              format: date
            next_payment_due_date:
              type:
              - string
              - 'null'
              format: date
            next_payment_minimum_amount:
              type:
              - integer
              - 'null'
              description: Minimum payment due in cents.
            interest_rate_type:
              type:
              - string
              - 'null'
            interest_rate_percentage_max:
              type:
              - number
              - 'null'
            interest_rate_percentage_min:
              type:
              - number
              - 'null'
            available_credit:
              type:
              - integer
              - 'null'
              description: Available credit in cents.
            credit_limit:
              type:
              - integer
              - 'null'
              description: Credit limit in cents.
            usage_pattern:
              type:
              - string
              - 'null'
        auto_loan:
          type:
          - object
          - 'null'
          description: Auto loan update data. Present when `type` is `auto_loan`.
          properties:
            sub_type:
              type:
              - string
              - 'null'
            opened_at:
              type:
              - string
              - 'null'
              format: date
            closed_at:
              type:
              - string
              - 'null'
              format: date
            balance:
              type:
              - integer
              - 'null'
              description: Current balance in cents.
            last_payment_amount:
              type:
              - integer
              - 'null'
              description: Last payment amount in cents.
            last_payment_date:
              type:
              - string
              - 'null'
              format: date
            next_payment_due_date:
              type:
              - string
              - 'null'
              format: date
            next_payment_minimum_amount:
              type:
              - integer
              - 'null'
              description: Minimum payment due in cents.
            interest_rate_type:
              type:
              - string
              - 'null'
            expected_payoff_date:
              type:
              - string
              - 'null'
              format: date
            original_loan_amount:
              type:
              - integer
              - 'null'
              description: Original loan amount in cents.
            term_length:
              type:
              - integer
              - 'null'
            interest_rate_percentage:
              type:
              - number
              - 'null'
            interest_rate_source:
              type:
              - string
              - 'null'
        mortgage:
          type:
          - object
          - 'null'
          description: Mortgage update data. Present when `type` is `mortgage`.
          properties:
            sub_type:
              type:
              - string
              - 'null'
            opened_at:
              type:
              - string
              - 'null'
              format: date
            closed_at:
              type:
              - string
              - 'null'
              format: date
            balance:
              type:
              - integer
              - 'null'
              description: Current balance in cents.
            last_payment_amount:
              type:
              - integer
              - 'null'
              description: Last payment amount in cents.
            last_payment_date:
              type:
              - string
              - 'null'
              format: date
            next_payment_due_date:
              type:
              - string
              - 'null'
              format: date
            next_payment_minimum_amount:
              type:
              - integer
              - 'null'
              description: Minimum payment due in cents.
            interest_rate_type:
              type:
              - string
              - 'null'
            expected_payoff_date:
              type:
              - string
              - 'null'
              format: date
            original_loan_amount:
              type:
              - integer
              - 'null'
              description: Original loan amount in cents.
            term_length:
              type:
              - integer
              - 'null'
            interest_rate_percentage:
              type:
              - number
              - 'null'
            interest_rate_source:
              type:
              - string
              - 'null'
        personal_loan:
          type:
          - object
          - 'null'
          description: Personal loan update data. Present when `type` is `personal_loan`.
          properties:
            sub_type:
              type:
              - string
              - 'null'
            opened_at:
              type:
              - string
              - 'null'
              format: date
            closed_at:
              type:
              - string
              - 'null'
              format: date
            balance:
              type:
              - integer
              - 'null'
              description: Current balance in cents.
            last_payment_amount:
              type:
              - integer
              - 'null'
              description: Last payment amount in cents.
            last_payment_date:
              type:
              - string
              - 'null'
              format: date
            next_payment_due_date:
              type:
              - string
              - 'null'
              format: date
            next_payment_minimum_amount:
              type:
              - integer
              - 'null'
              description: Minimum payment due in cents.
            interest_rate_type:
              type:
              - string
              - 'null'
            available_credit:
              type:
              - integer
              - 'null'
              description: Available credit in cents.
            original_loan_amount:
              type:
              - integer
              - 'null'
              description: Original loan amount in cents.
            term_length:
              type:
              - integer
              - 'null'
            interest_rate_percentage:
              type:
              - number
              - 'null'
            interest_rate_source:
              type:
              - string
              - 'null'
        student_loan:
          type:
          - object
          - 'null'
          description: Student loan update data. Present when `type` is `student_loan`.
          properties:
            sub_type:
              type:
              - string
              - 'null'
            opened_at:
              type:
              - string
              - 'null'
              format: date
            closed_at:
              type:
              - string
              - 'null'
              format: date
            balance:
              type:
              - integer
              - 'null'
              description: Current balance in cents.
            last_payment_amount:
              type:
              - integer
              - 'null'
              description: Last payment amount in cents.
            last_payment_date:
              type:
              - string
              - 'null'
              format: date
            next_payment_due_date:
              type:
              - string
              - 'null'
              format: date
            next_payment_minimum_amount:
              type:
              - integer
              -

# --- truncated at 32 KB (112 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/methodfi/refs/heads/main/openapi/methodfi-entities-api-openapi.yml