Change API endpoints from v1 to v3

[Mna010]

Hello,

I'm currently working on updating an integration that still uses the HubSpot V1 API to V3, but I'm encountering some issues with specific endpoints.

The endpoint:

https://api.hubapi.com/contacts/v1/contact/vid/{user_vid}/profile

Does this have a functional equivalent in V3, or will it continue to be supported?

Although there is an endpoint in V3:

/crm/v3/objects/contacts/{contactId}

it doesn't return all the same data as the V1 /profile endpoint. To retrieve similar information, I have to use the ?properties= query parameter — but the list of properties gets really long (I mean really), and I'm unsure if that's the proper or recommended approach.

Additionally, I'd like to confirm whether the following endpoint will continue to be supported:

https://api.hubapi.com/contacts/v1/lists/{listId}/contacts/all

We currently use this to fetch contacts from a specific list using its ID. So far, I haven’t found a direct equivalent in V3 that offers the same functionality and level of detail.

Thanks in advance — I look forward to your response!

[sylvain_tirreau · Accepted solution]

Hello,

For your first question, you have no other way than to list the properties you want in v3. I don't know what language you use for your queries, but there are ways to streamline the process, or even automate it. For example, you can retrieve all the properties with GET /crm/v3/properties/contacts and predefine the ones you need by developing routines that handle this in a smooth and readable way. You can also use the POST /crm/v3/objects/contacts/batch/read endpoint with your list of properties at the beginning and your contact IDs afterwards:

{
  "properties": ["firstname","lastname","email","propX","propY", …],
  "inputs": [
    {"id": "1111"},
    {"id": "2222"},
    …
  ]
}

For the second question, you can use these endpoints:

GET /crm/v3/lists/{listId}/memberships

GET /crm/v3/lists/{listId}/memberships/join-order

https://developers.hubspot.com/docs/reference/api/crm/lists

Let us know if this helps.

[sylvain_tirreau · Accepted solution]

Hello,

For your first question, you have no other way than to list the properties you want in v3. I don't know what language you use for your queries, but there are ways to streamline the process, or even automate it. For example, you can retrieve all the properties with GET /crm/v3/properties/contacts and predefine the ones you need by developing routines that handle this in a smooth and readable way. You can also use the POST /crm/v3/objects/contacts/batch/read endpoint with your list of properties at the beginning and your contact IDs afterwards:

{
  "properties": ["firstname","lastname","email","propX","propY", …],
  "inputs": [
    {"id": "1111"},
    {"id": "2222"},
    …
  ]
}

For the second question, you can use these endpoints:

GET /crm/v3/lists/{listId}/memberships

GET /crm/v3/lists/{listId}/memberships/join-order

https://developers.hubspot.com/docs/reference/api/crm/lists

Let us know if this helps.

[Mna010]

Hello,

I use JavaScript to create automations in a low-code platform.

I’d like to know if there’s a more readable way to include the properties query working with the /crm/v3/objects/contacts endpoint — for example, by storing it in a variable and appending it to the request.

Additionally, this 2 older API endpoints. Is there any official information on when these legacy endpoints might be deprecated? Or are they still expected to remain available for now?

Thank you very much in advance!

[sylvain_tirreau · Accepted solution]

Hello,

In javascript, you can do something like that:

const properties = [
  "firstname",
  "lastname",
  "email",
  "phone",
  "company",
  // … all other properties
];

const propertiesQuery = properties.join(",");
const contactId = "12345";
const url = `https://api.hubapi.com/crm/v3/objects/contacts/${contactId}?properties=${propertiesQuery}`;

For v1 endpoints, I seem to remember that everything will stop in September 2025. I advise you to adopt v3 as soon as possible.

[Mna010]

Hi Sylvain! Good morning (at least here in Brazil, haha),

Thank you very much for your response!

I’ve successfully updated the contact endpoint from v1 to v3, using the propertiesQuery—that worked great.

However, I’d like to ask again about the following legacy endpoint:

https://api.hubapi.com/contacts/v1/lists/{listId}/contacts/all

You had previously shared a v3 replacement for it, but I wasn't able to get the same result—specifically, a full list of contacts belonging to a static list.

I was able to retrieve the new list ID using:

/crm/v3/lists/idmapping?legacyListId=2011

But even with the new ID, I haven't been able to replicate the full list behavior like in the v1 endpoint.

Do you happen to have an updated example or documentation for how to fetch all contacts from a static list using the v3 API?

Thanks again for your support—really appreciate it!

Best regards,
Eduardo Montandon

[sylvain_tirreau]

Hi Eduardo,

Did you see this part of my first post?

For the second question, you can use these endpoints:

GET /crm/v3/lists/{listId}/memberships

GET /crm/v3/lists/{listId}/memberships/join-order

https://developers.hubspot.com/docs/reference/api/crm/lists

[Mna010]

Hi Sylvain,

Yes, I saw the first part of your post talking about these membership endpoints, but I couldn't get it to work with the list ID I was using. I tried using this request:

/crm/v3/lists/idmapping?legacyListId=2011

to get a new ID, but even with the new ID, it didn't work the same way. Also, I don't see how a membership list will retrieve a list of contacts in the same way as:

/contacts/v1/lists/{listId}/contacts/all

This member list could really retrieve the same information as contact list? 

[BérangèreL]

Hi @Mna010 and welcome, we are glad to see you here! 🎉

Thanks for reaching out to the HubSpot Community!

For reference, here are the documentation I believe you are speaking about:

- Contacts V1 API
- Contact V3 API

I can confirm that the V1 uses an older format but it is still stable and you can continue to use it. It is still supported.

I'd love to put you in touch with our Top Experts: Hi @sylvain_tirreau, @zach_threadint and @Bortami do you have suggestions to help @Mna010 with the long query parameters for the V3? Do you use it in the same way as @Mna010, please?

Have a lovely day and thanks so much in advance for your valuable contributions! ❤️
Bérangère