Produtos suportados
Requer um dos seguintes produtos ou superior.
Marketing HubMarketing HubEnterprise
Sales HubSales HubEnterprise
Service HubService HubEnterprise
Content HubContent HubEnterprise
Última modificação: 28 de agosto de 2025

Run in Postman

 Em cada conta do HubSpot, há os objetos padrão do CRM: contatos, empresas, negócios e tickets. Para representar e organizar seus dados de CRM com base nas necessidades da sua empresa, você também pode criar objetos personalizados. Você pode criar um objeto personalizado no HubSpot ou usar a API de objetos personalizados para definir objetos, propriedades e associações personalizadas a outros objetos do CRM. Abaixo, saiba como criar e gerenciar objetos personalizados por meio da API e veja um passo a passo sobre como criar um objeto personalizado de exemplo. Para saber mais sobre como criar objetos personalizados, confira os seguintes posts de blog para desenvolvedores da HubSpot:

​
Observação:

Objetos personalizados são específicos para cada conta e, dependendo da sua assinatura, há limites no número de objetos personalizados que você pode criar. Saiba mais sobre seus limites em nosso Catálogo de produtos e serviços da HubSpot.

​
Métodos de autenticação

Você pode criar, ler e atualizar objetos personalizados usando um dos seguintes métodos de autenticação:

​
Criar um objeto personalizado

Para criar um objeto personalizado, primeiramente, será necessário definir o esquema do objeto. O esquema inclui o nome do objeto, propriedades e associações a outros objetos do CRM. Você pode encontrar os detalhes completos da solicitação do esquema na guia Esquema do objeto na parte superior deste artigo. Você também pode visualizar uma solicitação de amostra no exemplo de passo a passo abaixo. Para criar o esquema de objeto personalizado, faça uma solicitação POST para crm/v3/schemas. No corpo da solicitação, inclua definições para seu esquema de objeto, incluindo seu nome, propriedades e associações. Ao nomear o objeto personalizado, saiba que:
  • Depois de criar um objeto, seu nome e rótulo não poderão ser alterados.
  • O nome pode conter somente letras, números e sublinhados.
  • O primeiro caractere do nome deve ser uma letra.
  • Os rótulos longos podem ser cortados em certas partes do produto.
Abaixo, leia sobre as definições necessárias para as propriedades e associações do objeto.

​
Propriedades

As propriedades que você definir no corpo da solicitação serão usadas para armazenar informações em registros de objetos personalizados individuais.

​
Observação:

Você pode ter até 10 propriedades de valor únicas para cada objeto personalizado na sua conta HubSpot.
Você usará suas propriedades definidas para preencher os seguintes campos baseados em propriedades:
  • requiredProperties: as propriedades que são necessárias ao criar um novo registro de objeto personalizado.
  • searchableProperties: as propriedades que são indexadas para pesquisa no HubSpot.
  • primaryDisplayProperty: a propriedade usada para nomear registros de objetos personalizados individuais.
  • **secondaryDisplayProperties: **as propriedades que aparecem em registros individuais sob primaryDisplayProperty.
custom-object-secondary-display-properties0
  • A primeira propriedade listada em secondaryDisplayProperties também será adicionada como um quarto filtro na página de índice de objetos se for um dos seguintes tipos de propriedades:
    • string
    • number
    • enumeration
    • boolean
    • datetime
custom-object-dashboard-filter0
  • Para remover uma propriedade de exibição da UI, você precisará, primeiramente, excluir a propriedade e depois recriá-la.
