> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tesouro.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Create an entity

> Create a new entity from the specified values.



## OpenAPI

````yaml /.tooling/schemas/rest/tags/product-finops.json post /finops/v1/entities
openapi: 3.1.0
info:
  title: Tesouro Partner API
  version: '2025-06-23'
  description: The Tesouro REST API, for Tesouro partners to integrate with our solution.
  termsOfService: https://tesouro.com/terms
  contact:
    name: Tesouro team
    url: https://tesouro.com/about/
    email: developers@tesouro.com
servers:
  - url: https://api.sandbox.tesouro.com
    description: Sandbox
security: []
tags:
  - name: Accounting connections
  - name: Accounting data pull
  - name: Accounting synchronized records
  - name: Accounting tax rates
  - name: Analytics
  - name: Approval policies
  - name: Approval requests
  - name: Bank details
  - name: Comments
  - name: Cost centers
  - name: Counterpart VAT IDs
  - name: Counterpart addresses
  - name: Counterpart bank accounts
  - name: Counterpart contacts
  - name: Counterparts
  - name: Credit notes
  - name: Custom tax rates
  - name: Delivery notes
  - name: Documents
  - name: Entities
  - name: Entity users
  - name: Events
  - name: Files
  - name: Identity
  - name: Ledger accounts
  - name: Mail templates
  - name: Mailbox domains
  - name: Mailboxes
  - name: Measure units
  - name: OCR
  - name: Overdue reminders
  - name: PDF templates
  - name: Payable line items
  - name: Payables
  - name: Payment intents
  - name: Payment links
  - name: Payment methods
  - name: Payment records
  - name: Payment reminders
  - name: Payment terms
  - name: Products
  - name: Projects
  - name: Purchase orders
  - name: Receipts
  - name: Receivables
  - name: Recurrences
  - name: Tags
  - name: Text templates
  - name: Transactions
  - name: VAT rates
  - name: Webhook deliveries
  - name: Webhook subscriptions
paths:
  /finops/v1/entities:
    post:
      tags:
        - Entities
      summary: Create an entity
      description: Create a new entity from the specified values.
      operationId: post_entities
      parameters:
        - required: true
          schema:
            type: string
            format: date
          example: '2025-06-23'
          name: x-finops-version
          in: header
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateEntityRequest'
      responses:
        '201':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EntityResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorSchemaResponse'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorSchemaResponse'
        '405':
          description: Method Not Allowed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorSchemaResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorSchemaResponse'
      security:
        - HTTPBearer: []
