openapi: 3.0.0
info:
  title: Mobile Identity API v1
  description: <p style='margin:0cm;font-size:16px;font-family:"Calibri",sans-serif;vertical-align:top;'>API that validates phone numbers and retrieve the social networks associated with mobile phone numbers.<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.6.0
servers:
  - url: https://services.circulodecredito.com.mx/v1/telco
tags:
  - name: Mobile Identity v1
    description: Phone verification aggregation.
paths:
  /aggregations:
    post:
      tags:
        - Mobile Identity v1
      summary: Start the aggregation process to validate the specified phone number and/or retrieve the social networks associated with it. [Asynchronous Process]
      description: "<b>WARNING:</b> This endpoint initiates the validation process. Results are sent asynchronously to your HTTP webhook as soon as they are ready."
      operationId: aggregatePhoneNumber
      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
        - name: username
          in: header
          description: Your username from the Círculo de Crédito Lender Web Portal. <br>If you have any questions please contact your Círculo de Crédito sales agent.
          required: true
          schema:
            type: string
        - name: password
          in: header
          description: Your password from the Círculo de Crédito Lender Web Portal. <br>If you have any questions please contact your Círculo de Crédito sales agent.
          required: true
          schema:
            type: string
        - name: x-signature
          in: header
          description: The digital signature of the full HTTP Request Body (payload) that you send to call this API. The siganture is created with your private key (SHA256withECDSA - secp384r) and the request body.<br><br><b>NOTE:</b> It is not necessary to canonicalize the request body, however, the request body that is sent when invoking the API must be exactly the same as the one used to generate the digital signature (x-signature).<br><br> <b>IMPORTANT:</b> Please refer to the <a href="https://developer.circulodecredito.com.mx/guia_de_inicio">Círculo de Crédito API-Hub</a> site to learn the details and specifications for the process of generating the certificates and cryptographic keys necessary to consume this API.
          required: true
          schema:
            type: string
      requestBody:
        description: Telco Aggregation request object.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PhoneNumberPostRequest'
        required: true
      responses:
        '200':
          description: Telco Aggregation response object.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PhoneNumberPostResponse'
        '400':
          description: Bad Request Response.
          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","subscriptionId"])
                  - code: 400.6-x
                    message: Object has missing required properties (["xxxxx"])
                  - code: 400.6-x
                    message: '[Path ''XXXXX''] Instance type (xxxx) does not match any allowed primitive type (allowed: ["xxxx"])'
                  - code: 400.6-x
                    message: '[Path ''/customer/authorizationDateTime''] 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.6-x
                    message: Header parameter 'x-api-key' is required on path '/aggregations' but not found in request.
                  - code: '400.7'
                    message: 'The field ''termsAcceptedAt'' is not present or is null.'
                  - code: '400.105'
                    message: Invalid subscription type, must be of type 'mx.com.circulodecredito.telcos'.
                  - code: '400.106'
                    message: None of the settings were selected. At least one must be true.
                  - code: '400.110'
                    message: Invalid phone number LADA code.
        '401':
          description: Telco Aggregation Unauthorized Error Response.
          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.
        '404':
          description: Not Found Response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResponseErrorObject'
              example:
                errors:
                  - code: '404.101'
                    message: Subscription 'XXXXXXXX' not found.
        '429':
          description: 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: Internal Server Error Response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResponseErrorObject'
              example:
                errors:
                  - code: '500.100'
                    message: Unexpected error.
                  - code: '500.101'
                    message: Subscription error.
                  - code: '500.102'
                    message: Database error.
                  - code: '500.103'
                    message: Orchestrator error.
  /aggregations/{id}:
    get:
      tags:
        - Mobile Identity v1
      summary: Get the Telco Aggregation associated with the specified id. [Synchronous Process]
      description: "Access an existing and completed aggregation."
      operationId: getPhoneNumberAggregation
      parameters:
        - name: id
          in: path
          description: The unique identifier of an aggregation. The id is provided in response to a successful start aggregation request by 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
        - name: username
          in: header
          description: Your username from the Círculo de Crédito Lender Web Portal. <br>If you have any questions please contact your Círculo de Crédito sales agent.
          required: true
          schema:
            type: string
        - name: password
          in: header
          description: Your password from the Círculo de Crédito Lender Web Portal. <br>If you have any questions please contact your Círculo de Crédito sales agent.
          required: true
          schema:
            type: string
        - name: x-signature
          in: header
          description: The digital signature of the <b>id</b> that you will send in the URL path to call this API. The siganture is created with your private key (SHA256withECDSA - secp384r) and the id from the URL.<br><br><b>NOTE:</b> The requested id that is sent to invoke the API must be exactly the same as the one used to generate the digital signature (x-signature).<br><br> <b>IMPORTANT:</b> Please refer to the <a href="https://developer.circulodecredito.com.mx/guia_de_inicio">Círculo de Crédito API-Hub</a> site to learn the details and specifications for the process of generating the certificates and cryptographic keys necessary to consume this API.
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Telco Aggregation Response Data.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AggregationPhoneNumberGetResponse'
        '400':
          description: Bad Request Response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResponseErrorObject'
              example:
                errors:
                  - code: 400.6-x
                    message: GET operation not allowed on path '/aggregations/'.
                  - code: 400.6-x
                    message: 'Instance type (string) does not match any allowed primitive type (allowed: ["integer"])'
                  - code: 400.6-x
                    message: Header parameter 'x-api-key' is required on path '/aggregations/{id}' but not found in request.
        '401':
          description: Unauthorized. Meaning some or all of the authorization credentials are invalid.
          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: Forbidden. Meaning you don't have permissions to view the requested resource.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResponseErrorObject'
              example:
                errors:
                  - code: '403.101'
                    message: Access to this resource is restricted due to privacy or security policies.
        '404':
          description: Not Found Response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResponseErrorObject'
              example:
                errors:
                  - code: '404.102'
                    message: The requested telco aggregation was not found.
        '410':
          description: 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 X days cannot be retrieved.
        '429':
          description: 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: Internal Server Error Response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResponseErrorObject'
              example:
                errors:
                  - code: '500.100'
                    message: Unexpected error.
                  - code: '500.102'
                    message: Database error.
