swagger: '2.0'
info:
  description: >-
    <p
    style='margin:0cm;font-size:16px;font-family:"Calibri",sans-serif;vertical-align:top;'>Sandbox
    API for the API Telco TLV.<br/><br/><img
    src='https://developer.circulodecredito.com.mx/sites/default/files/2020-10/circulo_de_credito-apihub.png'
    width='240' /><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/>
  version: 1.0.0
  title: Sandbox - Telco TLV (Telephone Line Verification)
  termsOfService: https://developer.circulodecredito.com.mx/legal-mx
  contact:
    email: api@circulodecredito.com.mx
  license:
    name: Derechos Reservados Círculo de Crédito 2024
    url: https://services.circulodecredito.com.mx
host: services.circulodecredito.com.mx
basePath: /sandbox/v1/telco
tags:
  - name: Sandbox Telco
    description: API for telco data aggregation.
schemes:
  - https
paths:
  /aggregations:
    post:
      tags:
        - Sandbox Telco
      summary: >-
        Start the aggregation process to validate the specified phone number and
        retrieve the data associated with it.
      description: >-
        Request a new Telco Aggregation. Note that this operation only start a
        new aggregation and do NOT return the final result, the final result is
        delivery through the webhook HTTP notification and additionally can be
        fetched using the endpoint '/aggregations/{inquiryId}' of this API.
        <table border='1' cellpadding='1' cellspacing='1'> <caption>Sandbox
        Cases</caption> <thead> <tr> <th scope='col'>Sandbox Case Number</th>
        <th scope='col'>Sandbox Case Description</th> <th scope='col'>Sandbox
        Values</th> <th scope='col'>JSON Request Example</th> </tr> </thead>
        <tbody> <tr> <td >1</td> <td >The final user/customer phone number
        is&nbsp;VALID with phone carrier TELCEL, phone type MOBILE. The
        ownership and socialNetoworks are not requested.</td> <td>
        <p>phoneNumber: 5500000001</p> <p>ownership: false</p>
        <p>socialNetworks: false</p> </td> <td> {&quot;requestId&quot;:
        &quot;c020d499-11fb-1b8a-a36b-00b0d063b220&quot;,&quot;subscriptionId&quot;:
        &quot;87d4e983-8498-439c-a9b1-c91dceac8cab&quot;,&quot;companyName&quot;:
        &quot;Company Demo&quot;,&quot;customer&quot;: {&quot;phoneNumber&quot;:
        &quot;5500000001&quot;,&quot;name&quot;:
        &quot;Juan Pruebas&quot;,&quot;authorization&quot;:
        true,&quot;authorizationDateTime&quot;:
        &quot;2023-08-09T17:40:28.372Z&quot;},&quot;settings&quot;:
        {&quot;ownership&quot;: false,&quot;socialNetworks&quot;:
        false,&quot;statistics&quot;: false}} </td> </tr> <tr> <td >2</td> <td
        >The final user/customer phone number is&nbsp;VALID with phone carrier
        AT&amp;T, phone type MOBILE. The ownership and socialNetoworks are not
        requested.</td> <td> <p>phoneNumber: 5500000002</p> <p>ownership:
        false</p> <p>socialNetworks: false</p> </td> <td>
        {&quot;requestId&quot;:
        &quot;c020d499-11fb-1b8a-a36b-00b0d063b220&quot;,&quot;subscriptionId&quot;:
        &quot;87d4e983-8498-439c-a9b1-c91dceac8cab&quot;,&quot;companyName&quot;:
        &quot;Company Demo&quot;,&quot;customer&quot;: {&quot;phoneNumber&quot;:
        &quot;5500000002&quot;,&quot;name&quot;:
        &quot;Juan Pruebas&quot;,&quot;authorization&quot;:
        true,&quot;authorizationDateTime&quot;:
        &quot;2023-08-09T17:40:28.372Z&quot;},&quot;settings&quot;:
        {&quot;ownership&quot;: false,&quot;socialNetworks&quot;:
        false,&quot;statistics&quot;: false}} </td> </tr> <tr> <td >3</td> <td
        >The final user/customer phone number is&nbsp;VALID with phone carrier
        TOTAL PLAY, phone type LANDLINE. The ownership and socialNetoworks are
        not requested.</td> <td> <p>phoneNumber: 5500000003</p> <p>ownership:
        false</p> <p>socialNetworks: false</p> </td> <td>
        {&quot;requestId&quot;:
        &quot;c020d499-11fb-1b8a-a36b-00b0d063b220&quot;,&quot;subscriptionId&quot;:
        &quot;87d4e983-8498-439c-a9b1-c91dceac8cab&quot;,&quot;companyName&quot;:
        &quot;Company Demo&quot;,&quot;customer&quot;: {&quot;phoneNumber&quot;:
        &quot;5500000003&quot;,&quot;name&quot;:
        &quot;Juan Pruebas&quot;,&quot;authorization&quot;:
        true,&quot;authorizationDateTime&quot;:
        &quot;2023-08-09T17:40:28.372Z&quot;},&quot;settings&quot;:
        {&quot;ownership&quot;: false,&quot;socialNetworks&quot;:
        false,&quot;statistics&quot;: false}} </td> </tr> <tr> <td >4</td> <td
        >The final user/customer phone number is INVALID.&nbsp;The ownership and
        socialNetoworks are not requested.</td> <td> <p>phoneNumber:
        5500000004</p> <p>ownership: false</p> <p>socialNetworks: false</p>
        </td> <td> {&quot;requestId&quot;:
        &quot;c020d499-11fb-1b8a-a36b-00b0d063b220&quot;,&quot;subscriptionId&quot;:
        &quot;87d4e983-8498-439c-a9b1-c91dceac8cab&quot;,&quot;companyName&quot;:
        &quot;Company Demo&quot;,&quot;customer&quot;: {&quot;phoneNumber&quot;:
        &quot;5500000004&quot;,&quot;name&quot;:
        &quot;Juan Pruebas&quot;,&quot;authorization&quot;:
        true,&quot;authorizationDateTime&quot;:
        &quot;2023-08-09T17:40:28.372Z&quot;},&quot;settings&quot;:
        {&quot;ownership&quot;: false,&quot;socialNetworks&quot;:
        false,&quot;statistics&quot;: false}} </td> </tr> <tr> <td >5</td> <td >
        <p>The final user/customer phone number is&nbsp;VALID with phone carrier
        TELCEL, phone type MOBILE. The ownership is requested and
        socialNetoworks is not.</p> <p>The simulation message response of the
        final user/customer confirms the ownership of the phone number.</p>
        </td> <td> <p>phoneNumber: 5500000001</p> <p>ownership: true</p>
        <p>socialNetworks: false</p> </td> <td> {&quot;requestId&quot;:
        &quot;c020d499-11fb-1b8a-a36b-00b0d063b220&quot;,&quot;subscriptionId&quot;:
        &quot;87d4e983-8498-439c-a9b1-c91dceac8cab&quot;,&quot;companyName&quot;:
        &quot;Company Demo&quot;,&quot;termsConditionsUrl&quot;:
        &quot;https://www.test.com/terms-conditions&quot;,&quot;customer&quot;:
        {&quot;phoneNumber&quot;: &quot;5500000001&quot;,&quot;name&quot;:
        &quot;Juan Pruebas&quot;,&quot;authorization&quot;:
        true,&quot;authorizationDateTime&quot;:
        &quot;2023-08-09T17:40:28.372Z&quot;},&quot;settings&quot;:
        {&quot;ownership&quot;: true,&quot;socialNetworks&quot;:
        false,&quot;statistics&quot;: false}} </td> </tr> <tr> <td >6</td> <td >
        <p>The final user/customer phone number is&nbsp;VALID with phone carrier
        AT&amp;T, phone type MOBILE. The ownership is requested and
        socialNetoworks is not.</p> <p>The simulation message response of the
        final user/customer denies the ownership of the phone number.</p> </td>
        <td> <p>phoneNumber: 5500000002</p> <p>ownership: true</p>
        <p>socialNetworks: false</p> </td> <td> {&quot;requestId&quot;:
        &quot;c020d499-11fb-1b8a-a36b-00b0d063b220&quot;,&quot;subscriptionId&quot;:
        &quot;87d4e983-8498-439c-a9b1-c91dceac8cab&quot;,&quot;companyName&quot;:
        &quot;Company Demo&quot;,&quot;termsConditionsUrl&quot;:
        &quot;https://www.test.com/terms-conditions&quot;,&quot;customer&quot;:
        {&quot;phoneNumber&quot;: &quot;5500000002&quot;,&quot;name&quot;:
        &quot;Juan Pruebas&quot;,&quot;authorization&quot;:
        true,&quot;authorizationDateTime&quot;:
        &quot;2023-08-09T17:40:28.372Z&quot;},&quot;settings&quot;:
        {&quot;ownership&quot;: true,&quot;socialNetworks&quot;:
        false,&quot;statistics&quot;: false}} </td> </tr> <tr> <td >7</td> <td >
        <p>The final user/customer phone number is&nbsp;VALID with phone carrier
        TOTAL PLAY, phone type LANDLINE. The ownership is requested and
        socialNetoworks is not.</p> <p>The message ownership process of the
        aggregation cannot be done since is a LANDLINE phone number. The
        ownership status will be marked as FAILED.</p> </td> <td>
        <p>phoneNumber: 5500000003</p> <p>ownership: true</p> <p>socialNetworks:
        false</p> </td> <td> {&quot;requestId&quot;:
        &quot;c020d499-11fb-1b8a-a36b-00b0d063b220&quot;,&quot;subscriptionId&quot;:
        &quot;87d4e983-8498-439c-a9b1-c91dceac8cab&quot;,&quot;companyName&quot;:
        &quot;Company Demo&quot;,&quot;termsConditionsUrl&quot;:
        &quot;https://www.test.com/terms-conditions&quot;,&quot;customer&quot;:
        {&quot;phoneNumber&quot;: &quot;5500000003&quot;,&quot;name&quot;:
        &quot;Juan Pruebas&quot;,&quot;authorization&quot;:
        true,&quot;authorizationDateTime&quot;:
        &quot;2023-08-09T17:40:28.372Z&quot;},&quot;settings&quot;:
        {&quot;ownership&quot;: true,&quot;socialNetworks&quot;:
        false,&quot;statistics&quot;: false}} </td> </tr> <tr> <td >8</td> <td
        >The final user/customer phone number is INVALID. The ownership is
        requested and socialNetoworks is not.</td> <td> <p>phoneNumber:
        5500000004</p> <p>ownership: true</p> <p>socialNetworks: false</p> </td>
        <td> {&quot;requestId&quot;:
        &quot;c020d499-11fb-1b8a-a36b-00b0d063b220&quot;,&quot;subscriptionId&quot;:
        &quot;87d4e983-8498-439c-a9b1-c91dceac8cab&quot;,&quot;companyName&quot;:
        &quot;Company Demo&quot;,&quot;termsConditionsUrl&quot;:
        &quot;https://www.test.com/terms-conditions&quot;,&quot;customer&quot;:
        {&quot;phoneNumber&quot;: &quot;5500000004&quot;,&quot;name&quot;:
        &quot;Juan Pruebas&quot;,&quot;authorization&quot;:
        true,&quot;authorizationDateTime&quot;:
        &quot;2023-08-09T17:40:28.372Z&quot;},&quot;settings&quot;:
        {&quot;ownership&quot;: true,&quot;socialNetworks&quot;:
        false,&quot;statistics&quot;: false}} </td> </tr> <tr> <td >9</td> <td >
        <p>The final user/customer phone number is&nbsp;VALID with phone carrier
        TELCEL, phone type MOBILE. The ownership is not requested and
        socialNetoworks is.</p> <p>The simulation result of the socialNetworks
        is true for all&nbsp;social-networks.</p> </td> <td> <p>phoneNumber:
        5500000001</p> <p>ownership: false</p> <p>socialNetworks: true</p> </td>
        <td> {&quot;requestId&quot;:
        &quot;c020d499-11fb-1b8a-a36b-00b0d063b220&quot;,&quot;subscriptionId&quot;:
        &quot;87d4e983-8498-439c-a9b1-c91dceac8cab&quot;,&quot;companyName&quot;:
        &quot;Company Demo&quot;,&quot;customer&quot;: {&quot;phoneNumber&quot;:
        &quot;5500000001&quot;,&quot;name&quot;:
        &quot;Juan Pruebas&quot;,&quot;authorization&quot;:
        true,&quot;authorizationDateTime&quot;:
        &quot;2023-08-09T17:40:28.372Z&quot;},&quot;settings&quot;:
        {&quot;ownership&quot;: false,&quot;socialNetworks&quot;:
        true,&quot;statistics&quot;: false}} </td> </tr> <tr> <td >10</td> <td >
        <p>The final user/customer phone number is&nbsp;VALID with phone carrier
        AT&amp;T, phone type MOBILE. The ownership is not requested and
        socialNetoworks is.</p> <p>The simulation result of the socialNetworks
        is true for all&nbsp;social-networks.</p> </td> <td> <p>phoneNumber:
        5500000002</p> <p>ownership: false</p> <p>socialNetworks: true</p> </td>
        <td> {&quot;requestId&quot;:
        &quot;c020d499-11fb-1b8a-a36b-00b0d063b220&quot;,&quot;subscriptionId&quot;:
        &quot;87d4e983-8498-439c-a9b1-c91dceac8cab&quot;,&quot;companyName&quot;:
        &quot;Company Demo&quot;,&quot;customer&quot;: {&quot;phoneNumber&quot;:
        &quot;5500000002&quot;,&quot;name&quot;:
        &quot;Juan Pruebas&quot;,&quot;authorization&quot;:
        true,&quot;authorizationDateTime&quot;:
        &quot;2023-08-09T17:40:28.372Z&quot;},&quot;settings&quot;:
        {&quot;ownership&quot;: false,&quot;socialNetworks&quot;:
        true,&quot;statistics&quot;: false}} </td> </tr> <tr> <td >11</td> <td >
        <p>The final user/customer phone number is&nbsp;VALID with phone carrier
        TOTAL PLAY, phone type LANDLINE. The ownership is not requested and
        socialNetoworks is.</p> <p>The socialNetwork&nbsp;process of the
        aggregation cannot be done since is a LANDLINE phone number. No data
        will be returned for the socialNetworks.</p> </td> <td> <p>phoneNumber:
        5500000003</p> <p>ownership: false</p> <p>socialNetworks: true</p> </td>
        <td> {&quot;requestId&quot;:
        &quot;c020d499-11fb-1b8a-a36b-00b0d063b220&quot;,&quot;subscriptionId&quot;:
        &quot;87d4e983-8498-439c-a9b1-c91dceac8cab&quot;,&quot;companyName&quot;:
        &quot;Company Demo&quot;,&quot;customer&quot;: {&quot;phoneNumber&quot;:
        &quot;5500000003&quot;,&quot;name&quot;:
        &quot;Juan Pruebas&quot;,&quot;authorization&quot;:
        true,&quot;authorizationDateTime&quot;:
        &quot;2023-08-09T17:40:28.372Z&quot;},&quot;settings&quot;:
        {&quot;ownership&quot;: false,&quot;socialNetworks&quot;:
        true,&quot;statistics&quot;: false}} </td> </tr> <tr> <td >12</td> <td
        >The final user/customer phone number is INVALID. The ownership is not
        requested and socialNetoworks is.</td> <td> <p>phoneNumber:
        5500000004</p> <p>ownership: false</p> <p>socialNetworks: true</p> </td>
        <td> {&quot;requestId&quot;:
        &quot;c020d499-11fb-1b8a-a36b-00b0d063b220&quot;,&quot;subscriptionId&quot;:
        &quot;87d4e983-8498-439c-a9b1-c91dceac8cab&quot;,&quot;companyName&quot;:
        &quot;Company Demo&quot;,&quot;customer&quot;: {&quot;phoneNumber&quot;:
        &quot;5500000004&quot;,&quot;name&quot;:
        &quot;Juan Pruebas&quot;,&quot;authorization&quot;:
        true,&quot;authorizationDateTime&quot;:
        &quot;2023-08-09T17:40:28.372Z&quot;},&quot;settings&quot;:
        {&quot;ownership&quot;: false,&quot;socialNetworks&quot;:
        true,&quot;statistics&quot;: false}} </td> </tr> <tr> <td >13</td> <td >
        <p>The final user/customer phone number is&nbsp;VALID with phone carrier
        TELCEL, phone type MOBILE. The ownership&nbsp;and socialNetoworks are
        requested.</p> <p>The simulation message response of the final
        user/customer confirms the ownership of the phone number.</p> <p>The
        simulation result of the socialNetworks is true for
        all&nbsp;social-networks.</p> </td> <td> <p>phoneNumber: 5500000001</p>
        <p>ownership: true</p> <p>socialNetworks: true</p> </td> <td>
        {&quot;requestId&quot;:
        &quot;c020d499-11fb-1b8a-a36b-00b0d063b220&quot;,&quot;subscriptionId&quot;:
        &quot;87d4e983-8498-439c-a9b1-c91dceac8cab&quot;,&quot;companyName&quot;:
        &quot;Company Demo&quot;,&quot;termsConditionsUrl&quot;:
        &quot;https://www.test.com/terms-conditions&quot;,&quot;customer&quot;:
        {&quot;phoneNumber&quot;: &quot;5500000001&quot;,&quot;name&quot;:
        &quot;Juan Pruebas&quot;,&quot;authorization&quot;:
        true,&quot;authorizationDateTime&quot;:
        &quot;2023-08-09T17:40:28.372Z&quot;},&quot;settings&quot;:
        {&quot;ownership&quot;: true,&quot;socialNetworks&quot;:
        true,&quot;statistics&quot;: false}} </td> </tr> <tr> <td >14</td> <td >
        <p>The final user/customer phone number is&nbsp;VALID with phone carrier
        AT&amp;T, phone type MOBILE. The ownership&nbsp;and socialNetoworks are
        requested.</p> <p>The simulation message response of the final
        user/customer denies the ownership of the phone number.</p> <p>The
        simulation result of the socialNetworks is true for
        all&nbsp;social-networks.</p> </td> <td> <p>phoneNumber: 5500000002</p>
        <p>ownership: true</p> <p>socialNetworks: true</p> </td> <td>
        {&quot;requestId&quot;:
        &quot;c020d499-11fb-1b8a-a36b-00b0d063b220&quot;,&quot;subscriptionId&quot;:
        &quot;87d4e983-8498-439c-a9b1-c91dceac8cab&quot;,&quot;companyName&quot;:
        &quot;Company Demo&quot;,&quot;termsConditionsUrl&quot;:
        &quot;https://www.test.com/terms-conditions&quot;,&quot;customer&quot;:
        {&quot;phoneNumber&quot;: &quot;5500000002&quot;,&quot;name&quot;:
        &quot;Juan Pruebas&quot;,&quot;authorization&quot;:
        true,&quot;authorizationDateTime&quot;:
        &quot;2023-08-09T17:40:28.372Z&quot;},&quot;settings&quot;:
        {&quot;ownership&quot;: true,&quot;socialNetworks&quot;:
        true,&quot;statistics&quot;: false}} </td> </tr> <tr> <td >15</td> <td >
        <p>The final user/customer phone number is&nbsp;VALID with phone carrier
        TOTAL PLAY, phone type LANDLINE. The ownership&nbsp;and socialNetoworks
        are requested.</p> <p>The message ownership process of the aggregation
        cannot be done since is a LANDLINE phone number. The ownership status
        will be marked as FAILED.</p> <p>The socialNetwork&nbsp;process of the
        aggregation cannot be done since is a LANDLINE phone number. No data
        will be returned for the socialNetworks.</p> </td> <td> <p>phoneNumber:
        5500000003</p> <p>ownership: true</p> <p>socialNetworks: true</p> </td>
        <td> {&quot;requestId&quot;:
        &quot;c020d499-11fb-1b8a-a36b-00b0d063b220&quot;,&quot;subscriptionId&quot;:
        &quot;87d4e983-8498-439c-a9b1-c91dceac8cab&quot;,&quot;companyName&quot;:
        &quot;Company Demo&quot;,&quot;termsConditionsUrl&quot;:
        &quot;https://www.test.com/terms-conditions&quot;,&quot;customer&quot;:
        {&quot;phoneNumber&quot;: &quot;5500000003&quot;,&quot;name&quot;:
        &quot;Juan Pruebas&quot;,&quot;authorization&quot;:
        true,&quot;authorizationDateTime&quot;:
        &quot;2023-08-09T17:40:28.372Z&quot;},&quot;settings&quot;:
        {&quot;ownership&quot;: true,&quot;socialNetworks&quot;:
        true,&quot;statistics&quot;: false}} </td> </tr> <tr> <td >16</td> <td
        >The final user/customer phone number is INVALID. The ownership and
        socialNetoworks are requested.</td> <td> <p>phoneNumber: 5500000004</p>
        <p>ownership: true</p> <p>socialNetworks: true</p> </td> <td>
        {&quot;requestId&quot;:
        &quot;c020d499-11fb-1b8a-a36b-00b0d063b220&quot;,&quot;subscriptionId&quot;:
        &quot;87d4e983-8498-439c-a9b1-c91dceac8cab&quot;,&quot;companyName&quot;:
        &quot;Company Demo&quot;,&quot;termsConditionsUrl&quot;:
        &quot;https://www.test.com/terms-conditions&quot;,&quot;customer&quot;:
        {&quot;phoneNumber&quot;: &quot;5500000004&quot;,&quot;name&quot;:
        &quot;Juan Pruebas&quot;,&quot;authorization&quot;:
        true,&quot;authorizationDateTime&quot;:
        &quot;2023-08-09T17:40:28.372Z&quot;},&quot;settings&quot;:
        {&quot;ownership&quot;: true,&quot;socialNetworks&quot;:
        true,&quot;statistics&quot;: false}} </td> </tr> </tbody> </table> 
      operationId: aggregatePhoneNumber
      consumes:
        - application/json
      produces:
        - application/json
      parameters:
        - in: header
          name: x-api-key
          type: string
          required: true
          description: >-
            Your developer API Key, this can be obtained from the Círculo de
            Crédito developers web portal.
        - in: body
          name: body
          description: Telco Aggregation request object.
          required: true
          schema:
            $ref: '#/definitions/PhoneNumberPostRequest'
      responses:
        '200':
          headers:
            x-signature:
              type: string
              description: >-
                Signature of the response body (payload), the signature is
                created by the Telco API with the Círculo de Crédito private
                key. You must verify the signature against the received response
                body (paylod) using the Círculo de Crédito public certificate
                downloaded from the Círculo de Crédito developers web portal.
          schema:
            $ref: '#/definitions/PhoneNumberPostResponse'
          description: Telco Aggregation response object.
        '400':
          headers:
            x-signature:
              type: string
              description: >-
                Signature of the response body (payload), the signature is
                created by the Telco API with the Círculo de Crédito private
                key. You must verify the signature against the received response
                body (paylod) using the Círculo de Crédito public certificate
                downloaded from the Círculo de Crédito developers web portal.
          schema:
            $ref: '#/definitions/ResponseErrorObject'
          description: Telco Aggregation Bad Request Error Response.
          examples:
            application/json:
              errors:
                - code: '400.1'
                  message: A request body is required but none found.
                - code: '400.1'
                  message: >-
                    Header parameter 'XXXXXXX' is required on path
                    '/aggregations' but not found in request.
                - code: '400.1'
                  message: 'Missing required property: XXXXXX'
                - code: '400.101'
                  message: >-
                    Invalid HTTP request body, missing or empty field 'xxxxx'.
                    The field 'xxxxx' is required when the 'ownership' setting
                    is activated (true).
                - code: '400.103'
                  message: >-
                    The provided subscription has an invalid event type. Event
                    type expected: 'mx.com.circulodecredito.telcos' but the
                    subscription xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx has an
                    event type of: 'mx.com.circulodecredito.xxxx'
        '401':
          headers:
            x-signature:
              type: string
              description: >-
                Signature of the response body (payload), the signature is
                created by the Telco API with the Círculo de Crédito private
                key. You must verify the signature against the received response
                body (paylod) using the Círculo de Crédito public certificate
                downloaded from the Círculo de Crédito developers web portal.
          schema:
            $ref: '#/definitions/ResponseErrorObject'
          description: Telco Aggregation Unauthorized Error Response.
          examples:
            application/json:
              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':
          headers:
            x-signature:
              type: string
              description: >-
                Signature of the response body (payload), the signature is
                created by the Telco API with the Círculo de Crédito private
                key. You must verify the signature against the received response
                body (paylod) using the Círculo de Crédito public certificate
                downloaded from the Círculo de Crédito developers web portal.
          schema:
            $ref: '#/definitions/ResponseErrorObject'
          description: Telco Aggregation Not Found Error Response.
          examples:
            application/json:
              errors:
                - code: '404.100'
                  message: >-
                    The provided subscription xxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
                    was not found.
        '500':
          headers:
            x-signature:
              type: string
              description: >-
                Signature of the response body (payload), the signature is
                created by the Telco API with the Círculo de Crédito private
                key. You must verify the signature against the received response
                body (paylod) using the Círculo de Crédito public certificate
                downloaded from the Círculo de Crédito developers web portal.
          schema:
            $ref: '#/definitions/ResponseErrorObject'
          description: Telco Aggregation Internal Server Error Response.
          examples:
            application/json:
              errors:
                - code: '500.100'
                  message: >-
                    Unexpected system error. Try again later or contact
                    technical support.
  /aggregations/{inquiryId}:
    get:
      tags:
        - Sandbox Telco
      summary: Get the Telco Aggregation associated with the specified inquiryId.
      description: >-
        Fetch the specified Telco Aggregation by inquiryId and return the
        result. This operation could return a partial result if the aggregation
        is not been completed yet or the final result if the aggregation process
        has been finished.
      operationId: getPhoneNumberAggregation
      consumes:
        - application/json
      produces:
        - application/json
      parameters:
        - in: path
          name: inquiryId
          type: string
          required: true
        - in: header
          name: x-api-key
          type: string
          required: true
          description: >-
            Your developer API Key, this can be obtained from the Círculo de
            Crédito developers web portal.
      responses:
        '200':
          headers:
            x-signature:
              type: string
              description: >-
                Signature of the response body (payload), the signature is
                created by the Telco API with the Círculo de Crédito private
                key. You must verify the signature against the received response
                body (paylod) using the Círculo de Crédito public certificate
                downloaded from the Círculo de Crédito developers web portal.
          schema:
            $ref: '#/definitions/AggregationPhoneNumberGetResponse'
          description: Telco Aggregation Response Data.
        '400':
          headers:
            x-signature:
              type: string
              description: >-
                Signature of the response body (payload), the signature is
                created by the Telco API with the Círculo de Crédito private
                key. You must verify the signature against the received response
                body (paylod) using the Círculo de Crédito public certificate
                downloaded from the Círculo de Crédito developers web portal.
          schema:
            $ref: '#/definitions/ResponseErrorObject'
          description: Telco Aggregation Bad Request Error Response.
          examples:
            application/json:
              errors:
                - code: '400.1'
                  message: >-
                    Header parameter 'XXXXXXX' is required on path
                    '/aggregations/{inquiryId}' but not found in request.
                - code: '400.1'
                  message: GET operation not allowed on path '/aggregations/'.
        '401':
          headers:
            x-signature:
              type: string
              description: >-
                Signature of the response body (payload), the signature is
                created by the Telco API with the Círculo de Crédito private
                key. You must verify the signature against the received response
                body (paylod) using the Círculo de Crédito public certificate
                downloaded from the Círculo de Crédito developers web portal.
          schema:
            $ref: '#/definitions/ResponseErrorObject'
          description: Telco Aggregation Unauthorized Error Response.
          examples:
            application/json:
              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':
          headers:
            x-signature:
              type: string
              description: >-
                Signature of the response body (payload), the signature is
                created by the Telco API with the Círculo de Crédito private
                key. You must verify the signature against the received response
                body (paylod) using the Círculo de Crédito public certificate
                downloaded from the Círculo de Crédito developers web portal.
          schema:
            $ref: '#/definitions/ResponseErrorObject'
          description: Telco Aggregation Not Found Error Response.
          examples:
            application/json:
              errors:
                - code: '404.101'
                  message: No request associated with the provided inquiryId was found.
                - code: '404.102'
                  message: No aggregation was found with the provided inquiryId.
        '500':
          headers:
            x-signature:
              type: string
              description: >-
                Signature of the response body (payload), the signature is
                created by the Telco API with the Círculo de Crédito private
                key. You must verify the signature against the received response
                body (paylod) using the Círculo de Crédito public certificate
                downloaded from the Círculo de Crédito developers web portal.
          schema:
            $ref: '#/definitions/ResponseErrorObject'
          description: Telco Aggregation Internal Server Error Response.
          examples:
            application/json:
              errors:
                - code: '500.100'
                  message: >-
                    Unexpected system error. Try again later or contact
                    technical support.
