Endpoints de objetos de datos
Usa estos endpoints para listar tipos de objetos de datos, gestionar registros de objetos de datos y gestionar relaciones entre objetos y usuarios.

Los objetos de datos están disponibles de forma general, pero tu espacio de trabajo debe estar aprovisionado para Cuentas antes de que puedas usar estos endpoints. Para solicitar el aprovisionamiento, ve a Configuración de datos > Cuentas y completa el cuestionario. Una vez completado el aprovisionamiento, los permisos de clave de API de objetos de datos aparecen en Configuración > Claves de API. Para más detalles, consulta Habilitar Cuentas.
Endpoints de tipos
Endpoints de objetos
Endpoints de relaciones entre objetos
Endpoints de relaciones de usuarios
URL base y autenticación
Utiliza el endpoint REST de tu espacio de trabajo y envía Authorization: Bearer YOUR_REST_API_KEY. En esta sección se explica dónde se alojan los endpoints de objetos de datos y cómo se autentican las solicitudes.
- Para conocer los hosts de los endpoints, consulta Resumen de la API de Braze.
- Todas las cargas útiles de solicitud y respuesta están en formato JSON.
- Las solicitudes se limitan al espacio de trabajo propietario de la clave de API.
- Si la clave tiene una lista de IP permitidas, las direcciones IP que no estén en la lista devuelven
403.
Permisos de clave de API
Esta sección asigna a cada endpoint su permiso obligatorio para que puedas delimitar el alcance de las claves de API de forma segura.
| Permiso | Grupo de endpoints |
|---|---|
data_objects.read |
Lecturas de tipos y objetos, y lecturas de relaciones entre objetos |
data_objects.create |
Creación de objetos |
data_objects.update |
Reemplazo y actualización de objetos |
data_objects.delete |
Eliminación de objetos |
data_objects.user_relationships.read |
Lecturas de relaciones con usuarios |
data_objects.user_relationships.create |
Creación de relaciones con usuarios |
data_objects.user_relationships.update |
Reemplazo y actualización de relaciones con usuarios |
data_objects.user_relationships.delete |
Eliminación de relaciones con usuarios |
data_objects.object_relationships.create |
Creación de relaciones entre objetos |
data_objects.object_relationships.update |
Reemplazo y actualización de relaciones entre objetos |
data_objects.object_relationships.delete |
Eliminación de relaciones entre objetos |
data_objects.bulk_upsert |
Creación o reemplazo masivo de objetos |
data_objects.bulk_delete |
Eliminación masiva de objetos |
data_objects.object_relationships.bulk_upsert |
Creación o reemplazo masivo de relaciones entre objetos |
data_objects.object_relationships.bulk_delete |
Eliminación masiva de relaciones entre objetos |
data_objects.user_relationships.bulk_upsert |
Creación o reemplazo masivo de relaciones con usuarios |
data_objects.user_relationships.bulk_delete |
Eliminación masiva de relaciones con usuarios |

