Contactos

Listar contactos

Devuelve los contactos (clientes y proveedores) visibles para la clave, paginados por cursor.

GET

/api/v1/contacts

curl https://app.filmo.io/api/v1/contacts \
  --header "Authorization: Bearer $FILMO_API_KEY"

Node.jsfetch('https://app.filmo.io/api/v1/contacts', { headers: { Authorization: 'Bearer YOUR_FILMO_API_KEY' } })Pythonimport requests requests.get("https://app.filmo.io/api/v1/contacts", headers={ "Authorization": "Bearer YOUR_FILMO_API_KEY" } )

{
  "data": [
    {
      "id": "contact_9f3a2b",
      "name": "Example contact",
      "contactType": "person",
      "role": "client",
      "status": "active",
      "nif": "B00000000",
      "commercialName": "Example commercial name",
      "position": "Example position",
      "contactNumber": "2026-0001",
      "emails": [
        {
          "id": "email_9f3a2b",
          "label": "Main",
          "email": "ana.garcia@example.com",
          "isPrimary": true
        }
      ],
      "billingEmail": "ana.garcia@example.com",
      "phoneNumbers": [
        {
          "id": "phone_number_9f3a2b",
          "label": "Main",
          "number": "+34 600 000 000",
          "countryCode": "+34",
          "isPrimary": true
        }
      ],
      "websites": [
        {
          "id": "website_9f3a2b",
          "label": "Main",
          "url": "https://example.com/resource"
        }
      ],
      "addresses": [
        {
          "id": "address_9f3a2b",
          "label": "Main",
          "addressLine1": "Calle de Ejemplo 12",
          "addressLine2": "Calle de Ejemplo 12",
          "city": "Madrid",
          "province": "Madrid",
          "postcode": "28001",
          "country": "ES",
          "isMain": true
        }
      ],
      "folder": "Example folder",
      "discountPercentage": 1,
      "preferredLanguage": "es-ES",
      "currency": "EUR",
      "paymentMethod": {
        "type": "bank_transfer",
        "customValue": "Example custom value"
      },
      "paymentDays": [
        1
      ],
      "expirationDays": 1,
      "subscribedToMarketing": true,
      "isAppUser": true,
      "customFields": {
        "example": "example"
      },
      "createdAt": "2026-09-01T08:00:00.000Z",
      "updatedAt": "2026-09-01T08:00:00.000Z"
    }
  ],
  "pagination": {
    "nextCursor": "eyJvIjoyMH0",
    "hasMore": true,
    "total": 1
  }
}

{
  "type": "https://docs.filmo.io/errors/validation_error",
  "title": "Validation error",
  "status": 400,
  "code": "validation_error",
  "detail": "2 validation errors",
  "requestId": "req_0b9f6c1d2e3a4f5a8b7c6d5e4f3a2b1c",
  "errors": [
    {
      "path": "name",
      "code": "too_small",
      "message": "Must be at least 1 characters long"
    },
    {
      "path": "contactType",
      "code": "invalid_value",
      "message": "Value not allowed; expected company, person"
    }
  ]
}

{
  "type": "https://docs.filmo.io/errors/unauthorized",
  "title": "Unauthorized",
  "status": 401,
  "code": "unauthorized",
  "detail": "Missing Authorization header: Bearer <api key>",
  "requestId": "req_0b9f6c1d2e3a4f5a8b7c6d5e4f3a2b1c"
}

{
  "type": "https://docs.filmo.io/errors/insufficient_scope",
  "title": "Insufficient scope",
  "status": 403,
  "code": "insufficient_scope",
  "detail": "The API key does not have the required scope (orders:write)",
  "requestId": "req_0b9f6c1d2e3a4f5a8b7c6d5e4f3a2b1c",
  "requiredScope": "contacts:read"
}

{
  "type": "https://docs.filmo.io/errors/rate_limited",
  "title": "Rate limit exceeded",
  "status": 429,
  "code": "rate_limited",
  "detail": "Rate limit exceeded: retry in 30 seconds",
  "requestId": "req_0b9f6c1d2e3a4f5a8b7c6d5e4f3a2b1c",
  "retryAfter": 30
}

{
  "type": "https://docs.filmo.io/errors/internal_error",
  "title": "Internal error",
  "status": 500,
  "code": "internal_error",
  "detail": "Internal error",
  "requestId": "req_0b9f6c1d2e3a4f5a8b7c6d5e4f3a2b1c"
}

Generado a partir del esquema

Aislamiento heredado de la cuenta principal: una cuenta de facturación ve también los contactos de su cuenta principal.

Autorizaciones

Clave de API como Bearer, con el permiso de abajo. contacts:read

Parámetros de consulta

limitintegerpredeterminado:50

Tamaño de página (1-500). Por defecto es 50.

Límites: mín. 1, máx. 500

cursorstring

Cursor opaco de la página que se devuelve. Pasa el valor de pagination.nextCursor de la respuesta anterior; trátalo como opaco.

Límites: longitud máx. 200

createdOnstring

La fecha de creación del recurso cae en esta fecha. Una fecha sin hora (YYYY-MM-DD, interpretada en la zona horaria del negocio) o un instante ISO 8601 con desplazamiento.