Fuente: https://crm.begraffic.com/docs/api
Índice para agentes: [llms.txt](https://crm.begraffic.com/llms.txt)

# GET /api/v1/contacts/lookup

URL base: https://crm.begraffic.com. Autenticación: Authorization: Bearer <CLAVE_V1_bcrm_...>.

Definición OpenAPI de la operación (los bloques schema son esquemas, no cuerpos de ejemplo):

```json
{
  "operationId": "contacts.lookup",
  "summary": "Buscar candidatos por teléfono internacional",
  "description": "Coincidencias exactas en campos de teléfono estándar indexados, verificando país. No autentica al titular, no cubre números históricos con separadores arbitrarios ni habilita crear/mezclar automáticamente. ambiguous obliga a selección humana; si la consulta se trunca, 409 invalid_state con reason lookup_incomplete.",
  "tags": [
    "Contactos"
  ],
  "x-scope": "contacts:read",
  "security": [
    {
      "bearerAuth": []
    }
  ],
  "parameters": [
    {
      "name": "phone",
      "in": "query",
      "required": true,
      "description": "Teléfono internacional E.164 exacto. No comprueba identidad ni cubre formatos históricos arbitrarios.",
      "schema": {
        "type": "string",
        "pattern": "^\\+[1-9]\\d{7,14}$"
      }
    }
  ],
  "responses": {
    "200": {
      "description": "Correcto.",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "required": [
              "data"
            ],
            "properties": {
              "data": {
                "type": "object",
                "properties": {
                  "matches": {
                    "type": "array",
                    "items": {
                      "type": "object",
                      "properties": {
                        "id": {
                          "type": "string"
                        },
                        "name": {
                          "anyOf": [
                            {
                              "type": "string"
                            },
                            {
                              "type": "null"
                            }
                          ]
                        },
                        "secondName": {
                          "anyOf": [
                            {
                              "type": "string"
                            },
                            {
                              "type": "null"
                            }
                          ]
                        },
                        "lastname": {
                          "anyOf": [
                            {
                              "type": "string"
                            },
                            {
                              "type": "null"
                            }
                          ]
                        },
                        "secondLastname": {
                          "anyOf": [
                            {
                              "type": "string"
                            },
                            {
                              "type": "null"
                            }
                          ]
                        },
                        "email": {
                          "anyOf": [
                            {
                              "type": "string"
                            },
                            {
                              "type": "null"
                            }
                          ]
                        },
                        "phone": {
                          "anyOf": [
                            {
                              "type": "object",
                              "properties": {
                                "phone_code": {
                                  "anyOf": [
                                    {
                                      "type": "string"
                                    },
                                    {
                                      "type": "null"
                                    }
                                  ]
                                },
                                "phone": {
                                  "anyOf": [
                                    {
                                      "type": "string"
                                    },
                                    {
                                      "type": "null"
                                    }
                                  ]
                                }
                              },
                              "required": [
                                "phone_code",
                                "phone"
                              ]
                            },
                            {
                              "type": "null"
                            }
                          ]
                        },
                        "movil": {
                          "anyOf": [
                            {
                              "type": "object",
                              "properties": {
                                "movil_code": {
                                  "anyOf": [
                                    {
                                      "type": "string"
                                    },
                                    {
                                      "type": "null"
                                    }
                                  ]
                                },
                                "movil": {
                                  "anyOf": [
                                    {
                                      "type": "string"
                                    },
                                    {
                                      "type": "null"
                                    }
                                  ]
                                }
                              },
                              "required": [
                                "movil_code",
                                "movil"
                              ]
                            },
                            {
                              "type": "null"
                            }
                          ]
                        },
                        "address": {
                          "anyOf": [
                            {
                              "type": "object",
                              "properties": {
                                "address1": {
                                  "anyOf": [
                                    {
                                      "type": "string"
                                    },
                                    {
                                      "type": "null"
                                    }
                                  ]
                                },
                                "address2": {
                                  "anyOf": [
                                    {
                                      "type": "string"
                                    },
                                    {
                                      "type": "null"
                                    }
                                  ]
                                },
                                "city": {
                                  "anyOf": [
                                    {
                                      "type": "string"
                                    },
                                    {
                                      "type": "null"
                                    }
                                  ]
                                },
                                "state": {
                                  "anyOf": [
                                    {
                                      "type": "string"
                                    },
                                    {
                                      "type": "null"
                                    }
                                  ]
                                },
                                "country": {
                                  "anyOf": [
                                    {
                                      "type": "string"
                                    },
                                    {
                                      "type": "null"
                                    }
                                  ]
                                },
                                "zip": {
                                  "anyOf": [
                                    {
                                      "type": "string"
                                    },
                                    {
                                      "type": "null"
                                    }
                                  ]
                                }
                              },
                              "required": [
                                "address1",
                                "address2",
                                "city",
                                "state",
                                "country",
                                "zip"
                              ]
                            },
                            {
                              "type": "null"
                            }
                          ]
                        },
                        "gender": {
                          "anyOf": [
                            {
                              "type": "string"
                            },
                            {
                              "type": "null"
                            }
                          ]
                        },
                        "birthdate": {
                          "anyOf": [
                            {
                              "type": "string",
                              "format": "date"
                            },
                            {
                              "type": "null"
                            }
                          ]
                        },
                        "image": {
                          "anyOf": [
                            {
                              "type": "string"
                            },
                            {
                              "type": "null"
                            }
                          ]
                        },
                        "tags": {
                          "type": "array",
                          "items": {
                            "type": "string"
                          }
                        },
                        "groups": {
                          "type": "array",
                          "items": {
                            "type": "string"
                          }
                        },
                        "active": {
                          "type": "boolean"
                        },
                        "ownerEmail": {
                          "anyOf": [
                            {
                              "type": "string"
                            },
                            {
                              "type": "null"
                            }
                          ]
                        },
                        "organizationId": {
                          "anyOf": [
                            {
                              "type": "string"
                            },
                            {
                              "type": "null"
                            }
                          ]
                        },
                        "organizationName": {
                          "anyOf": [
                            {
                              "type": "string"
                            },
                            {
                              "type": "null"
                            }
                          ]
                        },
                        "source": {
                          "anyOf": [
                            {
                              "type": "string"
                            },
                            {
                              "type": "null"
                            }
                          ]
                        },
                        "sourceDetail": {
                          "anyOf": [
                            {
                              "type": "string"
                            },
                            {
                              "type": "null"
                            }
                          ]
                        },
                        "stage": {
                          "anyOf": [
                            {
                              "type": "string"
                            },
                            {
                              "type": "null"
                            }
                          ]
                        },
                        "externalRefs": {
                          "type": "object",
                          "propertyNames": {
                            "type": "string"
                          },
                          "additionalProperties": {
                            "type": "string"
                          },
                          "description": "`{app: id}`; vacío si no tiene."
                        },
                        "attribution": {
                          "anyOf": [
                            {
                              "type": "object",
                              "properties": {
                                "first": {
                                  "anyOf": [
                                    {
                                      "type": "object",
                                      "properties": {
                                        "utm_source": {
                                          "type": "string"
                                        },
                                        "utm_medium": {
                                          "type": "string"
                                        },
                                        "utm_campaign": {
                                          "type": "string"
                                        },
                                        "utm_term": {
                                          "type": "string"
                                        },
                                        "utm_content": {
                                          "type": "string"
                                        },
                                        "landingUrl": {
                                          "type": "string"
                                        },
                                        "referrer": {
                                          "type": "string"
                                        },
                                        "at": {
                                          "anyOf": [
                                            {
                                              "type": "string",
                                              "format": "date-time"
                                            },
                                            {
                                              "type": "null"
                                            }
                                          ]
                                        }
                                      },
                                      "required": [
                                        "at"
                                      ]
                                    },
                                    {
                                      "type": "null"
                                    }
                                  ]
                                },
                                "last": {
                                  "anyOf": [
                                    {
                                      "type": "object",
                                      "properties": {
                                        "utm_source": {
                                          "type": "string"
                                        },
                                        "utm_medium": {
                                          "type": "string"
                                        },
                                        "utm_campaign": {
                                          "type": "string"
                                        },
                                        "utm_term": {
                                          "type": "string"
                                        },
                                        "utm_content": {
                                          "type": "string"
                                        },
                                        "landingUrl": {
                                          "type": "string"
                                        },
                                        "referrer": {
                                          "type": "string"
                                        },
                                        "at": {
                                          "anyOf": [
                                            {
                                              "type": "string",
                                              "format": "date-time"
                                            },
                                            {
                                              "type": "null"
                                            }
                                          ]
                                        }
                                      },
                                      "required": [
                                        "at"
                                      ]
                                    },
                                    {
                                      "type": "null"
                                    }
                                  ]
                                }
                              },
                              "required": [
                                "first",
                                "last"
                              ]
                            },
                            {
                              "type": "null"
                            }
                          ],
                          "description": "Primer y último toque de atribución, o `null`."
                        },
                        "customFields": {
                          "type": "object",
                          "propertyNames": {
                            "type": "string"
                          },
                          "additionalProperties": {
                            "anyOf": [
                              {
                                "type": "string"
                              },
                              {
                                "type": "number"
                              },
                              {
                                "type": "boolean"
                              },
                              {
                                "type": "null"
                              }
                            ]
                          },
                          "description": "Campos personalizados del contacto por clave API."
                        },
                        "createdAt": {
                          "anyOf": [
                            {
                              "type": "string",
                              "format": "date-time"
                            },
                            {
                              "type": "null"
                            }
                          ]
                        },
                        "updatedAt": {
                          "anyOf": [
                            {
                              "type": "string",
                              "format": "date-time"
                            },
                            {
                              "type": "null"
                            }
                          ]
                        }
                      },
                      "required": [
                        "id",
                        "name",
                        "secondName",
                        "lastname",
                        "secondLastname",
                        "email",
                        "phone",
                        "movil",
                        "address",
                        "gender",
                        "birthdate",
                        "image",
                        "tags",
                        "groups",
                        "active",
                        "ownerEmail",
                        "organizationId",
                        "organizationName",
                        "source",
                        "sourceDetail",
                        "stage",
                        "externalRefs",
                        "attribution",
                        "customFields",
                        "createdAt",
                        "updatedAt"
                      ]
                    }
                  },
                  "ambiguous": {
                    "type": "boolean"
                  },
                  "coverage": {
                    "type": "string",
                    "const": "indexed_standard_fields"
                  }
                },
                "required": [
                  "matches",
                  "ambiguous",
                  "coverage"
                ]
              }
            }
          }
        }
      }
    },
    "400": {
      "description": "`invalid_request`: Petición inválida (cuerpo, parámetros o consulta).",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Error"
          }
        }
      }
    },
    "401": {
      "description": "`unauthorized`: Falta la clave, no existe, está revocada o caducó.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Error"
          }
        }
      }
    },
    "403": {
      "description": "`insufficient_scope`: La clave no tiene el alcance que exige la ruta.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Error"
          }
        }
      }
    },
    "409": {
      "description": "`invalid_state`: Operación no válida en el estado actual.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Error"
          }
        }
      }
    },
    "429": {
      "description": "`rate_limited`: Demasiadas llamadas (límite por clave y minuto). Ver `Retry-After`.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Error"
          }
        }
      }
    },
    "500": {
      "description": "`internal`: Error interno.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Error"
          }
        }
      }
    }
  }
}
```