Por padrão, ao criar propriedades por meio da solicitação de esquema, a propriedade type é definida como string e fieldType é definida como text. Abaixo estão os valores que você pode usar para criar diferentes tipos de propriedades.
typeDescriçãoValores fieldType válidos
enumerationUma sequência de caracteres que representa um conjunto de opções separadas por ponto e vírgula.booleancheckbox, checkbox, radio, select
dateUm valor com formatação ISO 8601 que representa um dia, mês e ano específicos.date
dateTimeUm valor com formatação ISO 8601 que representa um dia, mês, ano e horário do dia específicos. O aplicativo HubSpot não exibirá o horário do dia.date
stringUma string de texto simples, com no máximo 65.536 caracteres.file, text, textarea
numberUm valor numérico que contém dígitos numéricos e, na maioria das vezes, um número decimal.number
fieldTypeDescrição
booleancheckboxUma entrada que permite que os usuários selecionem Sim ou Não. Quando usada em um formulário, essa entrada aparece como uma única caixa de seleção.
checkboxUma lista de caixas de seleção que permite que um usuário selecione várias opções em um conjunto de opções válidas para a propriedade.
dateUm valor de data, que é exibido como um seletor de data.
filePermite que um arquivo seja carregado em um formulário. Armazenado e exibido como link de URL para o arquivo.
numberUma string de numerais ou números escritos em formato decimal ou em notação científica.
radioUma entrada que permite que os usuários selecionem um conjunto de opções válidas para a propriedade. Quando usada em um formulário, essa entrada é exibida como um conjunto de botões de opção.
selectUma entrada suspensa que permite que os usuários selecionem um conjunto de opções válidas para a propriedade.
textUma string de texto simples, que é exibida em uma entrada de texto com uma única linha.
textareaUma string de texto simples, que é exibida como uma entrada de texto com várias linhas.

​
Associações

A HubSpot associará automaticamente um objeto personalizado com os e-mails, reuniões, notas, tarefas, chamadas e objetos de conversas. Você pode associar ainda mais seu objeto personalizado a outros objetos HubSpot padrão ou outros objetos personalizados. Ao criar associações por meio da solicitação create schema, identifique objetos padrão usando o nome e objetos personalizados usando o valor objectTypeId. Por exemplo: 

"associatedObjects": [
  "CONTACT",
  "COMPANY",
  "TICKET",
  "DEAL",
  "2-3453932"
]

​
Recuperar objetos personalizados existentes

Para recuperar todos os objetos personalizados, faça uma solicitação GET para /crm/v3/schemas. Para recuperar um objeto personalizado específico, faça uma solicitação GET para um dos seguintes pontos de extremidade:
  • /crm/v3/schemas/{objectTypeId}
  • /crm/v3/schemas/p_{object_name}
  • /crm/v3/schemas/{fullyQualifiedName} Você pode encontrar o fullyQualifiedName do objeto em seu esquema, que é derivado de p{portal_id}_{object_name}. Você pode encontrar o ID do portal da sua conta usando a API de informações da conta.
Por exemplo, para uma conta com um ID de 1234 e um objeto chamado lender, o URL de solicitação pode ser semelhante a qualquer um dos seguintes:

​
Obter registros de objetos personalizados

Você também pode obter os registros de um objeto personalizado.
  • Para recuperar um registro específico pelo seu valor de ID de registro, faça uma solicitação GET para crm/v3/objects/{objectType}/{recordId}.
Para este ponto de extremidade, você pode incluir os seguintes parâmetros de consulta no URL da solicitação:
ParâmetroDescrição
propertiesUma lista separada por vírgulas das propriedades a serem retornadas em resposta. Se o objeto personalizado solicitado não tiver um valor para uma propriedade, ele não será exibido na resposta.
propertiesWithHistoryUma lista separada por vírgulas das propriedades atuais e do histórico a serem retornadas em resposta. Se o objeto personalizado solicitado não tiver um valor para uma propriedade, ele não será exibido na resposta.
associationsUma lista separada por vírgulas de objetos para recuperar IDs associados. Todas as associações especificadas que não existem não serão retornadas na resposta. Saiba mais sobre a API de associações.
  • Para recuperar vários registros, faça uma solicitação POST para crm/v3/objects/{objectType}/batch/read. O ponto de extremidade em lote não pode recuperar associações. Saiba como fazer associações de leitura em lote com a API de associações.
Na sua solicitação, você pode recuperar os registros pelo ID do registro (hs_object_id) ou por uma propriedade de identificador exclusivo personalizada. Por padrão, os valores de id na solicitação referem-se ao ID do registro; portanto, o parâmetro idProperty não é necessário ao recuperar pelo ID do registro. Para usar uma propriedade de valor exclusivo personalizada, você deve incluir o parâmetro idProperty. Por exemplo, para recuperar um lote de registros de objetos personalizados, sua solicitação pode ser parecida com o seguinte: 
{
  "properties": ["petname"],
  "inputs": [
    {
      "id": "12345"
    },
    {
      "id": "67891"
    }
  ]
}

