Skip to main content

Excluir contatos com a API REST

Objetivos de aprendizagem

Após concluir esta unidade, você estará apto a:

  • Excluir contatos em lotes com a API REST.
  • Obter o status das solicitações de Exclusão de contatos.
  • Solucionar problemas das solicitações de exclusão de contatos.

Excluir contatos com mais eficiência

É bem simples excluir um ou dois contatos diretamente do Marketing Cloud Engagement. No entanto, se for excluir muitos mais, o processo poderá rapidamente se tornar tedioso. Portanto, embora o limite por lote de solicitação seja de um milhão de contatos, não esperamos que você selecione esse número de contatos manualmente. Portanto, se precisar excluir um grande número de contatos (e estiver bem informado para garantir que a exclusão de contatos será a melhor opção), há vários recursos da API REST disponíveis para fazer isso no Marketing Cloud Engagement.

Habilitar a Exclusão de contatos

Lembre-se de que a Exclusão de contatos precisa estar ativada antes de começar. Consulte a unidade anterior para relembrar como fazer isso. Da mesma forma, você pode modificar o período de supressão da conta com o recurso configSettings, conforme mostrado neste exemplo.

Exemplo: Configurar o período de supressão da exclusão de contatos

Este exemplo define o valor para 0 dias (usando um valor de -1) ou uma exclusão imediata.

