swagger: '2.0' info: description:

API that validates the specified phone number and obtain the metadata associated with it.


version: 1.0.1 title: 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: /v1/telco tags: - name: Telco description: API for telco data aggregation. schemes: - https paths: /aggregations: post: tags: - 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. operationId: aggregatePhoneNumber consumes: - application/json produces: - application/json parameters: - in: header name: x-api-key type: string required: true description: Your authentication API key. The Key is assigned through the Círculo de Crédito API-Hub Web site.
If you have any questions please contact your Círculo de Crédito sales agent. - in: header name: username type: string required: true description: Your username from the Círculo de Crédito Grantor Web Portal.
If you have any questions please contact your Círculo de Crédito sales agent. - in: header name: password type: string required: true description: Your password from the Círculo de Crédito Grantor Web Portal.
If you have any questions please contact your Círculo de Crédito sales agent. - in: header name: x-signature type: string required: true 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.

NOTE: It is not necessary to canonicalize the request body, however, the request body that is sent to invoke the API must be exactly the same as the one used to generate the digital signature (x-signature).

IMPORTANT: Please refer to the Círculo de Crédito API-Hub site to learn the details and specifications for the process of generating the certificates and cryptographic keys necessary to consume this API. - 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.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: - 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 description: The unique identifier of an aggregation. The inquiryId is provided in response to a successful start aggregation request by this API. required: true - in: header name: x-api-key type: string required: true description: Your authentication API key. The Key is assigned through the Círculo de Crédito API-Hub Web site.
If you have any questions please contact your Círculo de Crédito sales agent. - in: header name: username type: string required: true description: Your username from the Círculo de Crédito Grantor Web Portal.
If you have any questions please contact your Círculo de Crédito sales agent. - in: header name: password type: string required: true description: Your password from the Círculo de Crédito Grantor Web Portal.
If you have any questions please contact your Círculo de Crédito sales agent. - in: header name: x-signature type: string required: true description: The digital signature of the inquiryId that you will send in the URL path to call this API. The siganture is created with your private key (SHA256withECDSA - secp384r) and the inquiryId from the URL.

NOTE: The requested inquiryId that is sent to invoke the API must be exactly the same as the one used to generate the digital signature (x-signature).

IMPORTANT: Please refer to the Círculo de Crédito API-Hub site to learn the details and specifications for the process of generating the certificates and cryptographic keys necessary to consume this API. 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.

IMPORTANT: This value MUST be an UUID v1. This ensures efficient system performance.

' subscriptionId: type: string format: uuid description: The unique identifier of a valid 'Círculo de Crédito' subscription.

This value allows the asynchronous reception of the results of this API, through an HTTP call to the webhook associated with the subscription.

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.

IMPORTANT: This name will appear in the whatsapp message sent to the final user.

NOTE: This field only works if the ''setting'' ''ownership'' is activated (true).

' 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.

Note: This URL correspond with the terms and conditions of the grantor, NOT the terms and conditions of ''Círculo de Credito''.' 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.

IMPORTANT: This value MUST be an UUID v1. This ensures efficient system performance.

' inquiryId: type: string format: uuid description: 'The unique identifer of the Telco Aggregation, allows to track the progress and final result of the aggregation.

IMPORTANT: This is NOT an UUID string, is an alphanumeric string with hyphen characters, with variable length from 37 characters up to 64 characters.

NOTE: This value is automatically generated by the API Telco ONLY when there is a successful aggregation request.

' 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.

IMPORTANT: This value MUST be an UUID v1. This ensures efficient system performance.

' inquiryId: type: string format: uuid description: 'The unique identifer of the Telco Aggregation, allows to track the progress and final result of the aggregation.

IMPORTANT: This is NOT an UUID string, is an alphanumeric string with hyphen characters, with variable length from 37 characters up to 64 characters.

NOTE: This value is automatically generated by the API Telco ONLY when there is a successful aggregation request.

' 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.

IMPORTANT: This name will appear in the whatsapp message sent to the final user.

NOTE: This field only works if the ''setting'' ''ownership'' is activated (true).

' 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.

IMPORTANT: If the final user/customer do not authorize the Telco Aggregation process the process will not be carried out and will be cancelled.

' 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