{
  "properties": ["petname"],
  "idProperty": "uniquepropertyexample",
  "inputs": [
    {
      "id": "abc"
    },
    {
      "id": "def"
    }
  ]
}
Para recuperar registos de objetos personalizados com valores atuais e do histórico de uma propriedade, sua solicitação pode ser parecida com o seguinte: 
{
  "propertiesWithHistory": ["pet_owner"],
  "inputs": [
    {
      "id": "12345"
    },
    {
      "id": "67891"
    }
  ]
}

​
Atualizar os objetos personalizados existentes

Para atualizar o esquema de um objeto, faça uma solicitação PATCH para https://api.hubapi.com/crm/v3/schemas/{objectTypeId}. Quando seu objeto personalizado for definido:
  • O nome e os rótulos do objeto (singular e plural) não podem ser alterados.
  • As propriedades requiredProperties, searchableProperties, primaryDisplayProperty e secondaryDisplayProperties podem ser alteradas atualizando o esquema do objeto. Para definir uma nova propriedade como uma propriedade obrigatória, pesquisável ou de exibição, você precisa criá-la antes de atualizar o esquema.
  • Você pode criar e editar propriedades de objetos personalizados no HubSpot ou por meio da API de propriedades.

​
Atualizar associações

Para adicionar outras associações de objetos ao seu objeto personalizado, faça uma solicitação POST para /crm/v3/schemas/_{objectTypeId}_/associations. Você só pode associar seu objeto personalizado com objetos HubSpot padrão (por exemplo,_ contato_, empresa,_ negócio_ ou ticket) ou outros objetos personalizados. No campo toObjectTypeId, identifique objetos personalizados pelo valor objectTypeId e objetos padrão pelo seu nome. Por exemplo: 
{
  "fromObjectTypeId": "2-3444025",
  "toObjectTypeId": "ticket",
  "name": "cat_to_ticket"
}

​
Excluir um objeto personalizado

Você somente pode excluir um objeto personalizado depois que todas as instâncias de objeto desse tipo forem excluídas. Para excluir uma objeto personalizado, faça uma solicitação DELETE para /crm/v3/schemas/{objectType}. Se você precisar criar um novo objeto personalizado com o mesmo nome que o objeto excluído, você deve excluir o esquema fazendo uma solicitação DELETE para /crm/v3/schemas/{objectType}?archived=true. Você só pode excluir um tipo de objeto personalizado depois que todas as instâncias de objeto desse tipo, associações e propriedades de objeto personalizado forem excluídas.

​
Exemplo de objeto personalizado

Apresentamos a seguir um passo a passo para criar um exemplo de objeto personalizado. Para obter detalhes completos das solicitações mostradas, consulte a guia Definição do objeto na parte superior do artigo. Este passo a passo abrange:
  1. criação de um esquema de objeto personalizado.
  2. criação de um registro de objeto personalizado.
  3. associação de um registro de objeto personalizado a um contato do HubSpot.
  4. criação de uma nova definição de associação entre o objeto personalizado e o ticket da HubSpot.
  5. criação de uma nova definição de propriedade.
  6. atualização do esquema do objeto (ou seja, secondaryDisplayProperties) com a nova propriedade.
Meta: uma concessionária de automóveis chamada CarSpot deseja armazenar seu inventário na HubSpot usando um objeto personalizado. Para controlar a propriedade e compras de veículos, eles associarão carros a registros do contato. Além disso, eles também controlarão a manutenção do veículo usando tickets da HubSpot e propriedades personalizadas.

​
Crie o esquema do objeto

O CarSpot precisa criar um esquema de objeto que possa representar os seguintes atributos como propriedades:
  1. Condição (nova ou usada): enumeração
  2. Data de chegada na concessionária: data
  3. Ano: número
  4. Marca: cadeia de caracteres
  5. Modelo: cadeia de caracteres
  6. VIN: cadeia de caracteres (valor único)
  7. Cor: string
  8. Quilometragem: cadeia de caracteres
  9. Preço: número
  10. Observações: cadeia de caracteres
