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

# POST /api/v1/contacts

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.create",
  "summary": "Crear un contacto",
  "description": "409 `conflict` (con `details.id`) si ya existe un contacto con ese correo: para crear o actualizar, `POST /api/v1/contacts/upsert`.",
  "tags": [
    "Contactos"
  ],
  "x-scope": "contacts:write",
  "security": [
    {
      "bearerAuth": []
    }
  ],
  "parameters": [
    {
      "name": "Idempotency-Key",
      "in": "header",
      "required": false,
      "description": "Clave única por operación (≤ 255 caracteres). Repetir la misma petición devuelve la misma respuesta durante 24 h; con otro cuerpo, 422.",
      "schema": {
        "type": "string",
        "maxLength": 255
      }
    }
  ],
  "responses": {
    "201": {
      "description": "Correcto.",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "required": [
              "data"
            ],
            "properties": {
              "data": {
                "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"
                      }
                    ]
                  },
                  "stage": {
                    "anyOf": [
                      {
                        "type": "string"
                      },
                      {
                        "type": "null"
                      }
                    ]
                  },
                  "createdAt": {
                    "anyOf": [
                      {
                        "type": "string",
                        "format": "date-time"
                      },
                      {
                        "type": "null"
                      }
                    ]
                  },
                  "updatedAt": {
                    "anyOf": [
                      {
                        "type": "string",
                        "format": "date-time"
                      },
                      {
                        "type": "null"
                      }
                    ]
                  },
                  "noteCreatedId": {
                    "type": "string"
                  }
                },
                "required": [
                  "id",
                  "name",
                  "secondName",
                  "lastname",
                  "secondLastname",
                  "email",
                  "phone",
                  "movil",
                  "address",
                  "gender",
                  "birthdate",
                  "image",
                  "tags",
                  "groups",
                  "active",
                  "ownerEmail",
                  "organizationId",
                  "organizationName",
                  "source",
                  "stage",
                  "createdAt",
                  "updatedAt"
                ]
              }
            }
          }
        }
      }
    },
    "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"
          }
        }
      }
    },
    "402": {
      "description": "`contact_limit_exceeded`: Límite de contactos del plan superado: el workspace está bloqueado hasta subir de plan o de tramo (reintentar no lo arregla).",
      "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": "`conflict`: Conflicto con el estado actual (p. ej. ya existe). `idempotency_in_progress`: Otra petición con la misma Idempotency-Key se está procesando.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Error"
          }
        }
      }
    },
    "422": {
      "description": "`idempotency_key_reused`: La Idempotency-Key ya se usó con otra petición.",
      "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"
          }
        }
      }
    }
  },
  "requestBody": {
    "required": true,
    "content": {
      "application/json": {
        "schema": {
          "type": "object",
          "properties": {
            "email": {
              "type": "string",
              "format": "email"
            },
            "name": {
              "type": "string",
              "maxLength": 200
            },
            "secondName": {
              "type": "string",
              "maxLength": 200
            },
            "lastname": {
              "type": "string",
              "maxLength": 200
            },
            "secondLastname": {
              "type": "string",
              "maxLength": 200
            },
            "phone": {
              "anyOf": [
                {
                  "type": "object",
                  "properties": {
                    "phone_code": {
                      "type": "string",
                      "maxLength": 8,
                      "description": "Prefijo del país, p. ej. `+57`."
                    },
                    "phone": {
                      "type": "string",
                      "maxLength": 40
                    }
                  },
                  "required": [
                    "phone_code",
                    "phone"
                  ],
                  "additionalProperties": false
                },
                {
                  "type": "null"
                }
              ]
            },
            "movil": {
              "anyOf": [
                {
                  "type": "object",
                  "properties": {
                    "movil_code": {
                      "type": "string",
                      "maxLength": 8,
                      "description": "Prefijo del país, p. ej. `+57`."
                    },
                    "movil": {
                      "type": "string",
                      "maxLength": 40
                    }
                  },
                  "required": [
                    "movil_code",
                    "movil"
                  ],
                  "additionalProperties": false
                },
                {
                  "type": "null"
                }
              ]
            },
            "address": {
              "anyOf": [
                {
                  "type": "object",
                  "properties": {
                    "address1": {
                      "type": "string",
                      "maxLength": 200
                    },
                    "address2": {
                      "type": "string",
                      "maxLength": 200
                    },
                    "city": {
                      "type": "string",
                      "maxLength": 200
                    },
                    "state": {
                      "type": "string",
                      "maxLength": 200
                    },
                    "country": {
                      "type": "string",
                      "maxLength": 200
                    },
                    "zip": {
                      "type": "string",
                      "maxLength": 20
                    }
                  },
                  "additionalProperties": false
                },
                {
                  "type": "null"
                }
              ]
            },
            "gender": {
              "anyOf": [
                {
                  "type": "string",
                  "enum": [
                    "Masculino",
                    "Femenino"
                  ]
                },
                {
                  "type": "null"
                }
              ]
            },
            "birthdate": {
              "description": "`AAAA-MM-DD`; `null` la borra.",
              "anyOf": [
                {
                  "type": "string",
                  "format": "date"
                },
                {
                  "type": "null"
                }
              ]
            },
            "image": {
              "type": "string",
              "maxLength": 2000
            },
            "tags": {
              "description": "Se COMBINAN con las que ya tenga.",
              "maxItems": 100,
              "type": "array",
              "items": {
                "type": "string",
                "maxLength": 100
              }
            },
            "groups": {
              "description": "Ids de listas; se combinan con las que ya tenga.",
              "maxItems": 100,
              "type": "array",
              "items": {
                "type": "string",
                "minLength": 1,
                "maxLength": 200,
                "pattern": "^[^/]+$"
              }
            },
            "organizationId": {
              "description": "`null` desasigna la organización.",
              "anyOf": [
                {
                  "type": "string",
                  "minLength": 1,
                  "maxLength": 200,
                  "pattern": "^[^/]+$"
                },
                {
                  "type": "null"
                }
              ]
            },
            "organizationName": {
              "type": "string",
              "maxLength": 200
            },
            "active": {
              "type": "boolean"
            },
            "note": {
              "description": "Nota que se añade al contacto.",
              "type": "object",
              "properties": {
                "title": {
                  "type": "string",
                  "minLength": 1,
                  "maxLength": 200
                },
                "content": {
                  "type": "string",
                  "maxLength": 20000
                },
                "type": {
                  "type": "string",
                  "enum": [
                    "note",
                    "reminder"
                  ]
                },
                "dueDate": {
                  "anyOf": [
                    {
                      "type": "string",
                      "format": "date"
                    },
                    {
                      "type": "string",
                      "format": "date-time"
                    }
                  ]
                },
                "reminderAt": {
                  "anyOf": [
                    {
                      "type": "string",
                      "format": "date"
                    },
                    {
                      "type": "string",
                      "format": "date-time"
                    }
                  ]
                },
                "tags": {
                  "maxItems": 100,
                  "type": "array",
                  "items": {
                    "type": "string",
                    "maxLength": 100
                  }
                }
              },
              "required": [
                "title"
              ],
              "additionalProperties": false
            }
          },
          "additionalProperties": false,
          "description": "Al menos `email`, `phone` o `movil`."
        }
      }
    }
  }
}
```