Audiencia

Propiedades del contacto

Campos personalizados de los contactos, con tipo y valor predeterminado.

Las propiedades son los campos personalizados de los contactos, como plan, ciudad o fecha de nacimiento. Define la clave y el tipo una sola vez; después, usa la clave en properties al crear o actualizar contactos, en las importaciones y en los campos de los formularios. Cada equipo puede tener hasta 100 propiedades. En los endpoints con {id}, puedes usar el ID o la clave.

Las propiedades también entran en el lote de contactos y en los filtros de los segmentos dinámicos (cada tipo tiene sus propios operadores). Si eliminas una propiedad que usa un formulario, el formulario sigue recibiendo respuestas, pero la respuesta de ese campo deja de guardarse en el contacto.

#Tipos y conversión

Tipo	Valores aceptados	Se guarda como
`string`	Texto, hasta 1.000 caracteres.	Texto, sin espacios en los extremos.
`number`	`42`, `"42"`, `"1234,56"` o `"1234.56"`.	Número entero o decimal.
`boolean`	`true`/`false`, `"sim"`/`"não"`, `"yes"`/`"no"`, `"1"`/`"0"`, `"on"`/`"off"`.	`true` o `false`.
`date`	`"2024-03-18"`, `"18/03/2024"` u otra fecha reconocible.	`AAAA-MM-DD`.

Un valor vacío (null o "") borra la propiedad del contacto. Los valores que no se pueden convertir generan 422.

#Listar propiedades

GET/contact-properties

Clave de acceso total

Parámetros de consulta

limitinteger
De 1 a 100. Predeterminado: 20.
afterstring
Cursor de la página siguiente.
beforestring
Cursor de la página anterior.

GET /contact-properties

cURL

curl https://api.postal.so/contact-properties \
  -H "Authorization: Bearer $POSTAL_API_KEY"

Node.js

const response = await fetch('https://api.postal.so/contact-properties', {
  headers: {
    Authorization: `Bearer ${process.env.POSTAL_API_KEY}`,
  },
});

const data = await response.json();

Python

import os
import requests

response = requests.get(
    "https://api.postal.so/contact-properties",
    headers={"Authorization": f"Bearer {os.environ['POSTAL_API_KEY']}"},
    timeout=10,
)

data = response.json()

PHP

$client = new \GuzzleHttp\Client(['base_uri' => 'https://api.postal.so']);

$response = $client->get('contact-properties', [
    'headers' => ['Authorization' => 'Bearer '.getenv('POSTAL_API_KEY')],
]);

$data = json_decode($response->getBody(), true);

200Respuesta

{
  "object": "list",
  "has_more": false,
  "data": [
    {
      "object": "contact_property",
      "id": "019a1d80-5d6e-7f80-8a9b-0c1d2e3f4a5b",
      "key": "plan",
      "type": "string",
      "fallback_value": "free",
      "created_at": "2026-10-20T09:00:00.000000Z",
      "updated_at": "2026-10-20T09:00:00.000000Z"
    }
  ]
}

#Crear una propiedad

POST/contact-properties

Clave de acceso total

La clave y el tipo no pueden cambiar después, porque los contactos ya guardan valores de ese tipo.

Cuerpo de la solicitud

keystringobligatorio
Letras minúsculas, números y _, empezando por letra, hasta 64 caracteres. No puede ser id, email, external_id, user_id, first_name, last_name, unsubscribed, created_at, updated_at, properties, segments, topics, tags ni source.
typestringobligatorio
string, number, boolean o date.
fallback_valuestring | number | boolean | null
Valor que se usa cuando el contacto no tiene la propiedad (por ejemplo, al personalizar envíos).

Errores

422validation_error
Clave no válida, reservada o ya usada, tipo no válido, valor predeterminado incompatible con el tipo, o el equipo ya tiene 100 propiedades.

POST /contact-properties

cURL

curl -X POST https://api.postal.so/contact-properties \
  -H "Authorization: Bearer $POSTAL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "key": "plan",
    "type": "string",
    "fallback_value": "free"
  }'

Node.js

const response = await fetch('https://api.postal.so/contact-properties', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.POSTAL_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    key: 'plan',
    type: 'string',
    fallback_value: 'free',
  }),
});

const data = await response.json();

Python

import os
import requests

response = requests.post(
    "https://api.postal.so/contact-properties",
    headers={"Authorization": f"Bearer {os.environ['POSTAL_API_KEY']}"},
    json={
        "key": "plan",
        "type": "string",
        "fallback_value": "free",
    },
    timeout=10,
)

data = response.json()

PHP

$client = new \GuzzleHttp\Client(['base_uri' => 'https://api.postal.so']);

$response = $client->post('contact-properties', [
    'headers' => ['Authorization' => 'Bearer '.getenv('POSTAL_API_KEY')],
    'json' => [
        'key' => 'plan',
        'type' => 'string',
        'fallback_value' => 'free',
    ],
]);

