topic Re: Contact search API query string is limited to 200 characters in APIs & Integrations

Contact search API query string is limited to 200 characters

PR74 — Mon, 17 Nov 2025 12:04:43 GMT

It seems there is a bug with the contact search API when doing conditional searching for email addresses. The documentation states that the query property can be 3000 characters long (https://developers.hubspot.com/docs/api-reference/crm-contacts-v3/search/post-crm-v3-objects-contacts-search#body-query). However, if my request exceeds 200 characters for the query property, I get an error response.

Using

https://api.hubapi.com/crm/v3/objects/contacts/search

with this payload

{
  "query": "john.doe@eb3c98816-c3ab-11f0-a584-63ba2f7fb723.com OR john.doe@bd42b3c2-c3ab-11f0-8770-dfb98893914e.com OR john.doe@c2bb4c2e-c3ab-11f0-bed5-d33480d22c18.com OR john.doe@c86258ac-c3ab-11f0-ba78-ff99757320fe.com"
}

returns this response

{
  "status": "error",
  "message": "There was a problem with the request.",
  "correlationId": "f3dfb058-4345-4a6e-8081-388ea8292149"
}

whereas this payload where the length of the query string has been arbitrarily reduced to 200 characters

{
  "query": "john.doe@eb3c98816-c3ab-11f0-a584-63ba2f7fb723.com OR john.doe@bd42b3c2-c3ab-11f0-8770-dfb98893914e.com OR john.doe@c2bb4c2e-c3ab-11f0-bed5-d33480d22c18.com OR john.doe@c86258ac-c3ab-11f0-ba78-ff9.com"
}

returns the (expected) response

{
  "total": 0,
  "results": []
}

Re: Contact search API query string is limited to 200 characters

Jaycee_Lewis — Mon, 17 Nov 2025 20:35:10 GMT

Hey hey @PR74 🙌 Thanks for flagging this. This is definitely unexpected. I got the same result just now in my tests. I'll add my examples in a separate thread. My gut says the workaround will be to use FIlter Groups and the IN filter for now. I'm going to take your example and my tests and take it to the dev docs team. I'll reply here once I have more info for us. — Jaycee

Re: Contact search API query string is limited to 200 characters

Jaycee_Lewis — Mon, 17 Nov 2025 20:49:06 GMT

Here are my test payloads:

Worked
{ "query": "test@12345678-abcd-1234-abcd-1234567890ab.com OR test@22345678-abcd-1234-abcd-1234567890ab.com OR test@32345678-abcd-1234-abcd-1234567890ab.com" }
Worked
{ "query": "test@12345678-abcd-1234-abcd-1234567890ab.com OR test@22345678-abcd-1234-abcd-1234567890ab.com OR test@32345678-abcd-1234-abcd-1234567890ab.com OR test@42345678-abcd-1234-abcd-1234567890ab.com" }
(Didn't work > 200 characters)
{ "query": "test@12345678-abcd-1234-abcd-1234567890ab.com OR test@22345678-abcd-1234-abcd-1234567890ab.com OR test@32345678-abcd-1234-abcd-1234567890ab.com OR test@42345678-abcd-1234-abcd-1234567890ab.com OR test@52345678-abcd-1234-abcd-1234567890ab.com" }

One workaround approach:

{ "filterGroups": [ { "filters": [ { "propertyName": "email", "operator": "IN", "values": [ "test@12345678-abcd-1234-abcd-1234567890ab.com", "test@22345678-abcd-1234-abcd-1234567890ab.com", "test@32345678-abcd-1234-abcd-1234567890ab.com", "test@42345678-abcd-1234-abcd-1234567890ab.com", "test@52345678-abcd-1234-abcd-1234567890ab.com" ] } ] } ], "properties": [ "email", "firstname", "lastname" ] }

Best,

Jaycee

Re: Contact search API query string is limited to 200 characters

PR74 — Tue, 18 Nov 2025 15:26:06 GMT

Thank you, this seems to work in the interim

Re: Contact search API query string is limited to 200 characters

Jaycee_Lewis — Tue, 18 Nov 2025 16:32:22 GMT

You are welcome! Of all the endpoints we offer, the Search API is the one I've spent the most time with. For better and worse lol 😂 — Jaycee

Re: Contact search API query string is limited to 200 characters

GRajput — Thu, 20 Nov 2025 11:27:07 GMT

Hi @PR74

Use the Contact search APi with multiple values on OR. Right now you are using a single string but if you use search then on values you can comma seperated values to use multiple values.

I hope this will help you out. Please mark it as Solution Accepted and upvote to help another Community member.

Thanks!

Re: Contact search API query string is limited to 200 characters

RubenBurdin — Thu, 20 Nov 2025 23:18:30 GMT

Hi @PR74

I’ve hit this same edge case before and your testing is spot on. Even though the documentation says the query parameter accepts up to 3000 characters, the conditional OR parser seems to choke once the string goes past roughly 200 chars.

It’s not your payload format, it’s how HubSpot tokenizes long OR chains inside the free-text query. HubSpot’s property history and search docs show how this part of the engine behaves differently from filter-based searches (https://knowledge.hubspot.com/records/view-record-property-history )

The stable path is exactly what Jaycee highlighted. Use the Search API’s structured filters instead of the free search field. The IN operator avoids the character limit entirely and scales cleanly across dozens or hundreds of emails. HubSpot’s filter groups behave much more predictably for multi-value lookups

(https://developers.hubspot.com/docs/api-reference/search/guide )

If you end up pulling these large email batches from other systems and syncing into HubSpot, Stacksync keeps both sides aligned in real time so you don’t need to build long OR queries or run heavy search calls in the first place. Hope this helps.

Re: Contact search API query string is limited to 200 characters

Jaycee_Lewis — Fri, 21 Nov 2025 16:27:33 GMT

Thanks for confirming my approach, @RubenBurdin 🙌 I've done the dance with the Search API many times. It's so powerful, and it has quirks. If you or @PR74 has a moment, adding this as feedback in the Developer Feedback form is helpful. I did the same internally with both of our examples. +1 for teamwork! 😊 — Jaycee