components:
  schemas:
    CreateEntityRequest:
      properties:
        address:
          $ref: '#/components/schemas/EntityAddressSchema'
          description: An address description of the entity
        email:
          type: string
          format: email
          description: An official email address of the entity
        individual:
          anyOf:
            - $ref: '#/components/schemas/IndividualSchema'
            - type: 'null'
          description: A set of meta data describing the individual
        organization:
          anyOf:
            - $ref: '#/components/schemas/OrganizationSchema'
            - type: 'null'
          description: A set of meta data describing the organization
        phone:
          anyOf:
            - type: string
              maxLength: 20
            - type: 'null'
          description: >-
            The contact phone number of the entity. Required for US
            organizations to use payments.
        registration_authority:
          anyOf:
            - type: string
              maxLength: 100
              minLength: 1
            - type: 'null'
          description: >-
            (Germany only) The name of the local district court (_Amtsgericht_)
            where the entity is registered. Required if `registration_number` is
            provided.
          examples:
            - Amtsgericht Charlottenburg
        registration_number:
          anyOf:
            - type: string
              maxLength: 100
              minLength: 1
            - type: 'null'
          description: >-
            (Germany only) The entity's commercial register number
            (_Handelsregisternummer_) in the German Commercial Register, if
            available.
          examples:
            - HRB 202324
        tax_id:
          anyOf:
            - type: string
              maxLength: 30
              minLength: 1
            - type: 'null'
          description: >-
            The entity's taxpayer identification number or tax ID. This field is
            required for entities that are non-VAT registered.
        type:
          $ref: '#/components/schemas/EntityTypeEnum'
          description: A type for an entity
        website:
          anyOf:
            - type: string
              maxLength: 2083
              minLength: 1
              format: uri
            - type: 'null'
          description: A website of the entity
      additionalProperties: false
      type: object
      required:
        - address
        - email
        - type
      description: A schema for a request to create an entity of different types
    EntityResponse:
      oneOf:
        - $ref: '#/components/schemas/EntityOrganizationResponse'
        - $ref: '#/components/schemas/EntityIndividualResponse'
      description: A schema for a response after creation of an entity of different types
      discriminator:
        propertyName: type
        mapping:
          individual:
            $ref: '#/components/schemas/EntityIndividualResponse'
          organization:
            $ref: '#/components/schemas/EntityOrganizationResponse'
    ErrorSchemaResponse:
      properties:
        error:
          $ref: '#/components/schemas/ErrorSchema'
      type: object
      required:
        - error
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
      type: object
    EntityAddressSchema:
      properties:
        city:
          type: string
          maxLength: 100
          minLength: 1
          description: A city (a full name) where the entity is registered
        country:
          $ref: '#/components/schemas/AllowedCountries'
          description: 'A country name (as ISO code) where the entity is registered '
          examples:
            - DE
        line1:
          type: string
          maxLength: 200
          minLength: 1
          description: A street where the entity is registered
        line2:
          anyOf:
            - type: string
              maxLength: 100
              minLength: 1
            - type: 'null'
          description: An alternative street used by the entity
        postal_code:
          type: string
          maxLength: 10
          minLength: 1
          description: A postal code of the address where the entity is registered
        state:
          anyOf:
            - type: string
              maxLength: 100
              minLength: 1
            - type: 'null'
          description: >-
            State, county, province, prefecture, region, or similar component of
            the entity's address. For US entities, `state` is required and must
            be a two-letter [USPS state
            abbreviation](https://pe.usps.com/text/pub28/28apb.htm), for
            example, NY or CA.
      additionalProperties: false
      type: object
      required:
        - city
        - country
        - line1
        - postal_code
      description: A schema represents address info of the entity
    IndividualSchema:
      properties:
        date_of_birth:
          anyOf:
            - type: string
              format: date
            - type: 'null'
        first_name:
          type: string
          maxLength: 100
          minLength: 1
          description: A first name of an individual
        id_number:
          anyOf:
            - type: string
              maxLength: 100
              minLength: 1
            - type: 'null'
        last_name:
          type: string
          maxLength: 100
          minLength: 1
          description: A last name of an individual
        ssn_last_4:
          anyOf:
            - type: string
              maxLength: 4
              minLength: 4
            - type: 'null'
          description: The last four digits of the individual's Social Security number
        title:
          anyOf:
            - type: string
              maxLength: 10
              minLength: 1
            - type: 'null'
          description: A title of an individual
      additionalProperties: false
      type: object
      required:
        - first_name
        - last_name
      description: A schema contains metadata for an individual
    OrganizationSchema:
      properties:
        business_structure:
          anyOf:
            - $ref: '#/components/schemas/EntityBusinessStructure'
            - type: 'null'
          description: Business structure of the company
        directors_provided:
          anyOf:
            - type: boolean
            - type: 'null'
        executives_provided:
          anyOf:
            - type: boolean
            - type: 'null'
        legal_entity_id:
          anyOf:
            - type: string
              maxLength: 20
              minLength: 1
            - type: 'null'
          description: A code which identifies uniquely a party of a transaction worldwide
        legal_name:
          type: string
          maxLength: 255
          minLength: 1
          description: >-
            The legal name of the organization. If this organization will use
            Monite payment rails, this name must be up to 100 characters long,
            otherwise it can be up to 255 characters long.
        owners_provided:
          anyOf:
            - type: boolean
            - type: 'null'
        representative_provided:
          anyOf:
            - type: boolean
            - type: 'null'
      type: object
      required:
        - legal_name
      description: A schema contains metadata for an organization
    EntityTypeEnum:
      type: string
      enum:
        - individual
        - organization
    EntityOrganizationResponse:
      properties:
        id:
          type: string
          format: uuid
          description: UUID entity ID
        created_at:
          type: string
          format: date-time
          description: UTC datetime
        updated_at:
          type: string
          format: date-time
          description: UTC datetime
        address:
          $ref: '#/components/schemas/EntityAddressResponseSchema'
          description: An address description of the entity
        email:
          anyOf:
            - type: string
            - type: 'null'
          description: An official email address of the entity
        logo:
          anyOf:
            - $ref: '#/components/schemas/FileSchema2'
            - type: 'null'
          description: A logo image of the entity
        organization:
          $ref: '#/components/schemas/OrganizationResponseSchema'
          description: A set of metadata describing an organization
        phone:
          anyOf:
            - type: string
              maxLength: 100
            - type: 'null'
          description: A phone number of the entity
        registration_authority:
          anyOf:
            - type: string
              maxLength: 100
              minLength: 1
            - type: 'null'
          description: >-
            (Germany only) The name of the local district court (_Amtsgericht_)
            where the entity is registered. Required if `registration_number` is
            provided.
          examples:
            - Amtsgericht Charlottenburg
        registration_number:
          anyOf:
            - type: string
              maxLength: 100
              minLength: 1
            - type: 'null'
          description: >-
            (Germany only) The entity's commercial register number
            (_Handelsregisternummer_) in the German Commercial Register, if
            available.
          examples:
            - HRB 202324
        status:
          $ref: '#/components/schemas/EntityStatusEnum'
          description: record status, 'active' by default
        tax_id:
          anyOf:
            - type: string
              maxLength: 30
            - type: 'null'
          description: >-
            The entity's taxpayer identification number or tax ID. This field is
            required for entities that are non-VAT registered.
        type:
          type: string
          const: organization
          description: A type for an organization
        website:
          anyOf:
            - type: string
              maxLength: 2083
              minLength: 1
              format: uri
            - type: 'null'
          description: A website of the entity
      type: object
      required:
        - id
        - created_at
        - updated_at
        - address
        - organization
        - status
        - type
    EntityIndividualResponse:
      properties:
        id:
          type: string
          format: uuid
          description: UUID entity ID
        created_at:
          type: string
          format: date-time
          description: UTC datetime
        updated_at:
          type: string
          format: date-time
          description: UTC datetime
        address:
          $ref: '#/components/schemas/EntityAddressResponseSchema'
          description: An address description of the entity
        email:
          anyOf:
            - type: string
            - type: 'null'
          description: An official email address of the entity
        individual:
          $ref: '#/components/schemas/IndividualResponseSchema'
          description: A set of metadata describing an individual
        logo:
          anyOf:
            - $ref: '#/components/schemas/FileSchema2'
            - type: 'null'
          description: A logo image of the entity
        phone:
          anyOf:
            - type: string
              maxLength: 100
            - type: 'null'
          description: A phone number of the entity
        registration_authority:
          anyOf:
            - type: string
              maxLength: 100
              minLength: 1
            - type: 'null'
          description: >-
            (Germany only) The name of the local district court (_Amtsgericht_)
            where the entity is registered. Required if `registration_number` is
            provided.
          examples:
            - Amtsgericht Charlottenburg
        registration_number:
          anyOf:
            - type: string
              maxLength: 100
              minLength: 1
            - type: 'null'
          description: >-
            (Germany only) The entity's commercial register number
            (_Handelsregisternummer_) in the German Commercial Register, if
            available.
          examples:
            - HRB 202324
        status:
          $ref: '#/components/schemas/EntityStatusEnum'
          description: record status, 'active' by default
        tax_id:
          anyOf:
            - type: string
              maxLength: 30
            - type: 'null'
          description: >-
            The entity's taxpayer identification number or tax ID. This field is
            required for entities that are non-VAT registered.
        type:
          type: string
          const: individual
          description: A type for an individual
        website:
          anyOf:
            - type: string
              maxLength: 2083
              minLength: 1
              format: uri
            - type: 'null'
          description: A website of the entity
      type: object
      required:
        - id
        - created_at
        - updated_at
        - address
        - individual
        - status
        - type
    ErrorSchema:
      properties:
        message:
          type: string
      type: object
      required:
        - message
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
              - type: string
              - type: integer
          type: array
        msg:
          type: string
        type:
          type: string
      type: object
      required:
        - loc
        - msg
        - type
    AllowedCountries:
      type: string
      enum:
        - AF
        - AX
        - AL
        - DZ
        - AS
        - AD
        - AO
        - AI
        - AQ
        - AG
        - AR
        - AM
        - AW
        - AU
        - AT
        - AZ
        - BS
        - BH
        - BD
        - BB
        - BY
        - BE
        - BZ
        - BJ
        - BM
        - BT
        - BO
        - BA
        - BW
        - BV
        - BR
        - IO
        - BN
        - BG
        - BF
        - BI
        - KH
        - CM
        - CA
        - IC
        - CV
        - KY
        - CF
        - EA
        - TD
        - CL
        - CN
        - CX
        - CC
        - CO
        - KM
        - CG
        - CD
        - CK
        - CR
        - CI
        - HR
        - CU
        - CY
        - CZ
        - DK
        - DJ
        - DM
        - DO
        - EC
        - EG
        - SV
        - GQ
        - ER
        - EE
        - SZ
        - ET
        - FK
        - FO
        - FJ
        - FI
        - FR
        - GF
        - PF
        - TF
        - GA
        - GM
        - GE
        - DE
        - GH
        - GI
        - GR
        - GL
        - GD
        - GP
        - GU
        - GT
        - GG
        - GN
        - GW
        - GY
        - HT
        - HM
        - VA
        - HN
        - HK
        - HU
        - IS
        - IN
        - ID
        - IR
        - IQ
        - IE
        - IM
        - IL
        - IT
        - JM
        - JP
        - JE
        - JO
        - KZ
        - KE
        - KI
        - KP
        - KR
        - KW
        - KG
        - LA
        - LV
        - LB
        - LS
        - LR
        - LY
        - LI
        - LT
        - LU
        - MO
        - MG
        - MW
        - MY
        - MV
        - ML
        - MT
        - MH
        - MQ
        - MR
        - MU
        - YT
        - MX
        - FM
        - MD
        - MC
        - MN
        - ME
        - MS
        - MA
        - MZ
        - MM
        - NA
        - NR
        - NP
        - NL
        - AN
        - NC
        - NZ
        - NI
        - NE
        - NG
        - NU
        - NF
        - MP
        - MK
        - 'NO'
        - OM
        - PK
        - PW
        - PS
        - PA
        - PG
        - PY
        - PE
        - PH
        - PN
        - PL
        - PT
        - PR
        - QA
        - RE
        - RO
        - RU
        - RW
        - SH
        - KN
        - LC
        - PM
        - VC
        - WS
        - SM
        - ST
        - SA
        - SN
        - RS
        - SC
        - SL
        - SG
        - SK
        - SI
        - SB
        - SO
        - ZA
        - SS
        - GS
        - ES
        - LK
        - SD
        - SR
        - SJ
        - SE
        - CH
        - SY
        - TW
        - TJ
        - TZ
        - TH
        - TL
        - TG
        - TK
        - TO
        - TT
        - TN
        - TR
        - TM
        - TC
        - TV
        - UG
        - UA
        - AE
        - GB
        - US
        - UM
        - UY
        - UZ
        - VU
        - VE
        - VN
        - VG
        - VI
        - WF
        - EH
        - YE
        - ZM
        - ZW
        - BL
        - BQ
        - CW
        - MF
        - SX
    EntityBusinessStructure:
      type: string
      enum:
        - incorporated_partnership
        - unincorporated_partnership
        - public_corporation
        - private_corporation
        - sole_proprietorship
        - single_member_llc
        - multi_member_llc
        - private_partnership
        - unincorporated_association
        - public_partnership
    EntityAddressResponseSchema:
      properties:
        city:
          type: string
          maxLength: 255
          description: A city (a full name) where the entity is registered
        country:
          $ref: '#/components/schemas/AllowedCountries'
          description: 'A country name (as ISO code) where the entity is registered '
          examples:
            - DE
        line1:
          type: string
          maxLength: 255
          description: A street where the entity is registered
        line2:
          anyOf:
            - type: string
              maxLength: 100
            - type: 'null'
          description: An alternative street used by the entity
        postal_code:
          type: string
          maxLength: 10
          description: A postal code of the address where the entity is registered
        state:
          anyOf:
            - type: string
            - type: 'null'
          description: A state in a country where the entity is registered
      additionalProperties: false
      type: object
      required:
        - city
        - country
        - line1
        - postal_code
      description: A schema represents address info of the entity
    FileSchema2:
      properties:
        id:
          type: string
          format: uuid
          description: A unique ID of this file.
        created_at:
          type: string
          format: date-time
          description: >-
            UTC date and time when this file was uploaded to Monite. Timestamps
            follow the [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601)
            format.
        file_type:
          type: string
          description: The type of the business object associated with this file.
          examples:
            - payables
        md5:
          type: string
          description: The MD5 hash of the file.
          examples:
            - 31d1a2dd1ad3dfc39be849d70a68dac0
        mimetype:
          type: string
          description: >-
            The file's [media
            type](https://developer.mozilla.org/en-US/docs/Web/HTTP/MIME_types).
          examples:
            - application/pdf
        name:
          type: string
          maxLength: 512
          description: The original file name (if available).
          examples:
            - invoice.pdf
        pages:
          anyOf:
            - items:
                $ref: '#/components/schemas/PageSchema'
              type: array
            - type: 'null'
          description: >-
            If the file is a PDF document, this property contains individual
            pages extracted from the file. Otherwise, an empty array.
          default: []
        previews:
          anyOf:
            - items:
                $ref: '#/components/schemas/PreviewSchema'
              type: array
            - type: 'null'
          description: >-
            Preview images generated for this file. There can be multiple images
            with different sizes.
          default: []
        region:
          type: string
          description: Geographical region of the data center where the file is stored.
          examples:
            - eu-central-1
        size:
          type: integer
          minimum: 0
          description: The file size in bytes.
          examples:
            - 24381
        url:
          type: string
          description: The URL to download the file.
          examples:
            - https://bucketname.s3.amazonaws.com/12345/67890.pdf
      type: object
      required:
        - id
        - created_at
        - file_type
        - md5
        - mimetype
        - name
        - region
        - size
        - url
      description: Represents a file (such as a PDF invoice) that was uploaded to Monite.
    OrganizationResponseSchema:
      properties:
        business_structure:
          anyOf:
            - $ref: '#/components/schemas/EntityBusinessStructure'
            - type: 'null'
          description: Business structure of the company
        directors_provided:
          anyOf:
            - type: boolean
            - type: 'null'
        executives_provided:
          anyOf:
            - type: boolean
            - type: 'null'
        legal_entity_id:
          anyOf:
            - type: string
              maxLength: 20
            - type: 'null'
          description: A code which identifies uniquely a party of a transaction worldwide
        legal_name:
          type: string
          maxLength: 255
          description: The legal name of the organization.
        owners_provided:
          anyOf:
            - type: boolean
            - type: 'null'
        representative_provided:
          anyOf:
            - type: boolean
            - type: 'null'
      type: object
      required:
        - legal_name
      description: Contains data specific to entities of the `organization` type.
    EntityStatusEnum:
      type: string
      enum:
        - active
        - inactive
        - deleted
    IndividualResponseSchema:
      properties:
        date_of_birth:
          anyOf:
            - type: string
              format: date
            - type: 'null'
        first_name:
          type: string
          maxLength: 100
          description: A first name of an individual
        id_number:
          anyOf:
            - type: string
            - type: 'null'
        last_name:
          type: string
          maxLength: 100
          description: A last name of an individual
        ssn_last_4:
          anyOf:
            - type: string
              maxLength: 4
              minLength: 4
            - type: 'null'
          description: The last four digits of the individual's Social Security number
        title:
          anyOf:
            - type: string
              maxLength: 10
            - type: 'null'
          description: A title of an individual
      type: object
      required:
        - first_name
        - last_name
      description: Contains data specific to entities of the `individual` type.
    PageSchema:
      properties:
        id:
          type: string
          format: uuid
          description: A unique ID of the image.
        mimetype:
          type: string
          description: >-
            The [media
            type](https://developer.mozilla.org/en-US/docs/Web/HTTP/MIME_types)
            of the image.
          examples:
            - image/png
        number:
          type: integer
          minimum: 0
          description: The page number in the PDF document, from 0.
          examples:
            - 0
        size:
          type: integer
          minimum: 0
          description: Image file size, in bytes.
          examples:
            - 21972
        url:
          type: string
          description: The URL to download the image.
          examples:
            - https://bucket.s3.amazonaws.com/123/456.png
      type: object
      required:
        - id
        - mimetype
        - number
        - size
        - url
      description: >-
        When a PDF document is uploaded to Monite, it extracts individual pages
        from the document

        and saves them as PNG images. This object contains the image and
        metadata of a single page.
    PreviewSchema:
      properties:
        height:
          type: integer
          description: The image height in pixels.
          examples:
            - 400
        url:
          type: string
          description: The image URL.
          examples:
            - https://bucketname.s3.amazonaws.com/1/2/3.png
        width:
          type: integer
          description: The image width in pixels.
          examples:
            - 200
      type: object
      required:
        - height
        - url
        - width
      description: A preview image generated for a file.
  securitySchemes:
    HTTPBearer:
      type: http
      scheme: bearer

````