Add new contact to a list using contacts scope only


Hi, am new here so I apologize in advance if am doing something wrong...

I have an integration that use &scope=contacts only, and I need to add a contact to a list, in the following url it says that

This endpoint is designed for offline contacts ... If your contacts come through online forms, use the Form Submission endpoint.

However I don't have access to the "form scope", what are the alternative way to add a new subscriber to a specific list using the "contacts scope" ?



Hi @jim_child,

Just to make sure that we're on the same page, I think it's important to clarify that 'add a contact to a list' has a specific meaning in HubSpot. Lists are collections of contact objects in HubSpot, and interacting with them programmatically involves using the Contact Lists API (see below). This can be done with only the contacts scope.

If by 'add a contact to a list' you're actually referring to creating a new contact record in HubSpot, you can still accomplish that with only the contacts scope using the Contacts API (i.e. the method you linked to above). This is intended to be used for offline contacts, as the warning says. This is only an issue if the contacts you're creating came in through an online form. If that's the case, then it is not possible to add them to HubSpot 'correctly', since that requires using the form submission endpoint and the forms scope.

Can you give me some more specific information on what exactly you're trying to do? It's tough to give specific answers without knowing precisely what you're looking to accomplish. It's possible there's a solution that does not require the forms scope, but I can't be sure yet.


Hi @Derek_Gervais,

Thank you for your reply, am not sure what do you mean by " think it's important to clarify that 'add a contact to a list' has a specific meaning in HubSpot..." from my understanding it's like other email marketing tools, you might have a list of buyers for example which you want to interact with them differently than a list of non buyers (that's just an example), so a list is a collection like you said to group contacts!

We have a popup form that asks visitor to subscribe to receive a free report, so I want to put those visitors who sign up in a specific list. That's what am trying to do.

As you confirmed the 'add a contact to a list' I referred to was intended to be used for offline contacts, so I was looking for an alternative to accomplish the same thing through an online form, here is what I found :

I can maybe accomplish this by combining the following: +

I have tried it and it seems to work, can you please confirm it's ok to do it that way?

Thank you


Hi @jim_child,

I didn't mean to make things sound more complicated then they are; occasionally people coming from other systems use the phrase "add a contact to a list" to mean "create a contact record" and I wanted to make sure you and I were on the same page.

It sounds like you might be trying to do both; create a contact, and then add it to a list. I'll try to cover each separately, since they're not really directly related.

There are a number of ways to create contacts via the API. For offline contacts, your best bet is the Contacts API. If the contacts are submitting an external form, you'll want to check out the Forms API (see below). Other non-API methods include standard HubSpot forms, in-app creation, and imports.

Now to add those contacts to a list, it's important to know which kind of list we're working with. Static lists are simple; they're a list you can manually add/remove contacts to. If the list you're looking to add contacts to is a Static list, you'd want to use the 'Add contact to a list' endpoint. Active lists, on the other hand, are automatically populated based on their criteria. It's not possible to directly add a contact to an active list; you need to update the contact record to fit the criteria.

Let me know if that helps answer your question, and feel free to post any follow up questions below!