Las lecturas de relaciones entre objetos utilizan data_objects.read. No existe el permiso data_objects.object_relationships.read.
Los endpoints masivos utilizan sus propios permisos, y la inserción o actualización (upsert) y la eliminación son permisos independientes. Los permisos de registro único, como data_objects.create, no conceden acceso a los endpoints masivos.
Límites de velocidad
Esta sección explica las cuotas de solicitudes predeterminadas y los encabezados de respuesta para el tráfico de lectura y de escritura.
| Contenedor | Límite predeterminado |
|---|---|
| Lecturas de objetos de datos | 1000 solicitudes por minuto |
| Escrituras de objetos de datos | 1000 solicitudes por minuto |
| Escrituras masivas de objetos de datos | 1000 solicitudes por minuto, compartidas entre los seis endpoints masivos y con las sincronizaciones de objetos de datos de la ingesta de datos en la nube |
El límite de escritura masiva se aplica por espacio de trabajo y es independiente del límite de escritura de registro único.
Cada respuesta incluye X-RateLimit-Limit, X-RateLimit-Remaining y X-RateLimit-Reset.
Para las solicitudes limitadas, Braze devuelve 429 y una carga útil de error con id y message.
{
"errors": [
{
"id": "rate-limit-exceeded",
"message": "You have exceeded your limit of 1000 requests per minute."
}
]
}
Límites del producto
Esta sección enumera los límites que Braze aplica a los objetos de datos y qué esperar cuando alcanzas uno. Para saber cómo se aplican estos límites a los registros de cuentas, consulta Límites de los objetos de cuenta.
Límites de cantidad
Estos límites se aplican a tu empresa en su conjunto, salvo que se indique lo contrario. Son capacidades iniciales. Si necesitas más registros o un límite más alto, ponte en contacto con el equipo de tu cuenta de Braze para solicitar un aumento.
| Límite | Valor predeterminado |
|---|---|
| Registros de objetos de datos por empresa (en todos los espacios de trabajo) | 50 000 |
| Campos por tipo de objeto de datos | 500 |
| Objetos de datos vinculados a un usuario | 1000 |
| Usuarios vinculados a un objeto de datos | 10 000 |
| Relaciones entre objetos para un objeto de datos | 1000 |
Límites de campos y valores
Estos límites son fijos para todas las empresas.
| Límite | Valor |
|---|---|
| Campos por tipo de relación (relaciones con usuarios y relaciones entre objetos) | 25. Los campos de relación no cuentan para el límite de campos por tipo de objeto de datos. |
| Longitud del valor del atributo | 255 caracteres |
| Campos de fecha | Cadenas de fecha y hora RFC 3339 que incluyan una hora y una zona horaria, como 2026-11-03T00:00:00Z. Braze rechaza los valores que solo contienen la fecha, como 2026-11-03. Para más detalles, consulta Formato de los campos de fecha. |
Longitud y formato de object_id |
250 caracteres. Solo letras, números, guiones y guiones bajos. |
| Longitud y formato del nombre del campo | 250 caracteres. Solo letras, números y guiones bajos, y no puede empezar por un guion bajo. |
| Nombres de campo reservados | id, external_id, object_id y display_name no se pueden usar como nombres de campos personalizados. |
Formato de los campos de fecha
Los campos de fecha solo aceptan cadenas de fecha y hora RFC 3339 que incluyan tanto una hora como una zona horaria. Braze requiere el valor completo para no tener que adivinar nunca una hora o una zona horaria. Si tu origen almacena valores que solo contienen la fecha, como fechas de renovación o de contrato en tu almacén de datos, conviértelos antes de enviarlos, por ejemplo, en la transformación de tu almacén.
| Valor | Resultado |
|---|---|
2026-11-03T00:00:00Z |
Aceptado |
2026-11-03T00:00:00-05:00 |
Aceptado |
2026-11-03 |
Rechazado porque no tiene hora ni zona horaria |
2026-11-03T00:00:00 |
Rechazado porque no tiene zona horaria |
Este formato se aplica a los campos de fecha de los objetos de datos, las relaciones con usuarios y las relaciones entre objetos. La forma en que Braze informa de un valor rechazado depende de cómo lo envíes:
- Los endpoints de creación, reemplazo y actualización de un solo registro devuelven
400. Si hay más de un atributo no válido, el error solo nombra el primero. - Los endpoints de inserción y actualización masiva aceptan la solicitud con
202y luego registran un error de procesamientodata-object-schema-mismatchpara el registro, comoattributes: renewal_date is not valid for its field. - Las sincronizaciones de la ingesta de datos en la nube utilizan el mismo procesamiento que los endpoints masivos, por lo que Braze no aplica una fila con un valor que solo contiene la fecha, y el error aparece en los registros de sincronización.
Por ejemplo, una solicitud de un solo registro que envía 2026-11-03 para un campo de fecha renewal_date devuelve esta respuesta 400:
{
"error": "Validation failed: Attrs do not conform to field definitions: The property '#/renewal_date' must be a valid RFC3339 date/time string"
}
Qué ocurre cuando alcanzas un límite
Una solicitud que superaría un límite de cantidad devuelve 422 con un id de error que identifica el límite:
{
"errors": [
{
"id": "data-object-record-limit-exceeded",
"message": "This company has reached its data object record limit"
}
]
}
| Límite | id de error |
|---|---|
| Registros de objetos de datos por empresa | data-object-record-limit-exceeded |
| Campos por tipo de objeto de datos | data-object-field-limit-exceeded |
| Campos por tipo de relación | data-object-field-limit-exceeded |
| Objetos de datos vinculados a un usuario | data-objects-per-user-limit-exceeded |
| Usuarios vinculados a un objeto de datos | users-per-data-object-limit-exceeded |
| Relaciones entre objetos para un objeto de datos | data-object-relationship-limit-exceeded |
Tus registros y relaciones existentes se mantienen: solo se rechaza la solicitud que superaría el límite. Para liberar espacio bajo un límite, elimina los registros que ya no necesites o quita las relaciones que ya no uses. Para aumentar un límite de cantidad, ponte en contacto con el equipo de tu cuenta de Braze.
Las solicitudes que no superan la validación, como un object_id o un valor de atributo demasiado largo, devuelven 400. Las solicitudes que superan el límite de velocidad devuelven 429.
Conceptos básicos
Esta sección define los identificadores clave que se utilizan en todos los endpoints de objetos de datos.
type_name: El nombre de máquina del tipo de objeto de datos, único dentro de un espacio de trabajo.object_id: Tu identificador de objeto, único dentro de un tipo.user: El usuario en una solicitud de escritura de relación de usuario, identificado exactamente por uno de los siguientes:external_id,braze_id,alias,emailophone.attributes: Datos del objeto o de la relación, con claves por nombre de campo, validados con el esquema configurado.
Cómo funcionan las relaciones
En esta sección se explican los tipos de relación, los vínculos de relación y el comportamiento de anchor antes de que uses las páginas de referencia de los endpoints.
Resumen del modelo de relaciones
Usa este diagrama para ver cómo encajan los tipos, los registros y las relaciones, y qué te permite hacer en Braze vincularlos. Defines los tipos en el panel y, después, escribes los registros y los vínculos entre ellos mediante estos endpoints.
%%{init: {"flowchart": {"wrappingWidth": 400}} }%%
flowchart LR
subgraph define["Set up in the dashboard"]
objtype["Data object types define<br/>the fields a record has"]
reltype["Relationship types determine<br/>which links are allowed"]
end
subgraph write["Write with the API"]
person["A person you<br/>send messages to"]
record["A business record<br/>they belong to"]
related["Another record<br/>connected to it"]
person -- "A user relationship links<br/>a person to a record" --> record
record -- "An object relationship links<br/>one record to another" --> related
end
subgraph unlock["What it unlocks"]
segment["Segment people by the<br/>records they belong to"]
liquid["Personalize messages with<br/>data from those records"]
end
define -- "decides what you<br/>are allowed to link" --> write
write -- "makes these<br/>possible" --> unlock
Los tipos y los vínculos son independientes
- Los tipos de relación definen qué vínculos son válidos y se administran en el panel.
- Los vínculos de relación son los enlaces reales entre registros y se crean, actualizan y eliminan mediante estos endpoints de la API.
- Antes de escribir relaciones, enumera los valores válidos de
rel_kindcon:GET /data_objects/types/{type_name}/user_relationship_typesGET /data_objects/types/{type_name}/object_relationship_types
Por qué las relaciones entre objetos requieren related_type_name
rel_kindno es único de forma global en todos los pares de tipos de objeto. Por ejemplo,rel_kindpuede sersubaccountpara un par de tipos de objeto ypartner_accountpara otro.- Por eso, las escrituras de relaciones entre objetos requieren tanto
rel_kindcomorelated_type_namepara identificar el tipo de relación previsto junto con el otro tipo de objeto de la asociación. - Si
related_type_nameno coincide con el tipo de relación de eserel_kind, la solicitud devuelve400.
anchor controla la dirección de la relación
Las relaciones entre objetos son direccionales. El objeto de la URL se interpreta según anchor.
anchor |
Rol del objeto de la URL | Clave del objeto relacionado en las respuestas |
|---|---|---|
source (predeterminado) |
Lado de origen (vínculo saliente) | to_data_object |
target |
Lado de destino (vínculo entrante) | from_data_object |
Crear el mismo vínculo desde la perspectiva del anchor opuesto sigue apuntando a una única relación subyacente. Una segunda llamada de creación para el mismo vínculo devuelve 409 (duplicate-object-relationship).
Asimetría de rutas en las relaciones con usuarios
Las lecturas y escrituras de relaciones con usuarios usan intencionadamente rutas de endpoint distintas:
- Lectura:
GET /data_objects/objects/{type_name}/{object_id}/user_relationships - Escritura:
POST|PUT|PATCH|DELETE /data_objects/objects/{type_name}/{object_id}/users
Los atributos de relación son independientes de los atributos de objeto
- Los endpoints de relaciones devuelven los atributos a nivel de vínculo en el campo
attributesde nivel superior. - Los atributos de objeto permanecen anidados en
to_data_objectofrom_data_object. PUTreemplaza losattributesde la relación yPATCHfusiona losattributesde la relación.
Ejemplo práctico
Este ejemplo muestra un flujo de trabajo habitual con cuentas:
- Crea
account/acct-123. - Crea
account/acct-456como cuenta secundaria. - Vincula un usuario a
acct-123conrel_kind: account_user. - Vincula
acct-123aacct-456conrel_kind: subaccount.
Para volver a leer los vínculos:
GET /data_objects/objects/account/acct-123/user_relationshipspara los usuarios vinculadosGET /data_objects/objects/account/acct-123/object_relationshipspara los vínculos salientes entre objetosGET /data_objects/objects/account/acct-456/object_relationships?anchor=targetpara los vínculos entrantes entre objetos

