MethodFi Entities API
Individuals, corporations, and receive-only entities
OpenAPI Specification
openapi: 3.1.0
info:
title: Method Account Attributes Entities API
version: '2025-12-01'
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 `2025-12-01`.\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 `2025-12-01`. 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
- url: https://sandbox.methodfi.com
description: Sandbox
- url: https://dev.methodfi.com
description: 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:
CreateEntityIndividual:
type: object
properties:
first_name:
type: string
description: First name of the individual.
last_name:
type: string
description: Last name of the individual.
phone:
type: string
description: Phone number of the individual.
pattern: ^\+\d{10,15}$
example: '+15121231111'
email:
type: string
description: Email address of the individual.
format: email
dob:
type: string
format: date
description: Date of birth of the individual (YYYY-MM-DD).
ssn:
type: string
pattern: ^\d{9}$
description: Social security number (9 digits). Mutually exclusive with ssn_4.
ssn_4:
type: string
pattern: ^\d{4}$
description: Last 4 digits of SSN. Mutually exclusive with ssn.
CreateIndividualEntityRequest:
type: object
required:
- type
- individual
properties:
type:
type: string
description: The type of entity to create.
enum:
- individual
individual:
$ref: '#/components/schemas/CreateEntityIndividual'
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.
EntityAttribute:
type: object
required:
- id
- entity_id
- status
- attributes
- created_at
- updated_at
properties:
id:
type: string
description: Unique identifier for the entity attribute.
example: attr_QwMjMDEwMTY1
entity_id:
type: string
description: The ID of the entity this attribute belongs to.
example: ent_au22b1fbFJbp8
status:
type: string
description: Status of the attribute retrieval.
enum:
- completed
- in_progress
- pending
- failed
attributes:
$ref: '#/components/schemas/EntityAttributeData'
error:
type:
- object
- 'null'
description: Error details if the resource encountered an error.
allOf:
- $ref: '#/components/schemas/ResourceError'
created_at:
type: string
format: date-time
description: Timestamp when the attribute was created.
updated_at:
type: string
format: date-time
description: Timestamp when the attribute was last updated.
AccountExpandableSensitive:
title: AccountExpandableSensitive
description: 'The latest sensitive ID. This field is expandable. When expanded, returns the full AccountSensitive object.
'
oneOf:
- type: string
pattern: ^astv_\w+$
- type: 'null'
- $ref: '#/components/schemas/AccountSensitive'
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.
AccountSensitiveResourceError:
type:
- object
- 'null'
description: Error details when retrieving account sensitive data fails.
required:
- type
- code
- sub_type
- message
properties:
type:
type: string
description: The category of sensitive data error.
enum:
- ACCOUNT_SENSITIVE_FAILED
code:
type: integer
description: Numeric error code (17XXX range).
enum:
- 17001
sub_type:
type: string
description: Specific sensitive data error classification.
enum:
- ACCOUNT_SENSITIVE_FAILED_VERIFICATION_REQUIRED
message:
type: string
description: Human-readable error description.
example:
type: ACCOUNT_SENSITIVE_FAILED
code: 17001
sub_type: ACCOUNT_SENSITIVE_FAILED_VERIFICATION_REQUIRED
message: Account sensitive failed due to missing required verification.
AccountResourceError:
type:
- object
- 'null'
description: Error details when an account is disabled.
required:
- type
- code
- sub_type
- message
properties:
type:
type: string
description: The category of account error.
enum:
- ACCOUNT_DISABLED
code:
type: integer
description: Numeric error code (11XXX range).
enum:
- 11001
- 11002
- 11003
- 11004
- 11005
- 11006
sub_type:
type: string
description: Specific account error classification.
enum:
- ACCOUNT_INVALID_DETAILS
- ACCOUNT_UNAUTHORIZED_PAYMENT
- ACCOUNT_CLOSED
- ACCOUNT_CONSENT_WITHDRAWN
- ACCOUNT_DISABLED_INVALID_STATE
- ACCOUNT_DISABLED_HOLDER_ENTITY_DISABLED
message:
type: string
description: Human-readable error description.
example:
type: ACCOUNT_DISABLED
code: 11001
sub_type: ACCOUNT_INVALID_DETAILS
message: Account was disabled due to invalid information reported by the financial institution.
EntityCorporationResource:
allOf:
- $ref: '#/components/schemas/EntityBase'
- type: object
properties:
type:
type: string
enum:
- corporation
corporation:
$ref: '#/components/schemas/EntityCorporation'
AccountBalance:
type: object
description: A balance record for an account.
required:
- id
- account_id
- status
- amount
- created_at
- updated_at
properties:
id:
type: string
description: Unique identifier for the balance.
pattern: ^bal_\w+$
example: bal_dKe9ehC3hEBYy
account_id:
type: string
description: The account this balance belongs to.
pattern: ^acc_\w+$
status:
type: string
description: Current status of the balance request.
enum:
- completed
- pending
- failed
amount:
type:
- number
- 'null'
description: The balance amount in cents.
error:
$ref: '#/components/schemas/BalanceResourceError'
created_at:
type: string
format: date-time
description: Timestamp when the balance was created.
updated_at:
type: string
format: date-time
description: Timestamp when the balance was last updated.
AccountClearing:
type:
- object
- 'null'
description: Clearing account details. Present when `type` is `clearing`.
properties:
type:
type: string
description: The type of clearing account.
enum:
- single_use
- multi_use
routing:
type: string
description: The clearing routing number.
number:
type: string
description: The clearing account number.
BalanceResourceError:
type:
- object
- 'null'
description: Error details when a balance sync fails.
required:
- type
- code
- sub_type
- message
properties:
type:
type: string
description: The category of balance error.
enum:
- BALANCE_FAILED
code:
type: integer
description: Numeric error code (20XXX range).
enum:
- 20001
sub_type:
type: string
description: Specific balance error classification.
enum:
- BALANCE_TEMPORARILY_UNAVAILABLE
message:
type: string
description: Human-readable error description.
example:
type: BALANCE_FAILED
code: 20001
sub_type: BALANCE_TEMPORARILY_UNAVAILABLE
message: Balance is temporarily unavailable for this account.
EntityExpandableAttribute:
title: EntityExpandableAttribute
description: Expandable. The entity attribute ID or expanded attribute object.
example: attr_QwMjMDEwMTY1
oneOf:
- type: string
pattern: ^attr_\w+$
- type: 'null'
- $ref: '#/components/schemas/EntityAttribute'
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.
SuccessEnvelope:
type: object
description: Standard envelope for successful responses that return a single payload.
required:
- success
- data
- message
properties:
success:
type: boolean
description: Always `true` for successful responses.
data:
description: Operation-specific response payload.
message:
type:
- string
-
# --- truncated at 32 KB (106 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/methodfi/refs/heads/main/openapi/methodfi-entities-api-openapi.yml