openapi: 3.0.0
info:
  title: Sandbox - Mobile Identity v2 API
  description: <p style='margin:0cm;font-size:16px;font-family:"Calibri",sans-serif;vertical-align:top;'>Simulates the behavior of the API that retrieves relevant metadata associated with the provide mobile phone number.<br/><br/><img src='https://developer.circulodecredito.com.mx/sites/default/files/cdc-azul.png' height='50'width='170' /><em><span style='font-family:"Literata",sans-serif;'><span style='text-decoration:none; font-size:28px'><big><Big><Big><big><big><big><sup>APIHub</big></sup></big></big></big></big></span></em></p><br/>
  termsOfService: https://developer.circulodecredito.com.mx/legal-mx
  contact:
    email: api@circulodecredito.com.mx
  license:
    name: Derechos Reservados Círculo de Crédito 2025
    url: https://services.circulodecredito.com.mx
  version: 1.4.0
servers:
  - url: https://services.circulodecredito.com.mx/sandbox/v2/telco
tags:
  - name: Sandbox - Mobile Identity v2
paths:
  /phone/carrier-info:
    post:
      tags:
        - Sandbox - Mobile Identity v2
      summary: 'Retrieves the phone-carrier metadata associated with the provided phone number. WARNING: This service currently works for only two phone carrier companies, contact your Círculo de Crédito sales agent for more information. [Synchronous Process]'
      description: |2
         <!DOCTYPE html> <html> <head> <title>Page Title</title> </head> <body>
        <table border='1' cellpadding='1' cellspacing='1'> <caption>Sandbox Cases</caption>  <thead>  <tr>  <th scope='col'>Case</th> <th scope='col'>Description</th> <th scope='col'>Phone Number</th> </tr> </thead> <tbody> <!-- Sandbox Case 1 --> <tr>  <th scope='col'>Case 1</th> <th scope='col'>The phone number is a MOBILE and VALID phone with carrier TELCEL (POSTPAID line). <br><br> All the phone carrier variables/scores [POSTPAID] will succeed.</th> <th scope='col'>5500000001</th>  </tr> <!-- Sandbox Case 2 --> <tr>  <th scope='col'>Case 2</th> <th scope='col'>The phone number is a MOBILE and VALID phone with carrier TELCEL (PREPAID line). <br><br> All the phone carrier variables/scores [PREPAID] will succeed.</th> <th scope='col'>5500000002</th> </tr> <!-- Sandbox Case 3 --> <tr>  <th scope='col'>Case 3</th> <th scope='col'>The phone number is a MOBILE and VALID phone with carrier MOVISTAR (POSTPAID line).<br><br> All the phone carrier variables/scores [POSTPAID] will succeed.</th> <th scope='col'>5500000003</th>  </tr> <!-- Sandbox Case 4 --> <tr>  <th scope='col'>Case 4</th> <th scope='col'>The phone number is a MOBILE and VALID phone with carrier MOVISTAR (PREPAID line).<br><br> All the phone carrier variables/scores [PREPAID] will succeed.</th> <th scope='col'>5500000004</th>  </tr> <!-- Sandbox Case 5 --> <tr>  <th scope='col'>Case 5</th> <th scope='col'>The phone number is a MOBILE and VALID phone with carrier AT&amp;T.<br><br> All the phone carrier variables/scores will fail since this carrier is not supported yet.</th> <th scope='col'>5500000005</th> </tr> <!-- Sandbox Case 6 --> <tr>  <th scope='col'>Case 6</th> <th scope='col'>Unexpected error.</th> <th scope='col'>5500000006</th> </tr> <!-- Sandbox Case 7 --> <tr>  <th scope='col'>Case 7</th> <th scope='col'>Data provider not available at this time.</th> <th scope='col'>5500000007</th> </tr> <!-- Sandbox Case 8 --> <tr>  <th scope='col'>Case 8</th> <th scope='col'>Invalid phone number LADA code.</th> <th scope='col'>5500000008</th> </tr> </tbody> </table>
        </body> </html>
      operationId: phoneNumberCarrierData
      parameters:
        - name: x-api-key
          in: header
          description: Your authentication API key. The Key is assigned through the Círculo de Crédito API-Hub Web site.<br>If you have any questions please contact your Círculo de Crédito sales agent.
          required: true
          schema:
            type: string
      requestBody:
        description: Request body.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PhoneCarrierPostRequest'
        required: true
      responses:
        '200':
          description: Response body. <br><br><b>WARNING:</b> When the phone carrier company DO NOT have information available for a specific variable or score, the corresponding field will be filled with a null value.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PhoneCarrierPostResponse'
        '400':
          description: Response body - Bad Request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResponseErrorObject'
              example:
                errors:
                  - code: 400.6-x
                    message: A request body is required but none found.
                  - code: 400.6-x
                    message: Object has missing required properties (["customer","requestId","settings"])
                  - code: 400.6-x
                    message: Header parameter 'XXXX' is required on path '/phone/carrier-info' but not found in request.
                  - code: 400.6-x
                    message: '[Path ''XXXX''] Object has missing required properties (["XXXX"])'
                  - code: 400.6-x
                    message: '[Path ''XXXX''] Instance type (xxxx) does not match any allowed primitive type (allowed: ["XXXX"])'
                  - code: 400.6-x
                    message: '[Path ''/customer/termsAcceptedAt''] String "xxxxx" is invalid against requested date format(s) [yyyy-MM-dd''T''HH:mm:ssZ, yyyy-MM-dd''T''HH:mm:ss.[0-9]{1,12}Z]'
                  - code: '400.106'
                    message: None of the settings were selected. At least one must be true.
                  - code: '400.109'
                    message: Invalid Mexico state, must be a valid ISO 3166-2 value.
                  - code: '400.110'
                    message: Invalid phone number LADA code.
                  - code: '400.114'
                    message: The provided CURP or RFC is invalid. Unable to compute the birthdate.
                  - code: '400.115'
                    message: 'At least one of the following fields must be present: ''rfc'' or ''curp'' or ''birthdate''.'
        '401':
          description: Response body - Unauthorized.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResponseErrorObject'
              example:
                errors:
                  - code: '401.2'
                    message: Unauthorized, invalid x-api-key.
                  - code: '401.3'
                    message: Unauthorized, invalid x-signature value.
                  - code: '401.4'
                    message: Unauthorized, invalid username or password.
        '403':
          description: Response body - Forbiden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResponseErrorObject'
              example:
                errors:
                  - code: '403.2'
                    message: Forbiden, you don't have permissions to access this API product.
        '429':
          description: Response body - Too Many Requests
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResponseErrorObject'
              example:
                errors:
                  - code: '429.1'
                    message: Too Many Requests, you have exceeded the consumption threshold.
        '500':
          description: Response body - Internal Server Error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResponseErrorObject'
              example:
                errors:
                  - code: '500.100'
                    message: Unexpected error.
                  - code: '500.105'
                    message: Data provider not available at this time.
  /aggregations/{id}:
    get:
      tags:
        - Sandbox - Mobile Identity v2
      summary: Get the Aggregation associated with the specified id. [Synchronous Process]
      description: |2
         <!DOCTYPE html> <html> <head> <title>Page Title</title> </head> <body>
        <table border='1' cellpadding='1' cellspacing='1'> <caption>Sandbox Cases</caption>  <thead>  <tr>  <th scope='col'>Case</th> <th scope='col'>Description</th> <th scope='col'>Aggregation ID</th> </tr> </thead> <tbody> <!-- Sandbox Case 1 --> <tr> <th scope='col'>Case 1</th> <th scope='col'>Retrieve an aggregation already processed successfully from this API.</th> <th scope='col'>A valid aggregation id.</th> </tr> <!-- Sandbox Case 2 --> <tr>  <th scope='col'>Case 2</th> <th scope='col'>Access to this resource is restricted due to privacy or security policies.</th> <th scope='col'>019cfdf5-6f0f-703d-aa1b-bc1f9acfb33a</th> </tr> <!-- Sandbox Case 3 --> <tr>  <th scope='col'>Case 3</th> <th scope='col'>The requested resource is no longer available due to expiration policies. Resources older than 90 days cannot be retrieved.</th> <th scope='col'>019cfdf5-8759-7ae6-bb9d-4869e88341ce</th> </tr> <!-- Sandbox Case 4 --> <tr>  <th scope='col'>Case 4</th> <th scope='col'>Unexpected error.</th> <th scope='col'>019cfdf5-9791-7076-a163-0772a6f1d5ad</th> </tr> <!-- Sandbox Case 5 --> <tr>  <th scope='col'>Case 5</th> <th scope='col'>Database error.</th> <th scope='col'>019cfdf5-bac3-7653-af7e-2c38da3fd194</th> </tr> </tbody> </table>
        </body> </html>
      operationId: getPhoneNumberAggregation
      parameters:
        - name: id
          in: path
          description: The unique identifier of a telco aggregation. The id is provided in response to a successful  request to this API.
          required: true
          schema:
            type: string
            format: uuid
        - name: x-api-key
          in: header
          description: Your authentication API key. The Key is assigned through the Círculo de Crédito API-Hub Web site.<br>If you have any questions please contact your Círculo de Crédito sales agent.
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Response body
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AggregationPhoneNumberGetResponse'
        '400':
          description: Response body - Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResponseErrorObject'
              example:
                errors:
                  - code: 400.6-x
                    message: Header parameter 'XXXX' is required on path '/aggregations/{id}' but not found in request.
                  - code: 400.6-x
                    message: XXXX operation not allowed on path '/aggregations/'.
                  - code: 400.6-x
                    message: '[Path ''XXXX''] Instance type (xxxx) does not match any allowed primitive type (allowed: ["XXXX"])'
                  - code: '400.116'
                    message: Invalid 'id', must be a valid UUIDv7 value.
        '401':
          description: Response body - Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResponseErrorObject'
              example:
                errors:
                  - code: '401.2'
                    message: Unauthorized, invalid x-api-key.
                  - code: '401.3'
                    message: Unauthorized, invalid x-signature value.
                  - code: '401.4'
                    message: Unauthorized, invalid username or password.
        '403':
          description: Response body - Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResponseErrorObject'
              example:
                errors:
                  - code: '403.2'
                    message: Forbiden, you don't have permissions to access this API product.
                  - code: '403.101'
                    message: Access to this resource is restricted due to privacy or security policies.
        '404':
          description: Not Found. Meaning the requested aggregation was not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResponseErrorObject'
              example:
                errors:
                  - code: '404.102'
                    message: The requested telco aggregation was not found.
        '410':
          description: Response body - Gone. Meaning the requested aggregation telco existed but is not available any more.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResponseErrorObject'
              example:
                errors:
                  - code: '410.101'
                    message: The requested resource is no longer available due to expiration policies. Resources older than 90 days cannot be retrieved.
        '429':
          description: Response body - Too Many Requests
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResponseErrorObject'
              example:
                errors:
                  - code: '429.1'
                    message: Too Many Requests, you have exceeded the consumption threshold.
        '500':
          description: Response body - Internal Server Error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResponseErrorObject'
              example:
                errors:
                  - code: '500.100'
                    message: Unexpected error.
                  - code: '500.102'
                    message: Database error.
