openapi: 3.2.0
info:
  title: Identity Products API
  description: Registration, verification and management of CFX identities associated with financial transactions on the CFX network.
  termsOfService: ''
  contact:
    name: API Owner
    email: api@cfxlabs.com
  license:
    name: ''
    url: ''
  version: '@VERSION@'
  summary: CFX Identity API
servers:
- url: https://api.dev.cfx.to
  description: Customer Sandbox
- url: https://api.cfx.to
  description: Production
security:
- ApiKeyAuth: []
  ApiSecretAuth: []
tags:
- name: Products
  description: Products available to an identity and their activation status.
paths:
  /v1/identity/{identityId}/products:
    get:
      summary: List products available to an identity
      tags:
      - Products
      description: 'Returns every product configured for this customer with the identity''s effective activation status.


        Use this for product menus and route gates. For limits and usage, call `GET /v1/{deposit,withdrawal}/usage` — limits and current usage are returned together per product.'
      parameters:
      - schema:
          type: string
        in: query
        name: countryCode
        required: false
        description: ISO-3166-1 Alpha-2 country override for activation evaluation. Defaults to the entity's country of residence.
      - schema:
          type: string
        in: query
        name: regionCode
        required: false
        description: ISO-3166-2 region/state override
      - schema:
          type: string
        example: id_xxxxxxxxxx
        in: path
        name: identityId
        required: true
        description: The unique identifier for the identity
      responses:
        '200':
          description: Default Response
          content:
            application/json:
              schema:
                type: object
                required:
                - items
                properties:
                  items:
                    type: array
                    items:
                      type: object
                      required:
                      - name
                      - status
                      properties:
                        name:
                          enum:
                          - organization.v1
                          - identity.v1
                          - card.physical_card.v1
                          - card.virtual_card.v1
                          - deposit.us_cash.v1
                          - deposit.rtp.v1
                          - deposit.fednow.v1
                          - deposit.us_bank_ach.v1
                          - deposit.ach_credit.v1
                          - deposit.us_wire.v1
                          - deposit.swift_wire.v1
                          - transfer.redemption.v1
                          - swap.v1
                          - withdraw.blockchain.v1
                          - withdraw.ke_bank.v1
                          - withdraw.ke_momo.v1
                          - withdraw.mx_bank_spei.v1
                          - withdraw.swift_wire.v1
                          - withdraw.tg_momo.v1
                          - withdraw.us_bank_ach.v1
                          - withdraw.us_instant.v1
                          - withdraw.us_wire.v1
                          - withdraw.ach_pull.v1
                          - withdraw.us_wire_drawdown.v1
                          - account.virtual-account.v1
                          type: string
                        status:
                          enum:
                          - ACTIVE
                          - DENIED
                          - INACTIVE
                          type: string
                          description: 'Whether this product is currently usable by the entity.


                            * `ACTIVE`: at least one route resolves and no DENY rule matches

                            * `DENIED`: a customer-tier or admin DENY activation rule matches (e.g. country/region block, customer opt-out)

                            * `INACTIVE`: no eligible route exists for this entity at all'
                        denyReason:
                          type: string
                          description: Human-readable reason when status is `DENIED`. Stable identifiers come from the matched activation-rule's `label`.
                        supportedCurrencies:
                          type: array
                          items:
                            type: string
                          description: 'ISO 4217 currency codes this product accepts as source.


                            Absent when the product imposes no source-currency restriction at the rail level, or when no enumerable list could be derived (e.g. `card.*` products that don''t transact in a currency, or routes with unbounded matchers). Never empty.'
                        supportedCountries:
                          type: array
                          items:
                            type: string
                          description: 'ISO-3166-1 Alpha-2 country codes this product is available in.


                            Derived from the rail''s ADMIN `APPROVE` activation rules. Absent when the product has no country restriction at the rail level, or when no enumerable list could be derived (rule matcher is `ALWAYS` or unbounded). Never empty.'
        '400':
          description: The service cannot understand the request
          content:
            application/json:
              schema:
                type: object
                required:
                - code
                - message
                properties:
                  code:
                    type: string
                    enum:
                    - INVALID_REQUEST
                  message:
                    type: string
                  errors:
                    type: array
                    items:
                      type: object
                      properties: {}
                      additionalProperties: true
                title: INVALID_REQUEST
                description: The service cannot understand the request
        '401':
          description: The access to this resource has been denied
          content:
            application/json:
              schema:
                type: object
                required:
                - code
                - message
                properties:
                  code:
                    type: string
                    enum:
                    - UNAUTHORIZED
                  message:
                    type: string
                title: UNAUTHORIZED
                description: The access to this resource has been denied
        '403':
          description: The credentials are valid but the caller is not permitted to transact
          content:
            application/json:
              schema:
                type: object
                required:
                - code
                - message
                properties:
                  code:
                    type: string
                    enum:
                    - FORBIDDEN
                  message:
                    type: string
                title: FORBIDDEN
                description: The credentials are valid but the caller is not permitted to transact
        '404':
          description: The resource was not found
          content:
            application/json:
              schema:
                type: object
                required:
                - code
                - message
                properties:
                  code:
                    type: string
                    enum:
                    - NOT_FOUND
                  message:
                    type: string
                title: NOT_FOUND
                description: The resource was not found
        default:
          description: Catch-all error response for any unexpected internal errors
          content:
            application/json:
              schema:
                type: object
                required:
                - code
                - message
                properties:
                  code:
                    type: string
                    enum:
                    - INTERNAL
                  message:
                    type: string
                    enum:
                    - An unexpected internal error has occurred
                title: INTERNAL
                description: Catch-all error response for any unexpected internal errors
      operationId: getV1IdentityByIdentityIdProducts
      x-operation-id-source: derived
components:
  securitySchemes:
    ApiKeyAuth:
      name: x-api-key
      type: apiKey
      in: header
    ApiSecretAuth:
      name: x-api-secret
      type: apiKey
      in: header
externalDocs:
  description: Find out more about CFX
  url: https://www.cfxlabs.com/