Los endpoints DELETE para relaciones entre objetos y relaciones con usuarios requieren un cuerpo de solicitud JSON.
Endpoints masivos
Utiliza los endpoints masivos para sincronizar objetos de datos, relaciones entre objetos y relaciones de usuarios desde tus propios sistemas en lotes. Cada solicitud crea, reemplaza o elimina hasta 50 registros, y Braze procesa el lote en segundo plano.
| Método | Endpoint | Propósito |
|---|---|---|
PUT |
/data_objects/objects |
Crear o reemplazar hasta 50 objetos de datos, de cualquier combinación de tipos |
DELETE |
/data_objects/objects |
Eliminar hasta 50 objetos de datos, de cualquier combinación de tipos |
PUT |
/data_objects/object_relationships |
Crear o reemplazar hasta 50 relaciones entre objetos |
DELETE |
/data_objects/object_relationships |
Eliminar hasta 50 relaciones entre objetos |
PUT |
/data_objects/user_relationships |
Crear o reemplazar hasta 50 relaciones entre usuarios y objetos |
DELETE |
/data_objects/user_relationships |
Eliminar hasta 50 relaciones entre usuarios y objetos |
Cuándo utilizar los endpoints masivos
Utiliza los endpoints masivos cuando sincronices muchos registros desde tus propios sistemas y no necesites que cada cambio se aplique antes de que llegue la respuesta. Utiliza los endpoints de registro único cuando necesites que el cambio sea visible de inmediato, cuando necesites leer registros o cuando quieras actualizar solo algunos de los atributos de un registro con PATCH.
Los endpoints masivos se diferencian de los endpoints de registro único en lo siguiente:
- El procesamiento es asíncrono. Una respuesta
202significa que Braze aceptó el lote y lo puso en cola, no que haya aplicado los registros. Braze comprueba si existen los tipos, los tipos de relación, los objetos y los usuarios, y si los atributos coinciden con los campos del tipo, cuando procesa el lote. Una solicitud que devuelve202aún puede producir fallos en registros individuales más adelante. - La validación es de todo o nada. Si algún registro de una solicitud no supera la validación, Braze rechaza toda la solicitud con
400, no almacena nada y enumera todos los errores. - Los registros se ordenan por la hora de recepción. Braze marca cada registro con la hora en que recibió la solicitud, así que no envíes
updated_at. Cuando dos solicitudes cambian el mismo registro, prevalece la que Braze recibió más tarde. - Los registros pueden esperar a sus dependencias. La eliminación de un objeto o una relación que aún no existe, y una relación cuyo objeto o usuario aún no existe, quedan en espera en lugar de fallar de inmediato. Braze lo reintenta durante unas 40 horas (10 intentos). La creación o actualización de un objeto nunca queda en espera.
- Los endpoints masivos utilizan sus propios permisos de clave de API y comparten un límite de velocidad de 1000 solicitudes por minuto por espacio de trabajo.
- Los endpoints masivos nunca crean tipos de objetos de datos. Cada
type_namedebe existir previamente.
Los límites del producto se aplican a los endpoints masivos del mismo modo que a los endpoints de registro único.
Paginación y actualización de los datos
En esta sección se describe cómo funciona la paginación de las listas y cuánto tardan los datos en estar visibles después de las escrituras.
- Los endpoints de listado admiten
limityoffset. limittiene un valor predeterminado de100y se limita a un rango de1a250.offsettiene un valor predeterminado de0, y los valores negativos se redondean a0.- Las escrituras de un solo registro son visibles de inmediato para las lecturas y la personalización con Liquid. Las escrituras masivas se aplican cuando Braze procesa el lote en cola.
- La pertenencia a un Segment basada en objetos de datos puede tener un retraso de hasta una hora, porque los filtros calculados se actualizan cada hora.
Comportamiento de errores
Esta sección resume los patrones de estado y de respuesta de error que utilizan los endpoints de objetos de datos.
404,409,422y429devuelven una matrizerrorsconidymessage.400,401y403devuelven una única cadenaerror.- Los endpoints masivos devuelven los errores
400y500como una matrizerrorsconidymessage. Un error400también incluye elparameterque causa el fallo, cuando existe, y, para los errores a nivel de registro, elindexdel registro. 422significa que la solicitud superaría un límite del producto. Los valores de límite predeterminados varían según el contrato de cada empresa.