components:
  schemas:
    AggregationPhoneNumberGetResponse:
      type: object
      properties:
        id:
          type: string
          format: uuid
          description: 'The unique identifer of the Mobile Identity Aggregation. IMPORTANT: This is an UUID v7 value, note that UUID v7 are indexable values.'
        requestId:
          pattern: ^(?:\d+$|[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12})$
          type: string
          description: 'The client side identifier for the request, either a numeric string or an UUID.</p> IMPORTANT: This field is only intended as a reference for the client, so that clients can keep track of their own requests when receiving webhook notifications.'
          example: '2342'
        phoneNumber:
          type: string
          pattern: ^[0-9]{10}$
        status:
          type: string
          description: The possible 'status' values that the Telco Aggregation can have when it is queried.
          enum:
            - FINISHED
        dateTime:
          type: string
          description: The date-time when the Telco Aggregation was FINISHED.
          format: date-time
        errors:
          type: array
          description: If any, the errors ocurred during the telco aggregation process.
          items:
            type: string
            enum:
              - MOBILE_CARRIER_FAILED
        aggregation:
          $ref: '#/components/schemas/Aggregation'
    MobileCarrierSettings:
      required:
        - creditRisk
        - fraudRisk
        - lineQuality
        - usageLevel
        - simSwapLevel
        - technologyLevel
        - spendingTrend
        - contactNetworkLevel
        - callableLevel
        - planSize
        - planCreditLimit
        - planAutoPay
        - topUpLevel
        - topUpCadence
        - lineType
        - lineStatus
        - lineAge
      type: object
      properties:
        creditRisk:
          type: boolean
          nullable: false
          description: '[POSTPAID/PREPAID] Enables credit risk score.'
        fraudRisk:
          type: boolean
          nullable: false
          description: '[POSTPAID/PREPAID] Enables fraud risk score.'
        lineQuality:
          type: boolean
          nullable: false
          description: '[POSTPAID/PREPAID] Enables line quality variable.'
        usageLevel:
          type: boolean
          nullable: false
          description: '[POSTPAID/PREPAID] Enables SIM swap variable.'
        simSwapLevel:
          type: boolean
          nullable: false
          description: '[POSTPAID/PREPAID] Enables sim swap level variable.'
        technologyLevel:
          type: boolean
          nullable: false
          description: '[POSTPAID/PREPAID] Enables technology level variable.'
        spendingTrend:
          type: boolean
          nullable: false
          description: '[POSTPAID/PREPAID] Enables spending trend variable.'
        contactNetworkLevel:
          type: boolean
          nullable: false
          description: '[POSTPAID/PREPAID] Enables contacts network level variable.'
        callableLevel:
          type: boolean
          nullable: false
          description: '[POSTPAID/PREPAID] Enables callable level variable.'
        planSize:
          type: boolean
          nullable: false
          description: '[POSTPAID] Enables the planSize variable.'
        planCreditLimit:
          type: boolean
          nullable: false
          description: '[POSTPAID] Enables plan credit limit variable.'
        planAutoPay:
          type: boolean
          nullable: false
          description: '[POSTPAID] Enables plan auto pay variable.'
        topUpLevel:
          type: boolean
          nullable: false
          description: '[PREPAID] Enables top-up level variable.'
        topUpCadence:
          type: boolean
          description: '[PREPAID] Enables top-up cadence variable.'
        lineType:
          type: boolean
          nullable: false
          description: '[POSTPAID/PREPAID] Enables line type variable'
        lineStatus:
          type: boolean
          nullable: false
          description: '[POSTPAID/PREPAID] Enables line status variable.'
        lineAge:
          type: boolean
          nullable: false
          description: '[POSTPAID/PREPAID] Enables line age variable.'
    Aggregation:
      type: object
      properties:
        phone:
          $ref: '#/components/schemas/Phone'
        mobileCarrier:
          $ref: '#/components/schemas/MobileCarrier'
    MobileCarrier:
      type: object
      properties:
        creditRisk:
          type: integer
          example: 890
        fraudRisk:
          type: integer
          example: 750
        lineQuality:
          type: integer
          example: 2
        usageLevel:
          type: integer
          example: 7
        simSwapLevel:
          type: integer
          example: 2
        technologyLevel:
          type: integer
          example: 4
        spendingTrend:
          type: integer
          example: 9
        contactNetworkLevel:
          type: integer
          example: 10
        callableLevel:
          type: integer
          example: 3
        planSize:
          type: integer
          example: 3
        planCreditLimit:
          type: integer
          example: 2
        planAutoPay:
          type: boolean
          example: true
        topUpLevel:
          type: integer
          example: 6
        topUpCadence:
          type: integer
          example: 2
        lineType:
          type: integer
          example: 4
        lineStatus:
          type: integer
          example: 3
        lineAge:
          type: integer
          example: 5
    PhoneCarrierPostRequest:
      required:
        - requestId
        - customer
        - settings
      type: object
      properties:
        requestId:
          pattern: ^(?:\d+$|[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12})$
          type: string
          description: 'The client side identifier for the request, either a numeric string or an UUID.</p> IMPORTANT: This field is only intended as a reference for the client, so that clients can keep track of their own requests when receiving webhook notifications.'
          example: '235345'
        customer:
          $ref: '#/components/schemas/PhoneCarrierCustomer'
        settings:
          $ref: '#/components/schemas/PhoneCarrierSettings'
    PhoneCarrierCustomer:
      required:
        - phoneNumber
        - termsAcceptedAt
        - identity
        - address
      type: object
      properties:
        phoneNumber:
          pattern: ^[0-9]{10}$
          type: string
          maxLength: 10
          nullable: false
          description: The phone number that will be used for the phone-carrier process.
        termsAcceptedAt:
          type: string
          description: 'The date-time when the end user accepted the terms and conditions for the usage of their mobile phone number. IMPORTANT: MUST be a date-time in Zulu timezone with ISO 8601 format.'
          format: date-time
          nullable: false
        identity:
          $ref: '#/components/schemas/CustomerIdentityObject'
        address:
          $ref: '#/components/schemas/CustomerAddressObject'
    PhoneCarrierSettings:
      required:
        - mobileCarrier
      type: object
      properties:
        mobileCarrier:
          $ref: '#/components/schemas/MobileCarrierSettings'
    CustomerAddressObject:
      type: object
      required:
        - street
        - neighborhood
        - city
        - municipality
        - state
        - postalCode
      properties:
        street:
          type: string
          maxLength: 64
          pattern: ^[a-zA-ZñÑáéíóúÁÉÍÓÚ0-9\-.,\(\)\/ ]+$
          nullable: false
          example: Calle Constitución de 1917
        neighborhood:
          type: string
          maxLength: 64
          pattern: ^[a-zA-ZñÑáéíóúÁÉÍÓÚ0-9\-.,\(\)\/ ]+$
          nullable: false
          example: Colonia San Juan De la Garza
        city:
          type: string
          maxLength: 64
          pattern: ^[a-zA-ZñÑáéíóúÁÉÍÓÚ0-9\-.,\(\)\/ ]+$
          nullable: true
          example: Tlaltenango de Sánchez Román
        municipality:
          type: string
          maxLength: 64
          pattern: ^[a-zA-ZñÑáéíóúÁÉÍÓÚ0-9\-.,\(\)\/ ]+$
          nullable: false
          example: Santa Mónica Valley
        state:
          type: string
          nullable: false
          enum:
            - MX-AGU
            - MX-BCN
            - MX-BCS
            - MX-CAM
            - MX-CHP
            - MX-CHH
            - MX-CMX
            - MX-COA
            - MX-COL
            - MX-DUR
            - MX-GUA
            - MX-GRO
            - MX-HID
            - MX-JAL
            - MX-MIC
            - MX-MOR
            - MX-MEX
            - MX-NAY
            - MX-NLE
            - MX-OAX
            - MX-PUE
            - MX-QUE
            - MX-ROO
            - MX-SLP
            - MX-SIN
            - MX-SON
            - MX-TAB
            - MX-TAM
            - MX-TLA
            - MX-VER
            - MX-YUC
            - MX-ZAC
        postalCode:
          type: string
          maxLength: 5
          pattern: ^(0[1-9]\d{3}|[1-9]\d{4})$
          nullable: true
    CustomerIdentityObject:
      type: object
      required:
        - names
        - paternalSurname
        - maternalSurname
        - birthdate
        - rfc
        - curp
      properties:
        names:
          type: string
          maxLength: 64
          pattern: ^(?=.{2,64}$)(?:[A-Za-zñÑáéíóúÁÉÍÓÚ]+(?:\s+|$)){1,4}$
          nullable: false
          example: María Fernanda Sofía
        paternalSurname:
          type: string
          maxLength: 64
          pattern: ^(?=.{2,64}$)(?:[A-Za-zñÑáéíóúÁÉÍÓÚ]+(?:\s+|$)){1,4}$
          nullable: false
          example: Ruiz del Solar
        maternalSurname:
          type: string
          maxLength: 64
          pattern: ^(?=.{2,64}$)(?:[A-Za-zñÑáéíóúÁÉÍÓÚ]+(?:\s+|$)){1,4}$
          nullable: false
          example: Navarro
        birthdate:
          type: string
          maxLength: 10
          pattern: ^\d{4}-\d{2}-\d{2}$
          nullable: true
          example: '1997-11-24'
        rfc:
          type: string
          maxLength: 13
          pattern: ^[A-ZÑ]{4}\d{6}[A-ZñÑáéíóúÁÉÍÓÚ0-9]{3}$
          nullable: true
        curp:
          type: string
          maxLength: 18
          pattern: ^[A-Z]{1}[AEIOU]{1}[A-Z]{2}\d{2}(0[1-9]|1[0-2])(0[1-9]|[12][0-9]|3[01])[HM]{1}(AS|BC|BS|CC|CL|CM|CS|CH|DF|DG|GT|GR|HG|JC|MC|MN|MS|NT|NL|OC|PL|QT|QR|SP|SL|SR|TC|TS|TL|VZ|YN|ZS|NE)[B-DF-HJ-NP-TV-Z]{3}[A-Z\d]{1}\d{1}$
          nullable: true
    PhoneCarrierPostResponse:
      type: object
      properties:
        id:
          type: string
          format: uuid
          description: The unique identifer of the Telco Aggregation, allows to track the progress and final result of the aggregation.
        requestId:
          pattern: ^(?:\d+$|[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12})$
          type: string
          description: 'The client side identifier for the request, either a numeric string or an UUID.</p> IMPORTANT: This field is only intended as a reference for the client, so that clients can keep track of their own requests when receiving webhook notifications.'
          example: '2342'
        phoneNumber:
          type: string
          pattern: ^[0-9]{10}$
        status:
          type: string
          description: The possible 'status' values that the Telco Aggregation can have when it is queried.
          enum:
            - FINISHED
        dateTime:
          type: string
          description: The date-time when the Telco Aggregation was FINISHED or FAILED.
          format: date-time
        errors:
          type: array
          description: If any, the errors ocurred during the phone-carrier process.
          items:
            type: string
            enum:
              - MOBILE_CARRIER_FAILED
        aggregation:
          $ref: '#/components/schemas/AggregationPhoneCarrier'
    AggregationPhoneCarrier:
      type: object
      properties:
        phone:
          $ref: '#/components/schemas/Phone'
        mobileCarrier:
          $ref: '#/components/schemas/MobileCarrier'
    Phone:
      type: object
      properties:
        number:
          pattern: ^[0-9]{10}$
          type: string
          description: The phone number used for the Mobile Identity process.
        authenticity:
          type: string
          description: Indicates the validity of the phone number.
          enum:
            - VALID
            - INVALID
            - UNKNOWN
        type:
          type: string
          description: The type of phone number.
          enum:
            - MOBILE
            - LANDLINE
        carrier:
          type: string
          description: The phone carrier company to which the phone number belongs.
          example: TELCEL
    ResponseErrorObject:
      type: object
      properties:
        errors:
          type: array
          items:
            $ref: '#/components/schemas/ArrayErrorObject'
    ArrayErrorObject:
      type: object
      properties:
        code:
          type: string
        message:
          type: string