components:
  schemas:
    PhoneNumberPostRequest:
      required:
        - requestId
        - subscriptionId
        - 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'
        subscriptionId:
          type: string
          description: The unique identifier of a valid 'Círculo de Crédito' subscription. <p>This value allows the asynchronous reception of the results of this API, through an HTTP call to the webhook associated with the subscription.</p>
          format: uuid
        customer:
          $ref: '#/components/schemas/Customer'
        settings:
          $ref: '#/components/schemas/AggregationSettings'
    PhoneNumberPostResponse:
      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}$
          description: The same subscriptionId used in the request body.
        status:
          type: string
          description: The possible 'status' values that the Telco Aggregation can have when it is requested.
          enum:
            - STARTED
        dateTime:
          type: string
          description: The date-time when the Telco Aggregation was STARTED.
          format: date-time
    AggregationPhoneNumberGetResponse:
      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'
        subscriptionId:
          type: string
          format: uuid
        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
            - FAILED
        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 telco aggregation process.
          items:
            type: string
            enum:
              - PHONE_VALIDATION_FAILED
              - SOCIAL_NETWORKS_FAILED
        aggregation:
          $ref: '#/components/schemas/Aggregation'
    Customer:
      required:
        - phoneNumber
      type: object
      properties:
        phoneNumber:
          pattern: ^[0-9]{10}$
          type: string
          description: The phone number that will be used for the Telco Aggregation process.
        termsAcceptedAt:
          type: string
          description: 'The date-time when the end user accepted the terms and conditions for the usage of their phone number. IMPORTANT: MUST be a date-time in Zulu timezone with ISO 8601 format. '
          format: date-time
    AggregationSettings:
      required:
        - phone
        - socialNetworks
      type: object
      properties:
        phone:
          type: boolean
          description: Enable the phone validation.
        socialNetworks:
          type: boolean
          description: Enable the validation of social networks associated with the phone number.
      description: Settings available in the API Telco, allows you to choose the behavior that the API will have.
    Aggregation:
      type: object
      properties:
        phone:
          $ref: '#/components/schemas/Phone'
        socialNetworks:
          $ref: '#/components/schemas/SocialNetworks'
    Phone:
      type: object
      properties:
        number:
          pattern: ^[0-9]{10}$
          type: string
          description: The phone number used for the Telco Aggregation process.
        authenticity:
          type: string
          description: Indicates the validity of the telephone number.
          enum:
            - VALID
            - INVALID
            - UNKNOWN
        type:
          type: string
          description: The type of phone number.
          enum:
            - MOBILE
            - LANDLINE
        carrier:
          type: string
          description: The phone carrier of the phone number.
          example: TELCEL
        city:
          type: string
          description: The city associated with phone number.
          example: null
        state:
          type: string
          description: The state associated with the phone number, also the state to which the city of the phone number belongs.
          example: null
    SocialNetworks:
      type: object
      properties:
        whatsapp:
          type: boolean
        facebook:
          type: boolean
        instagram:
          type: boolean
        google:
          type: boolean
        twitter:
          type: boolean
        microsoft:
          type: boolean
        yahoo:
          type: boolean
        skype:
          type: boolean
        snapchat:
          type: boolean
        telegram:
          type: boolean
      description: Indicates the social networks associated with the provided phone number. True if the social network is associated with phone number, false otherwise
    ResponseErrorObject:
      type: object
      properties:
        errors:
          type: array
          items:
            $ref: '#/components/schemas/ArrayErrorObject'
    ArrayErrorObject:
      type: object
      properties:
        code:
          type: string
        message:
          type: string
x-original-swagger-version: '2.0'