Eles também adicionarão uma descrição para fornecer contexto sobre como usar o objeto e definirão uma associação entre seu objeto personalizado e o objeto de contatos padrão para que possam conectar carros a possíveis compradores. Com seu modelo de dados finalizado, eles criarão o esquema do objeto fazendo um POST solicitação para /crm/v3/schemas com o seguinte corpo de solicitação: 
{
  "name": "cars",
  "description": "Cars keeps track of cars currently or previously held in our inventory.",
  "labels": {
    "singular": "Car",
    "plural": "Cars"
  },
  "primaryDisplayProperty": "model",
  "secondaryDisplayProperties": ["make"],
  "searchableProperties": ["year", "make", "vin", "model"],
  "requiredProperties": ["year", "make", "vin", "model"],
  "properties": [
    {
      "name": "condition",
      "label": "Condition",
      "type": "enumeration",
      "fieldType": "select",
      "options": [
        {
          "label": "New",
          "value": "new"
        },
        {
          "label": "Used",
          "value": "used"
        }
      ]
    },
    {
      "name": "date_received",
      "label": "Date received",
      "type": "date",
      "fieldType": "date"
    },
    {
      "name": "year",
      "label": "Year",
      "type": "number",
      "fieldType": "number"
    },
    {
      "name": "make",
      "label": "Make",
      "type": "string",
      "fieldType": "text"
    },
    {
      "name": "model",
      "label": "Model",
      "type": "string",
      "fieldType": "text"
    },
    {
      "name": "vin",
      "label": "VIN",
      "type": "string",
      "hasUniqueValue": true,
      "fieldType": "text"
    },
    {
      "name": "color",
      "label": "Color",
      "type": "string",
      "fieldType": "text"
    },
    {
      "name": "mileage",
      "label": "Mileage",
      "type": "number",
      "fieldType": "number"
    },
    {
      "name": "price",
      "label": "Price",
      "type": "number",
      "fieldType": "number"
    },
    {
      "name": "notes",
      "label": "Notes",
      "type": "string",
      "fieldType": "text"
    }
  ],
  "associatedObjects": ["CONTACT"]
}
Depois de criar o esquema do objeto, o CarSpot registra o campo {objectTypeId} do novo objeto, pois ele será usado para buscar e atualizar o objeto posteriormente. Eles também podem usar o valor {fullyQualifiedName}, se preferirem.

​
Criar um registro de objeto personalizado

Com o objeto personalizado criado, agora, a CarSpot pode criar registros no objeto para cada carro em seu inventário. Eles criarão seu primeiro carro fazendo uma solicitação POST para /crm/v3/objects/2-3465404 com o seguinte corpo de solicitação: 
{
  "properties": {
    "condition": "used",
    "date_received": "1582416000000",
    "year": "2014",
    "make": "Nissan",
    "model": "Frontier",
    "vin": "4Y1SL65848Z411439",
    "color": "White",
    "mileage": "80000",
    "price": "12000",
    "notes": "Excellent condition. No accidents."
  }
}
A resposta para esta chamada de API seria semelhante a: 
{
  "id": "181308",
  "properties": {
    "color": "White",
    "condition": "used",
    "make": "Nissan",
    "mileage": "80000",
    "model": "Frontier",
    "vin": "4Y1SL65848Z411439",
    "notes": "Excellent condition. No accidents.",
    "price": "12000",
    "year": "2014",
    "date_received": "1582416000000"
  },
  "createdAt": "2020-02-23T01:44:11.035Z",
  "updatedAt": "2020-02-23T01:44:11.035Z",
  "archived": false
}
Com o registro criado, eles podem usar o valor id para associar posteriormente o carro a um contato existente.
Se quisessem recuperar mais tarde este registro junto com propriedades específicas, eles poderiam fazer uma solicitação GET para https://api.hubapi.com/crm/v3/objects/2-3465404/181308?portalId=1234567&properties=year&properties=make&properties=model

​
Associar o registro do objeto personalizado a outro registro

Você pode usar o ID do novo registro de carro (181308) e o ID de outro registro para associar um registro de objeto personalizado a um registro de outro objeto. Para criar uma associação, faça uma solicitação PUT para /crm/v3/objects/{objectType}/{objectId}/associations/{toObjectType}/{toObjectId}/{associationType}. Se a relação do objeto já estiver definida, para determinar o valor de associationType, faça uma solicitação GET para crm/v3/schemas/{objectType}. Por exemplo, com o _ID de contato 51 e o tipo de associação75, _o CarSpot pode associar o registro do carro a um contato. Usando os IDs acima, a URL da solicitação será construída da seguinte maneira: https://api.hubspot.com/crm/v3/objects/2-3465404/181308/associations/contacts/51/75

​
Definir uma nova associação

