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

# Create an external entity

> Creates an external entity for the institutional account.

To access the Core API for Institutions, contact your Circle account representative.




## OpenAPI

````yaml openapi/institutional.yaml post /v1/externalEntities
openapi: 3.0.2
info:
  version: ${version}
  title: Core API for Institutions
  description: >-
    The Circle Institutional API provides endpoints for the distribution of USDC
    to end institutions.
servers:
  - url: https://api-sandbox.circle.com
  - url: https://api.circle.com
security: []
tags:
  - name: External Entities
    description: Manage your external entities.
paths:
  /v1/externalEntities:
    post:
      tags:
        - External Entities
      summary: Create an external entity
      description: >
        Creates an external entity for the institutional account.


        To access the Core API for Institutions, contact your Circle account
        representative.
      operationId: createExternalEntity
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ExternalEntityCreationRequest'
      responses:
        '201':
          description: Successfully created an external entity.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExternalEntity'
              examples:
                response:
                  value:
                    walletId: '212000'
                    businessName: Circle Internet Financial Inc.
                    businessUniqueIdentifier: '1234567890'
                    identifierIssuingCountryCode: US
                    complianceState: PENDING
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/NotAuthorized'
        '409':
          $ref: '#/components/responses/Conflict'
      security:
        - bearerAuth: []
components:
  schemas:
    ExternalEntityCreationRequest:
      type: object
      required:
        - businessName
        - businessUniqueIdentifier
        - identifierIssuingCountryCode
        - address
      properties:
        businessName:
          type: string
          description: The name of the business.
          example: Circle Internet Financial Inc.
        businessUniqueIdentifier:
          type: string
          description: >-
            The unique identifier of the business. For example, a company number
            or tax ID.
          example: '1234567890'
        identifierIssuingCountryCode:
          type: string
          description: >-
            The country code of the issuing authority. Formatted as a two-letter
            country code specified in ISO 3166-1 alpha-2.
          pattern: ^[A-Z]{2}$
          example: US
        address:
          $ref: '#/components/schemas/InstitutionalAddress'
    ExternalEntity:
      type: object
      description: An external entity
      properties:
        walletId:
          $ref: '#/components/schemas/InstitutionalWalletId'
        businessName:
          type: string
          description: The name of the business.
          example: Circle Internet Financial Inc.
        businessUniqueIdentifier:
          type: string
          description: >-
            The unique identifier of the business. For example, a company number
            or tax ID.
          example: '1234567890'
        identifierIssuingCountryCode:
          type: string
          description: >-
            The country code of the issuing authority. Formatted as a two-letter
            country code specified in ISO 3166-1 alpha-2.
          pattern: ^[A-Z]{2}$
          example: US
        complianceState:
          type: string
          description: The compliance status of the external entity.
          enum:
            - PENDING
            - ACCEPTED
            - REJECTED
    InstitutionalAddress:
      type: object
      required:
        - country
        - state
        - city
        - postalCode
      properties:
        country:
          type: string
          description: >-
            Country portion of the address. Formatted as a two-letter country
            code specified in ISO 3166-1 alpha-2.
          pattern: ^[A-Z]{2}$
          example: US
        state:
          type: string
          description: >-
            State / county / province / region / district / emirate portion of
            the address. US and Canada use the two-letter code for the
            subdivision.
          example: MA
        city:
          type: string
          description: City portion of the address.
          example: Boston
        postcode:
          type: string
          description: >-
            Postal / ZIP code of the address. If there is no applicable postal
            code, set the value to `00000`.
          example: '01234'
        streetName:
          type: string
          description: Street name of the address.
          example: Main Street
        buildingNumber:
          type: string
          description: Street number of the address.
          example: '100'
    InstitutionalWalletId:
      type: string
      description: >-
        Unique system-generated identifier for the wallet of the institutional
        entity.
      example: '212000'
  responses:
    BadRequest:
      description: The request cannot be processed due to a client error.
      headers:
        X-Request-Id:
          $ref: '#/components/headers/XRequestId'
      content:
        application/json:
          schema:
            type: object
            title: BadRequest
            required:
              - code
              - message
            properties:
              code:
                type: integer
                example: 400
              message:
                type: string
                example: Something went wrong.
            example:
              code: 400
              message: Bad request.
          examples:
            response:
              value:
                code: 400
                message: Bad request.
    NotAuthorized:
      description: >-
        The request has not been applied because it lacks valid authentication
        credentials.
      headers:
        X-Request-Id:
          $ref: '#/components/headers/XRequestId'
      content:
        application/json:
          schema:
            type: object
            title: NotAuthorized
            required:
              - code
              - message
            properties:
              code:
                type: integer
                example: 400
              message:
                type: string
                example: Something went wrong.
            example:
              code: 401
              message: Malformed authorization.
          examples:
            response:
              value:
                code: 401
                message: Malformed authorization.
    Conflict:
      description: >-
        The request has not been applied because it comes in conflict with
        another request (such as re-using an idempotencyKey for a different
        request).
      headers:
        X-Request-Id:
          $ref: '#/components/headers/XRequestId'
      content:
        application/json:
          schema:
            type: object
            title: Conflict
            required:
              - code
              - message
            properties:
              code:
                type: integer
                example: 400
              message:
                type: string
                example: Something went wrong.
            example:
              code: 409
              message: Conflicts with another request.
          examples:
            response:
              value:
                code: 409
                message: Conflicts with another request.
  headers:
    XRequestId:
      description: >-
        Universally unique identifier (UUID v4) for the request. Helpful for
        identifying a request when communicating with Circle support.
      schema:
        type: string
        format: uuid
        example: 2adba88e-9d63-44bc-b975-9b6ae3440dde
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer

````