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

# Create Identity Control

> Create a new identity control on an identity.

```bash OAuth Scope theme={null}
identity:write_identity_control
```


## OpenAPI

````yaml post /v2/identity/controls
openapi: 3.0.0
info:
  title: Paxos Identity Controls API
  version: v2-preview
servers: []
security:
  - OAuth2:
      - identity:read_identity
      - identity:write_identity
paths:
  /v2/identity/controls:
    post:
      tags:
        - Identity Controls
      summary: Create Identity Control
      description: Create a new identity control on an identity.
      operationId: CreateIdentityControl
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateIdentityControlRequest'
        required: true
      responses:
        '200':
          description: A successful response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IdentityControl'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
      security:
        - OAuth2:
            - identity:write_identity_control
components:
  schemas:
    CreateIdentityControlRequest:
      type: object
      properties:
        identity_id:
          type: string
          description: The Identity ID
        type:
          $ref: >-
            #/components/schemas/CreateIdentityControlRequestClientIdentityControlType
        reason_code:
          $ref: '#/components/schemas/IdentityControlReasonCode'
        reason:
          type: string
          description: Freetext reason for setting the control
      required:
        - identity_id
        - type
        - reason_code
    IdentityControl:
      type: object
      properties:
        id:
          type: string
          description: Unique identifier for this control
        type:
          $ref: '#/components/schemas/IdentityControlType'
        set_by:
          $ref: '#/components/schemas/IdentityControlSetBy'
        is_overridable:
          type: boolean
          description: Whether this control can be deleted by the client application
        reason_code:
          $ref: '#/components/schemas/IdentityControlReasonCode'
        reason:
          type: string
          description: Freetext reason why this identity control was set
        created_at:
          type: string
          format: date-time
          description: Time this identity control was created
        deleted_at:
          type: string
          format: date-time
          description: Time this identity control was deleted
    CreateIdentityControlRequestClientIdentityControlType:
      type: string
      enum:
        - SELL_ONLY
        - CLOSED
        - DORMANT
      description: |-
        The type of control applied to an identity.

        - `SELL_ONLY`: Identity may only sell
        - `CLOSED`: Identity is closed and cannot perform any actions
        - `DORMANT`: Identity is dormant due to inactivity
    IdentityControlReasonCode:
      type: string
      enum:
        - OTHER
        - END_USER_REQUEST
        - INACTIVITY
        - COMPLIANCE_KYC
        - COMPLIANCE_EDD
        - COMPLIANCE_SCREENING
        - COMPLIANCE_INVESTIGATION
        - ONBOARDING_INCOMPLETE
        - RISK_FRAUD
        - LEGAL_ORDER
        - ADMINISTRATIVE
      description: >-
        Reason code for why a control was applied.


        - `OTHER`: Miscellaneous reason not captured by existing categories

        - `END_USER_REQUEST`: Control applied at the end user's request

        - `INACTIVITY`: Control applied due to prolonged inactivity in
        accordance with dormancy or lifecycle management policies

        - `COMPLIANCE_KYC`: Control applied due to unmet KYC requirements,
        including missing, expired, failed, or unresponsiveness to refresh
        obligations

        - `COMPLIANCE_EDD`: Control applied due to Enhanced Due Diligence (EDD)
        requirements, including failure to complete EDD reviews, provide
        requested information, or satisfy heightened risk assessment criteria

        - `COMPLIANCE_SCREENING`: Control applied as a result of sanctions,
        politically exposed person (PEP), or adverse media screening hits

        - `COMPLIANCE_INVESTIGATION`: Control applied while an identity is under
        active compliance, risk, or regulatory investigation, including reviews
        triggered by monitoring alerts or external inquiries

        - `ONBOARDING_INCOMPLETE`: Control applied because the onboarding
        process was not successfully completed, including failure to respond to
        requests for information or provide required documentation

        - `RISK_FRAUD`: Control applied due to suspected or confirmed fraud,
        abuse, or security risk, including account compromise, transaction
        fraud, or policy violations

        - `LEGAL_ORDER`: Control applied to comply with a legal, regulatory, or
        law-enforcement directive, including court orders, asset preservation
        requests, or regulatory instructions

        - `ADMINISTRATIVE`: Control applied for operational or
        platform-initiated reasons not attributable to the end user or
        compliance failure, such as system remediation or account restructuring
    IdentityControlType:
      type: string
      enum:
        - SELL_ONLY
        - CLOSED
        - FROZEN
        - DORMANT
      description: |-
        The type of control applied to an identity.

        - `SELL_ONLY`: Identity may only sell
        - `CLOSED`: Identity is closed and cannot perform any actions
        - `FROZEN`: Identity is frozen due to compliance reasons
        - `DORMANT`: Identity is dormant due to inactivity
    IdentityControlSetBy:
      type: string
      enum:
        - SET_BY_PAXOS
        - SET_BY_CLIENT
      description: Indicates who set the control.
  responses:
    BadRequest:
      description: Bad Request
      content:
        application/problem+json:
          schema:
            $ref: '#/components/examples/Problem_bad_request'
    Unauthorized:
      description: Unauthorized
      content:
        application/problem+json:
          schema:
            $ref: '#/components/examples/Problem_unauthorized'
    Forbidden:
      description: Forbidden
      content:
        application/problem+json:
          schema:
            $ref: '#/components/examples/Problem_forbidden'
    NotFound:
      description: Not Found
      content:
        application/problem+json:
          schema:
            $ref: '#/components/examples/Problem_not_found'
  examples:
    Problem_bad_request:
      value:
        type: about:blank
        title: Bad Request
        status: 400
        detail: Invalid request format or missing required fields
    Problem_unauthorized:
      value:
        type: about:blank
        title: Unauthorized
        status: 401
        detail: no authorization header set
    Problem_forbidden:
      value:
        type: about:blank
        title: Forbidden
        status: 403
        detail: user account is disabled
    Problem_not_found:
      value:
        type: about:blank
        title: Not Found
        status: 404
        detail: identity not found
  securitySchemes:
    OAuth2:
      type: oauth2
      flows:
        clientCredentials:
          tokenUrl: https://oauth.paxos.com/oauth2/token
          scopes:
            identity:read_identity: Read identity data
            identity:write_identity: Create and manage identities

````