Lead

Ultimo aggiornamento: 10 dicembre 2024
  • Argomenti:

Creato per:

  • Amministratore

Riferimento endpoint lead

L’API del lead di Marketo offre un’ampia serie di funzionalità per semplici applicazioni CRUD rispetto ai record dei lead, nonché la possibilità di modificare l’appartenenza di un lead a elenchi e programmi statici e di avviare l’elaborazione di campagne intelligenti per i lead.

Descrivere

Una delle funzionalità chiave dell’API Leads è il metodo Describe. Utilizza Descrivi lead per recuperare un elenco completo dei campi disponibili per l’interazione tramite l’API REST, nonché i metadati per ciascuno di essi:

  • Tipo di dati
  • Nomi API REST
  • Lunghezza (se applicabile)
  • Sola lettura
  • Etichetta intuitiva

Descrivi è la principale fonte di verità per stabilire se i campi sono disponibili per l’uso e i metadati su di essi.

Richiesta

GET /rest/v1/leads/describe.json

Risposta

{
   "requestId":"37ca#1475b74e276",
   "success":true,
   "result":[
      {
         "id":2,
         "displayName":"Company Name",
         "dataType":"string",
         "length":255,
         "rest":{
            "name":"company",
            "readOnly":false
         },
         "soap":{
            "name":"Company",
            "readOnly":false
         }
      }
}

Normalmente, le risposte includono un set molto più ampio di campi nell’array dei risultati, ma vengono omesse a scopo dimostrativo. Ogni elemento nella matrice dei risultati corrisponde a un campo disponibile nel record del lead e avrà almeno un ID, un displayName e un tipo di dati. Gli altri oggetti secondari soap e possono essere presenti o meno per un determinato campo e la loro presenza indicherà se il campo è valido per l’uso nelle API REST o SOAP. La proprietà readOnly indica se il campo è di sola lettura tramite l'API corrispondente (REST o SOAP). La proprietà length indica la lunghezza massima del campo, se presente. La proprietà dataType indica il tipo di dati del campo.

Query

Esistono due metodi principali per il recupero dei lead: il metodo Get Lead per ID e il metodo Get Lead per tipo di filtro. Ottieni lead per ID considera un singolo ID lead come parametro di percorso e restituisce un singolo record lead.

Facoltativamente, puoi trasmettere un parametro di campi contenente un elenco separato da virgole di nomi di campi da restituire. Se il parametro fields non è incluso in questa richiesta, vengono restituiti i seguenti campi predefiniti: email, updatedAt, createdAt, lastName, firstName e id. Quando si richiede un elenco di campi, se un particolare campo viene richiesto ma non restituito, il valore deve essere nullo.

Richiesta

GET /rest/v1/lead/{id}.json

Risposta

{
   "requestId": "10226#14d3049e51b",
   "success": true,
   "result": [
      {
         "id": 318581,
         "updatedAt":"2015-05-07T11:47:30-08:00"
         "lastName": "Doe",
         "email": "jdoe@marketo.com",
         "createdAt": "2015-05-01T16:47:30-08:00",
         "firstName": "John"
      }
   ]
}

Per questo metodo, ci sarà sempre un singolo record nella prima posizione della matrice dei risultati.

Ottieni lead per tipo di filtro restituirà lo stesso tipo di record, ma può restituire fino a 300 per pagina. Richiede i parametri di query filterType e filterValues.

filterType accetta qualsiasi campo personalizzato o la maggior parte dei campi comunemente utilizzati. Chiamare l'endpoint Describe2 per ottenere un elenco completo dei campi ricercabili consentiti in filterType. Durante la ricerca per campo personalizzato, sono supportati solo i seguenti tipi di dati: string, email, integer. È possibile ottenere i dettagli del campo (descrizione, tipo e così via) utilizzando il metodo Describe sopra indicato.

filterValues accetta fino a 300 valori in formato separato da virgole. La chiamata cerca i record in cui il campo del lead corrisponde a uno dei filterValues inclusi. Se il numero di lead che corrispondono al filtro lead è maggiore di 1.000, viene restituito un errore: "1003, Troppi risultati corrispondono al filtro".

Se la lunghezza totale della richiesta GET supera gli 8 KB, viene restituito un errore HTTP: "414, URI troppo lungo" (per RFC 7231). Come soluzione alternativa, è possibile modificare il GET in POST, aggiungere il parametro _method=GET e inserire una stringa di query nel corpo della richiesta.

Richiesta

GET /rest/v1/leads.json?filterType=id&filterValues=318581,318592

Risposta

{
    "requestId": "12951#15699db5c97",
    "result": [
        {
            "id": 318581,
            "updatedAt": "2016-05-17T22:11:45Z",
            "lastName": "Lincoln",
            "email": "abe@usa.gov",
            "createdAt": "2015-03-17T00:18:40Z",
            "firstName": "Abraham"
        },
        {
            "id": 318592,
            "updatedAt": "2016-05-17T22:20:51Z",
            "lastName": "Washington",
            "email": "george@usa.gov",
            "createdAt": "2015-04-06T16:29:21Z",
            "firstName": "George"
        }
    ],
    "success": true
}

Questa chiamata cerca i record corrispondenti agli ID inclusi in filterValues e restituisce tutti i record corrispondenti.

Se non viene trovato alcun record, la risposta indica che l’operazione è riuscita, ma l’array dei risultati sarà vuoto.

Risposta

{
"requestId": "177a1#1578b643357",
"result": [],
"success": true
}

Sia il metodo Get Lead by Id che Get Leads by Filter Type accettano anche un parametro di query fields, che accetta un elenco separato da virgole di campi API. Se è incluso, ogni record nella risposta includerà i campi elencati. Se viene omesso, verrà restituito un set predefinito di campi: id, email, updatedAt, createdAt, firstName e lastName.

ADOBE ECID

Quando la funzione Condivisione pubblico di Adobe Experience Cloud è abilitata, si verifica un processo di sincronizzazione dei cookie che associa Adobe Experience Cloud ID (ECID) ai lead di Marketo. I metodi di recupero dei lead sopra menzionati possono essere utilizzati per recuperare i valori ECID associati. Per farlo, specifica ecids nel parametro fields. Ad esempio, &fields=email,firstName,lastName,ecids.