Agora, a CarSpot quer começar o rastreamento dos serviços pós-venda de seus carros. Para fazer isso, eles usarão os tickets da HubSpot para registrar qualquer manutenção realizada. Para permitir associações entre carros e tickets, eles criarão uma nova associação fazendo uma solicitação POST para /crm/v3/schemas/2-3465404/associations com o seguinte corpo de solicitação: 
{
  "fromObjectTypeId": "2-3465404",
  "toObjectTypeId": "ticket",
  "name": "car_to_ticket"
}
A resposta para esta chamada de API seria semelhante a: 
{
  "id": "121",
  "createdAt": "2020-02-23T01:52:12.893826Z",
  "updatedAt": "2020-02-23T01:52:12.893826Z",
  "fromObjectTypeId": "2-3465404",
  "toObjectTypeId": "0-5",
  "name": "car_to_ticket"
}
Ao criar uma nova associação entre dois objetos personalizados, especifique os objetos personalizados por objectTypeId no campo toObjectTypeId. Para objetos padrão, você pode identificá-los pelo nome ou usar os seguintes valores:
  • Contato: 0-1
  • Empresa: 0-2
  • Negócio: 0-3
  • Ticket: 0-5

​
Definir uma nova propriedade

À medida que continuam a controlar a manutenção, a CarSpot vê uma oportunidade para agrupar serviços de manutenção em pacotes. Para controlar esses pacotes de manutenção em registros de carros individuais, eles criarão uma nova propriedade de enumeração que contém os pacotes disponíveis. Para definir uma nova propriedade, eles enviam uma solicitação POST para /crm/v3/properties/2-3465404 com o seguinte corpo de solicitação: 
{
  "groupName": "car_information",
  "name": "maintenance_package",
  "label": "Maintenance Package",
  "type": "enumeration",
  "fieldType": "select",
  "options": [
    {
      "label": "Basic",
      "value": "basic"
    },
    {
      "label": "Oil change only",
      "value": "oil_change_only"
    },
    {
      "label": "Scheduled",
      "value": "scheduled"
    }
  ]
}
A resposta para esta chamada de API seria semelhante a: 
{
  "updatedAt": "2020-02-23T02:08:20.055Z",
  "createdAt": "2020-02-23T02:08:20.055Z",
  "name": "maintenance_package",
  "label": "Maintenance Package",
  "type": "enumeration",
  "fieldType": "select",
  "groupName": "car_information",
  "options": [
    {
      "label": "Basic",
      "value": "basic",
      "displayOrder": -1,
      "hidden": false
    },
    {
      "label": "Oil change only",
      "value": "oil_change_only",
      "displayOrder": -1,
      "hidden": false
    },
    {
      "label": "Scheduled",
      "value": "scheduled",
      "displayOrder": -1,
      "hidden": false
    }
  ],
  "displayOrder": -1,
  "calculated": false,
  "externalOptions": false,
  "archived": false,
  "hasUniqueValue": false,
  "hidden": false,
  "modificationMetadata": {
    "archivable": true,
    "readOnlyDefinition": false,
    "readOnlyValue": false
  },
  "formField": false
}
Agora que a propriedade foi criada, eles querem exibi-la na barra lateral de cada registro de carro para que as informações fiquem facilmente disponíveis para seus representantes de vendas e técnicos. Para fazer isso, eles adicionarão a propriedade a secondaryDisplayProperties fazendo uma solicitação PATCH para /crm/v3/schemas/2-3465404 com o seguinte corpo de solicitação: 
{
  "secondaryDisplayProperties": ["maintenance_package"]
}
A resposta para esta chamada de API seria semelhante a: 
{
  "id": "3465404",
  "createdAt": "2020-02-23T01:24:54.537Z",
  "updatedAt": "2020-02-23T02:12:24.175874Z",
  "labels": {
    "singular": "Car",
    "plural": "Cars"
  },
  "requiredProperties": ["year", "model", "vin", "make"],
  "searchableProperties": ["year", "model", "vin", "make"],
  "primaryDisplayProperty": "model",
  "secondaryDisplayProperties": ["maintenance_package"],
  "portalId": 1234567,
  "name": "car"
}
Agora, quando um técnico abre um registro do contato com um carro associado, a propriedade será exibida no cartão de objeto personalizado na barra lateral:
Captura de tela 06-03-2020 às 11:08:41
Como a CarSpot continua a usar a HubSpot, eles provavelmente encontrarão maneiras de refinar e expandir esse objeto personalizado e muito mais usando a API da HubSpot. Eles podem até mesmo optar por criar páginas dinâmicas usando seus dados de objetos personalizados.