definitions:
  PhoneNumberPostRequest:
    type: object
    properties:
      requestId:
        type: string
        format: uuid
        description: >-
          The unique identifier of the request, this value is provided by the
          client consuming the API. <p>IMPORTANT: This value MUST be an UUID v1.
          This ensures efficient system performance.</p>
      subscriptionId:
        type: string
        format: uuid
        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>
      companyName:
        type: string
        pattern: >-
          ^[a-zA-ZñÑáéíóúÁÉÍÓÚ]+(([ ][a-zA-ZñÑáéíóúÁÉÍÓÚ
          ])?[a-zA-ZñÑáéíóúÁÉÍÓÚ]*)*$
        example: Pruebas Corportation
        description: >-
          The name of the 'business/company' that is trying to validate the
          phone number via 'whatsapp' message. <p>IMPORTANT: This name will
          appear in the whatsapp message sent to the final user.</p> <p>NOTE:
          This field only works if the 'setting' 'ownership' is activated
          (true).</p>
      termsConditionsUrl:
        type: string
        description: >-
          The company terms and conditions URL. This URL is shown in the
          whatsapp validation message that is send to the end-user.<br><br>NOTE:
          This URL correspond with the terms and conditions of the grantor, NOT
          the terms and conditions of 'Círculo de Credito'.<br><br>NOTE: This
          field only works if the 'setting' 'ownership' is activated (true).
        maxLength: 512
        pattern: >-
          ^(https?:\/\/(?:www\.|(?!www))[a-zA-Z0-9][a-zA-Z0-9-]+[a-zA-Z0-9]\.[^\s]{2,}|www\.[a-zA-Z0-9][a-zA-Z0-9-]+[a-zA-Z0-9]\.[^\s]{2,}|https?:\/\/(?:www\.|(?!www))[a-zA-Z0-9]+\.[^\s]{2,}|www\.[a-zA-Z0-9]+\.[^\s]{2,})$
        example: https://www.acme.com/terms-conditions
      customer:
        $ref: '#/definitions/Customer'
      settings:
        $ref: '#/definitions/AggregationSettings'
  PhoneNumberPostResponse:
    type: object
    properties:
      requestId:
        type: string
        format: uuid
        description: >-
          The unique identifier of the request, this value is provided by the
          client consuming the API. <p>IMPORTANT: This value MUST be an UUID v1.
          This ensures efficient system performance.</p>
      inquiryId:
        type: string
        format: uuid
        description: >-
          The unique identifer of the Telco Aggregation, allows to track the
          progress and final result of the aggregation. <p>IMPORTANT: This is
          NOT an UUID string, is an alphanumeric string with hyphen characters,
          with variable length from 37 characters up to 64 characters.</p>
          <p>NOTE: This value is automatically generated by the API Telco ONLY
          when there is a successful aggregation request.</p>
      dateTime:
        type: string
        format: date-time
        description: >-
          The date-time when the Telco Aggregation was STARTED, NOT_AUTHORIZED
          or FAILED.
      status:
        type: string
        enum:
          - STARTED
          - NOT_AUTHORIZED
          - FAILED
        description: >-
          The possible 'status' values that the Telco Aggregation can have when
          it is requested.
  AggregationPhoneNumberGetResponse:
    type: object
    properties:
      requestId:
        type: string
        format: uuid
        description: >-
          The unique identifier of the request, this value is provided by the
          client consuming the API. <p>IMPORTANT: This value MUST be an UUID v1.
          This ensures efficient system performance.</p>
      inquiryId:
        type: string
        format: uuid
        description: >-
          The unique identifer of the Telco Aggregation, allows to track the
          progress and final result of the aggregation. <p>IMPORTANT: This is
          NOT an UUID string, is an alphanumeric string with hyphen characters,
          with variable length from 37 characters up to 64 characters.</p>
          <p>NOTE: This value is automatically generated by the API Telco ONLY
          when there is a successful aggregation request.</p>
      status:
        type: string
        enum:
          - FINISHED
          - IN_PROGRESS
          - FAILED
          - NOT_AUTHORIZED
        description: >-
          The possible 'status' values that the Telco Aggregation can have when
          it is queried.
      dateTime:
        type: string
        format: date-time
        description: >-
          The date-time when the Telco Aggregation was FINISHED, IN_PROGRESS,
          NOT_AUTHORIZED or FAILED.
      aggregation:
        $ref: '#/definitions/Aggregation'
  Customer:
    type: object
    properties:
      phoneNumber:
        type: string
        pattern: ^[0-9]{10}$
        description: The phone number that will be used for the Telco Aggregation process.
      name:
        type: string
        pattern: >-
          ^[a-zA-ZñÑáéíóúÁÉÍÓÚ]+(([ ][a-zA-ZñÑáéíóúÁÉÍÓÚ
          ])?[a-zA-ZñÑáéíóúÁÉÍÓÚ]*)*$
        example: Juan Pruebas
        description: >-
          The name of the final user/customer which phone number will be
          validated via 'whatsapp' message. <p>IMPORTANT: This name will appear
          in the whatsapp message sent to the final user.</p> <p>NOTE: This
          field only works if the 'setting' 'ownership' is activated (true).</p>
      authorization:
        type: boolean
        description: >-
          A boolean flag to indicate the authorization of the final
          user/customer to do the Telco Aggregation process with their phone
          number. True if the final user/customer authorize the Telco
          Aggregation process, false otherwise.<p>IMPORTANT: If the final
          user/customer do not authorize the Telco Aggregation process the
          process will not be carried out and will be cancelled.</p>
      authorizationDateTime:
        type: string
        format: date-time
        description: >-
          The date-time when the final user/customer authorized the Telco
          Aggregation process on their own phone number.
  AggregationSettings:
    type: object
    description: >-
      Settings available in the API Telco, allows you to choose the behavior
      that the API will have.
    properties:
      ownership:
        type: boolean
        description: Activates the phone message validation via 'whatsapp' message.
      socialNetworks:
        type: boolean
        description: >-
          Activates the validation of social networks associated with the phone
          number.
      statistics:
        type: boolean
        description: Reserved for future use. Not working right now.
  Aggregation:
    type: object
    properties:
      phone:
        $ref: '#/definitions/Phone'
      socialNetworks:
        $ref: '#/definitions/SocialNetworks'
  Phone:
    type: object
    properties:
      number:
        type: string
        pattern: ^[0-9]{10}$
        description: The phone number used for the Telco Aggregation process.
      carrier:
        type: string
        example: TELCEL
        description: The phone carrier of the phone number.
      city:
        type: string
        example: CUAUHTEMOC
        description: The city associated with phone number.
      type:
        type: string
        enum:
          - MOBILE
          - LANDLINE
        description: The type of phone number.
      authenticity:
        type: string
        enum:
          - VALID
          - INVALID
          - UNKNOWN
        description: Indicates the validity of the telephone number.
      ownership:
        type: string
        enum:
          - WAITING_CONFIRMATION
          - NOT_REQUESTED
          - OWNERSHIP_CONFIRMED
          - OWNERSHIP_DENIED
          - NOT_CONFIRMED
          - FAILED
        description: >-
          Indicates the current 'status' of the 'ownership' process (i.e. the
          whatsapp message validation) in the Telco Aggregation.
  SocialNetworks:
    type: object
    description: >-
      Indicates the social networks associated with the provided phone number.
      True if the social network is associated with phone number, false
      otherwise
    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
  ResponseErrorObject:
    type: object
    properties:
      errors:
        type: array
        items:
          $ref: '#/definitions/ArrayErrorObject'
  ArrayErrorObject:
    type: object
    properties:
      code:
        type: string
      message:
        type: string
