Method Financial Entities API

openapi: 3.2.0
info:
  title: Method Entities API
  version: '2026-03-30'
  license:
    name: Proprietary
    url: https://methodfi.com
  description: "The Method API enables you to retrieve financial data, create payments, and manage\nentities and accounts programmatically. This specification covers the public API\nsurface for version `2026-03-30`.\n\n## Authentication\n\nMost API requests require a Bearer token in the `Authorization` header.\nUse your secret key (`sk_...`) for server-side requests and public key (`pk_...`)\nfor client-side Element requests. Public Message-Level Encryption key discovery\nendpoints are documented separately and do not require authentication.\n\n## Versioning\n\nThe API version is selected via the `Method-Version` header. This spec targets\nversion `2026-03-30`. The SDK sets this header automatically.\n\n## Response Envelope\n\nMost JSON responses are wrapped in a standard envelope:\n\n```json\n{\n  \"success\": true,\n  \"data\": { ... },\n  \"message\": null\n}\n```\n\nThe `/.well-known/jwks.json` endpoint is an exception and returns a bare JWK set.\n\n## Pagination\n\nList endpoints return pagination metadata in response headers:\n`Pagination-Page`, `Pagination-Page-Count`, `Pagination-Page-Limit`,\n`Pagination-Total-Count`, `Pagination-Page-Cursor-Prev`, `Pagination-Page-Cursor-Next`.\n\n## Expandable Fields\n\nCertain resource fields can be expanded from IDs to full objects using the\n`expand` query parameter. Maximum nesting depth is 4 levels.\n"
  contact:
    name: Method Financial
    url: https://methodfi.com
    email: team@methodfi.com
servers:
- url: https://production.methodfi.com
  description: Production
  x-fern-server-name: Production
- url: https://sandbox.methodfi.com
  description: Sandbox
  x-fern-server-name: Sandbox
- url: https://dev.methodfi.com
  description: Development
  x-fern-server-name: Development
security:
- SecretKey: []
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'
  /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'
