Increase Entities API

openapi: 3.1.0
info:
  description: Anything that you can achieve with PDFs, presence, and persistence in a bank branch you can do with our API. We've always wanted a fully programmatic bank so we built one. Our API faithfully exposes the data and capabilities of the Federal Reserve, Visa, The Clearing House, depository networks, and accounting tools. It's lovingly boring and exceptionally powerful. If you have any questions or want to get started, don't hesitate to ping us at sales@increase.com. We can't wait to see what you build!
  title: Increase Account Numbers Entities API
  version: 0.0.1
servers:
- url: https://api.increase.com
- url: https://sandbox.increase.com
security:
- bearerAuth: []
tags:
- description: Entities are the legal entities that own accounts. They can be people, corporations, partnerships, government authorities, or trusts. To learn more, see [Entities](/documentation/entities).
  name: Entities
paths:
  /entities:
    get:
      operationId: list_entities
      parameters:
      - in: query
        name: cursor
        required: false
        schema:
          description: Return the page of entries after this one.
          type: string
          x-documentation-priority: low
      - in: query
        name: limit
        required: false
        schema:
          description: Limit the size of the list that is returned. The default (and maximum) is 100 objects.
          minimum: 1
          type: integer
          x-documentation-priority: low
      - in: query
        name: status.in
        required: false
        schema:
          description: Filter Entities for those with the specified status or statuses. For GET requests, this should be encoded as a comma-delimited string, such as `?in=one,two,three`.
          items:
            enum:
            - active
            - archived
            - disabled
            type: string
            x-enum-descriptions:
            - The entity is active.
            - The entity is archived, and can no longer be used to create accounts.
            - The entity is temporarily disabled and cannot be used for financial activity.
          type: array
          x-documentation-priority: default
        explode: false
      - in: query
        name: created_at.after
        required: false
        schema:
          description: Return results after this [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) timestamp.
          format: date-time
          type: string
          x-documentation-priority: low
      - in: query
        name: created_at.before
        required: false
        schema:
          description: Return results before this [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) timestamp.
          format: date-time
          type: string
          x-documentation-priority: low
      - in: query
        name: created_at.on_or_after
        required: false
        schema:
          description: Return results on or after this [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) timestamp.
          format: date-time
          type: string
          x-documentation-priority: low
      - in: query
        name: created_at.on_or_before
        required: false
        schema:
          description: Return results on or before this [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) timestamp.
          format: date-time
          type: string
          x-documentation-priority: low
      - in: query
        name: idempotency_key
        required: false
        schema:
          description: Filter records to the one with the specified `idempotency_key` you chose for that object. This value is unique across Increase and is used to ensure that a request is only processed once. Learn more about [idempotency](https://increase.com/documentation/idempotency-keys).
          maxLength: 200
          minLength: 1
          type: string
          x-documentation-priority: default
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/entity_list'
          description: Entity List
        4XX:
          $ref: '#/components/responses/errorResponse'
        5XX:
          $ref: '#/components/responses/errorResponse'
      summary: List Entities
      x-sandbox-only: false
      x-tag: Entities
      tags:
      - Entities
    post:
      operationId: create_an_entity
      parameters: []
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/create_an_entity_parameters'
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/entity'
          description: Entity
        4XX:
          $ref: '#/components/responses/errorResponse'
        5XX:
          $ref: '#/components/responses/errorResponse'
      summary: Create an Entity
      x-sandbox-only: false
      x-tag: Entities
      tags:
      - Entities
  /entities/{entity_id}:
    get:
      operationId: retrieve_an_entity
      parameters:
      - example: entity_n8y8tnk2p9339ti393yi
        in: path
        name: entity_id
        required: true
        schema:
          description: The identifier of the Entity to retrieve.
          type: string
          x-documentation-priority: default
          x-id-reference-to: Entities
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/entity'
          description: Entity
        4XX:
          $ref: '#/components/responses/errorResponse'
        5XX:
          $ref: '#/components/responses/errorResponse'
      summary: Retrieve an Entity
      x-sandbox-only: false
      x-tag: Entities
      tags:
      - Entities
    patch:
      operationId: update_an_entity
      parameters:
      - example: entity_n8y8tnk2p9339ti393yi
        in: path
        name: entity_id
        required: true
        schema:
          description: The entity identifier.
          type: string
          x-documentation-priority: default
          x-id-reference-to: Entities
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/update_an_entity_parameters'
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/entity'
          description: Entity
        4XX:
          $ref: '#/components/responses/errorResponse'
        5XX:
          $ref: '#/components/responses/errorResponse'
      summary: Update an Entity
      x-sandbox-only: false
      x-tag: Entities
      tags:
      - Entities
  /entities/{entity_id}/archive:
    post:
      operationId: archive_an_entity
      parameters:
      - example: entity_n8y8tnk2p9339ti393yi
        in: path
        name: entity_id
        required: true
        schema:
          description: The identifier of the Entity to archive. Any accounts associated with an entity must be closed before the entity can be archived.
          type: string
          x-documentation-priority: default
          x-id-reference-to: Entities
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/entity'
          description: Entity
        4XX:
          $ref: '#/components/responses/errorResponse'
        5XX:
          $ref: '#/components/responses/errorResponse'
      summary: Archive an Entity
      x-sandbox-only: false
      x-tag: Entities
      tags:
      - Entities
components:
  schemas:
    error:
      anyOf:
      - properties:
          detail:
            anyOf:
            - type: string
            - type: 'null'
          status:
            enum:
            - 404
            type: integer
          title:
            type: string
          type:
            enum:
            - api_method_not_found_error
            type: string
        required:
        - type
        - title
        - detail
        - status
        type: object
        x-event-categories: []
      - properties:
          detail:
            anyOf:
            - type: string
            - type: 'null'
          status:
            enum:
            - 403
            type: integer
          title:
            type: string
          type:
            enum:
            - environment_mismatch_error
            type: string
        required:
        - type
        - title
        - detail
        - status
        type: object
        x-event-categories: []
      - properties:
          detail:
            anyOf:
            - type: string
            - type: 'null'
          resource_id:
            description: ''
            type: string
            x-documentation-priority: default
          status:
            enum:
            - 409
            type: integer
          title:
            type: string
          type:
            enum:
            - idempotency_key_already_used_error
            type: string
        required:
        - type
        - title
        - detail
        - status
        - resource_id
        type: object
        x-event-categories: []
      - properties:
          detail:
            anyOf:
            - type: string
            - type: 'null'
          status:
            enum:
            - 403
            type: integer
          title:
            type: string
          type:
            enum:
            - insufficient_permissions_error
            type: string
        required:
        - type
        - title
        - detail
        - status
        type: object
        x-event-categories: []
      - properties:
          detail:
            anyOf:
            - type: string
            - type: 'null'
          status:
            enum:
            - 500
            type: integer
          title:
            type: string
          type:
            enum:
            - internal_server_error
            type: string
        required:
        - type
        - title
        - detail
        - status
        type: object
        x-event-categories: []
      - properties:
          detail:
            anyOf:
            - type: string
            - type: 'null'
          reason:
            description: ''
            enum:
            - deleted_credential
            - expired_credential
            - ip_not_allowed
            - no_credential
            - no_header
            - no_api_access
            - wrong_environment
            type: string
            x-documentation-priority: default
            x-enum-descriptions:
            - deleted_credential
            - expired_credential
            - ip_not_allowed
            - no_credential
            - no_header
            - no_api_access
            - wrong_environment
          status:
            enum:
            - 401
            type: integer
          title:
            type: string
          type:
            enum:
            - invalid_api_key_error
            type: string
        required:
        - type
        - title
        - detail
        - status
        - reason
        type: object
        x-event-categories: []
      - properties:
          detail:
            anyOf:
            - type: string
            - type: 'null'
          status:
            enum:
            - 409
            type: integer
          title:
            type: string
          type:
            enum:
            - invalid_operation_error
            type: string
        required:
        - type
        - title
        - detail
        - status
        type: object
        x-event-categories: []
      - properties:
          detail:
            anyOf:
            - type: string
            - type: 'null'
          errors:
            description: All errors related to parsing the request parameters.
            items:
              additionalProperties: true
              properties: {}
              title: ErrorsElement
              type: object
              x-event-categories: []
              x-stainless-empty-object: false
              x-title-plural: ErrorsElements
            type: array
            x-documentation-priority: default
          status:
            enum:
            - 400
            type: integer
          title:
            type: string
          type:
            enum:
            - invalid_parameters_error
            type: string
        required:
        - type
        - title
        - detail
        - status
        - errors
        type: object
        x-event-categories: []
      - properties:
          detail:
            anyOf:
            - type: string
            - type: 'null'
          status:
            enum:
            - 400
            type: integer
          title:
            type: string
          type:
            enum:
            - malformed_request_error
            type: string
        required:
        - type
        - title
        - detail
        - status
        type: object
        x-event-categories: []
      - properties:
          detail:
            anyOf:
            - type: string
            - type: 'null'
          status:
            enum:
            - 404
            type: integer
          title:
            type: string
          type:
            enum:
            - object_not_found_error
            type: string
        required:
        - type
        - title
        - detail
        - status
        type: object
        x-event-categories: []
      - properties:
          detail:
            anyOf:
            - type: string
            - type: 'null'
          status:
            enum:
            - 403
            type: integer
          title:
            type: string
          type:
            enum:
            - private_feature_error
            type: string
        required:
        - type
        - title
        - detail
        - status
        type: object
        x-event-categories: []
      - properties:
          detail:
            anyOf:
            - type: string
            - type: 'null'
          retry_after:
            anyOf:
            - description: ''
              type: integer
              x-documentation-priority: default
            - type: 'null'
          status:
            enum:
            - 429
            type: integer
          title:
            type: string
          type:
            enum:
            - rate_limited_error
            type: string
        required:
        - type
        - title
        - detail
        - status
        type: object
        x-event-categories: []
    entity_list:
      additionalProperties: true
      description: A list of Entity objects.
      example:
        data:
        - corporation:
            address:
              city: New York
              country: US
              line1: 33 Liberty Street
              line2: null
              state: NY
              zip: '10045'
            beneficial_owners:
            - company_title: CEO
              id: entity_beneficial_owner_vozma8szzu1sxezp5zq6
              individual:
                address:
                  city: New York
                  country: US
                  line1: 33 Liberty Street
                  line2: null
                  state: NY
                  zip: '10045'
                date_of_birth: '1970-01-31'
                identification:
                  method: social_security_number
                  number_last4: '1120'
                name: Ian Crease
              prongs:
              - control
              - ownership
            email: null
            incorporation_state: NY
            industry_code: null
            legal_identifier:
              category: us_employer_identification_number
              value: '602214076'
            name: National Phonograph Company
            website: https://example.com
          created_at: '2020-01-31T23:59:59Z'
          creating_entity_onboarding_session_id: null
          description: null
          details_confirmed_at: null
          government_authority: null
          id: entity_n8y8tnk2p9339ti393yi
          idempotency_key: null
          joint: null
          natural_person: null
          risk_rating: null
          status: active
          structure: corporation
          supplemental_documents:
          - created_at: '2020-01-31T23:59:59Z'
            entity_id: entity_n8y8tnk2p9339ti393yi
            file_id: file_makxrc67oh9l6sg7w9yc
            idempotency_key: null
            type: entity_supplemental_document
          terms_agreements:
          - agreed_at: '2020-01-31T23:59:59Z'
            ip_address: 128.32.0.1
            terms_url: https://increase.com/example_terms
          third_party_verification: null
          trust: null
          type: entity
          validation: null
        next_cursor: v57w5d
      properties:
        data:
          description: The contents of the list.
          items:
            $ref: '#/components/schemas/entity'
          type: array
          x-documentation-priority: default
        next_cursor:
          anyOf:
          - description: A pointer to a place in the list. Pass this as the `cursor` parameter to retrieve the next page of results. If there are no more results, the value will be `null`.
            type: string
            x-documentation-priority: default
          - type: 'null'
      required:
      - data
      - next_cursor
      title: Entity List
      type: object
      x-event-categories: []
      x-stainless-empty-object: false
      x-title-plural: Entity Lists
    update_an_entity_parameters:
      additionalProperties: false
      example:
        corporation:
          address:
            city: New York
            country: US
            line1: 33 Liberty Street
            line2: Unit 2
            state: NY
            zip: '10045'
        risk_rating:
          rated_at: '2020-01-31T23:59:59Z'
          rating: low
      properties:
        corporation:
          additionalProperties: true
          description: Details of the corporation entity to update. If you specify this parameter and the entity is not a corporation, the request will fail.
          properties:
            address:
              additionalProperties: false
              description: The entity's physical address. Mail receiving locations like PO Boxes and PMB's are disallowed.
              properties:
                city:
                  description: The city, district, town, or village of the address.
                  maxLength: 200
                  minLength: 1
                  type: string
                  x-documentation-priority: default
                country:
                  description: The two-letter ISO 3166-1 alpha-2 code for the country of the address.
                  maxLength: 200
                  minLength: 1
                  type: string
                  x-documentation-priority: default
                line1:
                  description: The first line of the address. This is usually the street number and street.
                  maxLength: 200
                  minLength: 1
                  type: string
                  x-documentation-priority: default
                line2:
                  description: The second line of the address. This might be the floor or room number.
                  maxLength: 200
                  minLength: 1
                  type: string
                  x-documentation-priority: default
                state:
                  description: The two-letter United States Postal Service (USPS) abbreviation for the US state, province, or region of the address. Required in certain countries.
                  maxLength: 200
                  minLength: 1
                  type: string
                  x-documentation-priority: default
                zip:
                  description: The ZIP or postal code of the address. Required in certain countries.
                  maxLength: 200
                  minLength: 1
                  type: string
                  x-documentation-priority: default
              required:
              - line1
              - city
              - country
              type: object
              x-documentation-priority: default
              x-event-categories: []
              x-stainless-empty-object: false
            email:
              description: An email address for the business. Not every program requires an email for submitted Entities.
              format: email
              maxLength: 200
              minLength: 1
              type: string
              x-documentation-priority: default
            incorporation_state:
              description: The two-letter United States Postal Service (USPS) abbreviation for the corporation's state of incorporation.
              maxLength: 200
              minLength: 1
              type: string
              x-documentation-priority: default
            industry_code:
              description: The North American Industry Classification System (NAICS) code for the corporation's primary line of business. This is a number, like `5132` for `Software Publishers`. A full list of classification codes is available [here](https://increase.com/documentation/data-dictionary#north-american-industry-classification-system-codes).
              maxLength: 200
              minLength: 1
              type: string
              x-documentation-priority: default
            legal_identifier:
              additionalProperties: false
              description: The legal identifier of the corporation. This is usually the Employer Identification Number (EIN).
              properties:
                category:
                  description: The category of the legal identifier.
                  enum:
                  - us_employer_identification_number
                  - other
                  type: string
                  x-documentation-priority: default
                  x-enum-descriptions:
                  - The Employer Identification Number (EIN) for the company. The EIN is a 9-digit number assigned by the IRS; submit it as nine digits with no dashes or other separators.
                  - A legal identifier issued by a foreign government, like a tax identification number or registration number.
                value:
                  description: The identifier of the legal identifier. For US Employer Identification Numbers, submit nine digits with no dashes or other separators.
                  maxLength: 200
                  minLength: 1
                  type: string
                  x-documentation-priority: default
              required:
              - value
              type: object
              x-documentation-priority: default
              x-event-categories: []
              x-stainless-empty-object: false
            name:
              description: The legal name of the corporation.
              maxLength: 200
              minLength: 1
              type: string
              x-documentation-priority: default
            website:
              description: A website for the business. Not every program requires a website for submitted Entities.
              type: string
              x-documentation-priority: default
          type: object
          x-documentation-priority: default
          x-event-categories: []
          x-stainless-empty-object: false
        details_confirmed_at:
          description: When your user last confirmed the Entity's details. Depending on your program, you may be required to affirmatively confirm details with your users on an annual basis.
          format: date-time
          type: string
          x-documentation-priority: low
        government_authority:
          additionalProperties: false
          description: Details of the government authority entity to update. If you specify this parameter and the entity is not a government authority, the request will fail.
          properties:
            address:
              additionalProperties: false
              description: The entity's physical address. Mail receiving locations like PO Boxes and PMB's are disallowed.
              properties:
                city:
                  description: The city of the address.
                  maxLength: 200
                  minLength: 1
                  type: string
                  x-documentation-priority: default
                line1:
                  description: The first line of the address. This is usually the street number and street.
                  maxLength: 200
                  minLength: 1
                  type: string
                  x-documentation-priority: default
                line2:
                  description: The second line of the address. This might be the floor or room number.
                  maxLength: 200
                  minLength: 1
                  type: string
                  x-documentation-priority: default
                state:
                  description: The two-letter United States Postal Service (USPS) abbreviation for the state of the address.
                  maxLength: 2
                  minLength: 2
                  type: string
                  x-documentation-priority: default
                zip:
                  description: The ZIP code of the address.
                  maxLength: 200
                  minLength: 1
                  type: string
                  x-documentation-priority: default
              required:
              - line1
              - city
              - state
              - zip
              type: object
              x-documentation-priority: default
              x-event-categories: []
              x-stainless-empty-object: false
            name:
              description: The legal name of the government authority.
              maxLength: 200
              minLength: 1
              type: string
              x-documentation-priority: default
          type: object
          x-documentation-priority: default
          x-event-categories: []
          x-stainless-empty-object: false
        natural_person:
          additionalProperties: false
          description: Details of the natural person entity to update. If you specify this parameter and the entity is not a natural person, the request will fail.
          properties:
            address:
              additionalProperties: false
              description: The entity's physical address. Mail receiving locations like PO Boxes and PMB's are disallowed.
              properties:
                city:
                  description: The city, district, town, or village of the address.
                  maxLength: 200
                  minLength: 1
                  type: string
                  x-documentation-priority: default
                country:
                  description: The two-letter ISO 3166-1 alpha-2 code for the country of the address.
                  maxLength: 200
                  minLength: 1
                  type: string
                  x-documentation-priority: default
                line1:
                  description: The first line of the address. This is usually the street number and street.
                  maxLength: 200
                  minLength: 1
                  type: string
                  x-documentation-priority: default
                line2:
                  description: The second line of the address. This might be the floor or room number.
                  maxLength: 200
                  minLength: 1
                  type: string
                  x-documentation-priority: default
                state:
                  description: The two-letter United States Postal Service (USPS) abbreviation for the US state, province, or region of the address. Required in certain countries.
                  maxLength: 200
                  minLength: 1
                  type: string
                  x-documentation-priority: default
                zip:
                  description: The ZIP or postal code of the address. Required in certain countries.
                  maxLength: 200
                  minLength: 1
                  type: string
                  x-documentation-priority: default
              required:
              - line1
              - city
              - country
              type: object
              x-documentation-priority: default
              x-event-categories: []
              x-stainless-empty-object: false
            confirmed_no_us_tax_id:
              description: The identification method for an individual can only be a passport, driver's license, or other document if you've confirmed the individual does not have a US tax id (either a Social Security Number or Individual Taxpayer Identification Number).
              type: boolean
              x-documentation-priority: default
            identification:
              additionalProperties: true
              description: A means of verifying the person's identity.
              properties:
                drivers_license:
                  additionalProperties: false
                  description: Information about the United States driver's license used for identification. Required if `method` is equal to `drivers_license`.
                  properties:
                    back_file_id:
                      description: The identifier of the File containing the back of the driver's license.
                      type: string
                      x-documentation-priority: default
                      x-id-reference-to: Files
                    expiration_date:
                      description: The driver's license's expiration date in YYYY-MM-DD format.
                      format: date
                      type: string
                      x-documentation-priority: default
                    file_id:
                      description: The identifier of the File containing the front of the driver's license.
                      type: string
                      x-documentation-priority: default
                      x-id-reference-to: Files
                    state:
                      description: The state that issued the provided driver's license.
                      maxLength: 2
                      minLength: 2
                      type: string
                      x-documentation-priority: default
                  required:
                  - file_id
                  - expiration_date
                  - state
                  type: object
                  x-documentation-priority: default
                  x-event-categories: []
                  x-stainless-empty-object: false
                method:
                  description: A method that can be used to verify the individual's identity.
                  enum:
                  - social_security_number
                  - individual_taxpayer_identification_number
                  - passport
                  - drivers_license
                  - other
                  type: string
                  x-documentation-priority: default
                  x-enum-descriptions:
                  - A social security number.
                  - An individual taxpayer identification number (ITIN).
                  - A passport number.
                  - A driver's license number.
                  - Another identifying document.
                number:
                  description: An identification number that can be used to verify the individual's identity, such as a social security number. For Social Security Numbers and Individual Taxpayer Identification Numbers, submit nine digits with no dashes or other separators.
                  maxLength: 200
                  minLength: 4
                  type: string
                  x-documentation-priority: default
                other:
                  additionalProperties: false
                  description: Information about the identification document provided. Required if `method` is equal to `other`.
                  properties:
                    back_file_id:
                      description: The identifier of the File containing the back of the document. Not every document has a reverse side.
                      type: string
                      x-documentation-priority: default
                      x-id-reference-to: Files
                    country:
                      description: The two-character ISO 3166-1 code representing the country that issued the document (e.

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