Host: https://YOUR_SUBDOMAIN.rest.marketingcloudapis.com
POST /contacts/v1/contacts/actions/delete/configSettings
Content-Type: application/json
Authorization: Bearer YOUR_ACCESS_TOKEN
{
   "items" : [{
      "settingKey" : "SuppressionRestoreUntilDays",
      "value" : "-1"
      }
   ]

Optar por excluir contatos com a API REST

Agora que sua conta está ativada para excluir contatos, você pode usar um dos três valores diferentes para escolher quais contatos excluir: IDs de contatos, chaves de contatos ou extensões de dados. Vamos dar uma olhada mais atenta em cada um, juntamente com códigos de exemplo. 

IDs de contatos

Se optar por excluir contatos usando um valor de ID de contato, você deve passar os valores em uma matriz, como mostrado neste exemplo.

Exemplo: Excluir contatos pela ID de contatos

Host: https://YOUR_SUBDOMAIN.rest.marketingcloudapis.com
POST /contacts/v1/contacts/actions/delete?type=ids
Content-Type: application/json
Authorization: Bearer YOUR_ACCESS_TOKEN
{
   "values": [12345678, 12345679],
    "DeleteOperationType": "ContactAndAttributes"
}

Chaves de contatos

Se optar por excluir contatos usando o valor ContactKey, você também deve transmitir esses valores em uma matriz.

Exemplo: Excluir contatos pelas chaves de contatos

Host: https://YOUR_SUBDOMAIN.rest.marketingcloudapis.com
POST /contacts/v1/contacts/actions/delete?type=keys
Content-Type: application/json
Authorization: Bearer YOUR_ACCESS_TOKEN
{
   "values": [
      "TEST_317-531-5555", "TEST_317-531-5556"
      ],
   "DeleteOperationType": "ContactAndAttributes"
}

Extensões de dados

Você também pode optar por remover todos os contatos contidos em uma extensão de dados específica. Lembre-se de que esta operação exclui os registros de contato descritos na extensão de dados em todas as extensões de dados enviáveis. Isso inclui extensões de dados que enviam com base nos valores de ContactKey, ContactID e Endereço de email. Você também pode decidir se deve ou não excluir toda a extensão de dados quando terminar. São tantas opções! 

Esse processo cria uma solicitação assíncrona para seu lote de solicitações de exclusão. Você pode entrar em contato com o gerente da conta do Marketing Cloud Engagement para obter mais informações sobre como configurar os limites de solicitação de exclusão na conta.

Nota

Você deve especificar que está excluindo uma extensão de dados e incluir a chave externa para essa extensão de dados. Além disso, as extensões de dados sincronizadas não podem ser excluídas. Você pode usá-las para ajudar a identificar os contatos que serão excluídos, mas a extensão de dados real permanece.

Exemplo: Excluir contatos usando uma extensão de dados

Host: https://YOUR_SUBDOMAIN.rest.marketingcloudapis.com
POST /contacts/v1/contacts/actions/delete?type=listReference
Content-Type: application/json
Authorization: Bearer YOUR_ACCESS_TOKEN
{
   "deleteOperationType": "ContactAndAttributes",
   "targetList": {
      "listType": {
         "listTypeID": 3
      },
   "listKey": "ContactListDeleteSource_as_DataExtension"
   },
   "deleteListWhenCompleted": false,
   "deleteListContentsWhenCompleted": false
}

Verifique suas solicitações

Como mencionamos, as solicitações de exclusão de contatos levam algum tempo para serem concluídas. Na verdade, o processo pode levar várias horas dependendo de quantos contatos você incluiu na solicitação, quantas solicitações você fez e outros fatores do sistema. No entanto, você pode manter-se atualizado sobre o andamento das solicitações usando o valor de OperationID. Cada solicitação de Exclusão de contatos retorna um valor de OperationID que pode ser usado para recuperar todas as informações disponíveis. Veja algumas solicitações de exemplo.

Exemplo: Obter o status de uma solicitação de exclusão de contatos específica

Host: https://YOUR_SUBDOMAIN.rest.marketingcloudapis.com
GET /contacts/v1/contacts/actions/delete/status?operationID=IDVALUEHERE
Content-Type: application/json
Authorization: Bearer YOUR_ACCESS_TOKEN

Esta resposta de exemplo mostra as informações de um contato excluído.

{
   "operation": {
      "listTypeID": 3,
      "listIdentifier": "037c2811-ce62-4381-b3d2-1936e51fbf4d",
      "listKey": "037c2811-ce62-4381-b3d2-1936e51fbf4d",
      "expectedListCount": 1,
      "deleteType": "ContactAndAttributes",
      "deleteListOnCompleted": false,
      "operationID": 2,
      "eID": 12345,
      "mID": 12345,
      "employeeID": 30980,
      "operationRequestID": "21d0d10d-a15a-413c-bc3e-8b43b185e551",
      "status": "Completed",
      "scheduledTime": "2016-06-14T16:01:58.107",
      "retryCount": 0,
      "createdDate": "2016-06-14T16:02:00",
      "createdBy": 30980,
      "modifiedDate": "2016-06-14T16:02:00",
      "modifiedBy": 30980
    },
    "requestServiceMessageID": "93631be1-107f-4239-a8b7-cdae245d7403",
    "resultMessages": [],
    "serviceMessageID": "00e6add8-d79a-4bd6-9568-2f2a272538f0"
}

Exemplo: Recuperar solicitações de exclusão de contatos por data

Você também pode recuperar um resumo das solicitações feitas durante determinado período. 

Host: https://YOUR_SUBDOMAIN.rest.marketingcloudapis.com
GET contacts/v1/contacts/analytics/deleterequests?startdateutc=2019-02-18T00%3A00%3A00&enddateutc=2019-03-19T00%3A00%3A00&%24page=1&%24pagesize=20&%24orderby=operationId%20desc&statusid=5
Content-Type: application/json
Authorization: Bearer YOUR_ACCESS_TOKEN
{

A resposta inclui os valores de OperationID e resumos curtos de todas as solicitações aplicáveis. Para obter informações mais específicas, use o OperationID com o recurso /contacts/v1/contacts/actions/delete/status?operationID=.

"startDateUtc":"2019-02-18T00:00:00",
"endDateUtc":"2019-03-19T00:00:00",
"statusAsOfDateUtc":"2019-03-19T19:33:17.496471Z",
"pageNumber":1,
"pageSize":20,
"operations":[
   {
      "operationId":22944,
      "totalContactCount":1,
      "completedContactCount":1,
      "receivedDateUtc":"2019-03-04T22:42:00",
      "status":"Completed",
      "lastStatusDateUtc":"2019-03-19T04:47:40.293",
      "deleteMethod":"Contact Key/ID"
   },
   {
      "operationId":22943,
      "totalContactCount":1,
      "completedContactCount":1,
      "receivedDateUtc":"2019-03-04T22:41:00",
      "status":"Completed",
      "lastStatusDateUtc":"2019-03-19T04:47:40.293",
      "deleteMethod":"Contact Key/ID"
   },
   {
      "operationId":22625,
      "totalContactCount":1,
      "completedContactCount":1,
      "receivedDateUtc":"2019-02-26T23:26:00",
      "status":"Completed",
      "lastStatusDateUtc":"2019-03-13T10:10:17.9",
      "deleteMethod":"Contact Key/ID"
   }
   ],
   "requestServiceMessageID":"e1198208-6432-40fd-b5ae-172c9d9bc44a",
   "responseDateTime":"2019-03-19T13:33:18.2141124-06:00",
   "resultMessages":[],
   "serviceMessageID":"ef7d833c-509f-4dbc-8f99-060aac3c0382"
}

Exemplo: Recuperar um resumo das solicitações de exclusão de contatos

Este exemplo exibe um resumo dos relatórios de status de todas as solicitações durante o período especificado.

Host: https://YOUR_SUBDOMAIN.rest.marketingcloudapis.com
GET contacts/v1/contacts/analytics/deleterequests/summary?startdateutc=2018-01-15T00:00:00Z&enddateutc=2018-01-15T05:00:00Z
Content-Type: application/json
Authorization: Bearer YOUR_ACCESS_TOKEN

A resposta de exemplo divide as solicitações em concluídas, em processamento ou inválidas.

{
   "startdateutc":"2018-01-15T00:00:00Z",
   "enddateutc":"2018-01-15T04:30:00Z",
   "statusofdateutc": "2018-01-17T04:30:00Z",
   "interval":"0",
   "itemcount":5,
   "totaltimeseries":[
      {
         "requestcount":500,
         "minvalue":100,
         "maxvalue":100,
         "items":[
            {time:"01-15-2018 00:00:00","value":100},
            {time:"01-15-2018 01:00:00","value":100},
            {time:"01-15-2018 02:00:00","value":100},
            {time:"01-15-2018 03:0000:","value":100},
            {time:"01-15-2018 04:00:00","value":100}
         ]
      }],
      "statustimeseries":[
         {
            "statusid": 5,
            "status": "Completed",
            "requestcount":350,
            "minvalue":0,
            "maxvalue":100,
            "items":[
               {time:"01-15-2018 00:00:00","value":100},
               {time:"01-15-2018 01:00:00","value":100},
               {time:"01-15-2018 02:00:00","value":100},
               {time:"01-15-2018 03:00:00","value":50},
               {time:"01-15-2018 04:00:00","value":0}
            ]
         },
         {
            "statusid": 1,
            "status": “Processing”,
            "requestcount":100,
            "minvalue":0,
            "maxvalue":75,
            "items":[
               {time:"01-15-2018 00:00:00","value":0},
               {time:"01-15-2018 01:00:00","value":0},
               {time:"01-15-2018 02:00:00","value":0},
               {time:"01-15-2018 03:00:00","value":25},
               {time:"01-15-2018 04:00:00","value":75}
            ]
         },
         {
            "statusid": 7,
            "Status": "Invalid",
            "requestcount":50,
            "minvalue":0,
            "maxvalue":50,
            "items":[
               {time:"01-15-2018 00:00:00","value":0},
               {time:"01-15-2018 01:00:00","value":0},
               {time:"01-15-2018 02:00:00","value":0},
               {time:"01-15-2018 03:00:00","value":25},
               {time:"01-15-2018 04:00:00","value":25}
            ]
         }]
}

Você pode usar os valores de OperationID para acompanhar solicitações inválidas ou que estejam em processamento.

Muitos códigos, não é? Vamos deixar o código um pouco de lado e prosseguir para a unidade final para ver qual é a melhor maneira de evitar armadilhas durante a exclusão de contatos.

Recursos

Continue a aprender de graça!
Inscreva-se em uma conta para continuar.
Inscrever-se Login
O que você ganha com isso?
  • Receba recomendações personalizadas para suas metas de carreira
  • Pratique suas habilidades com desafios práticos e testes
  • Monitore e compartilhe seu progresso com os empregadores
  • Conecte-se a orientação e oportunidades de carreira
Pular por enquanto