$data = json_decode($response->getBody(), true);

201Respuesta

{
  "object": "contact_property",
  "id": "019a1d80-5d6e-7f80-8a9b-0c1d2e3f4a5b"
}

#Obtener una propiedad

GET/contact-properties/{id}

Clave de acceso total

Parámetros de ruta

idstringobligatorio
ID o clave.

Errores

404not_found
El recurso no existe o es de otro equipo.

GET /contact-properties/{id}

cURL

curl https://api.postal.so/contact-properties/plan \
  -H "Authorization: Bearer $POSTAL_API_KEY"

Node.js

const response = await fetch('https://api.postal.so/contact-properties/plan', {
  headers: {
    Authorization: `Bearer ${process.env.POSTAL_API_KEY}`,
  },
});

const data = await response.json();

Python

import os
import requests

response = requests.get(
    "https://api.postal.so/contact-properties/plan",
    headers={"Authorization": f"Bearer {os.environ['POSTAL_API_KEY']}"},
    timeout=10,
)

data = response.json()

PHP

$client = new \GuzzleHttp\Client(['base_uri' => 'https://api.postal.so']);

$response = $client->get('contact-properties/plan', [
    'headers' => ['Authorization' => 'Bearer '.getenv('POSTAL_API_KEY')],
]);

$data = json_decode($response->getBody(), true);

200Respuesta

{
  "object": "contact_property",
  "id": "019a1d80-5d6e-7f80-8a9b-0c1d2e3f4a5b",
  "key": "plan",
  "type": "string",
  "fallback_value": "free",
  "created_at": "2026-10-20T09:00:00.000000Z",
  "updated_at": "2026-10-20T09:00:00.000000Z"
}

#Actualizar una propiedad

PATCH/contact-properties/{id}

Clave de acceso total

Solo puede cambiar el valor predeterminado. Enviar key o type genera 422.

Parámetros de ruta

idstringobligatorio
ID o clave.

Cuerpo de la solicitud

fallback_valuestring | number | boolean | null
Nuevo valor predeterminado; null lo quita.

Errores

422validation_error
Algún campo no es válido. El mensaje indica cuál.
404not_found
El recurso no existe o es de otro equipo.

PATCH /contact-properties/{id}

cURL

curl -X PATCH https://api.postal.so/contact-properties/plan \
  -H "Authorization: Bearer $POSTAL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "fallback_value": "pro"
  }'

Node.js

const response = await fetch('https://api.postal.so/contact-properties/plan', {
  method: 'PATCH',
  headers: {
    Authorization: `Bearer ${process.env.POSTAL_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    fallback_value: 'pro',
  }),
});

const data = await response.json();

Python

import os
import requests

response = requests.patch(
    "https://api.postal.so/contact-properties/plan",
    headers={"Authorization": f"Bearer {os.environ['POSTAL_API_KEY']}"},
    json={
        "fallback_value": "pro",
    },
    timeout=10,
)

data = response.json()

PHP

$client = new \GuzzleHttp\Client(['base_uri' => 'https://api.postal.so']);

$response = $client->patch('contact-properties/plan', [
    'headers' => ['Authorization' => 'Bearer '.getenv('POSTAL_API_KEY')],
    'json' => [
        'fallback_value' => 'pro',
    ],
]);

$data = json_decode($response->getBody(), true);

200Respuesta

{
  "object": "contact_property",
  "id": "019a1d80-5d6e-7f80-8a9b-0c1d2e3f4a5b"
}

#Eliminar una propiedad

DELETE/contact-properties/{id}

Clave de acceso total

Quita la definición al instante; los valores que tenían los contactos se borran en segundo plano.

Parámetros de ruta

idstringobligatorio
ID o clave.

Errores

404not_found
El recurso no existe o es de otro equipo.

DELETE /contact-properties/{id}

cURL

curl -X DELETE https://api.postal.so/contact-properties/plan \
  -H "Authorization: Bearer $POSTAL_API_KEY"

Node.js

const response = await fetch('https://api.postal.so/contact-properties/plan', {
  method: 'DELETE',
  headers: {
    Authorization: `Bearer ${process.env.POSTAL_API_KEY}`,
  },
});

const data = await response.json();

Python

import os
import requests

response = requests.delete(
    "https://api.postal.so/contact-properties/plan",
    headers={"Authorization": f"Bearer {os.environ['POSTAL_API_KEY']}"},
    timeout=10,
)

data = response.json()

PHP

$client = new \GuzzleHttp\Client(['base_uri' => 'https://api.postal.so']);

$response = $client->delete('contact-properties/plan', [
    'headers' => ['Authorization' => 'Bearer '.getenv('POSTAL_API_KEY')],
]);

$data = json_decode($response->getBody(), true);

200Respuesta

{
  "object": "contact_property",
  "id": "019a1d80-5d6e-7f80-8a9b-0c1d2e3f4a5b",
  "deleted": true
}