components:
  schemas:
    ListEnvelope:
      type: object
      description: Standard envelope for successful responses that return a list payload.
      required:
      - success
      - data
      - message
      properties:
        success:
          type: boolean
          description: Always `true` for successful responses.
        data:
          description: Operation-specific list payload.
        message:
          type:
          - string
          - 'null'
      example:
        success: true
        data: []
        message: null
    CreateEntityRequest:
      description: Request body for creating an entity.
      oneOf:
      - $ref: '#/components/schemas/CreateIndividualEntityRequest'
      - $ref: '#/components/schemas/CreateCorporationEntityRequest'
      discriminator:
        propertyName: type
        mapping:
          individual: '#/components/schemas/CreateIndividualEntityRequest'
          corporation: '#/components/schemas/CreateCorporationEntityRequest'
    EntityIndividual:
      type:
      - object
      - 'null'
      properties:
        first_name:
          type:
          - string
          - 'null'
          description: First name of the individual.
        last_name:
          type:
          - string
          - 'null'
          description: Last name of the individual.
        phone:
          type:
          - string
          - 'null'
          description: Phone number of the individual.
          pattern: ^\+\d{10,15}$
          example: '+15121231111'
        email:
          type:
          - string
          - 'null'
          description: Email address of the individual.
          format: email
        dob:
          type:
          - string
          - 'null'
          format: date
          description: Date of birth of the individual (YYYY-MM-DD).
        ssn:
          type:
          - string
          - 'null'
          description: Social security number (masked).
        ssn_4:
          type:
          - string
          - 'null'
          description: Last 4 digits of SSN (masked).
    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.
    AccountVerificationSession:
      type: object
      description: A verification session for an account.
      required:
      - id
      - account_id
      - status
      - type
      - created_at
      - updated_at
      properties:
        id:
          type: string
          description: Unique identifier for the verification session.
          pattern: ^avf_\w+$
          example: avf_aTJMbnCjw34yQ
        account_id:
          type: string
          description: The account this verification session belongs to.
          pattern: ^acc_\w+$
        status:
          type: string
          description: Current status of the verification session.
          enum:
          - pending
          - in_progress
          - verified
          - failed
        type:
          type: string
          description: The type of verification.
          enum:
          - micro_deposits
          - mx
          - plaid
          - teller
          - auto_verify
          - trusted_provisioner
          - pre_auth
          - standard
          - issuer
          - instant
          - network
          - three_ds
        micro_deposits:
          type:
          - object
          - 'null'
          description: Populated when the verification session is of type micro_deposits.
          properties:
            amounts:
              type: array
              description: The latest amounts that this verification session was updated with.
              items:
                type: integer
        plaid:
          type:
          - object
          - 'null'
          description: Populated when the verification session is of type plaid.
          properties:
            balances:
              type: object
              description: The raw balance data received from Plaid.
            transactions:
              type: array
              description: The raw transaction data received from Plaid.
              items:
                type: object
        mx:
          type:
          - object
          - 'null'
          description: Populated when the verification session is of type mx.
          properties:
            account:
              type: object
              description: The raw account data received from MX.
            transactions:
              type: array
              description: The raw transaction data received from MX.
              items:
                type: object
        teller:
          type:
          - object
          - 'null'
          description: Populated when the verification session is of type teller.
          properties:
            balances:
              type: object
              description: The raw balance data received from Teller.
            transactions:
              type: array
              description: The raw transaction data received from Teller.
              items:
                type: object
        auto_verify:
          type:
          - object
          - 'null'
          description: Populated when the verification session is of type auto_verify.
        trusted_provisioner:
          type:
          - object
          - 'null'
          description: Populated when the verification session is of type trusted_provisioner.
        standard:
          type:
          - object
          - 'null'
          description: Populated when the verification session is of type standard.
          properties:
            number:
              type:
              - string
              - 'null'
              description: The masked card number. Null if the number still needs to be provided.
        pre_auth:
          type:
          - object
          - 'null'
          description: Populated when the verification session is of type pre_auth.
          properties:
            number:
              type:
              - string
              - 'null'
              description: The masked card number. Null if the number still needs to be provided.
            exp_month:
              type:
              - string
              - 'null'
              description: The masked card expiration month. Null if it still needs to be provided.
            exp_year:
              type:
              - string
              - 'null'
              description: The masked card expiration year. Null if it still needs to be provided.
            exp_check:
              type:
              - string
              - 'null'
              description: The card expiration verification check result.
              enum:
              - pass
              - fail
              - unavailable
            cvv:
              type:
              - string
              - 'null'
              description: The masked card CVV. Null if it still needs to be provided.
            cvv_check:
              type:
              - string
              - 'null'
              description: The card CVV verification check result.
              enum:
              - pass
              - fail
              - unavailable
            billing_zip_code:
              type:
              - string
              - 'null'
              description: The masked billing zip code.
            billing_zip_code_check:
              type:
              - string
              - 'null'
              description: The billing zip code verification check result.
              enum:
              - pass
              - fail
              - unavailable
            pre_auth_check:
              type:
              - string
              - 'null'
              description: The pre-auth verification check result.
              enum:
              - pass
              - fail
              - unavailable
        network:
          type:
          - object
          - 'null'
          description: Populated when the verification session is of type network.
          properties:
            number:
              type:
              - string
              - 'null'
              description: The masked card number. Null if the number still needs to be provided.
            exp_month:
              type:
              - string
              - 'null'
              description: The masked card expiration month. Null if it still needs to be provided.
            exp_year:
              type:
              - string
              - 'null'
              description: The masked card expiration year. Null if it still needs to be provided.
            exp_check:
              type:
              - string
              - 'null'
              description: The card expiration verification check result.
              enum:
              - pass
              - fail
              - unavailable
            cvv:
              type:
              - string
              - 'null'
              description: The masked card CVV. Null if it still needs to be provided.
            cvv_check:
              type:
              - string
              - 'null'
              description: The card CVV verification check result.
              enum:
              - pass
              - fail
              - unavailable
            billing_zip_code:
              type:
              - string
              - 'null'
              description: The masked billing zip code.
            billing_zip_code_check:
              type:
              - string
              - 'null'
              description: The billing zip code verification check result.
              enum:
              - pass
              - fail
              - unavailable
            network_check:
              type:
              - string
              - 'null'
              description: The network verification check result.
              enum:
              - pass
              - fail
              - unavailable
        instant:
          type:
          - object
          - 'null'
          description: Populated when the verification session is of type instant.
          properties:
            number:
              type:
              - string
              - 'null'
              description: The masked card number. Null if the number still needs to be provided.
            exp_month:
              type:
              - string
              - 'null'
              description: The masked card expiration month. Null if it still needs to be provided.
            exp_year:
              type:
              - string
              - 'null'
              description: The masked card expiration year. Null if it still needs to be provided.
            exp_check:
              type:
              - string
              - 'null'
              description: The card expiration verification check result.
              enum:
              - pass
              - fail
              - unavailable
        error:
          $ref: '#/components/schemas/AccountVerificationSessionResourceError'
        created_at:
          type: string
          format: date-time
          description: Timestamp when the verification session was created.
        updated_at:
          type: string
          format: date-time
          description: Timestamp when the verification session was last updated.
    EntityCreditScore:
      type: object
      required:
      - id
      - entity_id
      - status
      - scores
      - created_at
      - updated_at
      properties:
        id:
          type: string
          description: Unique identifier for the credit score.
          example: crs_pn4ca33GRnrJm
        entity_id:
          type: string
          description: The ID of the entity this credit score belongs to.
          example: ent_au22b1fbFJbp8
        status:
          type: string
          description: Status of the credit score retrieval.
          enum:
          - completed
          - in_progress
          - pending
          - failed
        scores:
          type:
          - array
          - 'null'
          description: Array of credit score results.
          items:
            type: object
            required:
            - score
            - source
            - model
            - factors
            - created_at
            properties:
              score:
                type:
                - integer
                - 'null'
                description: The credit score value.
              source:
                type:
                - string
                - 'null'
                description: The source of the credit score.
              model:
                type:
                - string
                - 'null'
                description: The scoring model used.
              factors:
                type:
                - array
                - 'null'
                description: Factors affecting the credit score.
                items:
                  $ref: '#/components/schemas/EntityCreditScoreFactor'
              created_at:
                type: string
                format: date-time
                description: Timestamp when this score was generated.
        error:
          type:
          - object
          - 'null'
          description: Error details if the resource encountered an error.
          allOf:
          - $ref: '#/components/schemas/CreditScoreResourceError'
        created_at:
          type: string
          format: date-time
          description: Timestamp when the credit score was created.
        updated_at:
          type: string
          format: date-time
          description: Timestamp when the credit score was last updated.
    EntityResourceError:
      type:
      - object
      - 'null'
      description: Error details when an entity is disabled or verification fails.
      required:
      - type
      - code
      - sub_type
      - message
      properties:
        type:
          type: string
          description: The category of entity error.
          enum:
          - ENTITY_DISABLED
          - ENTITY_VERIFICATION_FAILED
        code:
          type: integer
          description: Numeric error code (12XXX range).
          enum:
          - 12001
          - 12002
          - 12003
          - 12004
          - 12005
          - 12006
          - 12007
        sub_type:
          type: string
          description: Specific entity error classification.
          enum:
          - ENTITY_UNAUTHORIZED_PAYMENT
          - ENTITY_INVALID_DETAILS
          - ENTITY_SSN_MISMATCH
          - ENTITY_CONSENT_WITHDRAWN
          - ENTITY_PENDING_KYC_REVIEW
          - ENTITY_CANNOT_PERFORM_ACTION
        message:
          type: string
          description: Human-readable error description.
      example:
        type: ENTITY_DISABLED
        code: 12002
        sub_type: ENTITY_INVALID_DETAILS
        message: Entity was disabled due to invalid information.
    EntityCorporation:
      type:
      - object
      - 'null'
      properties:
        name:
          type:
          - string
          - 'null'
          description: Legal name of the corporation.
        dba:
          type:
          - string
          - 'null'
          description: Doing business as name.
        ein:
          type:
          - string
          - 'null'
          description: Employer Identification Number.
        owners:
          type:
          - array
          - 'null'
          items:
            $ref: '#/components/schemas/EntityCorporationOwner'
          description: List of beneficial owners.
    EntityVehicle:
      type: object
      required:
      - id
      - entity_id
      - status
      - vehicles
      - created_at
      - updated_at
      properties:
        id:
          type: string
          description: Unique identifier for the vehicle record.
          example: vhl_JMDEwMTY1Qw4c
        entity_id:
          type: string
          description: The ID of the entity this vehicle belongs to.
          example: ent_au22b1fbFJbp8
        status:
          type: string
          description: Status of the vehicle data retrieval.
          enum:
          - completed
          - in_progress
          - pending
          - failed
        vehicles:
          type:
          - array
          - 'null'
          description: Array of vehicles associated with this entity.
          items:
            type: object
            properties:
              vin:
                type:
                - string
                - 'null'
                description: Vehicle identification number.
              year:
                type:
                - string
                - 'null'
                description: Model year.
              make:
                type:
                - string
                - 'null'
                description: Vehicle make.
              model:
                type:
                - string
                - 'null'
                description: Vehicle model.
              series:
                type:
                - string
                - 'null'
                description: Vehicle series.
              major_color:
                type:
                - string
                - 'null'
                description: Primary color of the vehicle.
              style:
                type:
                - string
                - 'null'
                description: Body style.
        error:
       

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