[Documentation Errors Bug] Poor Documentation for /contacts/search

[jbwx]

🐛 Describe the Issue

Just some poor documentation for this.

📍 API Endpoint

https://services.leadconnectorhq.com/contacts/search

💻 Screenshots or Code Samples

The default example given is this:

const url = 'https://services.leadconnectorhq.com/contacts/search';
const options = {
  method: 'POST',
  headers: {
    Authorization: 'Bearer [key]',
    Version: '2021-07-28',
    'Content-Type': 'application/json',
    Accept: 'application/json'
  },
  body: '{}'
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}

Nowhere does it say body should look something like this:

{
    "pageLimit" : 1,
    "locationId" : "yfyIrXrm61r57rx3ex4N",
    "query" : "your query here"
}

I had to figure this out on my own. Also, if pageLimit and locationId aren't specified, it'll 422. Nowhere in the documentation is this exemplified or made obvious, even on the linked page here. Please fix your documentation!

[i-am-rad]

Query field isn't there. Are you saying that works? locationId and pageLimit are marked as required on the clickup doc...

[jbwx]

True about locationId and pageLimit, although my primary point is that query isn't mentioned anywhere in the docs, and it should be. You'd think a "search contacts" endpoint would include documentation for a "query" parameter – which yes, does work, as per this example:

async function searchContacts(query, token) {
        const url = "https://services.leadconnectorhq.com/contacts/search";
        const options = {
            method: "POST",
            headers: {
                Authorization: "Bearer " + token,
                Version: "2021-07-28",
                "Content-Type": "application/json",
                Accept: "application/json",
            },
            body: `{
                     "pageLimit" : 1,
                     "locationId" : "locationIDHere",
                     "query" : "${query}"
                   }`,
        };

        try {
            const response = await fetch(url, options);
            const data = await response.json();
            console.log(data);
        } catch (error) {
            console.error(error);
        }
    }

[Cobeas]

I agree here, even if the query was named, what is it tested against? Just name, phone, email, or more?

With that, and I hope I don't need to make an additional issue for this, why don't we get the full name of the contact?

And lastly, the return type in the Clickup documentation does not align with the Stoplight documentation (or Docusaurus) as the following fields are not mentioned:

• visitorId which is an optional string
• skipEmailVerification which is an optional boolean

Then the next fields are always returned but might be null:

• phoneLabel
• address
• source
• website
• state
• businessName
• companyName
• phone
• city
• dateOfBirth
• firstNameLowerCase
• lastNameLowerCase
• validEmail <- this one is also optional and if present can be null
• postalCode
• businessId